Unidad 2.5: Aprovisionamiento de servicios de base de datos y streaming

Introducción

TaskBoard ahora cuenta con cómputo, red y almacenamiento en código. La aplicación aún necesita un lugar para mantener el estado. Las tareas, los tableros y los usuarios deben almacenarse en un almacén relacional con TLS y backups automatizados. Los datos de sesión y las rutas de lectura de alta frecuencia deben ubicarse en una caché en memoria. Los eventos de cambio de tareas que consume el servicio de trabajadores deben ubicarse en un flujo.

Esta unidad aprovisiona los tres como recursos de Terraform. Usted define el clúster de PostgreSQL (almacenamiento transaccional) y el conjunto de réplicas de In-Memory DB (caché de sesión y lectura) en los que TaskBoard depende, y luego ve el mismo patrón de aprovisionamiento aplicado a MongoDB, MariaDB y Kafka. La regla estricta que se aplica en todos los ejemplos: los motores relacionales (PostgreSQL, MariaDB) se ejecutan como un único primario escribible, sin réplicas de lectura legibles para escalar las lecturas; solo MongoDB Enterprise puede agregar secundarios legibles. Usted aprovisiona un clúster y escala las lecturas con la caché, no con la base de datos. Todos los ejemplos marcan las credenciales sensitive para que el material de conexión nunca aparezca en la salida del plan ni en los registros de CI.

1. Aprovisionamiento de PostgreSQL con Terraform

PostgreSQL es el sistema de registro de TaskBoard. El recurso ionoscloud_pg_cluster crea un clúster administrado: usted especifica la versión del motor, el número de instancias, el tamaño de los recursos, el almacenamiento, la conexión a la LAN, la ventana de mantenimiento y las credenciales iniciales. El aprovisionamiento es asíncrono, y un nuevo clúster puede tardar de 20 a 30 minutos en alcanzar AVAILABLE, ya que la plataforma aprovisiona nodos nuevos para cada instancia solicitada.

El clúster se adjunta a una LAN privada (el nivel de base de datos de la Unidad 2.2), por lo que nunca se expone directamente a internet. El puerto predeterminado es 5432 y no es configurable.

1.1 El recurso pg_cluster

Las versiones de PostgreSQL admitidas son 14, 15 y 16. Los tipos de almacenamiento son SSD Premium, SSD y HDD. El bloque connections vincula el clúster a una LAN existente y le asigna un CIDR dentro de esa LAN.

resource "ionoscloud_pg_cluster" "taskboard" {
  postgres_version = "16"
  instances        = 1
  cores            = 4
  ram              = 8192
  storage_size     = 50
  storage_type     = "SSD Premium"
  location         = ionoscloud_datacenter.taskboard.location
  display_name     = "taskboard-pg"

  connections {
    datacenter_id = ionoscloud_datacenter.taskboard.id
    lan_id        = ionoscloud_lan.db.id
    cidr          = "10.20.30.4/24"
  }

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

  credentials {
    username = "taskboard_admin"
    password = var.pg_admin_password
  }

  synchronization_mode = "ASYNCHRONOUS"
}

El valor de instances es el número total de nodos, no el número de réplicas de lectura. El rango admitido es de 1 a 5 instancias por clúster. Las instancias adicionales son standby de HA, no puntos finales desde los que su aplicación realiza lecturas. PostgreSQL admite dos modos de replicación: ASYNCHRONOUS (el predeterminado) y STRICTLY_SYNCHRONOUS. El modo síncrono estricto requiere un mínimo de 3 instancias. Para TaskBoard, usted aprovisiona un primario único (instances = 1) y escala las lecturas con In-Memory DB en la Sección 2.

1.2 Copias de seguridad, mantenimiento y fijación de versión

Managed PostgreSQL mantiene copias de seguridad automatizadas con una retención de 7 días de forma predeterminada y admite la recuperación en un punto en el tiempo dentro de esa ventana, pero en la API v2 la retención es configurable de 1 a 365 días mediante backup.retentionDays al momento de crear o actualizar el clúster. Tenga en cuenta que el Backup Service general no realiza copias de seguridad de bases de datos administradas, por lo que no planee apuntarlo al clúster. La recuperación consiste en PITR más sus propias volcados programados, cubierto en el Módulo 4.

