Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Una base de datos gestionada y el servicio que la lee, en Terraform y CloudFormation

Un Aggregate contiene una base de datos PostgreSQL y el servidor que la lee. El mismo Aggregate se compila de tres maneras para AWS: como una única configuración raíz de Terraform, con la base de datos aprovisionada por el módulo RDS publicado del proyecto terraform-aws-modules y el servidor ejecutado como un servicio de Amazon ECS en Fargate; como un único stack de CloudFormation que contiene ambos; y como dos stacks de CloudFormation, la base de datos en uno y el servidor en el otro.

En cada destino, el servidor recibe la dirección de la base de datos en la forma que ese destino resuelve por sí mismo: una referencia a una salida de módulo en la configuración raíz, un Fn::GetAtt dentro de un único stack, un Fn::ImportValue entre dos. El compilador no evalúa ninguna de ellas. La dirección no existe hasta que se crea la instancia, así que la compilación canaliza una referencia sin resolverla y el destino la resuelve cuando despliega.

Los bloques de salida de esta página están copiados de una ejecución real, según Leer la salida en estas páginas.

Archivos

  • aggregate.yaml — intención del desarrollador: un componente db de tipo core/datastore/postgres con una base de datos lógica orders cuyo propietario es el rol orders_admin, y un componente api de tipo core/compute/server que lo usa. Ninguna clave ni valor que contiene trata de AWS.
  • manifest-terraform.yaml — enlaza la base de datos con la Recipe terraform/postgres-rds-terraform-aws-modules, el servidor con terraform/server-ecs y la Feature core/backup con terraform/backup-native.
  • manifest-cloudformation.yaml — enlaza la base de datos con cloudformation/postgres-rds, el servidor con cloudformation/server-ecs y la Feature core/backup con cloudformation/backup-native.
  • release-terraform.yaml — ambos componentes en un único límite, compilados mediante el Manifest de Terraform.
  • release-one-stack.yaml — ambos componentes en un único límite, compilados mediante el Manifest de CloudFormation, así que ambos se ensamblan en un único stack.
  • release-two-stacks.yaml — la misma intención dividida en dos límites, así que la referencia del servidor a la base de datos cruza un borde de stack.
  • .aggrega-config.yaml — nombra el registro del hub desde el que se resuelve el catálogo de la biblioteca estándar.

Todas las entidades que usa este ejemplo residen en ese catálogo. No se copia nada junto a los archivos de release.

Lo que pide el servidor

El servidor declara una arista, en un socket al que llama database, y pide cuatro de las entradas que publica la base de datos, con los nombres de variable de entorno que lee su propia configuración:

api:
type: core/compute/server
uses:
database:
db:
target: db
inject:
env:
- in: DB_HOST
from: host
- in: DB_PORT
from: port
- in: DB_USER
from: user
- in: DB_NAME
from: database

core/compute/server no declara ningún socket propio, así que database es uno ad hoc: la arista no lleva ningún selector ni ninguna lista de permitidos de inject, y cada clave from: debe seguir siendo una que publica la base de datos — consulta adhoc-uses-socket para ese contrato. El Aggregate nunca nombra una dirección, un número de puerto ni un proveedor de nube, y es el mismo archivo para las tres compilaciones de abajo.

Lo que aporta el operador

Cada Release nombra, bajo infra.overrides, cosas que el operador ya ejecuta y que leen las Recipes: el grupo de subredes de base de datos de RDS y los grupos de seguridad de la base de datos, y el clúster de ECS, las subredes y los grupos de seguridad a los que se conectan las tareas, y el rol de ejecución con el que ECS descarga la imagen y escribe los registros. La imagen del servidor es infra.image. Ambas Recipes del servidor requieren la imagen, el clúster, las subredes, los grupos de seguridad y el rol de ejecución, y la Recipe de Terraform de la base de datos requiere el grupo de subredes: una compilación a la que le falta alguno se detiene, nombrando la clave, en lugar de elegir una red o un rol por ti.

Cada uno de esos valores es un marcador de posición — 123456789012 es el número de cuenta que la documentación de AWS usa en los ejemplos, y example-cluster, example-private-db-subnets, los ID subnet-… y sg-…, el rol y registry.example.com/orders-api:1.0.0 representan recursos de tu propia cuenta. La compilación los acepta porque nunca los consulta; sustitúyelos antes de planificar o desplegar.

