13 Min. Lesezeit

Lernziele

Am Ende dieses Moduls werden Sie in der Lage sein:

  • Ein PostgreSQL-Cluster mit `ionoscloud_pg_cluster_v2` bereitstellen, einschließlich Instanzgröße, Replikationsmodus, Sicherungen und Wartungsfenster
  • Ein In-Memory DB-Cluster mit `ionoscloud_inmemorydb_cluster_v2` für die Sitzungs- und Lese-Cache von TaskBoard bereitstellen
  • Verwaltete Datenbanken mit einem privaten LAN verbinden, wobei Adressen verwendet werden, die DHCP- und reservierte Bereiche vermeiden
  • Verbindungsdetails aus Terraform als Ausgaben bereitstellen, während Passwörter aus dem State ferngehalten werden
  • Dasselbe Muster auf `ionoscloud_mariadb_cluster_v2`, `ionoscloud_mongo_cluster` und `ionoscloud_kafka_cluster` anwenden

Einheit 2.5: Bereitstellung von Datenbank- und Streaming-Diensten

Einführung

Die transaktionalen Daten von TaskBoard befinden sich weiterhin auf einem Block Storage-Volumen des API-Servers. Sie benötigen einen verwalteten PostgreSQL-Cluster mit Sicherungen und Failover sowie einen Cache davor für Sitzungen und häufig gelesene Daten, ohne dass Sie eines der beiden selbst betreiben müssen. Beide müssen aus demselben Terraform-Projekt wie der übrige Stack erstellt werden, damit jede Branch-Umgebung ihre eigene Datenbank-Ebene erhält.

In dieser Einheit provisionieren Sie diese Datenbank-Ebene als Code. Sie dimensionieren und konfigurieren den PostgreSQL-Cluster, verbinden ihn mit dem privaten DB-LAN aus Einheit 2.2, fügen einen In-Memory DB-Cluster hinzu und geben die Verbindungsdaten aus, die Ihre Anwendung benötigt. MariaDB, MongoDB und Event Streams for Apache Kafka folgen demselben Muster, und Sie sehen deren Ressourcenbezeichnungen und wesentlichen Unterschiede. Im Code Lab deployen Sie die Datenbank-Ebene von TaskBoard und verbinden sich mit beiden Clustern.

1. PostgreSQL mit ionoscloud_pg_cluster_v2

resource "ionoscloud_pg_cluster_v2" "taskboard" {
  name             = "taskboard-pg"
  description      = "TaskBoard transactional data"
  version          = var.pg_version
  location         = ionoscloud_datacenter.taskboard.location
  replication_mode = "ASYNCHRONOUS"

  instances = {
    count        = 3
    cores        = 2
    ram          = 4
    storage_size = 50
  }

  connections = {
    datacenter_id            = ionoscloud_datacenter.taskboard.id
    lan_id                   = ionoscloud_lan.db.id
    primary_instance_address = "10.10.2.6/24"
  }

  backup = {
    location       = var.backup_location
    retention_days = 7
  }

  maintenance_window = {
    day_of_the_week = "Sunday"
    time            = "03:00:00"
  }

  credentials = {
    username         = "taskboard"
    password         = var.pg_password
    password_version = "1"
    database         = "taskboard"
  }
}

Die v2-Ressource kommuniziert mit der regionalen PostgreSQL v2 API, die location entspricht, und eine Änderung von location zerstört den Cluster und erstellt einen neuen. In instances sind ram und storage_size in GB angegeben, im Gegensatz zu den MB des ram eines Servers.

1.1 Dimensionierung und Replikation

instances.count ist die Gesamtzahl der Instanzen: eine Primärinstanz und n-1 Standby-Instanzen. Ein Cluster hat maximal fünf Instanzen, und IONOS CLOUD empfiehlt mindestens drei für den Produktivbetrieb. replication_mode ist entweder ASYNCHRONOUS oder STRICTLY_SYNCHRONOUS:

Modus Verhalten Kompromiss
ASYNCHRONOUS Die Primärinstanz wartet nicht darauf, dass eine Standby-Instanz einen Schreibvorgang bestätigt Bessere Leistung; beim Failover kann ein kleiner Datenverlust auftreten
STRICTLY_SYNCHRONOUS Jeder Commit wartet auf eine synchrone Standby-Instanz; wenn keine Standby-Instanz verfügbar ist, werden keine Schreibvorgänge akzeptiert Kein Datenverlust beim Failover; opfert Verfügbarkeit zugunsten der Dauerhaftigkeit

Wie die Tabelle zeigt, stoppt STRICTLY_SYNCHRONOUS Schreibvorgänge, wenn keine Standby-Instanz verfügbar ist, und benötigt daher mindestens drei Instanzen. Die Entwicklungsumgebung von TaskBoard verwendet ASYNCHRONOUS.

Standby-Instanzen dienen der Hochverfügbarkeit: Eine übernimmt, wenn die Primärinstanz ausfällt. Ihre Anwendung verbindet sich über den einzelnen dns_name des Clusters. Planen Sie das Read-Scaling mit dem Cache in Abschnitt 2, nicht mit den Standby-Instanzen; Modul 4 baut diese Cache-Ebene auf.

1.2 Sicherungen, Wartung und Versionen

backup.location ist der Object Storage-Ort für Sicherungen und ist unveränderlich. Rufen Sie die gültigen Werte mit GET /backup-locations der PostgreSQL v2 API ab, beispielsweise eu-central-3. Die Aufbewahrungsdauer beträgt standardmäßig 7 Tage, und Sie können innerhalb des Aufbewahrungsfensters zu einem bestimmten Zeitpunkt wiederherstellen, und zwar über restore_from_backup. Das maintenance_window ist ein wöchentliches Zeitfenster von 4 Stunden; sein time ist in UTC angegeben.

Die unterstützten Hauptversionen sind 14, 15, 16, 17 und 18. Lesen Sie die genauen Versionszeichenketten für Ihren Standort aus der Datenquelle:

data "ionoscloud_pg_versions_v2" "available" {
  location = ionoscloud_datacenter.taskboard.location
}

output "pg_versions" {
  value = [for v in data.ionoscloud_pg_versions_v2.available.versions : "${v.version} ${v.status}"]
}

Sie können nur auf eine höhere Version upgraden; Downgrades werden nicht unterstützt.

1.3 Zugangsdaten ohne Zustandslecks

credentials.password ist nur schreibbar: Es wird nie im Terraform-Zustand gespeichert und erfordert Terraform 1.11 oder höher. Da Terraform eine Änderung an einem Wert, den es nicht speichert, nicht erkennen kann, erhöhen Sie password_version (zum Beispiel von "1" auf "2"), wann immer Sie das Passwort rotieren. Lesen Sie das Passwort aus Ihrem Secret Store, niemals aus einer .tfvars-Datei in Git:

variable "pg_password" {
  type      = string
  sensitive = true
  ephemeral = true
}
export TF_VAR_pg_password="$(vault kv get -field=pg_password secret/taskboard/dev)"

Die Benutzernamen postgres, admin, root, sys, replication sowie Namen, die mit pg_ beginnen, sind reserviert. Wählen Sie daher einen anwendungsspezifischen Namen wie taskboard.

2. In-Memory DB mit ionoscloud_inmemorydb_cluster_v2

In-Memory DB v2 führt Valkey aus, das mit Redis-Clients in den Versionen 9, 8.1 und 8 kompatibel ist.

resource "ionoscloud_inmemorydb_cluster_v2" "cache" {
  name             = "taskboard-cache"
  location         = ionoscloud_datacenter.taskboard.location
  version          = var.cache_version
  eviction_policy  = "allkeys-lru"
  persistence_mode = "None"

  instances = {
    count = 1
    cores = 1
    ram   = 4
  }

  connections = {
    datacenter_id            = ionoscloud_datacenter.taskboard.id
    lan_id                   = ionoscloud_lan.db.id
    primary_instance_address = "10.10.2.7/24"
  }

  snapshot = {
    location       = var.backup_location
    retention_days = 7
  }

  maintenance_window = {
    day_of_the_week = "Sunday"
    time            = "04:00:00"
  }

  credentials = {
    username = "taskboard"
    password = {
      algorithm = "SHA-256"
      hash      = sha256(var.cache_password)
    }
  }
}