Fije postgres_version de forma explícita en lugar de permitir que flote. Las actualizaciones mayores cambian el comportamiento y no es algo que desee que una diferencia de plan active de forma silenciosa.

variable "pg_admin_password" {
  type      = string
  sensitive = true
}

# Pass at apply time or via TF_VAR_pg_admin_password, never hardcode:
#   terraform apply -var="pg_admin_password=$(openssl rand -base64 24)"

El maintenance_window controla cuándo la plataforma aplica parches. Cada ventana tiene una duración máxima de 4 horas. Elija un intervalo de bajo tráfico para que la conmutación por error de alta disponibilidad durante la aplicación de parches se produzca fuera de las horas punta.

2. Aprovisionamiento de In-Memory DB para caché

TaskBoard utiliza In-Memory DB para el almacenamiento de sesiones y para la caché de listas de tareas. Dado que PostgreSQL no tiene réplicas legibles, la caché es la capa de escalado de lectura, no una optimización opcional. El recurso ionoscloud_inmemorydb_replicaset aprovisiona un conjunto de réplicas compatible con Redis. El motor es la versión estable 7.2 de Redis OSS y el puerto predeterminado es 6379.

In-Memory DB ahora expone dos versiones de API. La API v2 (versión 2.0.0), cuyo recurso principal es Cluster, está disponible de forma general (GA) y es la API recomendada para producción. La API v1 (versión 1.0.0), cuyo recurso principal es ReplicaSet, es la implementación heredada y tiene una obsolescencia anunciada para una próxima versión; la migración de v1 a v2 es iniciada por el cliente, no es automática, por lo que los clústeres existentes de v1 deben migrarse manualmente al recurso Cluster de v2 antes de que se elimine v1. Los ejemplos de Terraform a continuación aprovisionan el conjunto de réplicas de In-Memory DB, y el modelo de conexión que producen (motor, puerto, TLS, límite de conexión fijo) es el mismo independientemente de la versión de API que respalde el recurso. Para el nuevo desarrollo directo de API o SDK, diríjase a los puntos de acceso Cluster de v2.

El conjunto de réplicas consta de un nodo activo y n-1 nodos pasivos. Los nodos pasivos proporcionan conmutación por error, no un rendimiento de lectura adicional desde la perspectiva del cliente, ya que los clientes se conectan a través del punto de acceso activo.

2.1 El recurso inmemorydb_replicaset

Una restricción crítica: las credenciales se configuran solo en el momento de la creación. No puede cambiar la contraseña mediante una actualización posterior, por lo que genérela una vez y guárdela en un lugar donde su aplicación pueda leerla. El almacenamiento mínimo es de 10 GB por nodo. La política de expulsión predeterminada es allkeys-lru. El modo de persistencia predeterminado es None; la API acepta None, AOF, RDB y RDB_AOF.