Las Recipes de Terraform leen sus claves con la grafía terraform del catálogo (subnet_group, subnet_ids, vpc_security_groups, cluster, execution_role_arn); las Recipes de CloudFormation las leen con los nombres propios de las propiedades de los recursos (DBSubnetGroupName, VPCSecurityGroups, Cluster, Subnets, SecurityGroups, ExecutionRoleArn), así que los mismos valores del operador se escriben de forma distinta en los dos destinos.

Generar el ejemplo

Puedes compilar este ejemplo con los comandos de abajo, o hacer que tu asistente de IA lo compile por ti.

Escribe el ejemplo en una carpeta nueva con su nombre:

Terminal window
aggrega scaffold --example aws-rds-and-ecs-service

Después imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:

Terminal window
cd aws-rds-and-ecs-service

Compilación

Este ejemplo incluye tres releases, así que nombra la que quieras. Se compila una release por ejecución. En una copia recién hecha, pasa --auto-pull la primera vez que se compila cada release, para que su lockfile se rellene durante la compilación. La primera compilación de Terraform obtiene el módulo RDS de su repositorio git, en el commit que registra la fijación propia de la Recipe:

Terminal window
aggrega build --release release-terraform.yaml --auto-pull

Imprime, con <workspace> en lugar de la carpeta de este ejemplo:

Pull complete: release-terraform.lock (entities=11, source_artifacts=1, external_inputs=0)
Total build time: 9.4s
Build completed: 151 files written to <workspace>/dist

Una vez que existe el lockfile, el comando simple compila contra él:

Terminal window
aggrega build --release release-terraform.yaml
Total build time: 5.7s
Build completed: 151 files written to <workspace>/dist

Con un asistente de IA

Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pégale este prompt.

Usa solo las herramientas de Aggrega y no crees ninguna carpeta tú mismo. Si la carpeta del espacio de trabajo aún no contiene una carpeta `aws-rds-and-ecs-service`, llama una sola vez a la herramienta `scaffold` con `example` establecido en `aws-rds-and-ecs-service` y sin `dir`: escribe el ejemplo en una nueva carpeta `aws-rds-and-ecs-service`. Después llama a la herramienta `build` con `workspace_root` establecido en `aws-rds-and-ecs-service`, `release` establecido en `release-terraform.yaml`, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió la compilación; están en `aws-rds-and-ecs-service/dist/`.

Una única configuración raíz de Terraform

La configuración raíz del límite queda en dist/one-root/terraform/aggrega.modules.tf, y los archivos propios de cada componente están en el directorio al que apunta su bloque module: el módulo RDS copiado localmente en modules/db/, y el módulo ECS del servidor, guardado junto a su Recipe en el catálogo, en modules/api/. La configuración raíz completa:

# Root configuration for this boundary. Each component rendered here is one
# module block below, and the directory that block points at holds that
# component's own files. One configuration means one dependency graph, which is
# what lets a reference or a depends_on reach from one component to another.
module "api" {
source = "./modules/api"
assign_public_ip = false
cluster = "example-cluster"
cpu = "256"
desired_count = 2
environment = {"DB_HOST":"${module.db.db_instance_address}","DB_NAME":"orders","DB_PORT":"5432","DB_USER":"orders_admin"}
execution_role_arn = "arn:aws:iam::123456789012:role/example-ecs-task-execution"
image = "registry.example.com/orders-api:1.0.0"
memory = "512"
name = "api"
port = 8080
security_groups = ["sg-0fedcba9876543210"]
subnet_ids = ["subnet-0123456789abcdef0","subnet-0fedcba9876543210"]
}
module "db" {
source = "./modules/db"
allocated_storage = 50
backup_retention_period = 14
create_db_subnet_group = false
db_name = "orders"
db_subnet_group_name = "example-private-db-subnets"
engine = "postgres"
engine_version = "16"
family = "postgres16"
identifier = "db"
instance_class = "db.t3.small"
manage_master_user_password = true
multi_az = true
port = "5432"
skip_final_snapshot = false
storage_type = "gp3"
username = "orders_admin"
vpc_security_group_ids = ["sg-0123456789abcdef0"]
}

El argumento environment del servidor lleva los cuatro valores que pidió la arista. DB_HOST es ${module.db.db_instance_address}: la Recipe de la base de datos publica una referencia a la salida db_instance_address propia del módulo RDS a través de la llamada de módulo que esta misma raíz declara como module "db", así que Terraform la evalúa aquí, en tiempo de plan y apply, y el módulo del servidor recibe la dirección de la instancia como una entrada ordinaria. Los otros tres son texto plano que el compilador conocía de antemano — el puerto que configura la Release y los dos nombres que escribió el Aggregate.