2.1 Cache-spezifische Argumente

  • Passwort-Hash: Die API akzeptiert nur einen vorab gehashten SHA-256-Wert als 64 Zeichen langer, kleingeschriebener Hexadezimalzeichenfolge. Die Funktion sha256() von Terraform erzeugt genau diesen Wert, sodass das Klartextpasswort weder die API noch den Zustand erreicht.
  • eviction_policy: erforderlich. allkeys-lru eignet sich für einen Lese-Cache; noeviction lehnt Schreibvorgänge ab, wenn der Speicher voll ist.
  • persistence_mode: None, AOF, RDB oder RDB_AOF. Ein reiner Cache kann ohne Persistenz betrieben werden; Sitzungen, die nach einem Neustart nicht verloren gehen sollen, benötigen RDB oder AOF.
  • instances: count von 1 bis 5, ram von 4 bis 240 GB. Der Arbeitsspeicher kann nicht herabgestuft werden, und der Speicherplatz wird aus dem Arbeitsspeicher und dem Persistenzmodus abgeleitet.
  • connections: Pro Cluster ist nur eine Verbindung zulässig.

Die verfügbaren Versionszeichenfolgen können mit der ionoscloud_inmemorydb_versions_v2-Datenquelle abgerufen werden, auf dieselbe Weise wie bei PostgreSQL. Clients verbinden sich mit redis-cli oder einem beliebigen Redis-kompatiblen Treiber, optional über TLS, und das dns_name des Clusters zeigt auf seine primäre Instanz.

3. Netzwerkplatzierung und Verbindungsoutputs

3.1 Adressen im DB-LAN

Jede verwaltete Datenbank erhält eine statische Adresse in einem privaten LAN, das Sie im Code festlegen. Zwei Regeln sorgen dafür, dass diese Adressen sicher bleiben:

  1. Wählen Sie sie aus dem für verwaltete Dienste reservierten Bereich, .2 bis .9 (Einheit 2.2, Abschnitt 1.3). TaskBoard verwendet .4 für das NAT-Gateway, .6 für PostgreSQL und .7 für den Cache.
  2. Vermeiden Sie die Bereiche, die DBaaS blockiert: 10.208.0.0/12, 10.233.0.0/18, 192.168.230.0/24 und 10.233.64.0/18.

Die Cluster befinden sich im DB-LAN, daher benötigen die App-Server eine Netzwerkkarte (NIC) in diesem LAN, um sie zu erreichen:

resource "ionoscloud_nic" "api_db" {
  datacenter_id   = ionoscloud_datacenter.taskboard.id
  server_id       = ionoscloud_server.api.id
  lan             = ionoscloud_lan.db.id
  name            = "db"
  dhcp            = true
  ips             = ["10.10.2.11"]
  firewall_active = false
}

Fügen Sie dieselbe NIC mit 10.10.2.21 zum Worker hinzu. Die NSG-Regeln der DB-Ebene aus Einheit 2.3 akzeptieren dann diese beiden Adressen.

3.2 Ausgaben für die Anwendung

output "pg_host" {
  value = ionoscloud_pg_cluster_v2.taskboard.dns_name
}

output "pg_url" {
  value     = "postgresql://taskboard@${ionoscloud_pg_cluster_v2.taskboard.dns_name}:5432/taskboard?sslmode=verify-full"
  sensitive = true
}

output "cache_host" {
  value = ionoscloud_inmemorydb_cluster_v2.cache.dns_name
}

Die URL enthält bewusst kein Passwort: Ihre Anwendung liest es aus demselben Secret Store, der auch Terraform versorgt. Alle Client-Verbindungen zu PostgreSQL werden mit TLS verschlüsselt; der Standard-SSL-Modus ist prefer, und Clients können die Verschlüsselung nicht deaktivieren. Für verify-ca oder verify-full benötigt der Client das Stammzertifikat ISRG Root X1, da die Serverzertifikate von Let's Encrypt für den DNS-Namen des Clusters ausgestellt werden. Client-Bibliotheken müssen die SCRAM-SHA-256-Authentifizierung unterstützen.

4. Referenzen mit gleichem Muster: MariaDB, MongoDB und Kafka

Diese Dienste teilen sich die grundlegenden Bausteine: einen Standort, eine private LAN-Verbindung und die Dimensionierung. MariaDB und MongoDB unterstützen zusätzlich ein Wartungsfenster, und MariaDB erfordert Zugangsdaten.

resource "ionoscloud_mariadb_cluster_v2" "reports" {
  name     = "taskboard-reports"
  location = ionoscloud_datacenter.taskboard.location
  version  = var.mariadb_version
  instances = { count = 1, cores = 2, ram = 4, storage_size = 20 }
  connections = {
    datacenter_id            = ionoscloud_datacenter.taskboard.id
    lan_id                   = ionoscloud_lan.db.id
    primary_instance_address = "10.10.2.8/24"
  }
  backup             = { location = var.backup_location, retention_days = 7 }
  maintenance_window = { day_of_the_week = "Sunday", time = "05:00:00" }
  credentials        = { username = "app", password = var.mariadb_password, database = "app" }
}
Service Ressource Wesentliche Unterschiede
DBaaS for MariaDB ionoscloud_mariadb_cluster_v2 Port 3306; Versionen 10.6, 10.11, 11.4, 11.8 und 12.3; Replikation ist ausschließlich asynchron; password ist ein sensibles Argument, null im Zustand nach dem Import
MongoDB ionoscloud_mongo_cluster edition (Playground, Business oder Enterprise), mongodb_version (6.0 oder 7.0), Änderungen an instances und connections erzwingen die Neuanlage; connections.cidr_list übernimmt die Liste der IPs mit Subnetz für den Cluster; die berechnete connection_string verwendet mongodb+srv
Event Streams for Apache Kafka ionoscloud_kafka_cluster, ionoscloud_kafka_cluster_topic size statt Instanzgrößen; drei Broker, deren broker_addresses Sie im LAN festlegen; mTLS-Authentifizierung mit Client-Zertifikaten, die 365 Tage gültig sind; Themen mit replication_factor und number_of_partitions festgelegt

Wie die Tabelle zeigt, ist die Struktur dieselbe, aber die Regeln für die Neuanlage und die Authentifizierung unterscheiden sich. Prüfen Sie die RequiresReplace und die Hinweise zu „erzwingt Neuanlage“, bevor Sie ein Argument in einem aktiven Cluster ändern.

resource "ionoscloud_kafka_cluster" "events" {
  name     = "taskboard-events"
  location = ionoscloud_datacenter.taskboard.location
  version  = "4.0.0"
  size     = "S"
  connections {
    datacenter_id    = ionoscloud_datacenter.taskboard.id
    lan_id           = ionoscloud_lan.db.id
    broker_addresses = ["10.10.2.2/24", "10.10.2.3/24", "10.10.2.5/24"]
  }
}

resource "ionoscloud_kafka_cluster_topic" "task_events" {
  cluster_id           = ionoscloud_kafka_cluster.events.id
  location             = ionoscloud_kafka_cluster.events.location
  name                 = "task-events"
  replication_factor   = 3
  number_of_partitions = 6
}

Ein Replikationsfaktor von 3 ist der Standardwert und der empfohlene Wert. Broker-Adressen müssen 10.224.0.0/11 vermeiden. Ihre Clients holen ihre Zertifikate und den Schlüssel von GET /clusters/{clusterId}/users/{userId}/access; Einheit 4.3 behandelt die Client-Seite.

API-Referenz Schnellkarte

Wichtige API-Endpunkte hinter den Ressourcen dieser Einheit:

