Stack CloudFormation avec rattachements
Une base de données gérée et l’application qui la lit, écrites une seule fois comme intention du développeur et assemblées en templates de stacks AWS CloudFormation. Deux rattachements apportent leurs propres ressources — une alarme sur la base de données et un paramètre de réglages partagés sur la frontière — si bien que cet exemple montre où les ressources d’un rattachement aboutissent dans la stack assemblée et comment elles sont nommées à côté de celles du composant.
La même intention du développeur est construite de trois façons : en une seule stack, en deux stacks avec une référence qui passe de l’une à l’autre, et — délibérément — en un build qui s’arrête.
Les blocs de sortie de cette page sont copiés d’une exécution réelle, conformément à Lire la sortie sur ces pages.
Fichiers
aggregate.yaml— l’intention du développeur : une base de donnéespayments-dbde typecore/datastore/mariadbet unereporting-appde typeexample/compute/db-readerqui déclare utiliser la base de données. Rien de ce qui concerne AWS ne se trouve ici. Le blocfeatures:de la base de données portestorage-headroom, qui rattacheexample/storage-alarm.release-one-stack.yaml— les deux composants dans une seule frontière, si bien que les deux s’assemblent en une seule stack. Rattachecore/shared-configà l’ensemble de la frontière.release-two-stacks.yaml— la même intention répartie sur deux frontières, si bien que la référence de l’application à la base de données franchit une limite de stack.release-negative-name-collision.yamlavecaggregate-name-collision.yaml— censée échouer. Rattache l’alarme deux fois à un même composant.manifest.yaml— lie chaque type de composant et chaque Feature rattachée à la Recipe qui l’implémente sur cette cible..aggrega-config.yaml— nomme le registre du hub depuis lequel se résolvent les entités du catalogue.
Chaque release lie le slot root_password de la base de données dans son entrée pour payments-db, avec core/generated-secret. Sur cette cible, c’est RDS qui possède le mot de passe administrateur, et la Recipe de base de données que choisit le Manifest porte la directive qui le dit ; cela fait de la liaison une décision de l’opérateur, écrite dans la Release, et l’Aggregate n’en dit rien.
Chaque release rattache aussi core/backup à payments-db, avec infra.retention_days: 14, et le Manifest la lie à cloudformation/backup-native. RDS conserve les sauvegardes automatisées de l’instance pendant 7 jours lorsque rien n’indique le contraire ; ce rattachement conserve chacune pendant 14 jours. La FeatureRecipe ne rend rien : la sauvegarde est un paramètre de l’instance, si bien que la Recipe de la base de données lit le rattachement et écrit "BackupRetentionPeriod": 14 dans les propres Properties de l’instance.
Les entités qu’utilise cet exemple se trouvent toutes dans le catalogue publié. Rien n’est copié à côté des fichiers de release, si bien que l’exemple se résout par rapport au catalogue tel qu’il est plutôt que par rapport à un instantané privé de celui-ci.
Générer l’exemple
Vous pouvez construire cet exemple avec les commandes ci-dessous, ou le faire construire pour vous par votre assistant IA.
Écrivez l’exemple dans un nouveau dossier qui porte son nom :
aggrega scaffold --example cloudformation-rds-stackElle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :
cd cloudformation-rds-stackBuild
Cet exemple fournit trois releases, nommez donc celle que vous voulez. Une seule release est construite par exécution. Le premier build de chaque release a besoin de son lockfile, qu’écrit la commande pull :
aggrega pull --release release-one-stack.yamlaggrega build --release release-one-stack.yamlLe build affiche, <workspace> désignant le dossier de cet exemple :
Total build time: 4.1sBuild completed: 1 file written to <workspace>/distLa stack assemblée se trouve dans dist/one-stack/cloudformation/cloudformation-stack.json. Chaque composant et chaque rattachement qui rend dans ce répertoire contribue à cet unique template — le fournisseur émet une seule stack en JSON pur plutôt qu’un fichier par contributeur.
Avec un assistant IA
Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-lui ce prompt.
Utilisez uniquement les outils d’Aggrega et ne créez vous-même aucun dossier. Si le dossier de l’espace de travail ne contient pas encore de dossier `cloudformation-rds-stack`, appelez une fois l’outil `scaffold` avec `example` défini sur `cloudformation-rds-stack` et sans `dir` : il écrit l’exemple dans un nouveau dossier `cloudformation-rds-stack`. Appelez ensuite l’outil `build` avec `workspace_root` défini sur `cloudformation-rds-stack`, `release` défini sur `release-one-stack.yaml`, `auto_pull` défini sur true et `write` défini sur true. Indiquez-moi quels fichiers le build a écrits ; ils se trouvent sous `cloudformation-rds-stack/dist/`.Ce qui arrive dans la stack, et qui l’a apporté
Le build à une seule stack assemble quatre ressources provenant de quatre contributeurs différents :
| Ressource | Apporté par |
|---|---|
PaymentsDb | la propre Recipe du composant de base de données |
PaymentsDbStorageHeadroom | le rattachement storage-headroom sur ce composant |
AppSharedConfig | le rattachement shared-settings sur la frontière |
ReportingApp | la propre Recipe du composant applicatif |
Le rattachement backup sur payments-db ne figure pas dans le tableau, car il n’apporte aucune ressource qui lui soit propre : ce qu’il définit arrive à l’intérieur de PaymentsDb.
Chaque ressource porte un bloc de provenance nommant le contributeur dont elle est issue, si bien que les deux moitiés restent distinguables au sein d’une stack à laquelle les deux ont contribué :
"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" },Les deux entrées de version sont les seules lignes de ce bloc qui changent d’un build à l’autre, c’est pourquoi elles sont omises ; la troisième omission n’est que les Properties de l’alarme, affichées à part ci-dessous. Tout ce qui est montré est ce qu’écrit votre propre build.
L’alarme est la ressource du rattachement, et non celle de la base de données. Détacher storage-headroom de l’Aggregate supprime exactement cette ressource et l’unique sortie qu’elle publie, et laisse PaymentsDb octet pour octet tel qu’il était.
Le nom de ressource d’un rattachement porte la portée qui porte le rattachement
Une Feature est écrite une fois et rattachée de nombreuses fois, si bien que le nom que dérive une FeatureRecipe doit être distinct pour chaque rattachement. Celle-ci compose le composant hôte et le nom du rattachement : l’hôte payments-db, porté sous storage-headroom, donne PaymentsDbStorageHeadroom.
Composer l’hôte seul suffirait à tenir l’alarme à l’écart de la ressource qu’elle surveille, et ne suffirait pas à empêcher la même Feature rattachée deux fois à un même composant d’entrer en collision avec elle-même — c’est l’objet de la release en échec ci-dessous.
Les propres propriétés de l’alarme désignent l’hôte par le nom dérivé de l’hôte :
"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 sur la ressource de base de données se résout en l’identifiant de cette instance lorsque la stack est déployée. Les deux moitiés dérivent PaymentsDb du même nom de composant, ce qui les fait concorder — rien n’est recherché ici.
Qui décide quoi, sur un seul rattachement
Le rattachement répartit ses entrées comme le fait un composant. La marge dont l’application a besoin relève de l’intention du développeur, écrite sur le rattachement dans aggregate.yaml — c’est une propriété de l’application. L’endroit que l’alarme notifie, et la durée pendant laquelle une baisse doit persister avant qu’elle ne se déclenche, relèvent du dimensionnement de l’opérateur, fourni par la Release :
payments-db: features: storage-headroom: infra: evaluation_periods: 3 notify_target: "arn:aws:sns:eu-west-1:123456789012:payments-oncall"Une Release fournit infra pour un rattachement que l’Aggregate a déclaré, et jamais values. La release à deux stacks définit les deux ; la release à une seule stack n’en définit aucun, et la différence se lit dans la sortie. Définis :
"Properties": { "AlarmActions": [ "arn:aws:sns:eu-west-1:123456789012:payments-oncall" ],Non défini, le champ est absent plutôt que vide — l’alarme est émise sans aucune action de notification, et EvaluationPeriods retombe sur le 2 que porte la Recipe plutôt que sur quoi que ce soit que la Feature a déclaré. Une Release qui ne fournit ni l’un ni l’autre obtient tout de même une alarme fonctionnelle, et en fournir un ajoute exactement un champ.
Les sorties d’un rattachement sont nommées d’après son hôte, et non d’après lui-même
Les deux moitiés de la stack sont nommées selon des règles différentes, et c’est cette moitié-ci qui surprend.
L’ID logique d’une ressource provient de la propre Recipe du rattachement — le nom ci-dessus. Une sortie est nommée d’après le composant qui publie et l’entrée ensemble, et pour un rattachement, le composant qui publie est l’hôte. L’alarme publie une entrée, alarm-id, et elle apparaît sous la forme :
"paymentsXzhdbXXalarmXzhid": { "Value": { "Ref": "PaymentsDbStorageHeadroom" } },Les deux moitiés se lisent une fois la règle connue : un ID logique n’admet que des lettres et des chiffres, si bien que le fournisseur écrit en toutes lettres ce que cet alphabet refuse au lieu de le supprimer — Xzh est le trait d’union que vous avez écrit, et XX est l’endroit où le nom du composant se termine et où commence le nom de l’entrée. payments-db publiant alarm-id, et rien d’autre, aboutit à ce nom. Les noms dans la stack assemblée expose le schéma en entier.
C’est le même nom de sortie que celui auquel on aurait abouti si la base de données avait elle-même publié alarm-id. Un nom d’entrée que l’hôte publie aussi rencontrerait donc celui du rattachement en un seul nom de sortie — c’est pourquoi des noms d’entrée qui se lisent comme propres au rattachement les tiennent à l’écart de ceux de l’hôte.
Un rattachement à l’échelle de la frontière est rendu une seule fois pour la frontière
core/shared-config est rattachée dans la Release, sur la frontière plutôt que sur un composant, et elle est rendue une seule fois pour cette frontière — et non une fois par composant qu’elle contient. Le build à une seule stack contient deux composants et exactement 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" },Construisez la release à deux stacks et le propos devient plus net : chaque frontière reçoit le sien, portant les paramètres résolus propres à cette frontière. Les Properties de celui de chacun des deux templates qu’écrit ce build :
"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" },Elle est rattachée dans la Release parce que ce qu’elle porte relève de l’organisation propre à l’opérateur plutôt que de quoi que ce soit que l’Aggregate déclare. Un rattachement de frontière définit infra: et jamais values: — l’Aggregate reste l’endroit où sont écrites les valeurs du développeur.
Répartir la même intention sur deux stacks
aggrega pull --release release-two-stacks.yamlaggrega build --release release-two-stacks.yamlRien ne change dans aggregate.yaml. L’application déclare toujours qu’elle utilise la base de données ; l’opérateur décide dans la Release que les deux sont provisionnées séparément, et la référence entre elles franchit par conséquent une limite de stack.
Dans le build à une seule stack, l’application reçoit le point de terminaison comme une référence à l’intérieur de l’unique template :
"Properties": { "Name": "/reporting/db-host", "Tier": "Standard", "Type": "String", "Value": { "Fn::GetAtt": [ "PaymentsDb", "Endpoint.Address" ] } },Dans le build à deux stacks, la stack productrice publie cette valeur comme un export :
"paymentsXzhdbXXhost": { "Value": { "Fn::GetAtt": [ "PaymentsDb", "Endpoint.Address" ] }, "Export": { "Name": "aggrega--cloudformation-two-stacks--two-stacks-data-zscloudformation--payments-db--host" } },et la stack consommatrice la relit sous ce même nom :
"Properties": { "Name": "/reporting/db-host", "Tier": "Standard", "Type": "String", "Value": {"Fn::ImportValue":"aggrega--cloudformation-two-stacks--two-stacks-data-zscloudformation--payments-db--host"} },Seul host porte un Export, car c’est l’entrée qu’une arête consomme réellement ; les autres entrées publiées de la base de données apparaissent comme de simples sorties. L’alarme de portée composant suit son hôte dans la stack productrice, et chaque frontière conserve son propre rattachement à l’échelle de la frontière.
Aucune des deux fonctions intrinsèques n’est évaluée au moment du build. Le point de terminaison n’existe pas tant que la stack n’est pas déployée, si bien que le compilateur transmet la référence telle quelle et que CloudFormation la résout — c’est pourquoi l’application ne nomme jamais une adresse.
Pour la façon dont le nom d’export est construit, et le cas où le consommateur lit via Fn::ImportValue plutôt que par une lecture directe entre comptes, voir Câblage entre stacks.
Le build qui s’arrête
aggrega pull --release release-negative-name-collision.yamlaggrega build --release release-negative-name-collision.yamlaggregate-name-collision.yaml rattache l’alarme deux fois à un même composant, sous deux noms de rattachement. Le nom de ressource de chaque rattachement compose son propre nom de rattachement, si bien que les deux alarmes sont deux ressources distinctes et n’entrent pas en collision à cet endroit. Leurs sorties, si : chacune publie alarm-id, une sortie est nommée d’après le composant hôte et l’entrée, et l’hôte est le même composant pour les deux.
[… 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")Quatre choses à y lire, et chacune est délibérée.
- Les deux extrémités sont nommées. Chaque entrée donne le composant et le nom de rattachement qu’il portait, si bien que les deux peuvent être recherchés dans les fichiers que vous avez écrits. Rien dans une collision ne fait du nom d’un contributeur celui qui était voulu, si bien que les deux sont signalés plutôt que le premier.
- L’espace de clés est nommé.
output-logical-idsvous indique lequel des deux espaces de noms de la stack a été atteint et — puisque l’espace de noms des ressources est absent de cet arrêt — que les noms de ressources étaient corrects. - Rien n’est émis. Le build s’arrête plutôt que d’écrire une stack dans laquelle l’une des deux alarmes n’a silencieusement aucune sortie.
- Nommer les ressources différemment ne corrige pas ce cas. Le nom de sortie est construit à partir du composant hôte et de l’entrée, si bien que c’est l’entrée qui doit différer — soit un seul rattachement au lieu de deux, soit une Feature dont les noms d’entrée publiés se lisent comme propres à ce rattachement.
Entrée identique, sortie identique
Construire deux fois à partir d’entrées inchangées produit des templates identiques octet pour octet. Le compilateur ne résout aucune donnée en direct — il n’appelle jamais AWS, ne recherche jamais un identifiant de compte et n’exécute jamais CloudFormation —, si bien qu’une reconstruction n’a rien à découvrir qui puisse déplacer les octets. C’est la propriété sur laquelle repose une revue fondée sur les diffs.
dist/ et les fichiers *.lock sont générés et ne sont pas commités ; ils se régénèrent à partir des fichiers qui le sont.