Esto funciona porque la Recipe del servidor es una Recipe source:: su mapeo se convierte en los argumentos del bloque module del servidor, que es la única posición que Terraform evalúa en un ámbito donde está declarado el módulo vecino — consulta Consumir el valor publicado de otro componente y Un par desarrollado para la mecánica, y para lo que sale mal cuando un consumidor escribe la referencia en cualquier otro lugar. Por la misma razón, planifica este directorio — el que contiene aggrega.modules.tf — en lugar de cualquiera de los dos directorios de módulo por separado.

En una copia de prueba de ese directorio, tofu init -backend=false carga desde el disco la raíz y los módulos copiados localmente y solo obtiene los proveedores:

Initializing modules...
- api in modules/api
- db in modules/db
- db.db_instance in modules/db/modules/db_instance
- db.db_instance_role_association in modules/db/modules/db_instance_role_association
- db.db_option_group in modules/db/modules/db_option_group
- db.db_parameter_group in modules/db/modules/db_parameter_group
- db.db_subnet_group in modules/db/modules/db_subnet_group
[… omitted: provider installation, whose versions move with the registry, and OpenTofu's closing advice]

y tofu validate imprime entonces:

Success! The configuration is valid.

Un único stack de CloudFormation

Terminal window
aggrega build --release release-one-stack.yaml --auto-pull
Pull complete: release-one-stack.lock (entities=11, source_artifacts=0, external_inputs=0)
Total build time: 6.2s
Build completed: 1 file written to <workspace>/dist

El stack ensamblado queda en dist/one-stack/cloudformation/cloudformation-stack.json, con tres recursos: Db, la instancia RDS; Api, el servicio de ECS; y ApiTaskDefinition, la definición de tarea que ejecuta. El entorno del contenedor en ApiTaskDefinition:

"Environment": [
{
"Name": "DB_HOST",
"Value": {
"Fn::GetAtt": [
"Db",
"Endpoint.Address"
]
}
},
{
"Name": "DB_NAME",
"Value": "orders"
},
{
"Name": "DB_PORT",
"Value": "5432"
},
{
"Name": "DB_USER",
"Value": "orders_admin"
}
],

DB_HOST es un Fn::GetAtt sobre el Endpoint.Address de la instancia, contra el ID lógico Db que la Recipe de la base de datos deriva del nombre de componente db. CloudFormation lo resuelve cuando crea el stack y, como la definición de tarea del servidor lee un atributo de Db, crea primero la instancia. Consulta Referencias dentro del stack.

Dos stacks de CloudFormation

Terminal window
aggrega build --release release-two-stacks.yaml --auto-pull
Pull complete: release-two-stacks.lock (entities=11, source_artifacts=0, external_inputs=0)
Total build time: 6.2s
Build completed: 2 files written to <workspace>/dist

Nada cambia en aggregate.yaml. La Release coloca la base de datos en el límite data y el servidor en el límite app, así que cada uno se ensambla en un stack propio, y la arista del servidor hacia la base de datos cruza de un stack al otro. El stack de la base de datos, dist/two-stacks-data/cloudformation/cloudformation-stack.json, publica cada entrada que consume la arista como una salida con un Export. Sus Outputs:

"Outputs": {
"dbXXdatabase": {
"Value": "orders",
"Export": {
"Name": "aggrega--orders-two-stacks--two-stacks-data-zscloudformation--db--database"
}
},
"dbXXhost": {
"Value": {
"Fn::GetAtt": [
"Db",
"Endpoint.Address"
]
},
"Export": {
"Name": "aggrega--orders-two-stacks--two-stacks-data-zscloudformation--db--host"
}
},
"dbXXport": {
"Value": "5432",
"Export": {
"Name": "aggrega--orders-two-stacks--two-stacks-data-zscloudformation--db--port"
}
},
"dbXXprotocol": {
"Value": "postgres"
},
"dbXXuser": {
"Value": "orders_admin",
"Export": {
"Name": "aggrega--orders-two-stacks--two-stacks-data-zscloudformation--db--user"
}
}
},

protocol también se publica, y no lleva ningún Export porque ninguna arista lo lee. El stack del servidor, dist/two-stacks-app/cloudformation/cloudformation-stack.json, vuelve a leer cada una de las cuatro por el mismo nombre:

"Environment": [
{
"Name": "DB_HOST",
"Value": {"Fn::ImportValue":"aggrega--orders-two-stacks--two-stacks-data-zscloudformation--db--host"}
},
{
"Name": "DB_NAME",
"Value": {"Fn::ImportValue":"aggrega--orders-two-stacks--two-stacks-data-zscloudformation--db--database"}
},
{
"Name": "DB_PORT",
"Value": {"Fn::ImportValue":"aggrega--orders-two-stacks--two-stacks-data-zscloudformation--db--port"}
},
{
"Name": "DB_USER",
"Value": {"Fn::ImportValue":"aggrega--orders-two-stacks--two-stacks-data-zscloudformation--db--user"}
}
],

Cada nombre de export une el nombre de la Release, el directorio de salida del límite productor, el componente y la entrada, así que queda fijado en tiempo de compilación y el consumidor puede nombrarlo antes de que exista cualquiera de los dos stacks. Ninguna Release de aquí declara una cuenta ni una región, así que la lectura es un Fn::ImportValue en la misma cuenta. Cómo se construye el nombre, y cuándo el consumidor lee en cambio entre cuentas, se expone en Conexión entre stacks. Una importación solo se resuelve contra un export que ya existe, así que el stack de la base de datos se crea antes que el del servidor; ordenar los dos stacks corresponde al operador, fuera de la compilación.

La contraseña es la de RDS

El Aggregate nombra al usuario de la base de datos y nada sobre su contraseña, y ninguna Release vincula una credencial a la base de datos. En ambos destinos, la Recipe que selecciona el Manifest entrega la contraseña a RDS: manage_master_user_password = true en el bloque de módulo de arriba, y ManageMasterUserPassword en la instancia de cada stack. Las Properties de la base de datos en la plantilla de un solo stack:

"Properties": {
"AllocatedStorage": 50,
"BackupRetentionPeriod": 14,
"DBInstanceClass": "db.t3.small",
"DBName": "orders",
"DBSubnetGroupName": "example-private-db-subnets",
"Engine": "postgres",
"EngineVersion": "16",
"ManageMasterUserPassword": true,
"MasterUsername": "orders_admin",
"MultiAZ": true,
"Port": 5432,
"StorageType": "gp3",
"VPCSecurityGroups": [
"sg-0123456789abcdef0"
]
},

RDS genera la contraseña de administrador cuando crea la instancia y la guarda en AWS Secrets Manager. Ninguna entrada de la compilación lleva una contraseña, así que ninguna de las tres compilaciones escribe una en ningún archivo. El servidor recibe el nombre del usuario y no su contraseña; leer la contraseña de Secrets Manager queda a cargo del código que ejecuta la imagen del servidor.

La copia de seguridad es una vinculación

RDS hace por sí mismo la copia de seguridad de la instancia y conserva cada copia de seguridad automatizada durante 7 días cuando nada indica lo contrario. Cada Release las conserva durante 14 vinculando core/backup a la base de datos, en su entrada para db:

db:
features:
backup:
type: core/backup
infra:
retention_days: 14

Cada Manifest enlaza la Feature con la FeatureRecipe de su destino, terraform/backup-native o cloudformation/backup-native, y ninguna de las dos renderiza nada: la copia de seguridad es un ajuste de la instancia, así que la Recipe de la base de datos lee la vinculación y escribe la retención donde se escribe la instancia — backup_retention_period = 14 en el bloque de módulo, y "BackupRetentionPeriod": 14 en las Properties de la instancia de arriba. Por eso la plantilla de un solo stack contiene exactamente tres recursos.

Compilar no es desplegar

Cada compilación escribe archivos en dist/ y termina. Nunca ejecuta Terraform, OpenTofu ni CloudFormation, nunca se autentica en AWS y no consulta ninguno de los identificadores que nombran las Releases. Planificar y aplicar la configuración raíz, y crear los stacks, son pasos que das sobre la salida, con tus propias credenciales, después de sustituir los marcadores de posición.

Entrada idéntica, salida idéntica

Compilar dos veces a partir de entradas sin cambios produce una salida idéntica byte a byte, para cada una de las tres releases. El compilador no resuelve ningún dato en vivo, así que una recompilación no tiene nada que descubrir que pueda mover los bytes. Esa es la propiedad en la que se apoya una revisión basada en diffs.

dist/, .aggrega/ y los archivos *.lock se generan y no se incluyen en ningún commit; se regeneran a partir de los archivos que sí se incluyen.