resource "ionoscloud_inmemorydb_replicaset" "taskboard_cache" {
  display_name    = "taskboard-cache"
  location        = ionoscloud_datacenter.taskboard.location
  version         = "7.2"
  replicas        = 2
  persistence_mode = "RDB"
  eviction_policy  = "allkeys-lru"

  resources {
    cores = 2
    ram   = 4
  }

  connections {
    datacenter_id = ionoscloud_datacenter.taskboard.id
    lan_id        = ionoscloud_lan.db.id
    cidr          = "10.20.30.5/24"
  }

  credentials {
    username = "default"
    plain_text_password = var.cache_password
  }

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

2.2 TLS para la conexión de caché

El punto de acceso de la caché admite TLS, pero solo se cifra si habilita TLS en la instancia durante su creación; no está habilitado de forma predeterminada. Una vez habilitado, la autoridad de certificación es Let's Encrypt, por lo que un paquete de CA del sistema estándar valida la conexión sin que tenga que distribuir una raíz personalizada. Su cliente de Redis se conecta con TLS habilitado contra el punto de acceso activo:

import redis

# host comes from the Terraform output (Section 4); password set at creation
r = redis.Redis(
    host=cache_host,
    port=6379,
    username="default",
    password=cache_password,
    ssl=True,
    ssl_cert_reqs="required",
)
r.set("session:abc123", "user-42", ex=3600)

Dado que la contraseña no puede rotarse in situ, trate una rotación como un reemplazo: aprovisione un nuevo conjunto de réplicas, redirija el tráfico y luego destruya el conjunto anterior.

3. Aprovisionamiento de Kafka, MongoDB y MariaDB (mismo patrón)

PostgreSQL e In-Memory DB cubren las necesidades de TaskBoard, pero el patrón de aprovisionamiento se generaliza. Kafka, MongoDB y MariaDB siguen todos la misma estructura: un recurso de clúster, un bloque de conexiones vinculado a una LAN, una ventana de mantenimiento y credenciales, todo de forma asíncrona. A continuación se presentan los nombres de los recursos y las diferencias relevantes al utilizarlos.

3.1 Clústeres y temas de Kafka

El flujo de eventos de TaskBoard (eventos de cambio de tareas consumidos por el worker) se ejecuta en Kafka. El aprovisionamiento consta de dos recursos: el clúster y un recurso por cada tema. La versión de Kafka admitida es 4.0.0. Las versiones 3.9.0 y 3.9.1 están deprecadas; los clústeres existentes en esas versiones continúan funcionando, pero los nuevos clústeres deben utilizar 4.0.0. Un clúster ejecuta 3 brokers, e IONOS CLOUD recomienda (aunque no lo establece como valor predeterminado) un factor de replicación de 3 para los temas, lo que coincide con la configuración de 3 brokers. La autenticación es mTLS para el plano de datos y un token Bearer para la API de gestión. El cifrado en tránsito es TLS.

resource "ionoscloud_kafka_cluster" "events" {
  name    = "taskboard-events"
  version = "4.0.0"
  size    = "S"
  location = ionoscloud_datacenter.taskboard.location

  connections {
    datacenter_id   = ionoscloud_datacenter.taskboard.id
    lan_id          = ionoscloud_lan.app.id
    broker_addresses = ["10.20.20.10/24", "10.20.20.11/24", "10.20.20.12/24"]
  }
}

resource "ionoscloud_kafka_cluster_topic" "task_changes" {
  cluster_id          = ionoscloud_kafka_cluster.events.id
  location            = ionoscloud_kafka_cluster.events.location
  name                = "task-changes"
  number_of_partitions = 6
  replication_factor   = 3
  retention_time       = 604800000
}

La cantidad de particiones es el límite de paralelismo para los consumidores, por lo que debe dimensionarla según la expansión de consumidores que se espera (el Módulo 4 aborda la escalabilidad de los consumidores). El factor de replicación de 3 coincide con la topología de 3 brokers. Los certificados de cliente emitidos para mTLS son válidos por 365 días, por lo que planifique la rotación antes de que caduquen.

3.2 MongoDB y MariaDB

MongoDB utiliza ionoscloud_mongo_cluster. Las versiones admitidas son 6.0 y 7.0. La cadena de conexión sigue el formato mongodb+srv://m-<id>.mongodb.<region>.ionos.com, por lo que su controlador obtiene un registro SRV en lugar de una lista de hosts cruda.

MariaDB utiliza ionoscloud_mariadb_cluster. Solo admite versiones LTS, a partir de 10.6 (por ejemplo, 10.6, 10.11), el puerto predeterminado es 3306, y la replicación es solo asíncrona. La autoridad de certificación es Let's Encrypt.

resource "ionoscloud_mariadb_cluster" "reporting" {
  mariadb_version = "10.11"
  instances       = 1
  cores           = 2
  ram             = 4
  storage_size    = 20
  display_name    = "taskboard-reporting"
  location        = ionoscloud_datacenter.taskboard.location

  connections {
    datacenter_id = ionoscloud_datacenter.taskboard.id
    lan_id        = ionoscloud_lan.db.id
    cidr          = "10.20.30.6/24"
  }

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

  credentials {
    username = "reporting_admin"
    password = var.maria_password
  }
}

La tabla de decisión para qué motor aprovisionar:

Elija PostgreSQL o MariaDB para datos transaccionales relacionales, MongoDB para datos de documentos, In-Memory DB para caché y Kafka para flujos de eventos. Ninguno de los motores relacionales le ofrece réplicas legibles, por lo que la respuesta para escalar la lectura es siempre la caché.

4. Salidas de conexión y la restricción de primario único

La aprovisionación solo es útil si la aplicación puede conectarse. Terraform conoce el nombre DNS del clúster y las credenciales después de aplicar, por lo que debe exponerlos como salidas, marcando cada uno de ellos como sensitive para que no aparezcan en la salida del plan, en los registros de CI o en terraform output sin -raw.

4.1 Salidas sensibles

El clúster de PostgreSQL expone un nombre de host DNS estable, por ejemplo pg-010203.postgresql.de-fra.ionos.com, que su aplicación utiliza en lugar de una IP. Construya la cadena de conexión a partir del nombre DNS del clúster más las credenciales que haya proporcionado.

output "pg_connection_string" {
  value     = "postgresql://${ionoscloud_pg_cluster.taskboard.credentials[0].username}@${ionoscloud_pg_cluster.taskboard.dns_name}:5432/postgres?sslmode=require"
  sensitive = true
}

output "cache_host" {
  value     = ionoscloud_inmemorydb_replicaset.taskboard_cache.dns_name
  sensitive = true
}

output "kafka_broker_addresses" {
  value     = ionoscloud_kafka_cluster.events.connections[0].broker_addresses
  sensitive = true
}

El modo SSL predeterminado para PostgreSQL es prefer y no puede desactivarse desde el cliente, por lo que siempre debe configurar sslmode=require (o un modo más estricto) en el lado de la aplicación. El certificado raíz TLS para PostgreSQL es ISRG Root X1, el cual se encuentra en cualquier paquete de CA de un sistema moderno.

4.2 Por qué no hay réplica de lectura a la que apuntar

Esta es la restricción que invalida los planes de escalado simplistas. No existe una salida read_endpoint que crear, porque no hay réplica de lectura. El conjunto de réplicas de In-Memory DB consta de un nodo activo y n-1 nodos pasivos, y los pasivos son destinos de conmutación por error, no puntos de acceso de lectura. PostgreSQL instances > 1 le proporciona servidores de reserva de alta disponibilidad, no destinos de consultas.

# WRONG: there is no separate read endpoint to expose
# output "pg_read_endpoint" { value = ... }  # does not exist

# RIGHT: reads scale through the cache, writes go to the single primary
output "pg_primary_dns" {
  value     = ionoscloud_pg_cluster.taskboard.dns_name
  sensitive = true
}

Configure la aplicación de modo que cada escritura y cada lectura coherente se dirija a la instancia principal, y cada lectura frecuente pase por In-Memory DB mediante un patrón cache-aside. Dicha integración es el tema del Módulo 4, pero la decisión de aprovisionamiento se toma aquí: una instancia principal y una instancia de caché.

Tarjeta rápida de referencia de la API

Puntos finales de la API clave para el aprovisionamiento de bases de datos y streaming:

URL base (Cloud DBaaS): https://api.ionos.com/databases/postgresql In-Memory DB / Kafka: hosts específicos de región (por ejemplo, https://in-memory-db.de-fra.ionos.com) Autenticación: Authorization: Bearer <token> para las API de gestión; mTLS para el plano de datos de Kafka

Laboratorio de código

Objetivo: Desplegar la capa de base de datos de TaskBoard con Terraform: un clúster PostgreSQL con un único nodo primario y un conjunto de réplicas de In-Memory DB, y luego emitir sus detalles de conexión como valores sensibles.

Requisitos previos:

• Cuenta de IONOS CLOUD con token de API (IONOS_TOKEN exportado)
• Terraform >= 1.5 con el proveedor ionoscloud
• Un centro de datos y una LAN de base de datos existentes de las unidades 2.1 y 2.2

Paso 1: Declarar variables sensibles

variable "pg_admin_password" {
  type      = string
  sensitive = true
}
variable "cache_password" {
  type      = string
  sensitive = true
}

Paso 2: Agregar el clúster de PostgreSQL (de la sección 1.1), y luego validar:

terraform validate

Salida esperada:

Success! The configuration is valid.

Paso 3: Agregar el conjunto de réplicas de In-Memory DB (de la sección 2.1) y las salidas sensibles (de la sección 4.1). Luego, planifique:

terraform plan \
  -var="pg_admin_password=$(openssl rand -base64 24)" \
  -var="cache_password=$(openssl rand -base64 24)"

Salida esperada:

Plan: 2 to add, 0 to change, 0 to destroy.
Changes to Outputs:
  + cache_host           = (sensitive value)
  + pg_connection_string = (sensitive value)

Paso 4: Aplicar (el aprovisionamiento es asíncrono y puede tardar de 20 a 30 minutos para PostgreSQL):

terraform apply -auto-approve \
  -var="pg_admin_password=$PG_PW" \
  -var="cache_password=$CACHE_PW"

Salida esperada:

ionoscloud_pg_cluster.taskboard: Creation complete after 24m12s
ionoscloud_inmemorydb_replicaset.taskboard_cache: Creation complete after 6m41s
Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

Paso 5: Leer la cadena de conexión sensible (observe -raw, necesaria porque es sensible):

terraform output -raw pg_connection_string

Salida esperada:

postgresql://taskboard_admin@pg-010203.postgresql.de-fra.ionos.com:5432/postgres?sslmode=require

Paso 6: Verificar la conexión de PostgreSQL a través de TLS desde un host en la LAN de la base de datos:

psql "$(terraform output -raw pg_connection_string)" -c "SELECT version();"

Salida esperada:

PostgreSQL 16.x ...

Paso 7: Verificar la caché con una operación rápida de set/get sobre TLS:

redis-cli -h "$(terraform output -raw cache_host)" -p 6379 \
  --tls --user default -a "$CACHE_PW" PING

Salida esperada:

PONG

Lista de verificación:

• [ ] El clúster de PostgreSQL alcanzó AVAILABLE y acepta una conexión TLS
• [ ] El conjunto de réplicas de In-Memory DB responde a PING a través de TLS
• [ ] Todas las salidas de conexión están marcadas como confidenciales y requieren -raw para leerlas
• [ ] Ninguna contraseña aparece en la salida del plan ni en los registros de aplicación

Limpieza:

terraform destroy -auto-approve \
  -var="pg_admin_password=$PG_PW" \
  -var="cache_password=$CACHE_PW"

Errores comunes

1. Tratar las instancias del clúster como réplicas de solo lectura

   • Problema: Configura instances = 3 en el clúster de PostgreSQL e intenta enviar consultas de lectura a un segundo nodo para descargar la carga del nodo primario. Las conexiones siguen llegando todas al mismo punto de acceso con escritura, y nunca se logra la escalabilidad de lectura.
   • Por qué ocurre: Las bases de datos administradas de IONOS CLOUD ejecutan un único nodo primario con escritura. Las instancias adicionales son réplicas de alta disponibilidad (HA), no réplicas de solo lectura, y no existe un punto de acceso de lectura separado.
   • Solución: Provisione un nodo primario y dirija las lecturas de alta frecuencia a través de In-Memory DB:

   resource "ionoscloud_pg_cluster" "taskboard" {
     instances = 1   # single primary; cache handles read scaling
   }
   

2. Fuga de credenciales a través de las salidas de Terraform

   • Problema: Sus registros de CI imprimen la contraseña de la base de datos porque una salida no se marcó como sensible y terraform apply la reproduce en la ejecución.
   • Por qué ocurre: Las salidas son visibles por defecto. Cualquier cadena de conexión construida a partir de credenciales es texto plano a menos que se marque.
   • Solución: Marque cada salida que contenga credenciales como sensitive = true y lea con -raw solo cuando sea necesario:

   output "pg_connection_string" {
     value     = local.pg_conn
     sensitive = true
   }
   

3. Intentar cambiar la contraseña de In-Memory DB posteriormente

   • Problema: Se ejecuta una actualización para rotar la contraseña de la caché y la aplicación falla o el cambio se ignora.
   • Por qué ocurre: Las credenciales de In-Memory DB se configuran solo en el momento de la creación y no pueden modificarse después.
   • Solución: Considere la rotación como un reemplazo. Provisione un nuevo conjunto de réplicas, migre el tráfico y luego destruya el conjunto anterior. Genere la contraseña una sola vez en el momento de la creación:

   credentials {
     username            = "default"
     plain_text_password = var.cache_password  # set once, immutable
   }
   

Resumen

Ahora puede aprovisionar toda la capa de datos de TaskBoard como código: un clúster de PostgreSQL con un único nodo primario para transacciones, un conjunto de réplicas de In-Memory DB para sesiones y caché de lectura, y (utilizando el mismo patrón de recursos) Kafka, MongoDB o MariaDB cuando una carga de trabajo los requiera. Sabe cómo vincular cada clúster a una LAN privada, configurar una ventana de mantenimiento, proporcionar credenciales de forma segura y exponer los detalles de conexión como salidas sensibles de Terraform. Lo más importante es que aprovisiona en torno al modelo de un único nodo primario: un clúster escribible, con la escalabilidad de lecturas gestionada por la caché; los motores relacionales no ofrecen réplicas de lectura (MongoDB Enterprise sí puede, pero la capa de TaskBoard es relacional).

Puntos clave:

• ionoscloud_pg_cluster aprovisiona PostgreSQL (versiones 14, 15, 16; puerto 5432); instances son nodos de alta disponibilidad, no réplicas de lectura, y el rango es de 1 a 5
• ionoscloud_inmemorydb_replicaset aprovisiona Redis 7.2 en el puerto 6379; las credenciales se configuran solo en la creación y no se pueden cambiar in situ
• ionoscloud_kafka_cluster junto con ionoscloud_kafka_cluster_topic aprovisionan Kafka 4.0.0 con 3 brokers y factor de replicación 3; el plano de datos se autentica con mTLS
• Cada salida de conexión debe marcarse como sensitive; el modo SSL predeterminado de PostgreSQL es prefer y no se puede desactivar, por lo que la aplicación establece sslmode=require
• Los motores relacionales (PostgreSQL, MariaDB) no exponen réplicas de lectura legibles; MongoDB Enterprise admite hasta cinco secundarios legibles. Para la capa relacional de TaskBoard, aprovisione un único nodo primario y escale las lecturas a través de In-Memory DB

Terminología importante:

• Modelo de un único nodo primario: La restricción de aprovisionamiento que establece que los motores relacionales ejecutan un clúster escribible sin réplicas legibles; las lecturas escalan en la capa de caché. (MongoDB Enterprise es la excepción: puede agregar hasta cinco secundarios legibles.)
• Conjunto de réplicas (In-Memory DB): Un nodo activo más n-1 nodos pasivos de conmutación por error; los clientes se conectan a través del punto de acceso activo.
• Ventana de mantenimiento: Un intervalo semanal configurable (hasta 4 horas) en el que la plataforma aplica parches y puede provocar una conmutación por error de alta disponibilidad.
• Salida sensible: Una salida de Terraform marcada como sensitive = true para que se oculte en los registros de plan, apply y CI, y requiera -raw para leerse.
• Factor de replicación (Kafka): El número de copias de cada partición en los brokers; el valor predeterminado es 3, coincidiendo con el clúster de 3 brokers.

Próximos pasos

Continuar aprendiendo: Unidad 2.6: Verificación de conocimientos - Infraestructura como código

Temas relacionados:

• Unidad 2.4: Aprovisionamiento de almacenamiento como código
• Unidad 4.1: Integración de base de datos y caché