15 min de lecture

Objectifs d'apprentissage

À la fin de ce module, vous serez en mesure de:

  • Provisionner un cluster PostgreSQL avec `ionoscloud_pg_cluster_v2`, y compris la dimension des instances, le mode de réplication, les sauvegardes et la fenêtre de maintenance
  • Provisionner un cluster In-Memory DB avec `ionoscloud_inmemorydb_cluster_v2` pour le cache de session et de lecture de TaskBoard
  • Connecter les bases de données gérées à un LAN privé avec des adresses qui évitent les plages DHCP et réservées
  • Exposer les détails de connexion depuis Terraform en tant que sorties, tout en gardant les mots de passe hors de l'état
  • Appliquer le même schéma à `ionoscloud_mariadb_cluster_v2`, `ionoscloud_mongo_cluster` et `ionoscloud_kafka_cluster`

Unité 2.5 : Provisionnement des services de base de données et de streaming

Introduction

Les données transactionnelles de TaskBoard sont toujours stockées sur un volume Block Storage du serveur API. Vous souhaitez disposer d'un cluster PostgreSQL géré avec sauvegardes et basculement, ainsi que d'un cache placé en amont pour les sessions et les lectures fréquentes, sans avoir à exploiter vous-même l'un ou l'autre. Les deux doivent être créés depuis le même projet Terraform que le reste de la pile, afin que chaque environnement de branche dispose de sa propre couche de base de données.

Dans cette unité, vous provisionnez cette couche de base de données à l'aide du code. Vous dimensionnez et configurez le cluster PostgreSQL, le connectez au LAN privé de base de données de l'unité 2.2, ajoutez un cluster In-Memory DB, et sortez les détails de connexion dont votre application a besoin. MariaDB, MongoDB et Event Streams for Apache Kafka suivent le même schéma, et vous découvrez leurs noms de ressources et leurs principales différences. Dans le Code Lab, vous déployez la couche de base de données de TaskBoard et vous connectez aux deux clusters.

1. PostgreSQL avec 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"
  }
}

La ressource v2 communique avec l'API régionale PostgreSQL v2 qui correspond à location, et la modification de location détruit le cluster et en crée un nouveau. Dans instances, ram et storage_size sont exprimés en Go, contrairement aux Mo de ram d'un serveur.

1.1 Dimensionnement et réplication

instances.count est le nombre total d'instances : une instance principale et n-1 instances en attente. Un cluster comporte au maximum cinq instances, et IONOS CLOUD en recommande au moins trois pour la production. replication_mode est ASYNCHRONOUS ou STRICTLY_SYNCHRONOUS :

Mode Comportement Compromis
ASYNCHRONOUS L'instance principale n'attend pas qu'une instance en attente confirme une écriture Meilleure performance ; une petite quantité de données peut être perdue lors d'une bascule
STRICTLY_SYNCHRONOUS Chaque validation attend une instance en attente synchrone ; en l'absence d'instance en attente disponible, aucune écriture n'est acceptée Aucune perte de données lors d'une bascule ; sacrifie la disponibilité au profit de la durabilité

Comme le montre le tableau, STRICTLY_SYNCHRONOUS interrompt les écritures lorsqu'aucune instance en attente n'est disponible, il nécessite donc au moins trois instances. L'environnement de développement de TaskBoard utilise ASYNCHRONOUS.

Les instances en attente assurent la haute disponibilité : l'une prend le relais lorsque l'instance principale tombe en panne. Votre application se connecte via l'unique dns_name du cluster. Planifiez la mise à l'échelle des lectures avec le cache de la section 2, et non avec les instances en attente ; le module 4 construit cette couche de cache.

1.2 Sauvegardes, maintenance et versions

backup.location est l'emplacement Object Storage pour les sauvegardes et est immuable. Listez les valeurs valides avec GET /backup-locations de l'API PostgreSQL v2, par exemple eu-central-3. La rétention est de 7 jours par défaut, et vous pouvez restaurer à un instant donné dans la fenêtre de rétention via restore_from_backup. La maintenance_window est une fenêtre hebdomadaire de 4 heures ; sa time est en UTC.

Les versions majeures prises en charge sont 14, 15, 16, 17 et 18. Lisez les chaînes de version exactes pour votre emplacement à partir de la source de données :

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}"]
}

Vous ne pouvez effectuer une mise à niveau que vers une version supérieure ; les rétrogradations ne sont pas prises en charge.

1.3 Identifiants sans fuite d'état

credentials.password est en écriture seule : il n'est jamais stocké dans l'état Terraform et nécessite Terraform 1.11 ou une version ultérieure. Comme Terraform ne peut pas détecter une modification d'une valeur qu'il ne stocke pas, vous incrémentez password_version (par exemple de "1" à "2") chaque fois que vous effectuez une rotation du mot de passe. Lisez le mot de passe depuis votre coffre de secrets, et jamais depuis un fichier .tfvars dans Git :

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

Les noms d'utilisateur postgres, admin, root, sys, replication ainsi que les noms commençant par pg_ sont réservés. Choisissez donc un nom spécifique à l'application, tel que taskboard.

2. In-Memory DB avec ionoscloud_inmemorydb_cluster_v2

In-Memory DB v2 exécute Valkey, qui est compatible avec les clients Redis, en versions 9, 8.1 et 8.

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 Arguments spécifiques à la mise en cache

  • Empreinte du mot de passe : l'API n'accepte qu'une valeur SHA-256 pré-hachée, sous forme de chaîne hexadécimale minuscule de 64 caractères. La fonction sha256() de Terraform produit exactement cela, de sorte que le mot de passe en clair n'atteint jamais l'API ni l'état.
  • eviction_policy : obligatoire. allkeys-lru convient à un cache en lecture ; noeviction rejette les écritures lorsque la mémoire est pleine.
  • persistence_mode : None, AOF, RDB ou RDB_AOF. Un cache pur peut fonctionner sans persistance ; les sessions que vous ne souhaitez pas perdre après un redémarrage nécessitent RDB ou AOF.
  • instances : count de 1 à 5, ram de 4 à 240 Go. La RAM ne peut pas être réduite, et le stockage est dérivé de la RAM et du mode de persistance.
  • connections : seule une connexion est autorisée par cluster.

Consultez les chaînes de version disponibles avec la source de données ionoscloud_inmemorydb_versions_v2, de la même manière que pour PostgreSQL. Les clients se connectent avec redis-cli ou tout pilote compatible Redis, éventuellement via TLS, et le dns_name du cluster pointe vers son instance principale.

3. Placement réseau et sorties de connexion

3.1 Adresses dans le LAN de base de données

Chaque base de données gérée reçoit une adresse statique dans un LAN privé que vous définissez dans le code. Deux règles permettent de maintenir la sécurité de ces adresses :

  1. Les tirer de la plage réservée aux services gérés, de .2 à .9 (Unité 2.2, section 1.3). TaskBoard utilise .4 pour la passerelle NAT, .6 pour PostgreSQL et .7 pour le cache.
  2. Éviter les plages bloquées par DBaaS : 10.208.0.0/12, 10.233.0.0/18, 192.168.230.0/24 et 10.233.64.0/18.

Les clusters sont situés dans le LAN de base de données, de sorte que les serveurs d'application ont besoin d'une carte réseau dans ce LAN pour y accéder :

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
}

Ajoutez la même NIC avec 10.10.2.21 au worker. Les règles NSG de la couche DB de l'unité 2.3 autorisent ensuite ces deux adresses.

3.2 Sorties de l'application

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
}

L'URL ne contient délibérément aucun mot de passe : votre application le lit depuis le même magasin de secrets qui alimentait Terraform. Toutes les connexions client à PostgreSQL sont chiffrées avec TLS ; le mode SSL par défaut est prefer et les clients ne peuvent pas désactiver le chiffrement. Pour verify-ca ou verify-full, le client a besoin du certificat racine ISRG Root X1, car les certificats du serveur sont émis par Let's Encrypt pour le nom DNS du cluster. Les bibliothèques client doivent prendre en charge l'authentification SCRAM-SHA-256.

4. Références de même modèle : MariaDB, MongoDB et Kafka

