Unidad 2.5: Aprovisionamiento de servicios de base de datos y streaming
Introducción
Los datos transaccionales de TaskBoard siguen almacenándose en un volumen de Block Storage del servidor de la API. Desea un clúster gestionado de PostgreSQL con copias de seguridad y conmutación por error, y un cache delante de este para sesiones y lecturas frecuentes, sin tener que operar ninguno de los dos por su cuenta. Ambos deben crearse desde el mismo proyecto de Terraform que el resto de la pila, de modo que cada entorno de rama disponga de su propia capa de base de datos.
En esta unidad, provisiona esa capa de base de datos como código. Dimensiona y configura el clúster de PostgreSQL, lo conecta a la LAN privada de base de datos de la Unidad 2.2, añade un clúster de In-Memory DB y genera como salida los detalles de conexión que su aplicación necesita. MariaDB, MongoDB y Event Streams for Apache Kafka siguen el mismo patrón, y puede ver sus nombres de recursos y las diferencias clave. En el Code Lab, despliega la capa de base de datos de TaskBoard y se conecta a ambos clústeres.
1. PostgreSQL con 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"
}
}
El recurso v2 se comunica con la API regional de PostgreSQL v2 que coincide con location, y cambiar location destruye el clúster y crea uno nuevo. En instances, ram y storage_size están en GB, a diferencia de los MB de ram de un servidor.
1.1 Dimensionamiento y replicación
instances.count es el número total de instancias: una primaria y n-1 en espera. Un clúster tiene un máximo de cinco instancias, e IONOS CLOUD recomienda al menos tres para producción. replication_mode es ASYNCHRONOUS o STRICTLY_SYNCHRONOUS:
| Modo | Comportamiento | Compensación |
|---|---|---|
ASYNCHRONOUS |
La primaria no espera a que un servidor en espera confirme una escritura | Mejor rendimiento; se puede perder una pequeña cantidad de datos durante el conmutado por error |
STRICTLY_SYNCHRONOUS |
Cada confirmación espera a un servidor en espera síncrono; si no hay ningún servidor en espera disponible, no se aceptan escrituras | Sin pérdida de datos durante el conmutado por error; sacrifica la disponibilidad a cambio de la durabilidad |
Como muestra la tabla, STRICTLY_SYNCHRONOUS detiene las escrituras cuando no hay ningún servidor en espera disponible, por lo que requiere al menos tres instancias. El entorno de desarrollo de TaskBoard utiliza ASYNCHRONOUS.
Las instancias en espera sirven para la alta disponibilidad: una asume el control cuando la primaria falla. Su aplicación se conecta a través del único dns_name del clúster. Planifique la escalabilidad de lecturas con la caché de la Sección 2, no con los servidores en espera; el Módulo 4 construye esa capa de caché.
1.2 Copias de seguridad, mantenimiento y versiones
backup.location es la ubicación de Object Storage para las copias de seguridad y es inmutable. Enumere los valores válidos con GET /backup-locations de la API de PostgreSQL v2, por ejemplo eu-central-3. La retención predeterminada es de 7 días, y puede restaurar a un punto en el tiempo dentro de la ventana de retención a través de restore_from_backup. El maintenance_window es una ventana semanal de 4 horas; su time está en UTC.
Las versiones principales admitidas son 14, 15, 16, 17 y 18. Lea las cadenas de versión exactas para su ubicación desde la fuente de datos:
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}"]
}
Solo puede actualizarse a una versión superior; no se admiten las degradaciones.
1.3 Credenciales sin fugas de estado
credentials.password es solo de escritura: nunca se almacena en el estado de Terraform y requiere Terraform 1.11 o posterior. Dado que Terraform no puede detectar un cambio en un valor que no almacena, debe incrementar password_version (por ejemplo, de "1" a "2") cada vez que rote la contraseña. Lea la contraseña desde su almacén de secretos, nunca desde un archivo .tfvars en Git:
variable "pg_password" {
type = string
sensitive = true
ephemeral = true
}
export TF_VAR_pg_password="$(vault kv get -field=pg_password secret/taskboard/dev)"
Los nombres de usuario postgres, admin, root, sys, replication y los nombres que comienzan con pg_ están reservados, por lo que debe elegir un nombre específico de la aplicación, como taskboard.
2. In-Memory DB con ionoscloud_inmemorydb_cluster_v2
In-Memory DB v2 ejecuta Valkey, que es compatible con clientes de Redis, en las versiones 9, 8.1 y 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 Argumentos específicos de caché
- Hash de contraseña: la API solo acepta un valor SHA-256 previamente hasheado como una cadena hexadecimal de 64 caracteres en minúsculas. La función
sha256()de Terraform produce exactamente eso, por lo que la contraseña en texto plano nunca llega a la API ni al estado. eviction_policy: obligatorio.allkeys-lrues adecuado para una caché de lectura;noevictionrechaza las escrituras cuando la memoria está llena.persistence_mode:None,AOF,RDBoRDB_AOF. Una caché pura puede funcionar sin persistencia; las sesiones que no desea perder tras un reinicio requierenRDBoAOF.instances:countde 1 a 5,ramde 4 a 240 GB. La RAM no puede degradarse, y el almacenamiento se deriva de la RAM y del modo de persistencia.connections: solo se permite una conexión por clúster.
Lea las cadenas de versión disponibles con la fuente de datos ionoscloud_inmemorydb_versions_v2, de la misma manera que para PostgreSQL. Los clientes se conectan con redis-cli o con cualquier controlador compatible con Redis, opcionalmente a través de TLS, y el dns_name del clúster apunta a su instancia principal.
3. Colocación de red y salidas de conexión
3.1 Direcciones en la LAN de BD
Cada base de datos administrada obtiene una dirección estática en una LAN privada que usted elige en el código. Dos reglas mantienen seguras estas direcciones:
- Obténgalas del rango reservado para servicios administrados, desde
.2hasta.9(Unidad 2.2, Sección 1.3). TaskBoard utiliza.4para la pasarela NAT,.6para PostgreSQL y.7para la caché. - Evite los rangos que DBaaS bloquea:
10.208.0.0/12,10.233.0.0/18,192.168.230.0/24y10.233.64.0/18.
Los clústeres se encuentran en la LAN de BD, por lo que los servidores de la aplicación necesitan una NIC en esa LAN para alcanzarlos:
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
}
Agregue la misma NIC con 10.10.2.21 al worker. Las reglas del NSG de la capa de BD de la Unidad 2.3 admiten entonces estas dos direcciones.
3.2 Salidas para la aplicación
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
}
La URL no contiene deliberadamente una contraseña: su aplicación la lee del mismo almacén de secretos que alimentó a Terraform. Todas las conexiones de cliente a PostgreSQL se cifran con TLS; el modo SSL predeterminado es prefer y los clientes no pueden deshabilitar el cifrado. Para verify-ca o verify-full, el cliente necesita el certificado raíz ISRG Root X1, porque los certificados del servidor se emiten mediante Let's Encrypt para el nombre de DNS del clúster. Las bibliotecas de cliente deben admitir la autenticación SCRAM-SHA-256.
4. Referencias con el mismo patrón: MariaDB, MongoDB y Kafka
Estos servicios comparten los bloques de construcción básicos: una ubicación, una conexión privada de LAN y el dimensionamiento. MariaDB y MongoDB también requieren una ventana de mantenimiento, y MariaDB requiere credenciales.
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" }
}
| Servicio | Recurso | Diferencias clave |
|---|---|---|
| DBaaS for MariaDB | ionoscloud_mariadb_cluster_v2 |
Puerto 3306; versiones 10.6, 10.11, 11.4, 11.8 y 12.3; la replicación es solo asíncrona; password es un argumento sensible, nulo en el estado después de la importación |
| MongoDB | ionoscloud_mongo_cluster |
edition (playground, business o enterprise), mongodb_version (6.0 o 7.0), los cambios en instances y connections fuerzan la recreación; connections.cidr_list toma la lista de IPs con subred para el clúster; el connection_string calculado usa mongodb+srv |
| Event Streams for Apache Kafka | ionoscloud_kafka_cluster, ionoscloud_kafka_cluster_topic |
size en lugar del dimensionamiento de instancias; tres brokers cuyo broker_addresses usted configura en la LAN; autenticación mTLS con certificados de cliente válidos por 365 días; temas configurados con replication_factor y number_of_partitions |
Como muestra la tabla, la estructura es la misma, pero las reglas de recreación y la autenticación difieren. Revise el RequiresReplace y las notas de "fuerza la recreación" antes de modificar un argumento en un clúster en producción.
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 factor de replicación de 3 es el valor predeterminado y el valor recomendado. Las direcciones de los brokers deben evitar 10.224.0.0/11. Sus clientes obtienen sus certificados y clave desde GET /clusters/{clusterId}/users/{userId}/access; la Unidad 4.3 cubre el lado del cliente.
Tarjeta rápida de referencia de la API
Endpoints principales de la API detrás de los recursos de esta unidad:
| Método | Endpoint | Descripción |
|---|---|---|
POST |
/clusters |
Creado por ionoscloud_pg_cluster_v2 (API de PostgreSQL v2, https://postgresql.de-txl.ionos.com/v2) |
GET |
/backup-locations |
Lista los valores válidos de backup.location (API de PostgreSQL v2) |
GET |
/versions |
Lista las versiones disponibles (APIs de PostgreSQL v2 e In-Memory DB v2) |
POST |
/clusters |
Creado por ionoscloud_inmemorydb_cluster_v2 (API de In-Memory DB v2, https://in-memory-db.de-txl.ionos.com/v2) |
GET |
/clusters/{clusterId}/users/{userId}/access |
Certificados del cliente y clave de Kafka (API de Kafka) |
URL base: regional por servicio, por ejemplo https://postgresql.de-txl.ionos.com/v2
Autenticación: Authorization: Bearer <token>
Laboratorio de código
Objetivo: Desplegar la capa de base de datos de TaskBoard con Terraform (un clúster de PostgreSQL y un clúster de In-Memory DB en la LAN de BD), mostrar los detalles de conexión y conectarse a ambos desde el servidor de API.
Requisitos previos:
- El proyecto de las unidades 2.1 a 2.4, aplicado, con
IONOS_TOKENconfigurado y Terraform 1.11 o posterior - Dos contraseñas en su almacén de secretos, exportadas como
TF_VAR_pg_passwordyTF_VAR_cache_password psqlyredis-cli(ovalkey-cli) en el servidor de API
Paso 1: Listar las versiones disponibles
Agregue la fuente de datos ionoscloud_pg_versions_v2 y la salida de la sección 1.2, además del mismo patrón para ionoscloud_inmemorydb_versions_v2 (su atributo de lista es items).
terraform apply -auto-approve -target=data.ionoscloud_pg_versions_v2.available >/dev/null
terraform output pg_versions
Salida esperada:
[
"14 ...",
...
"18 ..."
]
Paso 2: Establecer las versiones y la ubicación de la copia de seguridad
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" }
Salida esperada:
(file saved)
Paso 3: Agregar los clústeres, las NIC y las salidas
Agregue el clúster de PostgreSQL (sección 1), la caché (sección 2), la NIC api_db y la NIC de BD del worker (sección 3.1), y las salidas (sección 3.2). Luego, aplique:
terraform apply -auto-approve | grep "Apply complete"
terraform output -raw pg_host; echo
Salida esperada:
Apply complete! Resources: 4 added, 0 changed, 0 destroyed.
pg-<id>.postgresql.de-txl.ionos.com
La creación del clúster tarda varios minutos; el proveedor espera hasta los límites de tiempo de los recursos.
Paso 4: Conectar a PostgreSQL desde el servidor de 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();'"
Salida esperada:
PostgreSQL 17...
(1 row)
Paso 5: Conectar a la caché
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"
Salida esperada:
PONG
Lista de verificación de validación:
- [ ]
terraform applycreó ambos clústeres y las dos NIC de DB-LAN - [ ]
psqlse conecta mediante TLS al nombre de DNS del clúster - [ ] La caché responde a
PONGcon el usuario configurado - [ ]
terraform state show ionoscloud_pg_cluster_v2.taskboardno muestra ninguna contraseña
Limpieza:
terraform destroy -auto-approve
Errores comunes
Errores de desarrollo a evitar con el tema de esta unidad:
-
Dirección primaria en un rango bloqueado o de DHCP
- Problema: La creación del Cluster falla, o la base de datos colisiona con la dirección de un servidor.
- Por qué ocurre: La dirección se encuentra en un rango que DBaaS bloquea, o fuera del rango de servicios administrados de
.2a.9, donde DHCP podría asignarla a una NIC. - Solución: Planifique todas las direcciones de servicios administrados por LAN en un solo mapa
locals, desde.2hasta.9, fuera de los rangos bloqueados (Sección 3.1).
-
Rotación de contraseñas que nunca se realiza
- Problema: Usted cambia
TF_VAR_pg_password,terraform planno muestra cambios, y la contraseña antigua sigue funcionando. - Por qué ocurre: La contraseña es de solo escritura y no se almacena en el estado, por lo que Terraform no puede ver que se haya cambiado.
- Solución: Incremente
credentials.password_versionjunto con la nueva contraseña.
- Problema: Usted cambia
-
Conexiones que se interrumpen durante el failover
- Problema: Después del mantenimiento o de un failover, la API registra errores de conexión hasta que se reinicia.
- Por qué ocurre: Durante un failover, el cliente debe reconectarse. En una falla no controlada, la conexión puede no cerrarse de forma limpia.
- Solución: Reconecte con un back-off exponencial, comenzando con un reintento inmediato, y utilice un pool de conexiones que valide las conexiones.
Resumen
Ahora puede aprovisionar la capa de base de datos de TaskBoard como código. El clúster PostgreSQL v2 cuenta con un nodo primario y nodos en espera para el conmutado por error, un modo de replicación que usted elige deliberadamente, copias de seguridad en una ubicación de Object Storage y una contraseña de solo escritura que nunca se guarda en el estado. El clúster In-Memory DB ejecuta Valkey con una contraseña con hash SHA-256 y una política de expulsión adecuada para una caché. Ambos se conectan a la LAN privada de bases de datos en direcciones del rango de managed-services, y su aplicación obtiene sus nombres de DNS de las salidas de Terraform.
Puntos clave:
- Utilice los recursos v2
ionoscloud_pg_cluster_v2,ionoscloud_inmemorydb_cluster_v2yionoscloud_mariadb_cluster_v2 - Un clúster PostgreSQL tiene hasta cinco instancias: una primaria y n-1 en espera para alta disponibilidad
- Las conexiones a PostgreSQL siempre están cifradas con TLS; use ISRG Root X1 para
verify-full - Mantenga las contraseñas fuera del estado: de solo escritura para PostgreSQL, hashes
sha256()para In-Memory DB - Asigne a las bases de datos administradas direcciones estáticas desde
.2hasta.9y evite los rangos bloqueados de DBaaS
Terminología importante:
- Instancia en espera: Una instancia de PostgreSQL que replica el nodo primario y asume el control en caso de conmutación por error
- Modo de replicación:
ASYNCHRONOUSoSTRICTLY_SYNCHRONOUS, el equilibrio entre velocidad de escritura y durabilidad - Argumento de solo escritura: Un argumento de Terraform enviado a la API pero que nunca se almacena en el estado, como la contraseña de PostgreSQL
- Política de expulsión: La regla que determina qué claves elimina In-Memory DB cuando la memoria está llena
- Dirección de la instancia primaria: La IP y la máscara de red estáticas que una base de datos administrada obtiene en su LAN privada
Próximos pasos
Siga aprendiendo: Unidad 2.6: Evaluación de conocimientos - Infraestructura como código
Temas relacionados: