Stack de CloudFormation con vinculaciones
Una base de datos gestionada y la aplicación que la lee, escritas una sola vez como intención del desarrollador y ensambladas en plantillas de stacks de AWS CloudFormation. Dos vinculaciones aportan recursos propios — una alarma sobre la base de datos y un parámetro de ajustes compartidos sobre el límite —, así que este ejemplo muestra dónde quedan los recursos de una vinculación en el stack ensamblado y cómo se nombran junto a los del componente.
La misma intención del desarrollador se compila de tres maneras: como un stack, como dos stacks con una referencia que cruza entre ellos y — deliberadamente — como una compilación que se detiene.
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: una base de datospayments-dbde tipocore/datastore/mariadby unareporting-appde tipoexample/compute/db-readerque declara que usa la base de datos. Aquí no hay nada sobre AWS. El bloquefeatures:de la base de datos llevastorage-headroom, que vinculaexample/storage-alarm.release-one-stack.yaml— ambos componentes en un único límite, así que ambos se ensamblan en un único stack. Vinculacore/shared-configa todo el límite.release-two-stacks.yaml— la misma intención dividida en dos límites, así que la referencia de la aplicación a la base de datos cruza un borde de stack.release-negative-name-collision.yamlconaggregate-name-collision.yaml— pensada para fallar. Vincula la alarma dos veces a un mismo componente.manifest.yaml— enlaza cada tipo de componente y cada Feature vinculada con la Recipe que lo implementa en este destino..aggrega-config.yaml— nombra el registro del hub desde el que se resuelven las entidades del catálogo.
Cada release enlaza el slot root_password de la base de datos en su entrada para payments-db, con core/generated-secret. En este destino, RDS es el dueño de la contraseña de administrador, y la Recipe de base de datos que elige el Manifest lleva la directiva que lo indica; eso convierte el enlace en una decisión del operador, escrita en la Release, y el Aggregate no dice nada al respecto.
Cada release vincula además core/backup a payments-db, con infra.retention_days: 14, y el Manifest la enlaza con cloudformation/backup-native. RDS conserva las copias de seguridad automatizadas de la instancia durante 7 días cuando nada indica lo contrario; esta vinculación conserva cada una durante 14. La FeatureRecipe no 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 "BackupRetentionPeriod": 14 en las Properties propias de la instancia.
Todas las entidades que usa este ejemplo residen en el catálogo publicado. No se copia nada junto a los archivos de release, así que el ejemplo se resuelve contra el catálogo tal como está y no contra una instantánea privada de él.
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:
aggrega scaffold --example cloudformation-rds-stackDespués imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:
cd cloudformation-rds-stackCompilación
Este ejemplo incluye tres releases, así que nombra la que quieras. Se compila una release por ejecución. La primera compilación de cada release necesita su lockfile, que escribe el comando pull:
aggrega pull --release release-one-stack.yamlaggrega build --release release-one-stack.yamlLa compilación imprime, con <workspace> en lugar de la carpeta de este ejemplo:
Total build time: 4.1sBuild completed: 1 file written to <workspace>/distEl stack ensamblado queda en dist/one-stack/cloudformation/cloudformation-stack.json. Cada componente y cada vinculación que renderiza en ese directorio contribuye a esa única plantilla — el proveedor emite un único stack en JSON puro en lugar de un archivo por contribuidor.
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 por tu cuenta. Si la carpeta del espacio de trabajo aún no contiene una carpeta `cloudformation-rds-stack`, llama una vez a la herramienta `scaffold` con `example` establecido en `cloudformation-rds-stack` y sin `dir`: escribe el ejemplo en una nueva carpeta `cloudformation-rds-stack`. Luego llama a la herramienta `build` con `workspace_root` establecido en `cloudformation-rds-stack`, `release` establecido en `release-one-stack.yaml`, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió la compilación; están en `cloudformation-rds-stack/dist/`.Qué llega al stack y quién lo aportó
La compilación de un solo stack ensambla cuatro recursos de cuatro contribuidores distintos:
| Recurso | Aportado por |
|---|---|
PaymentsDb | la propia Recipe del componente de base de datos |
PaymentsDbStorageHeadroom | la vinculación storage-headroom en ese componente |
AppSharedConfig | la vinculación shared-settings en el límite |
ReportingApp | la propia Recipe del componente de aplicación |
La vinculación backup en payments-db no aparece en la tabla porque no aporta ningún recurso propio: lo que establece va a parar dentro de PaymentsDb.
Cada recurso lleva un bloque de procedencia que nombra al contribuidor del que procede, así que las dos mitades siguen siendo distinguibles dentro de un stack al que ambas aportaron:
"PaymentsDbStorageHeadroom": { "Metadata": { "aggrega.ai/provenance": { "aggrega.ai/aggregate-name": "aggregate", "aggrega.ai/boundary-path": "app", [… omitted: a compiler-version entry, which moves with the build] "aggrega.ai/component-id": "cfr--payments-db--storage-headroom", "aggrega.ai/environment": "production", "aggrega.ai/provider": "cloudformation", [… omitted: a provider-version entry, which moves with the build] "aggrega.ai/recipe-uri": "storage-alarm:1.0.0" } }, [… omitted: the alarm's Properties, printed in full just below] "Type": "AWS::CloudWatch::Alarm" },Las dos entradas de versión son las únicas líneas de este bloque que cambian entre compilaciones, por eso se omiten; la tercera omisión son solo las Properties de la alarma, impresas aparte más abajo. Todo lo que se muestra es lo que escribe tu propia compilación.
La alarma es el recurso de la vinculación, no el de la base de datos. Desvincular storage-headroom del Aggregate elimina exactamente ese recurso y la única salida que publica, y deja PaymentsDb byte a byte como estaba.
El nombre de recurso de una vinculación lleva el ámbito que lleva la vinculación
Una Feature se escribe una vez y se vincula muchas veces, así que el nombre que deriva una FeatureRecipe tiene que ser distinto para cada vinculación. Esta compone el componente host y el nombre de la vinculación: el host payments-db, llevado bajo storage-headroom, da PaymentsDbStorageHeadroom.
Componer solo el host bastaría para mantener la alarma separada del recurso que vigila, y no bastaría para evitar que la misma Feature vinculada dos veces a un componente colisione consigo misma — que es de lo que trata la release que falla más abajo.
Las propiedades de la propia alarma se refieren al host por el nombre derivado del host:
"Properties": { "AlarmDescription": "Free storage below 21474836480 bytes on payments-db", "ComparisonOperator": "LessThanThreshold", "Dimensions": [ { "Name": "DBInstanceIdentifier", "Value": { "Ref": "PaymentsDb" } } ], "EvaluationPeriods": 2, "MetricName": "FreeStorageSpace", "Namespace": "AWS/RDS", "Period": 300, "Statistic": "Minimum", "Threshold": 21474836480, "TreatMissingData": "breaching" },Ref sobre el recurso de la base de datos se resuelve en el identificador de esa instancia cuando se despliega el stack. Ambas mitades derivan PaymentsDb del mismo nombre de componente, y eso es lo que hace que coincidan — aquí no se consulta nada.
Quién decide qué, en una sola vinculación
La vinculación reparte sus entradas como lo hace un componente. Cuánto margen necesita la aplicación es intención del desarrollador, escrita en la vinculación en aggregate.yaml — es una propiedad de la aplicación. Adónde notifica la alarma, y cuánto debe persistir una caída antes de que se dispare, son dimensionamiento del operador, aportado desde la Release:
payments-db: features: storage-headroom: infra: evaluation_periods: 3 notify_target: "arn:aws:sns:eu-west-1:123456789012:payments-oncall"Una Release aporta infra para una vinculación que declaró el Aggregate, y nunca values. La release de dos stacks establece ambos; la release de un solo stack no establece ninguno, y la diferencia se puede leer en la salida. Establecidos:
"Properties": { "AlarmActions": [ "arn:aws:sns:eu-west-1:123456789012:payments-oncall" ],Sin establecer, el campo está ausente en lugar de vacío — la alarma se emite sin ninguna acción de notificación, y EvaluationPeriods cae en el 2 que lleva la Recipe en lugar de en algo que declarara la Feature. Una Release que no aporta ninguno obtiene igualmente una alarma que funciona, y aportar uno añade exactamente un campo.
Las salidas de una vinculación se nombran por su host, no por ella misma
Las dos mitades del stack se nombran según reglas distintas, y esta es la mitad que sorprende.
El ID lógico de un recurso procede de la propia Recipe de la vinculación — el nombre de arriba. Una salida se nombra por el componente que publica y la entrada juntos, y para una vinculación el componente que publica es el host. La alarma publica una entrada, alarm-id, y aparece como:
"paymentsXzhdbXXalarmXzhid": { "Value": { "Ref": "PaymentsDbStorageHeadroom" } },Las dos mitades se leen una vez conocida la regla: un ID lógico admite solo letras y dígitos, así que el proveedor escribe por extenso lo que ese alfabeto rechaza en lugar de descartarlo — Xzh es el guion que escribiste, y XX es donde termina el nombre del componente y empieza el nombre de la entrada. payments-db publicando alarm-id, y nada más, llega a ese nombre. Nombres en el stack ensamblado expone el esquema completo.
Es el mismo nombre de salida al que se habría llegado si la propia base de datos hubiera publicado alarm-id. Así que un nombre de entrada que también publica el host coincidiría con el de la vinculación en un único nombre de salida — por eso los nombres de entrada que se leen como propios de la vinculación los mantienen separados de los del host.
Una vinculación de todo el límite se renderiza una sola vez para el límite
core/shared-config se vincula en la Release, en el límite y no en un componente, y se renderiza una vez para ese límite — no una vez por cada componente que contiene. La compilación de un solo stack contiene dos componentes y exactamente un AppSharedConfig:
"AppSharedConfig": { [… omitted: the provenance Metadata, whose shape is shown above] "Properties": { "Description": "Settings shared by every component in the app boundary", "Name": "/app/shared-config", "Type": "String", "Value": "tier=production" }, "Type": "AWS::SSM::Parameter" },Compila la release de dos stacks y la cuestión queda más clara: cada límite recibe el suyo, con los ajustes resueltos propios de ese límite. Las Properties del que hay en cada una de las dos plantillas que escribe esa compilación:
"Properties": { "Description": "Settings shared by every component in the data boundary", "Name": "/data/shared-config", "Type": "String", "Value": "tier=production-data" }, "Properties": { "Description": "Settings shared by every component in the app boundary", "Name": "/app/shared-config", "Type": "String", "Value": "tier=production-app" },Se vincula en la Release porque lo que lleva es una disposición propia del operador y no algo que declare el Aggregate. Una vinculación de límite establece infra: y nunca values: — el Aggregate sigue siendo donde se escriben los valores del desarrollador.
Dividir la misma intención en dos stacks
aggrega pull --release release-two-stacks.yamlaggrega build --release release-two-stacks.yamlNada cambia en aggregate.yaml. La aplicación sigue declarando que usa la base de datos; el operador decide en la Release que las dos se aprovisionen por separado, y como resultado la referencia entre ellas cruza un borde de stack.
En la compilación de un solo stack, la aplicación recibe el endpoint como una referencia dentro de la única plantilla:
"Properties": { "Name": "/reporting/db-host", "Tier": "Standard", "Type": "String", "Value": { "Fn::GetAtt": [ "PaymentsDb", "Endpoint.Address" ] } },En la compilación de dos stacks, el stack productor publica ese valor como un export:
"paymentsXzhdbXXhost": { "Value": { "Fn::GetAtt": [ "PaymentsDb", "Endpoint.Address" ] }, "Export": { "Name": "aggrega--cloudformation-two-stacks--two-stacks-data-zscloudformation--payments-db--host" } },y el stack consumidor lo vuelve a leer por ese mismo nombre:
"Properties": { "Name": "/reporting/db-host", "Tier": "Standard", "Type": "String", "Value": {"Fn::ImportValue":"aggrega--cloudformation-two-stacks--two-stacks-data-zscloudformation--payments-db--host"} },Solo host lleva un Export, porque es la entrada que una arista consume realmente; las demás entradas publicadas de la base de datos aparecen como salidas simples. La alarma de ámbito de componente sigue a su host al stack productor, y cada límite conserva su propia vinculación de todo el límite.
Ninguna de las dos funciones intrínsecas se evalúa en tiempo de compilación. El endpoint no existe hasta que se despliega el stack, así que el compilador canaliza la referencia tal cual y CloudFormation la resuelve — por eso la aplicación nunca nombra una dirección.
Para saber cómo se construye el nombre de export, y cuándo el consumidor lee mediante Fn::ImportValue en lugar de con una lectura directa entre cuentas, consulta Conexión entre stacks.
La compilación que se detiene
aggrega pull --release release-negative-name-collision.yamlaggrega build --release release-negative-name-collision.yamlaggregate-name-collision.yaml vincula la alarma dos veces a un componente, bajo dos nombres de vinculación. El nombre de recurso de cada vinculación compone su propio nombre de vinculación, así que las dos alarmas son dos recursos distintos y ahí no colisionan. Sus salidas sí: cada una publica alarm-id, una salida se nombra por el componente host y la entrada, y el host es el mismo componente para ambas.
[… omitted: the pull's lines, which report the same collision while writing the lockfile][TRANSLATION_ERROR E0038] dispatch groups whose contributors derive one name more than once in one key space caused by (2): [TRANSLATION_ERROR] release-negative-name-collision.yaml derived name collision: one name is derived more than once in one key space ("paymentsXzhdbXXalarmXzhid", key space "output-logical-ids", derived by component "payments-db", carrying attachment "storage-headroom", provider "cloudformation", dispatch path "name-collision/cloudformation") --- [TRANSLATION_ERROR] release-negative-name-collision.yaml derived name collision: one name is derived more than once in one key space ("paymentsXzhdbXXalarmXzhid", key space "output-logical-ids", derived by component "payments-db", carrying attachment "storage-headroom-strict", provider "cloudformation", dispatch path "name-collision/cloudformation")Cuatro cosas que leer ahí, y cada una es deliberada.
- Se nombran ambos extremos. Cada entrada da el componente y el nombre de vinculación que llevaba, así que ambos se pueden buscar en los archivos que escribiste. Nada en una colisión hace que el nombre de un contribuidor sea el previsto, así que se informan ambos y no solo el primero.
- Se nombra el espacio de claves.
output-logical-idste dice cuál de los dos espacios de nombres del stack se alcanzó y — como el espacio de nombres de los recursos no aparece en esta detención — que los nombres de los recursos estaban bien. - No se emite nada. La compilación se detiene en lugar de escribir un stack en el que una de las dos alarmas no tiene, sin aviso, ninguna salida.
- Dar nombres distintos a los recursos no lo arregla. El nombre de salida se construye a partir del componente host y la entrada, así que es la entrada la que tiene que diferir — o bien una sola vinculación en lugar de dos, o bien una Feature cuyos nombres de entrada publicados se lean como propios de esa vinculación.
Entrada idéntica, salida idéntica
Compilar dos veces a partir de entradas sin cambios produce plantillas idénticas byte a byte. El compilador no resuelve ningún dato en vivo — nunca llama a AWS, nunca consulta un identificador de cuenta y nunca ejecuta CloudFormation —, 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/ 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.