Ces services partagent les éléments de base suivants : un emplacement, une connexion LAN privée et la dimensionnement. MariaDB et MongoDB acceptent également une fenêtre de maintenance, et MariaDB accepte des informations d'identification.

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 Différences clés
DBaaS for MariaDB ionoscloud_mariadb_cluster_v2 Port 3306 ; versions 10.6, 10.11, 11.4, 11.8 et 12.3 ; la réplication est uniquement asynchrone ; password est un argument sensible, nul dans l'état après importation
MongoDB ionoscloud_mongo_cluster edition (playground, business ou enterprise), mongodb_version (6.0 ou 7.0), les modifications de instances et connections forcent la recréation ; connections.cidr_list prend la liste des IP avec sous-réseau pour le cluster ; le connection_string calculé utilise mongodb+srv
Event Streams for Apache Kafka ionoscloud_kafka_cluster, ionoscloud_kafka_cluster_topic size au lieu du dimensionnement des instances ; trois brokers dont le broker_addresses que vous définissez dans le LAN ; authentification mTLS avec des certificats clients valides pendant 365 jours ; sujets définis replication_factor et number_of_partitions

Comme le montre le tableau, la structure est la même, mais les règles de recréation et l'authentification diffèrent. Vérifiez le RequiresReplace et les notes « forces re-creation » avant de modifier un argument sur un cluster en production.

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
}

Un facteur de réplication de 3 est la valeur par défaut et la valeur recommandée. Les adresses des brokers doivent éviter 10.224.0.0/11. Vos clients récupèrent leurs certificats et leur clé depuis GET /clusters/{clusterId}/users/{userId}/access ; l'unité 4.3 aborde le côté client.

Fiche de référence rapide de l'API

Principaux points de terminaison d'API derrière les ressources de cette unité :

Méthode Point de terminaison Description
POST /clusters Créé par ionoscloud_pg_cluster_v2 (API PostgreSQL v2, https://postgresql.de-txl.ionos.com/v2)
GET /backup-locations Énumère les valeurs valides de backup.location (API PostgreSQL v2)
GET /versions Énumère les versions disponibles (API PostgreSQL v2 et In-Memory DB v2)
POST /clusters Créé par ionoscloud_inmemorydb_cluster_v2 (API In-Memory DB v2, https://in-memory-db.de-txl.ionos.com/v2)
GET /clusters/{clusterId}/users/{userId}/access Certificats et clé du client Kafka (API Kafka)

URL de base : régionale par service, par exemple https://postgresql.de-txl.ionos.com/v2 Authentification : Authorization: Bearer <token>

Atelier de code

Objectif : Déployer la couche de base de données de TaskBoard avec Terraform (un cluster PostgreSQL et un cluster In-Memory DB dans le LAN de la base de données), afficher les détails de connexion et se connecter aux deux depuis le serveur API.

Prérequis :

  • Le projet des Unités 2.1 à 2.4, appliqué, avec IONOS_TOKEN défini et Terraform 1.11 ou une version ultérieure
  • Deux mots de passe dans votre coffre de secrets, exportés en tant que TF_VAR_pg_password et TF_VAR_cache_password
  • psql et redis-cli (ou valkey-cli) sur le serveur API

Étape 1 : Lister les versions disponibles

Ajoutez la source de données ionoscloud_pg_versions_v2 et la sortie de la section 1.2, ainsi que le même modèle pour ionoscloud_inmemorydb_versions_v2 (son attribut de liste est items).

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

Sortie attendue :

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

Étape 2 : Définir les versions et l'emplacement de sauvegarde

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" }

Sortie attendue :

(file saved)

Étape 3 : Ajouter les clusters, les NIC et les sorties

Ajoutez le cluster PostgreSQL (section 1), le cache (section 2), la NIC api_db et la NIC de base de données du worker (section 3.1), ainsi que les sorties (section 3.2). Appliquez ensuite :

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

Sortie attendue :

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

La création d'un cluster prend plusieurs minutes ; le fournisseur attend jusqu'à l'expiration des délais d'attente des ressources.

Étape 4 : Se connecter à PostgreSQL depuis le serveur API

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();'"

Sortie attendue :

 PostgreSQL 17...
(1 row)

Étape 5 : Connexion au cache

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"

Sortie attendue :

PONG

Liste de contrôle de validation :

  • [ ] terraform apply a créé les deux clusters et les deux NIC DB-LAN
  • [ ] psql se connecte via TLS au nom DNS du cluster
  • [ ] Le cache répond à PONG avec l'utilisateur configuré
  • [ ] terraform state show ionoscloud_pg_cluster_v2.taskboard n'affiche aucun mot de passe

Nettoyage :

terraform destroy -auto-approve

Erreurs courantes

Erreurs de développement à éviter concernant le sujet de cette unité :

  1. Adresse principale dans une plage bloquée ou DHCP

    • Problème : La création du Cluster échoue, ou la base de données entre en collision avec l'adresse d'un serveur.
    • Pourquoi cela se produit : L'adresse se situe dans une plage bloquée par DBaaS, ou en dehors de la plage de services gérés allant de .2 à .9, où DHCP pourrait l'attribuer à une carte réseau.
    • Correction : Planifiez toutes les adresses des services gérés par LAN dans une seule carte locals, de .2 à .9, en dehors des plages bloquées (section 3.1).
  2. Rotation de mot de passe qui n'a jamais lieu

    • Problème : Vous modifiez TF_VAR_pg_password, terraform plan n'affiche aucune modification, et l'ancien mot de passe fonctionne toujours.
    • Pourquoi cela se produit : Le mot de passe est en écriture seule et n'est pas stocké dans l'état, si bien que Terraform ne peut pas détecter qu'il a changé.
    • Correction : Incrémentez credentials.password_version en même temps que le nouveau mot de passe.
  3. Connexions qui se rompent lors d'une bascule

    • Problème : Après une maintenance ou une bascule, l'API journalise des erreurs de connexion jusqu'à son redémarrage.
    • Pourquoi cela se produit : Lors d'une bascule, le client doit se reconnecter. En cas d'échec non contrôlé, la connexion peut ne pas être fermée proprement.
    • Correction : Reconnectez-vous avec un retour exponentiel, en commençant par une nouvelle tentative immédiate, et utilisez un pool de connexions qui valide les connexions.

Résumé

Vous pouvez désormais provisionner la couche de base de données de TaskBoard en tant que code. Le cluster PostgreSQL v2 comporte une instance principale et des instances en attente pour la bascule, un mode de réplication que vous choisissez délibérément, des sauvegardes dans un emplacement Object Storage, et un mot de passe en écriture seule qui n'apparaît jamais dans l'état. Le cluster In-Memory DB exécute Valkey avec un mot de passe haché en SHA-256 et une politique d'éviction adaptée à un cache. Les deux se connectent au LAN privé de la base de données sur des adresses issues de la plage des services managés, et votre application obtient leurs noms DNS à partir des sorties Terraform.

Points clés :

  • Utilisez les ressources v2 ionoscloud_pg_cluster_v2, ionoscloud_inmemorydb_cluster_v2 et ionoscloud_mariadb_cluster_v2
  • Un cluster PostgreSQL comporte jusqu'à cinq instances : une instance principale et n-1 instances en attente pour la haute disponibilité
  • Les connexions PostgreSQL sont toujours chiffrées en TLS ; utilisez ISRG Root X1 pour verify-full
  • Gardez les mots de passe hors de l'état : en écriture seule pour PostgreSQL, hachés sha256() pour In-Memory DB
  • Attribuez aux bases de données managées des adresses statiques de .2 à .9 et évitez les plages bloquées de DBaaS

Terminologie importante :

  • Instance en attente : Une instance PostgreSQL qui réplique l'instance principale et prend le relais lors d'une bascule
  • Mode de réplication : ASYNCHRONOUS ou STRICTLY_SYNCHRONOUS, le compromis entre la vitesse d'écriture et la durabilité
  • Argument en écriture seule : Un argument Terraform envoyé à l'API mais jamais stocké dans l'état, tel que le mot de passe PostgreSQL
  • Politique d'éviction : La règle qui détermine quelles clés In-Memory DB supprime lorsque la mémoire est pleine
  • Adresse de l'instance principale : L'IP statique et le masque de réseau qu'une base de données managée reçoit dans votre LAN privé

Prochaines étapes

Continuer l'apprentissage : Unité 2.6 : Vérification des connaissances - Infrastructure as Code

Sujets connexes :