Methode Endpunkt Beschreibung
POST /clusters Erzeugt von ionoscloud_pg_cluster_v2 (PostgreSQL v2 API, https://postgresql.de-txl.ionos.com/v2)
GET /backup-locations Listet gültige backup.location-Werte (PostgreSQL v2 API)
GET /versions Listet verfügbare Versionen (PostgreSQL v2 und In-Memory DB v2 APIs)
POST /clusters Erzeugt von ionoscloud_inmemorydb_cluster_v2 (In-Memory DB v2 API, https://in-memory-db.de-txl.ionos.com/v2)
GET /clusters/{clusterId}/users/{userId}/access Kafka-Client-Zertifikate und Schlüssel (Kafka API)

Basis-URL: regional pro Dienst, beispielsweise https://postgresql.de-txl.ionos.com/v2 Authentifizierung: Authorization: Bearer <token>

Code Lab

Ziel: Deployen der Datenbank-Ebene von TaskBoard mit Terraform (ein PostgreSQL-Cluster und ein In-Memory DB-Cluster im DB LAN), Ausgabe der Verbindungsdaten und Verbindungsaufbau zu beiden von dem API-Server aus.

Voraussetzungen:

  • Das Projekt aus den Einheiten 2.1 bis 2.4, angewendet, mit IONOS_TOKEN gesetzt und Terraform 1.11 oder neuer
  • Zwei Passwörter in Ihrem Secret Store, exportiert als TF_VAR_pg_password und TF_VAR_cache_password
  • psql und redis-cli (oder valkey-cli) auf dem API-Server

Schritt 1: Verfügbare Versionen auflisten

Fügen Sie die ionoscloud_pg_versions_v2-Datenquelle und die Ausgabe aus Abschnitt 1.2 hinzu, sowie das gleiche Muster für ionoscloud_inmemorydb_versions_v2 (sein List-Attribut ist items).

terraform apply -auto-approve -target=data.ionoscloud_pg_versions_v2.available >/dev/null
terraform output pg_versions

Erwartete Ausgabe:

[
  "14 ...",
  ...
  "18 ..."
]

Schritt 2: Versionen und Sicherungsstandort festlegen

variable "pg_version"      { default = "17" }   # one of the versions from Step 1
variable "cache_version"   { type = string }    # one of the In-Memory DB versions
variable "backup_location" { default = "eu-central-3" }

Erwartete Ausgabe:

(file saved)

Schritt 3: Cluster, NICs und Ausgänge hinzufügen

Fügen Sie das PostgreSQL-Cluster (Abschnitt 1), den Cache (Abschnitt 2), die api_db NIC und die DB-NIC des Workers (Abschnitt 3.1) sowie die Ausgänge (Abschnitt 3.2) hinzu. Wenden Sie dann die Änderungen an:

terraform apply -auto-approve | grep "Apply complete"
terraform output -raw pg_host; echo

Erwartete Ausgabe:

Apply complete! Resources: 4 added, 0 changed, 0 destroyed.
pg-<id>.postgresql.de-txl.ionos.com

Die Clustererstellung dauert mehrere Minuten; der Anbieter wartet bis zu den Ressourcen-Timeouts.

Schritt 4: Verbindung zu PostgreSQL vom API-Server aus herstellen

PGHOST=$(terraform output -raw pg_host)
ssh root@"$(terraform output -raw api_public_ip)" \
  "PGPASSWORD='$TF_VAR_pg_password' psql 'host=$PGHOST dbname=taskboard user=taskboard sslmode=require' -c 'select version();'"

Erwartete Ausgabe:

 PostgreSQL 17...
(1 row)

Schritt 5: Verbindung mit dem Cache herstellen

CACHE=$(terraform output -raw cache_host)
ssh root@"$(terraform output -raw api_public_ip)" \
  "redis-cli -h $CACHE --user taskboard --pass '$TF_VAR_cache_password' PING"

Erwartete Ausgabe:

PONG

Validierungscheckliste:

  • [ ] terraform apply hat beide Cluster und die zwei DB-LAN-NICs erstellt
  • [ ] psql verbindet sich über TLS mit dem DNS-Namen des Clusters
  • [ ] Der Cache beantwortet PONG mit dem konfigurierten Benutzer
  • [ ] terraform state show ionoscloud_pg_cluster_v2.taskboard zeigt kein Passwort

Aufräumarbeiten:

terraform destroy -auto-approve

Häufige Fehler

Entwicklerfehler, die bei dem Thema dieser Einheit zu vermeiden sind:

  1. Primäre Adresse in einem blockierten oder DHCP-Bereich

    • Problem: Die Cluster-Erstellung schlägt fehl, oder die Datenbank kollidiert mit einer Serveradresse.
    • Ursache: Die Adresse liegt in einem Bereich, den DBaaS blockiert, oder außerhalb des verwalteten Dienstebereichs von .2 bis .9, in dem DHCP sie einem Netzwerkadapter zuweisen kann.
    • Lösung: Planen Sie alle Adressen für verwaltete Dienste pro LAN in einer einzigen locals-Karte, von .2 bis .9, außerhalb der blockierten Bereiche (Abschnitt 3.1).
  2. Passwortrotation, die nie stattfindet

    • Problem: Sie ändern TF_VAR_pg_password, terraform plan zeigt keine Änderungen an, und das alte Passwort funktioniert weiterhin.
    • Ursache: Das Passwort ist nur schreibbar und wird nicht im Zustand gespeichert, sodass Terraform nicht erkennen kann, dass es sich geändert hat.
    • Lösung: Erhöhen Sie credentials.password_version zusammen mit dem neuen Passwort.
  3. Verbindungen, die bei einem Failover abbrechen

    • Problem: Nach Wartungsarbeiten oder einem Failover protokolliert die API Verbindungsfehler, bis sie neu gestartet wird.
    • Ursache: Während eines Failovers muss der Client die Verbindung neu aufbauen. Bei einem unkontrollierten Ausfall wird die Verbindung möglicherweise nicht sauber geschlossen.
    • Lösung: Bauen Sie die Verbindung mit exponentiellem Back-off neu auf, beginnend mit einem sofortigen erneuten Versuch, und verwenden Sie einen Verbindungspool, der Verbindungen validiert.

Zusammenfassung

Sie können die Datenbank-Ebene von TaskBoard jetzt als Code bereitstellen. Der PostgreSQL v2-Cluster verfügt über eine Primärinstanz und Standby-Instanzen für Failover, einen bewusst gewählten Replikationsmodus, Sicherungen in einem Object Storage-Standort sowie ein nur schreibbares Passwort, das niemals im Zustand gespeichert wird. Der In-Memory DB-Cluster läuft mit Valkey, einem per SHA-256 gehashten Passwort und einer Verdrängungsrichtlinie, die für einen Cache geeignet ist. Beide verbinden sich mit dem privaten DB-LAN über Adressen aus dem Bereich für verwaltete Dienste, und Ihre Anwendung erhält deren DNS-Namen aus Terraform-Ausgaben.

Wichtige Punkte:

  • Verwenden Sie die v2-Ressourcen ionoscloud_pg_cluster_v2, ionoscloud_inmemorydb_cluster_v2 und ionoscloud_mariadb_cluster_v2
  • Ein PostgreSQL-Cluster hat bis zu fünf Instanzen: eine Primärinstanz und n-1 Standby-Instanzen für Hochverfügbarkeit
  • PostgreSQL-Verbindungen sind immer TLS-verschlüsselt; verwenden Sie ISRG Root X1 für verify-full
  • Halten Sie Passwörter aus dem Zustand heraus: nur schreibbar für PostgreSQL, sha256()-Hashes für In-Memory DB
  • Vergeben Sie statische Adressen von .2 bis .9 für verwaltete Datenbanken und vermeiden Sie die blockierten Bereiche von DBaaS

Wichtige Begriffe:

  • Standby-Instanz: Eine PostgreSQL-Instanz, die die Primärinstanz repliziert und bei einem Failover übernimmt
  • Replikationsmodus: ASYNCHRONOUS oder STRICTLY_SYNCHRONOUS, der Kompromiss zwischen Schreibgeschwindigkeit und Dauerhaftigkeit
  • Nur schreibbares Argument: Ein Terraform-Argument, das an die API gesendet, aber niemals im Zustand gespeichert wird, wie das PostgreSQL-Passwort
  • Verdrängungsrichtlinie: Die Regel, die bestimmt, welche Schlüssel In-Memory DB entfernt, wenn der Arbeitsspeicher voll ist
  • Primärinstanz-Adresse: Die statische IP und Netzmaske, die eine verwaltete Datenbank in Ihrem privaten LAN erhält

Nächste Schritte

Weiter lernen: Einheit 2.6: Wissensprüfung - Infrastructure as Code

Verwandte Themen: