Provider CloudFormation
Le fournisseur cloudformation effectue le rendu des Recipes d’Aggrega en templates de stack AWS CloudFormation. Chaque composant dont le rendu aboutit dans le même répertoire de sortie avec ce fournisseur est assemblé dans une seule stack, émise sous la forme d’un unique template en JSON pur qui utilise des fonctions intrinsèques en forme longue. Une frontière devient donc une stack dans le cas ordinaire — et deux frontières dont le directory: se résout vers le même chemin sont assemblées ensemble dans une seule stack, partageant les noms de ce template. Comme tout fournisseur Aggrega, il est hors ligne et hermétique — un build Aggrega est une compilation anticipée, si bien que le fournisseur n’appelle jamais AWS, ne résout jamais d’identifiants générés par le compte et n’exécute jamais CloudFormation. Les valeurs connues uniquement à l’exécution restent des références intrinsèques CloudFormation (Fn::GetAtt, Fn::ImportValue, Fn::GetStackOutput) que CloudFormation résout au moment du déploiement.
Recipes de fragments assemblées en une stack
Une Recipe cloudformation rédige un fragment — les ressources CloudFormation apportées par un seul composant — plutôt qu’un template entier. Lorsque les composants d’une frontière effectuent leur rendu, le fournisseur assemble chaque fragment du groupe de distribution en un seul template de stack : les ressources fusionnent sous une seule table Resources, les valeurs provides de chaque composant apparaissent comme Outputs de la stack, et les autres sections de premier niveau du template sont traitées une par une sous Sections de premier niveau dans la stack assemblée. Deux formes de rédaction sont acceptées :
- Entrée par fragments (artefacts). Une Recipe rédige directement des fragments de ressources ; le fournisseur les normalise en JSON pur avec des fonctions intrinsèques en forme longue et les fusionne dans la stack assemblée.
- Entrée issue d’une source. Une Recipe fait référence à un template CloudFormation existant (YAML ou JSON) ; le fournisseur le normalise en JSON en forme longue et valide sa structure avant l’assemblage, remplit les paramètres que le template déclare à partir du
valuesMappingde la Recipe — voir Valeurs des paramètres d’un template source — et laisse de côté toute ressource que nomment les entréesomits:de la Recipe — voir Laisser de côté des ressources d’un template source.
Le template assemblé est en JSON pur. Les fonctions intrinsèques sont émises telles quelles et jamais évaluées au moment du build — le compilateur ne peut pas résoudre une valeur qui n’existe qu’après le déploiement de la stack, et en évaluer une romprait le contrat de compilation anticipée.
Une Feature rattachée à un composant contribue à la même stack
Une Feature rattachée à un composant apporte ses ressources à la stack dans laquelle son composant hôte est assemblé, aux mêmes conditions que la propre Recipe du composant hôte. Il n’y a pas de template distinct à côté : la stack assemblée est la totalité de ce que ce fournisseur émet pour un répertoire de sortie, si bien que les ressources d’une Feature rattachée sont soit dans cette stack, soit pas déployées du tout. Détacher la Feature retire exactement ces ressources et laisse intactes celles du composant hôte.
Puisqu’elles aboutissent dans la stack assemblée, elles en partagent les noms. Les ID logiques des ressources d’une Feature rattachée se trouvent dans le même espace que ceux du composant hôte et que ceux de toute autre Feature rattachée à côté d’elle, si bien que Les noms dans la stack assemblée s’applique à eux sans changement. Lorsque deux contributeurs se rencontrent sur un même nom, l’arrêt nomme le composant et la clé sous laquelle la Feature est rattachée, de sorte que les deux extrémités de la collision peuvent être recherchées dans vos propres fichiers.
Les sorties d’une Feature rattachée sont publiées sous le nom de son composant hôte, mais pas les ID logiques de ses ressources. Les deux moitiés de la stack sont nommées selon des règles différentes, elles répondent donc différemment à cette question. Un ID logique de ressource est émis exactement tel que la FeatureRecipe l’a rédigé, comme celui de toute Recipe. Une sortie est nommée d’après le composant qui publie et l’entrée ensemble — et pour une Feature rattachée à un composant, le composant qui publie est l’hôte : une Feature rattachée à payments-db qui publie alarm aboutit à paymentsXzhdbXXalarm, le même nom auquel elle aboutirait si le composant hôte avait publié cette entrée lui-même. Ainsi, un nom d’entrée que l’hôte publie aussi rencontre celui du rattachement sur un même nom de sortie, et le build s’arrête en nommant le composant et la clé sous laquelle la Feature est rattachée, à côté du composant seul. Choisir des noms d’entrée qui se lisent comme propres à la Feature — backup-alarm plutôt que alarm — les tient à l’écart de ceux de l’hôte.
Chaque ressource qu’une Feature apporte conserve, dans la provenance que le build y écrit, l’identité composée pour ce rattachement plutôt que celle du composant hôte, de sorte que les deux restent distinguables au sein d’une stack à laquelle toutes deux ont contribué. Labels et annotations explique comment cette identité est construite.
Sections de premier niveau dans la stack assemblée
Plusieurs composants s’assemblent en une seule stack, de sorte que l’assemblage doit rendre compte de chaque section de premier niveau qu’admet un template CloudFormation — y compris Globals et Hooks, les deux sections qu’une transformation hébergée par CloudFormation ajoute au langage des templates. Chacune relève d’exactement un des groupes ci-dessous, et une clé de premier niveau qu’écrit un composant et qui n’est pas du tout une section reçoit un avertissement nommant le composant et la clé, de sorte que rien n’est écarté sans être signalé.
Assemblés sous des noms auxquels le fournisseur donne une portée, ou lus tels qu’ils sont écrits. Resources et Outputs, que Les noms dans la stack assemblée traite en entier. AWSTemplateFormatVersion est écrit par le fournisseur plutôt que lu depuis un composant : le langage des templates n’admet qu’une seule valeur pour lui, il n’y a donc rien qu’un composant ait à décider.
Portés sous exactement les noms que vous avez écrits. Parameters, Mappings, Conditions, Metadata et Rules. Chacune de ces sections est une table dont vous avez choisi les clés, de sorte que les entrées de chaque composant atteignent la stack assemblée sous ces noms, sans réécriture — c’est ce qui permet à un Condition: d’une ressource, à un Fn::FindInMap ou à un Ref vers un paramètre de se résoudre par rapport à la déclaration arrivée avec lui. Chacune est portée séparément, parce que chacune est écrite séparément : une règle formule une assertion sur un paramètre du même document, une condition peut ne référencer aucun paramètre, et CloudFormation n’autorise pas de référence à un paramètre à l’intérieur d’un mapping.
Un même mot recouvre ici deux endroits différents, et seul le premier vous appartient. Le Metadata de la liste ci-dessus est la section de premier niveau propre au template, une table de noms que vous avez choisis. Une ressource individuelle porte aussi son propre attribut Metadata, et c’est là que le build écrit la provenance — sous une unique clé réservée aggrega.ai/, ajoutée à côté de tout ce que vous y avez écrit plutôt que de le remplacer. Une entrée de provenance qui apparaît à l’intérieur d’une ressource n’est donc ni quelque chose que vous avez écrit, ni quelque chose que la section de premier niveau a porté.
Parameters, Mappings, Conditions et Rules nomment leurs entrées avec un ID logique. Comme le fournisseur porte un nom exactement tel que vous l’avez écrit, l’alphabet qu’admet un ID logique atteint aussi ces sections : un nom dans l’une des quatre qui contient autre chose que des lettres et des chiffres arrête le build — voir Un nom de section porté hors de l’alphabet arrête le build. Le fournisseur ne soumet pas les noms de la section Metadata de premier niveau à cet alphabet : ils nomment des informations que vous stockez plutôt que quoi que ce soit que le template adresse.
Deux composants qui déclarent des noms différents dans l’une de ces sections aboutissent tous les deux. Deux qui déclarent un même nom avec un contenu identique fusionnent en une seule entrée et le build se poursuit. Deux qui déclarent un même nom avec un contenu différent arrêtent le build, en nommant la section, le nom et les deux composants — car sinon l’un des deux corps serait écarté, laissant au composant qui l’a écrit une déclaration que la stack ne porte pas. C’est la même réconciliation que suivent les noms de ressources et de sorties, et renommer l’un ou l’autre la lève.
Nommés plutôt que portés. Description est une seule affirmation sur un template entier plutôt qu’une table de noms que vous avez choisis, de sorte qu’un assemblage puisant dans plusieurs composants n’a pas de réponse pour elle : deux descriptions sont deux réponses à une même question et aucune n’est celle de la stack. Hooks n’est lu que par la transformation AWS::CodeDeployBlueGreen, que la stack assemblée ne porte jamais (voir ci-dessous). La stack assemblée ne porte donc aucune des deux sections, et chaque composant qui en a écrit une reçoit un avertissement nommant le composant et la section. De même pour un composant qui écrit Globals sans déclarer la transformation AWS::Serverless-2016-10-31 qui la lit. L’avertissement est consultatif et hors bande : le template émis est octet pour octet ce qu’il serait sans lui, et --no-unsupported-field-warnings le fait taire avec le reste de cette classe.
Transform est construit à partir de celui de chaque composant. Une transformation est une macro que CloudFormation exécute sur le template entier avant de déployer quoi que ce soit, de sorte que le Transform de la stack assemblée est l’union des transformations que déclarent ses composants — celles d’un template source comme celles d’un fragment — dans l’ordre que documente CloudFormation : une macro que votre compte définit avant les transformations hébergées par CloudFormation, et AWS::LanguageExtensions avant AWS::Serverless-2016-10-31. L’ordre propre à chaque composant est conservé, et deux transformations que rien n’ordonne s’exécutent dans l’ordre où les composants les déclarent pour la première fois, de sorte que les mêmes composants donnent la même stack. Une seule transformation s’écrit sous forme de chaîne et plusieurs sous forme de liste. Une stack n’ayant qu’un seul composant, qui déclare son Transform dans un template ou un fragment, le conserve exactement tel qu’il a été écrit partout où le tableau ci-dessous le porte, et une stack dont les composants n’en déclarent aucune n’en porte aucune. La transformation d’un composant ne déclenche aucun avertissement : elle est portée, ou le build s’arrête en la nommant.
Comme une transformation traite le template entier, en porter une change la façon dont le contenu de chaque autre composant est déployé, à moins que ce qu’elle fait ne se limite au contenu écrit pour elle. Chaque transformation reçoit donc le traitement que permet la propre documentation de CloudFormation la concernant, et une combinaison que la stack ne peut pas porter arrête le build, en nommant la transformation et chaque composant de la stack :
| transformation | dans la stack assemblée |
|---|---|
AWS::Serverless-2016-10-31 | portée, avec les Globals du composant qui la déclare. Elle arrête le build là où ces Globals atteindraient les ressources serverless d’un autre composant, et là où l’une des sources d’événements de ses ressources désigne une ressource qu’un autre composant déclare, car la transformation réécrit la ressource que désigne un événement. |
AWS::LanguageExtensions | portée seule, ou à côté de AWS::Serverless-2016-10-31 du même composant. Elle arrête le build à côté du contenu serverless d’un autre composant, car la transformation serverless nomme ce qu’elle génère différemment une fois que les extensions de langage ont résolu ses valeurs. |
AWS::SecretsManager-2020-07-23, AWS::SecretsManager-2024-09-16 | portées : elles ne traitent que les calendriers de rotation qui les demandent. |
AWS::ServiceCatalog | portée pour une stack n’ayant qu’un seul composant. À côté de tout autre, elle arrête le build, car elle substitue son motif de référence partout dans le template. |
AWS::CodeDeployBlueGreen | arrête le build, même seule : CloudFormation refuse Outputs et Fn::ImportValue partout dans un template qui la déclare, et la stack assemblée porte les sorties que publient ses composants. |
AWS::Include | arrête le build, même seule : elle insère du contenu récupéré depuis S3 au moment où la stack est déployée, contenu que le build ne peut pas lire. |
| une macro que votre compte définit | portée pour une stack n’ayant qu’un seul composant. À côté de tout autre, elle arrête le build, car ce qu’elle fait au reste du template est inconnu du build. |
Deux composants qui déclarent une même paire de transformations dans des ordres opposés arrêtent eux aussi le build, en nommant les deux ordres et les deux composants, puisque la stack les exécute dans un seul ordre. Un composant qui a besoin d’une transformation que la stack ne peut pas porter va dans une frontière qui lui est propre.
Les noms dans la stack assemblée
Un ID logique CloudFormation est unique au sein d’un template et n’admet que des lettres et des chiffres, et chaque composant qui s’assemble dans ce template en partage les noms — y compris des composants d’une seconde frontière, lorsque les deux se résolvent dans le même répertoire de sortie. Chaque nom par lequel la stack adresse quelque chose doit donc être distinct entre tous les composants qui y ont contribué, et l’ensemble des contributeurs n’est pas toujours une seule frontière.
Les ID logiques de ressource proviennent de la Recipe. Le fournisseur les émet exactement tels qu’ils ont été écrits et n’en réécrit aucun, de sorte que le nom que vous lisez dans le template assemblé est le nom qu’a écrit la Recipe. Les Recipes CloudFormation de la bibliothèque standard le dérivent du nom propre de l’instance de composant, en lisant les séparateurs de ce nom comme des limites de mots : l’instance payments-db nomme sa ressource PaymentsDb. Deux instances du même type décrivent donc deux ressources plutôt que de s’en disputer une.
Les noms de sortie ont pour portée le composant qui les a publiés. Chaque entrée de provides apparaît comme une sortie nommée d’après le composant qui publie et l’entrée ensemble — le composant payments-db publiant host apparaît comme paymentsXzhdbXXhost — de sorte que deux composants qui publient la même entrée aboutissent à deux sorties distinctes, et le sens d’une sortie ne change pas quand un autre composant rejoint la stack. Un consommateur entre stacks dans le même compte et la même région importe par le nom d’export plutôt que par celui-ci, de sorte que le nom d’export n’est pas affecté ; une lecture entre comptes ou entre régions nomme cette sortie, telle que le fournisseur l’écrit pour vous (voir Câblage entre stacks).
Comment un nom de sortie est construit
Un ID logique n’admet aucun caractère séparateur, de sorte qu’un nom construit à partir de quelque chose que vous avez écrit doit transporter vos séparateurs d’une manière ou d’une autre. Les supprimer ferait perdre de l’information : payments-db et payments_db sont deux composants, et un nom qui supprimerait la ponctuation n’identifierait ni l’un ni l’autre. Le fournisseur encode donc plutôt ce que l’alphabet refuse, en écrivant en toutes lettres chaque caractère refusé avec des caractères que l’alphabet admet.
Le schéma réserve un caractère pour ouvrir une séquence d’échappement — un X majuscule — et écrit tout le reste tel que vous l’avez saisi, majuscules comprises. Seule la majuscule est réservée, de sorte que le x minuscule d’un nom comme nginx-proxy est porté tel que vous l’avez écrit :
| ce que vous avez écrit | ce qu’il devient | pourquoi |
|---|---|---|
une lettre ou un chiffre, X excepté | le caractère lui-même | l’alphabet l’admet |
- | Xzh | l’alphabet refuse un trait d’union |
_ | Xzu | l’alphabet refuse un tiret bas |
. | Xzd | l’alphabet refuse un point |
/ | Xzs | l’alphabet refuse une barre oblique, que porte une identité de composant imbriquée |
X | Xzx000058 | réservé pour ouvrir une séquence d’échappement, il est donc écrit en toutes lettres par son point de code |
| toute autre chose | Xzx et le point de code du caractère | une seule règle couvre tous les caractères restants |
| la rencontre des deux moitiés | XX | deux caractères d’ouverture à la suite, qu’aucune des deux moitiés ne peut contenir |
La relecture est sans ambiguïté, et c’est là l’essentiel plutôt qu’un agrément. Un X est conservé tel quel seulement quand le caractère qui le suit est un caractère que l’alphabet admet, de sorte qu’une moitié encodée ne se termine jamais par l’un d’eux et n’en contient jamais deux à la suite — ce qui laisse XX libre de signifier la jonction, et seulement la jonction.
Ainsi, trois noms qui ne diffèrent que par l’endroit où se trouve leur ponctuation restent distincts :
component payments-db publishing host → paymentsXzhdbXXhostcomponent payments_db publishing host → paymentsXzudbXXhostcomponent payments publishing db-host → paymentsXXdbXzhhostLes noms sont plus longs et moins immédiatement lisibles que le nom de composant que vous avez écrit, et c’est là le compromis. Un nom qui identifie exactement une entrée vaut plus qu’un nom plus court qui n’identifie aucune de deux — et vous adressez une sortie par le nom d’export plutôt qu’en tapant celui-ci, de sorte que ce qu’il coûte est un second coup d’œil à la lecture d’un template émis.
Les ID logiques de ressource suivent une autre règle, car le fournisseur ne les construit pas : il émet ce qu’a écrit la Recipe. Les Recipes CloudFormation de la bibliothèque standard en dérivent un en lisant les séparateurs du nom d’instance comme des limites de mots — l’instance payments-db nomme sa ressource PaymentsDb — et cette dérivation supprime les séparateurs, de sorte que deux noms d’instance ne différant que par la ponctuation, ou seulement par la casse d’une lettre, dérivent malgré tout un même nom de ressource. Le build s’arrête, en nommant chaque instance arrivée à ce nom ainsi que le nom auquel elles ont abouti, plutôt que d’émettre une seule ressource là où deux composants ont été déclarés. Chacune d’elles est nommée plutôt que certaines seulement, car rien dans une collision ne fait de la dérivation d’une instance celle qui était voulue. Renommer toutes sauf une lève l’arrêt.
Un ID logique de ressource hors de l’alphabet arrête le build
L’unicité et l’alphabet sont deux exigences distinctes, et un ensemble de noms peut satisfaire la première et échouer à la seconde. Comme le fournisseur émet un ID logique de ressource exactement tel que la Recipe l’a écrit, l’ID qu’écrit une Recipe doit être un ID qu’un template CloudFormation peut contenir à lui seul : des lettres et des chiffres, et rien d’autre.
C’est ici qu’un nom dérivé et un nom transmis tel quel se séparent. Un nom de sortie est construit par le fournisseur, qui encode le composant qui publie et l’entrée, de sorte qu’un nom de sortie reste dans l’alphabet quelle que soit la façon dont vous écrivez l’une ou l’autre moitié. Un ID logique de ressource est transmis tel quel, de sorte que ce qu’a écrit la Recipe est ce que reçoit le template.
Cela en fait aussi une contrainte sur les noms de composants, chaque fois qu’une Recipe écrit le nom d’une instance de composant directement dans l’ID logique. Un nom de composant peut contenir un trait d’union ou un tiret bas ; un ID logique ne le peut pas. Un composant que vous ciblez vers ce fournisseur via une telle Recipe est donc nommé uniquement avec des lettres et des chiffres — paymentsdb plutôt que payments-db — et toute autre chose arrête le build.
L’arrêt nomme le contributeur dont la Recipe a écrit l’ID, l’ID lui-même et chacun de ses caractères qui ne peut pas s’y trouver, et il indique ce que vous pouvez écrire à la place. Deux choses le lèvent, et la première est celle qui vous est toujours accessible :
- Faites en sorte que la Recipe écrive un ID logique qui lui est propre plutôt que de transmettre un nom tel quel. Les Recipes CloudFormation de la bibliothèque standard suivent cette voie — elles lisent les séparateurs du nom d’instance comme des limites de mots, de sorte que l’instance
payments-dbnomme sa ressourcePaymentsDbet que vous conservez le nom de composant que vous avez choisi. Dériver un ID de cette façon échange cet arrêt contre la règle de collision ci-dessus : deux noms d’instance ne différant que par la ponctuation dérivent un même nom de ressource. - Lorsqu’une Recipe transmet bel et bien un nom tel quel, renommez ce qu’elle transmet uniquement avec des lettres et des chiffres. Pour la Recipe propre à un composant, il s’agit du nom du composant. Une Feature rattachée à un composant nomme ses ressources à partir de sa propre FeatureRecipe, de sorte que renommer le composant hôte ne les atteint pas — c’est l’ID qu’écrit cette Recipe qui doit changer.
Le fournisseur refuse ; il ne répare pas en silence. Réécrire l’ID à votre place semblerait être la chose utile à faire, et ce n’est pas le cas. Un ID logique est la façon dont CloudFormation identifie une ressource d’une mise à jour à l’autre, de sorte qu’en changer un n’est pas un renommage — il adresse une ressource différente. Un ID que le fournisseur aurait substitué pointerait ailleurs que vers la ressource déjà déployée sous l’ID que vous avez écrit, et la substitution est une substitution que vous n’avez jamais demandée et que vous devriez découvrir dans le template émis. Un build qui s’arrête nomme le problème tant qu’il vous appartient encore de le corriger.
Un nom de section porté hors de l’alphabet arrête le build
Les ID logiques de ressource ne sont pas les seuls noms que le fournisseur porte exactement tels que vous les avez écrits. Parameters, Mappings, Conditions et Rules nomment eux aussi leurs entrées avec un ID logique, et chacune des quatre sections atteint la stack assemblée sous le nom qu’a choisi son auteur. L’exigence est donc la même, sur quatre surfaces de plus : le nom doit être un nom qu’un template CloudFormation peut contenir à lui seul — des lettres et des chiffres, et rien d’autre — et toute autre chose arrête le build.
Il y a une conséquence qui va au-delà de la section qui porte le nom, et c’est la raison pour laquelle ceci arrête le build plutôt que d’émettre un avertissement. Ces noms sont ce par rapport à quoi se résolvent le Condition: d’une ressource, un Fn::FindInMap ou un Ref vers un paramètre. Un nom que l’alphabet n’admet pas fait donc sortir du template déployable la référence qui pointe vers lui en même temps que la déclaration elle-même, de sorte qu’un seul nom écrit rend les deux inaccessibles d’un coup — et sans l’arrêt, cela se découvre au moment du déploiement, par la personne qui déploie plutôt que par celle qui a écrit le nom.
L’arrêt nomme le contributeur dont la Recipe a écrit le nom, la section dans laquelle il a été écrit, le nom lui-même et chacun de ses caractères qui ne peut pas s’y trouver. La section est le terme à rechercher dans vos Recipes : ces noms sont portés exactement sous la section où vous les avez écrits, c’est donc le seul mot qui apparaît à la fois dans le message et dans vos propres fichiers. Renommer l’entrée uniquement avec des lettres et des chiffres lève l’arrêt, et c’est là tout le remède — un ID logique de ressource offre l’alternative de faire dériver un ID par la Recipe plutôt que de transmettre un nom tel quel, et ici il n’y a rien à dériver, car le nom dans la section est ce que vous avez écrit.
Seuls les noms propres d’une section sont soumis à l’alphabet, jamais les clés à l’intérieur d’une entrée. Vous choisissez librement les clés de second niveau d’un mapping — us-east-1 sous une table RegionCidr est le cas ordinaire, et il atteint le template émis intact. Les clés à l’intérieur du corps d’un paramètre, d’une condition ou d’une règle nomment des attributs, des assertions et des fonctions intrinsèques plutôt que quoi que ce soit que la stack adresse : les Assertions d’une règle, et un Fn::Contains écrit à l’intérieur, sont des clés de ce type. Aucune n’est un ID logique, et aucune n’est vérifiée.
Deux noms d’entrée que vous avez écrits séparément restent distincts
Trois sortes de noms d’entrée sont assez proches pour se rencontrer en un seul nom de sortie, et aucune n’est exotique. Comme les deux moitiés sont encodées plutôt que compactées, et se rencontrent sur une séquence qu’aucune des deux moitiés ne peut contenir, toutes trois aboutissent à des noms qui leur sont propres :
- Des entrées qui ne diffèrent que par la ponctuation. Un composant publiant à la fois
db-hostetdb_hostaboutit àdbXzhhostetdbXzuhost. - Des entrées qui ne diffèrent que par la casse d’une lettre.
hostetHostaboutissent àhostetHost, car une lettre est portée dans la casse où vous l’avez écrite. - Des entrées qui se rencontrent à travers la jonction. Le Component
payments-dbpublianthostaboutit àpaymentsXzhdbXXhost; le composantpaymentspubliantdb-hostaboutit àpaymentsXXdbXzhhost.
Deux entrées se rencontrent malgré tout là où elles nomment réellement une même chose. Le nom de sortie est construit à partir du composant qui publie et de l’entrée, de sorte que tout ce qui partage les deux aboutit à un seul nom, quel que soit l’encodage. Le cas que vous rencontrerez le plus probablement est une même Feature rattachée deux fois à un seul composant : un rattachement publie sous son hôte, de sorte que deux rattachements d’une Feature sur un composant publient tous deux alarm-id depuis payments-db, et rien dans la paire ne permet de les distinguer. Le build s’arrête plutôt que d’émettre une seule sortie là où deux ont été écrites, en nommant le composant et la clé de rattachement que portait chaque côté, de sorte que les deux extrémités sont recherchables dans vos propres fichiers. Rattachez la Feature une seule fois, ou utilisez une Feature dont les noms d’entrée publiés se lisent comme propres à ce rattachement.
Cela vaut que les deux entrées portent ou non la même valeur. Deux entrées ayant la même valeur décrivent tout de même deux sorties qu’un auteur a demandées, de sorte que les fusionner en une seule laisserait l’une des deux sorties écrites absente de la stack.
Un nom qu’une Recipe compose dans un template n’est pas couvert par ceci
L’encodage ci-dessus est celui du fournisseur, et il s’applique aux noms de sortie que construit le fournisseur. Il ne vous est pas disponible à l’intérieur d’un template de Recipe, et un nom que votre template compose ne porte donc aucune de ses garanties. Le dire clairement compte, car le risque est invisible depuis l’intérieur du template : le compactage disponible là lit son argument comme des mots et supprime tout ce qui se trouve entre eux, de sorte que joindre deux valeurs avant de les compacter perd la jonction en même temps que la ponctuation.
Une FeatureRecipe nommant une ressource à partir d’une instance et d’une clé de rattachement, jointes par un espace puis compactées, est la forme à surveiller — app avec cache et app-cache avec rien se compactent tous deux en AppCache, et les deux entrent en collision avant qu’aucune propriété du compactage ne s’applique. Deux choses maintiennent un tel nom distinct, et toutes deux vous reviennent plutôt qu’au fournisseur :
- Gardez les parties composées en lettres et en chiffres, de sorte que rien n’est supprimé et que rien n’a à être distingué.
- Ne joignez pas deux valeurs qui peuvent chacune contenir le séparateur de l’autre. Là où un nom doit porter deux parties, faites de l’une d’elles un littéral fixe que l’autre ne peut pas contenir.
Là où un nom composé entre bel et bien en collision, il entre en collision en tant qu’ID logique de ressource plutôt qu’en tant que nom de sortie, de sorte que l’arrêt que vous rencontrez est celui sur les noms de ressource décrit plus haut.
Une clé écrite deux fois dans un même mapping arrête le build
Un fragment CloudFormation est lu comme un mapping, et un mapping contient une valeur par clé, de sorte qu’une clé écrite deux fois conserverait le corps arrivé en dernier et écarterait l’autre. Là où le mapping est un bloc Resources ou Outputs, le corps écarté est une ressource ou une sortie qui a été écrite et qui ne serait tout simplement pas dans la stack.
Le build s’arrête à la place, en nommant la clé répétée et les deux lignes où elle a été écrite. C’est une règle qui porte sur le fragment entier plutôt qu’une règle sur les noms de la stack : elle s’applique à tout mapping du fragment, y compris les Properties d’une ressource. La façon la plus courante d’y arriver est une Recipe qui dérive un ID logique d’une valeur écrite par un auteur, là où deux valeurs écrites ne diffèrent que par la ponctuation — app-cache et app_cache dérivent tous deux AppCache, de sorte que le fragment écrit AppCache deux fois.
Un nom de clé qui revient à différents endroits du document est ordinaire et n’est pas touché : Type apparaît une fois par ressource, et Value une fois par sortie, quel que soit le nombre de ressources et de sorties que porte le fragment. Seule une répétition à l’intérieur d’un même mapping perd un corps.
Un seul composant peut revendiquer deux fois un même nom. Une Recipe apporte plusieurs fragments — plusieurs entrées artifacts:, ou un répertoire source contenant plusieurs templates — et chacun d’eux s’assemble dans la même stack, de sorte que les fragments propres à un composant partagent entre eux les noms de la stack exactement comme ils les partagent entre composants. Deux fragments qui donnent à un même nom deux corps différents arrêtent le build, et l’arrêt nomme l’espace de clés dans lequel se trouve le nom — ID logiques de ressource ou noms de sortie — ainsi que le composant et le nom lui-même. Les deux espaces sont atteignables de cette façon : deux fragments peuvent écrire un même ID logique de ressource sur des ressources différentes, et un composant atteint ses noms de sortie par deux voies, un bloc Outputs: explicite et ses entrées provides:, de sorte qu’une entrée de chacune portant un même nom s’y rencontre aussi.
Répéter un nom n’est pas en soi un conflit. Un nom écrit plus d’une fois avec un contenu identique adresse une seule chose de toute façon, de sorte que les répétitions fusionnent en une seule entrée et que le build se poursuit — une répétition ordinaire ne coûte rien. Ce qui arrête le build est le cas qui perd du contenu : l’un des deux corps devrait être écarté, et la ressource ou la sortie que la Recipe a déclarée manquerait alors dans la stack. Renommer l’un ou l’autre lève l’arrêt.
Validation structurelle des entrées
Un template CloudFormation source est validé structurellement avant son rendu : le fournisseur analyse le template et normalise ses fonctions intrinsèques, en arrêtant le build avec un message clair qui nomme le nœud fautif lorsqu’un template est mal formé. L’analyse vérifie la forme, pas la sémantique — elle ne contacte pas AWS, ne résout pas les références et n’évalue pas les fonctions intrinsèques.
Un template qui passe l’analyse n’est pas pour autant porté en entier. L’analyse dit que le document est bien formé ; ce qui atteint la stack assemblée est décidé séparément et section par section, sous Sections de premier niveau dans la stack assemblée — un template source passe par le même décompte qu’un fragment.
L’analyse ne se demande pas non plus si les références du template se résolvent. Savoir si un Ref nomme un paramètre, ou un Fn::FindInMap une table, est une question sur la stack assemblée plutôt que sur un document d’entrée particulier, et c’est à CloudFormation d’y répondre au moment du déploiement. Le build indique ce qu’il n’a pas porté au lieu de juger à quoi le résultat fait référence. Les références qu’il juge sont celles que le build lui-même a laissées pendantes : une vers un paramètre que la liaison d’un template source a renseigné, que traite la section suivante, et une vers une ressource qu’une entrée omits: a laissée hors du template, que traite la section d’après.
Valeurs des paramètres d’un template source
Un template source reçoit des valeurs de la façon dont CloudFormation lui-même donne des valeurs à un template : par les Parameters qu’il déclare. Le valuesMapping de ce qui l’utilise comme source — la Recipe d’un composant, ou la FeatureRecipe d’une Feature rattachée — écrit une clé par paramètre qu’il renseigne, et le fournisseur lie chacune dans chaque template de la source — chaque Ref vers le paramètre dans Resources, Outputs, Conditions, Rules et les Globals de SAM devient la valeur, chaque Fn::Sub nommant le paramètre comme variable reçoit la valeur par sa table de variables, et le paramètre quitte les Parameters de chaque template qui le déclare. Un paramètre qu’aucune clé ne nomme est laissé exactement tel que le template l’a écrit, pour une valeur passée au moment où la stack est déployée ou pour son Default.
La source est l’unité qui déclare un paramètre. Les templates d’une source de type répertoire s’assemblent en une seule stack, de sorte qu’un template peut référencer un paramètre que déclare un autre template de la même source. Renseigner le paramètre le renseigne là aussi : un template qui ne fait que le référencer reçoit la valeur telle que l’a convertie le premier template de la source qui le déclare, et plus rien dans la source ne référence un paramètre dont la liaison a supprimé la déclaration.
Rien d’autre dans la stack ne peut référencer un paramètre renseigné. Un contenu extérieur à la source — le fragment ou le template source d’un autre composant dans la même stack — qui nomme un paramètre que la liaison de la source a renseigné, par Ref, une variable de Fn::Sub ou le Fn::ValueOf d’une règle, nommerait quelque chose que la stack assemblée ne déclare plus, ce que CloudFormation refuse au moment où la stack est déployée. Le build s’arrête donc, en nommant chaque composant, son template et le paramètre, ainsi que le composant dont le valuesMapping l’a renseigné — celui d’une Recipe, ou celui de la FeatureRecipe d’une Feature rattachée ; une Feature rattachée à un composant est nommée par ce composant, et une Feature rattachée à une frontière par l’identité que ses ressources portent comme aggrega.ai/component-id, composée du chemin de la frontière et du nom du rattachement (bfr--stack--aux pour un rattachement aux sur la frontière stack). Le fragment du composant auquel une Feature est rattachée, ou d’un composant de la frontière à laquelle elle est rattachée, qui référence un paramètre que la liaison du rattachement a renseigné arrête lui aussi le build. Un nom que la stack déclare encore n’est pas concerné : là où un autre composant déclare lui-même un paramètre de ce nom, ou une ressource le porte comme ID logique, ses références se résolvent vers cette déclaration et sont laissées telles qu’elles sont écrites. Pour transmettre la valeur, faites-la publier par le composant qui renseigne le paramètre, déclarez le paramètre dans le template qui le référence, ou retirez la clé du valuesMapping.
spec: capability: cloudformation implements: core/delivery-stream:1.0.0 source: kind: git-repository url: https://github.com/aws-cloudformation/aws-cloudformation-templates.git ref: a0f43bc6d20813052892546f445037cf84c75b54 module_subdir: DataFirehose valuesMapping: | CloudWatchLogGroupRetention: {{ .values.retention_days }} DestinationBucketName: "{{ .context.inject.env.BUCKET_NAME }}"Seul un valuesMapping renseigne des paramètres. Les clés qu’il écrit sont les noms de paramètres que vous visiez pour le template, de sorte que chacune doit nommer un paramètre qu’un template de la source déclare : une clé qui n’en nomme aucun arrête le build, en nommant la clé et les paramètres que chaque template déclare effectivement — l’échec que CloudFormation signalerait pour un paramètre inconnu, signalé tant qu’il vous appartient encore de le corriger. Une Recipe ou une FeatureRecipe qui ne déclare aucun valuesMapping ne renseigne rien : les valeurs propres du composant ou du rattachement atteignent le fournisseur sous leurs propres noms, écrits pour ses autres entrées, et restent non lues.
Ce qu’est une valeur décide de ce qui atteint le template.
- Un littéral — une chaîne, un nombre, un booléen, ou une liste de ceux-ci — est écrit dans le template, converti de la façon dont CloudFormation convertit la même valeur passée pour le
Typedu paramètre au moment où la stack est déployée : unNumberdevient la chaîne que renvoie unRefvers lui, de sorte que7arrive sous la forme"7"; un typeCommaDelimitedListouList<…>devient une liste de chaînes, en acceptant soit une liste, soit une chaîne séparée par des virgules dont les membres sont débarrassés de leurs espaces ; tout autre type accepte une seule chaîne. Un littéral est vérifié par rapport auxAllowedValues,AllowedPattern,MinLength,MaxLength,MinValueetMaxValuedu paramètre lui-même, et un littéral qu’ils refusent arrête le build, en nommant le paramètre et la contrainte, de sorte que renseigner un paramètre ne supprime aucune vérification que le template a déclarée. Un motif écrit dans une syntaxe d’expressions régulières que le build ne sait pas lire est laissé à CloudFormation, qui le vérifie au moment où la stack est déployée. - Une valeur qui est entièrement une fonction intrinsèque de CloudFormation atteint l’emplacement de la référence en tant que cette fonction intrinsèque, pour que CloudFormation l’évalue au moment où la stack est déployée : un mapping en forme longue tel que
{"Fn::GetAtt": [Queue, Arn]}, ou une chaîne qui est exactement une forme courte —!GetAtt Queue.Arn,!Ref Bucket,!Sub …et les autres formes que définit CloudFormation. C’est ainsi que la référence publiée par un autre composant atteint un paramètre : les Recipes CloudFormation du catalogue publient une telle référence sous forme de texte en forme courte, et unvaluesMappingqui la lit dans le contexte d’injection la transmet. Une référence insérée se lit de la même façon entre guillemets ou sans. Entre guillemets —"{{ .context.inject.env.BUCKET_NAME }}"— le mapping transmet la chaîne!GetAtt Queue.Arn; sans guillemets, le YAML propre du mapping lit!GetAtt Queue.Arncomme un tag, et le tag est conservé avec son argument plutôt qu’écarté. L’une comme l’autre atteint le paramètre en tant que fonction intrinsèque. Une valeur qui ne fait que commencer par un point d’exclamation, ou qui ne nomme aucune forme courte de CloudFormation, reste du texte. - Une référence dynamique —
{{resolve:ssm:…}},{{resolve:ssm-secure:…}}ou{{resolve:secretsmanager:…}}— atteint l’emplacement de la référence telle qu’elle est écrite, pour que CloudFormation la résolve au moment où la stack est déployée, de sorte que la valeur qu’elle nomme n’est jamais dans le template. - Une valeur qu’un autre composant publie depuis une stack différente atteint le template sous la forme d’une référence entre stacks, le même
Fn::ImportValueouFn::GetStackOutputque reçoit un fragment (voir Câblage entre stacks), à chaque endroit où le template référençait le paramètre.
Un paramètre dont CloudFormation lit le type depuis Parameter Store — AWS::SSM::Parameter::Value<…> — n’a aucun littéral qui reproduise ce que CloudFormation en ferait, de sorte qu’un littéral lié à un tel paramètre arrête le build ; liez une référence {{resolve:ssm:…}} ou une fonction intrinsèque, ou laissez-le non lié. Une liste liée à un paramètre que le template nomme comme variable de Fn::Sub arrête elle aussi le build, car une variable substitue une seule chaîne. Une clé que le valuesMapping fixe à null arrête également le build, en nommant le paramètre, car un paramètre prend une valeur et null n’en est pas une ; pour laisser un paramètre à une valeur passée au moment où la stack est déployée ou à son Default, laissez sa clé hors du mapping.
Une règle qui lit un paramètre par son nom le garde non lié. Fn::ValueOf dans les Rules d’un template nomme un paramètre déclaré par son ID logique plutôt que par Ref, et renseigner le paramètre supprime sa déclaration, de sorte que lier un paramètre qu’une règle lit de cette façon arrête le build, en nommant la règle et le paramètre.
Un littéral susceptible de porter un secret est refusé ; une fonction intrinsèque est écrite telle qu’elle est donnée. Une valeur écrite dans le template est lisible par quiconque peut lire le template de la stack :
- Un paramètre que le template déclare
NoEchoaccepte une référence dynamique ou une fonction intrinsèque, et un littéral lié à lui arrête le build. - Là où le
valuesMappinglit une valeur qu’un auteur a déclarée sensible, rien de sa sortie ne permet de remonter à la valeur dont elle provient, de sorte que chaque littéral qu’il lie arrête le build. Une référence dynamique et une fonction intrinsèque qu’il lie sont écrites telles qu’elles sont données — y compris le texte à l’intérieur d’une fonction intrinsèque. Un secret que le mapping insère dans le texte d’unFn::Sub, par exemple, atteint donc le template sous la forme de ce texte : seule une référence dynamique garde le secret lui-même hors du template. Là où un tel build se poursuit, il affiche aussi un avertissement par feuille déclarée, pour le mapping d’une Recipe comme pour celui de la FeatureRecipe d’une Feature rattachée à un composant, en nommant la feuille et l’entité à laquelle appartient le mapping — voir A declared-sensitive value reaches the target through a values mapping (Une valeur déclarée sensible atteint la cible par un mappage values). - Une référence dynamique arrête le build là où son paramètre est référencé dans la propriété
UserDatad’une ressource, dans les métadonnéesAWS::CloudFormation::Initou dansOutputs: CloudFormation ne résout pas une référence dynamique dans les données utilisateur EC2 ni dans ces métadonnées, et montreOutputsà quiconque lit la stack.
Chacun de ces refus nomme les paramètres, et ne cite aucune valeur.
Laisser des ressources hors d’un template source
Les ressources d’un template source lui appartiennent : les valeurs ne l’atteignent que par les paramètres qu’il déclare, de sorte qu’un template récupéré depuis un dépôt git qui déclare une ressource que la Release ne doit pas créer — un bucket que l’opérateur fournit déjà, une clé que la plateforme gère ailleurs — ne peut pas être modifié par une valeur. C’est à cela que servent les entrées omits: d’une Recipe ou d’une FeatureRecipe. Ce fournisseur les respecte sur un template source et sur rien d’autre : les fragments qu’une entrée artifacts: écrit sont rendus sans elles.
spec: capability: cloudformation implements: core/store:1.0.0 source: kind: git-repository url: https://git.example.com/platform/templates.git ref: v3.2.0 module_subdir: store omits: # The template bundles an access-log bucket; this Release logs elsewhere. - kind: AWS::S3::Bucket name: StoreLogsUne entrée nomme une ressource par son Type et son ID logique. Le kind de l’entrée est le Type de la ressource, comme AWS::S3::Bucket, et son name est l’ID logique de la ressource, sa clé sous Resources ; les deux sont comparés exactement tels qu’ils sont écrits, et les deux doivent correspondre, de sorte qu’une entrée dont le Type est juste et dont l’ID logique ne l’est pas ne laisse rien de côté. Un template n’a pas d’espaces de noms, de sorte qu’une entrée portant un namespace arrête le build lorsque le composant est rendu, en nommant l’entrée ; chaque entrée est vérifiée avant que quoi que ce soit ne soit laissé de côté.
Chaque template de la source est examiné. Une source à fichier unique a un template. Une source de type répertoire — une source récupérée depuis un dépôt git en est toujours une — a chaque fichier se terminant par .yaml, .yml, .json ou .template, et une entrée laisse de côté chaque ressource qu’elle nomme dans n’importe lequel d’entre eux ; un fichier transporté à côté des templates n’est jamais lu. Le fournisseur indique combien de ressources chaque entrée a laissées de côté dans l’ensemble, et une entrée qui n’en a laissé aucune de côté arrête le build ; voir An omits entry left out nothing the source rendered (Une entrée omits n’a rien laissé de côté de ce que la source a rendu).
Une ressource laissée de côté a disparu avant que quoi que ce soit d’autre ne lise le template. Elle n’est pas marquée de sa provenance, n’est pas comptée parmi les noms que porte la stack — de sorte qu’un autre composant peut apporter une ressource sous le même ID logique sans que les deux se rencontrent — et elle n’atteint jamais la stack assemblée. Tout le reste du template est écrit exactement comme il l’aurait été si le template avait été écrit sans la ressource, et un template dont toutes les ressources sont laissées de côté conserve une section Resources vide.
Une ressource laissée de côté ne doit pas rester nommée par ce qui reste, car CloudFormation refuse un template qui nomme une ressource qu’il ne déclare pas. Une fois les ressources retirées, chaque référence que les templates restants font encore à l’une d’elles arrête le build, et le message nomme le template, la ressource, la manière dont la référence la nomme et l’endroit où se trouve la référence, sous forme de chemin depuis la racine du template — /Resources/Store/Properties/LoggingConfiguration/DestinationBucketName, par exemple. Une référence est ce que la référence des templates de CloudFormation définit comme le fait de nommer une ressource par son ID logique, lu dans le corps de chaque ressource — ses propriétés, ses métadonnées et ses politiques comprises — et dans chaque sortie :
Ref, avec l’ID logique comme argument ;Fn::GetAtt, sous forme de liste dont le premier élément est l’ID logique, ou sous forme d’une chaîne —!GetAtt StoreLogs.Arn— dont le texte avant le premier point l’est ;- le
DependsOnd’une ressource, sous forme d’un ID logique ou d’une liste d’ID logiques ; - chaque variable de
Fn::Sub, sous sa forme chaîne et sous sa forme liste :${StoreLogs}et${StoreLogs.Arn}nomment tous deuxStoreLogs.
Certaines valeurs ne font que ressembler à des références et ne sont pas lues comme telles. ${!StoreLogs} est du texte littéral, et une variable que nomme la map de la forme liste est la valeur de cette map. La Condition d’une ressource et le premier argument de Fn::If nomment une condition, Fn::FindInMap nomme un mappage, Fn::ImportValue un export d’une autre stack, et Fn::GetAZs une région. Les sections Conditions, Mappings, Parameters et Rules ne peuvent pas nommer de ressource, et la section Metadata de premier niveau propre au template est une information que CloudFormation stocke plutôt qu’il ne la lit, de sorte qu’aucune d’elles n’est vérifiée. Un Ref ou un Fn::GetAtt dont l’ID logique est lui-même écrit sous forme de fonction intrinsèque n’est valide que sous la transformation AWS::LanguageExtensions, qui le résout lorsque la stack est déployée (voir Sections de premier niveau dans la stack assemblée), de sorte qu’il ne nomme aucune ressource que la vérification puisse lire et est laissé tel quel ; il en va de même d’une référence à une ressource que la source n’a jamais déclarée.
La vérification lit ensemble les templates propres à la Recipe ou à la FeatureRecipe qui déclare. Ils s’assemblent en une seule stack, de sorte qu’une référence à un ID logique qu’un autre de ces templates déclare encore n’est pas arrêtée. Rien d’autre n’est lu : une référence à une ressource laissée de côté arrête le build même là où un autre composant déclare une ressource de cet ID logique, et une référence faite par quoi que ce soit d’autre qui s’assemble dans la stack — un autre composant, une Feature rattachée ou les propres entrées artifacts: de la Recipe — échappe à cette vérification, de sorte que CloudFormation refuse la stack lorsqu’elle est déployée. Pour conserver une référence, conservez la ressource. Une valeur liée à un paramètre ne remplace qu’une référence à ce paramètre, de sorte qu’une référence à une ressource appartient au template et ne peut pas être modifiée par une valeur : laissez aussi de côté la ressource qui la fait, ou retirez l’entrée. Une sortie n’est pas une ressource et aucune entrée n’en nomme une, de sorte qu’une ressource que nomment les Outputs du template ne peut pas en être laissée de côté : la laisser de côté arrête le build.
Annotations de cible cloud
Trois annotations de frontière indiquent au fournisseur où une stack est déployée, afin qu’il puisse câbler correctement les références entre stacks :
aggrega.ai/aws-account— le compte AWS dans lequel la stack est déployée.aggrega.ai/aws-region— la région AWS dans laquelle la stack est déployée.aggrega.ai/aws-assume-role-arn— l’ARN du rôle IAM qu’une lecture de stack entre comptes assume pour atteindre les valeurs exportées d’une stack homologue.
Ces annotations sont opaques pour le compilateur — il transmet leurs valeurs au fournisseur sans les interpréter (voir well-known-annotations.md). Elles sont écrites sur la frontière du producteur — la stack qui possède la valeur exportée. Une lecture entre comptes assume un rôle dans le compte du producteur, de sorte que le compte, la région et le rôle qui décrivent la lecture proviennent tous des annotations de la frontière du producteur, et non de celles du consommateur.
Références au sein d’une stack
Lorsqu’une arête uses relie deux composants qui aboutissent dans la même frontière — la même stack — la valeur consommée est câblée comme un Fn::GetAtt sur l’ID logique de la ressource du producteur au sein de l’unique template. La valeur provides du producteur s’écoule dans l’entrée rendue du consommateur sous forme de référence native au sein de la stack ; aucun export ni import n’est nécessaire. Le fragment du consommateur peut écrire une telle valeur sans guillemets — Value: {{ .context.inject.env.DB_HOST }} — ou entre guillemets — Value: "{{ .context.inject.env.DB_HOST }}" : dans les deux cas, le template lit !GetAtt Db.Endpoint.Address comme la fonction intrinsèque, car une chaîne qui est exactement une forme courte atteint la stack comme cette fonction intrinsèque dans un fragment comme dans un valuesMapping. L’exemple aws-rds-and-ecs-service le montre dans une définition de tâche Amazon ECS qui lit l’adresse d’une instance RDS dans une seule stack.
Câblage entre stacks
Lorsqu’une arête uses passe d’une frontière à une autre — les deux composants s’assemblent dans des stacks différentes — la référence ne peut pas être une simple valeur, car la valeur produite n’existe pas tant que la stack du producteur n’est pas déployée. Le fournisseur la câble comme une référence entre stacks de CloudFormation. La stack productrice publie la valeur comme Output de la stack avec un Export sous un nom d’export déterministe (dérivé de la release, de la frontière, du composant et de la clé fournie). La stack consommatrice la lit avec l’une de deux fonctions intrinsèques, choisie en comparant le placement déclaré des deux frontières :
Fn::ImportValue— le cas même compte, même région. CloudFormation résout l’import par rapport au nom d’export correspondant au sein du compte et de la région.Fn::GetStackOutput— une véritable lecture entre comptes ou entre régions. Le consommateur lit directement la sortie de la stack productrice, en assumant le rôleaws-assume-role-arnde la frontière du producteur dans le compte et la région du producteur.
Sémantique de détection. Le fournisseur oriente vers Fn::GetStackOutput uniquement lorsque les deux extrémités déclarent un placement (compte/région) et que ces placements diffèrent. Dans tous les autres cas — aucune ne déclare, une seule déclare, ou les deux déclarent le même placement — il utilise Fn::ImportValue. C’est une règle prudente : une lecture entre stacks dans le même compte reste un simple import, et la fonction intrinsèque de lecture directe est réservée à un véritable saut entre comptes ou entre régions.
La stack productrice publie toujours l’Export, même lorsqu’un consommateur particulier le lit entre comptes via Fn::GetStackOutput. Un export inutilisé est inerte, et le publier inconditionnellement garde le template du producteur indépendant de la manière dont chaque consommateur choisit de lire la valeur.
Plusieurs consommateurs d’une valeur lisent un seul export. Lorsque plus d’un composant lit la même valeur fournie à travers une frontière — deux consommateurs dans une stack, ou des consommateurs dans plusieurs stacks — la stack productrice publie l’Export de cette valeur une seule fois, et chaque consommateur lit l’unique nom : chaque Fn::ImportValue importe le même export, et un consommateur placé dans un autre compte ou une autre région lit la même sortie via Fn::GetStackOutput. Un consommateur qui lit aussi une valeur qu’aucun autre consommateur ne lit ajoute uniquement l’export de cette valeur.
L’exemple aws-rds-and-ecs-service construit le cas même compte : la stack d’une instance RDS exporte chaque entrée que consomme l’arête d’un serveur, et la stack du serveur relit chacune avec Fn::ImportValue.
Note de version.
Fn::GetStackOutputest une fonction intrinsèque native de CloudFormation. Une référence entre comptes rendue avec elle nécessite un outillage CloudFormation qui reconnaît la fonction intrinsèque. Le chemin même compte utiliseFn::ImportValue, qui est disponible partout.
Une valeur lue sur la connexion plutôt qu’injectée
La Recipe d’un consommateur peut lire les valeurs d’un producteur directement sur la connexion, via .context.uses.<alias>.provides, au lieu de les recevoir par le bloc inject de la connexion. À travers une limite de stack, une telle lecture est câblée de la même manière qu’une valeur injectée :
- Une valeur qui est une fonction intrinsèque CloudFormation — une balise de forme courte comme
!GetAtt Db.Endpoint.Address, ou unRefou un mappageFn::de forme longue — nomme quelque chose que seule la stack du producteur déclare, de sorte que le consommateur reçoit la même référence entre stacks qu’une valeur injectée : la stack productrice publie unExportpour cette clé, et le consommateur le lit avecFn::ImportValue, ou avecFn::GetStackOutputlorsque les deux frontières déclarent des placements qui diffèrent. - Une valeur qui est du texte brut — un port, un protocole, un nom de base de données — signifie la même chose dans l’une ou l’autre stack, de sorte que le consommateur reçoit la valeur elle-même et qu’aucun export n’est publié pour elle. Elle arrive sous la forme dans laquelle CloudFormation la lit : une valeur écrite entière est rendue comme elle l’aurait été sans la frontière, et une valeur d’allure numérique écrite entre guillemets arrive comme un nombre.
C’est ce fournisseur qui décide si une valeur est une fonction intrinsèque, en lisant la valeur de la même manière qu’il lit le bloc provides propre au producteur. Le compilateur transmet la valeur telle que la Recipe du producteur l’a écrite et ne l’interprète pas.
Un template ne peut que copier une telle valeur. Il peut écrire la valeur entière, ou à l’intérieur d’une chaîne plus longue, ou la passer par une fonction qui la laisse telle quelle, comme quote. Une comparaison, un branchement, une longueur ou une fonction qui modifie la valeur — eq, if, len, upper — serait décidé par rapport à autre chose que la valeur, car sur une telle connexion le template reçoit un substitut que le fournisseur remplace une fois les deux stacks assemblées. Le build s’arrête à la place, en nommant le template et chaque valeur qu’il a lue, avec la connexion sur laquelle il l’a lue et le composant à chaque extrémité ; faites porter le branchement sur une valeur propre au composant consommateur. Il en va de même pour l’injectMapping d’une FeatureRecipe rattachée et pour une FeatureRecipe de portée frontière qui lit les connexions de la frontière. Une valeur écrite à l’intérieur d’une chaîne plus longue se heurte aussi à la limite propre du fournisseur : une référence entre stacks ne peut figurer que comme valeur entière, de sorte qu’une fonction intrinsèque écrite à l’intérieur d’une chaîne plus longue arrête le build, comme pour une valeur injectée.
Comment un nom d’export est construit
Les quatre parties sont jointes par un double trait d’union, et chaque partie est écrite avec les lettres, chiffres et traits d’union dont est fait un nom d’export. Une lettre ou un chiffre est porté tel qu’il est écrit, de même qu’un trait d’union à l’intérieur d’une partie — payments-db reste payments-db. Tout autre caractère est écrit sous forme d’une courte séquence d’échappement commençant par -z : une barre oblique en -zs, un tiret bas en -zu, un point en -zd. Une partie sans aucune valeur s’écrit -ze. Un nom de stack est construit de la même manière à partir de la release et de la frontière.
Ainsi, l’export qui publie host depuis le composant db, dans la frontière dont le répertoire de sortie sous dist/ est stack-a/cloudformation, de la release orders, est :
aggrega--orders--stack-a-zscloudformation--db--hostLa relecture est sans ambiguïté, et c’est là le but plutôt qu’une coquetterie : comme une partie ne contient jamais deux traits d’union de suite et ne se termine jamais par un, les doubles traits d’union sont toujours les jonctions. Deux ensembles de parties différents produisent donc toujours deux noms différents. payments-db et payments_db aboutissent à deux exports distincts au lieu de converger vers un seul, et un trait d’union au bord d’une partie ne peut pas être lu comme appartenant à sa voisine.
Par rapport à quoi un nom d’export est unique, et où cela s’arrête
Au sein d’un build, un nom d’export identifie exactement une release, une frontière, un composant et une clé fournie — deux d’entre eux ne convergent jamais vers un même nom, de sorte qu’un build ne peut pas perdre une valeur exportée derrière une autre.
CloudFormation exige en outre qu’un nom d’export soit unique parmi tout ce qui est déjà déployé dans le compte et la région où la stack aboutit. C’est une propriété du déploiement plutôt que du build, et elle se situe au-delà de ce que toute dérivation au moment du build peut atteindre : le compilateur ne s’authentifie pas auprès d’AWS, ne l’interroge pas et ne peut pas lire la sortie d’un autre build, de sorte que rien de calculé à l’avance ne peut observer ce qui y est déjà déployé.
Ce qui porte la distinction au-delà de cette ligne, c’est l’identité de la release placée en tête de chaque nom d’export et de stack. Deux déploiements qui partagent un compte et une région gardent leurs exports séparés en étant publiés sous des noms différents — c’est le levier que vous tenez en main, et la raison pour laquelle l’identité de la release ouvre le nom plutôt que de le clore.
Une entrée Outputs peut déclarer son propre nom d’export
Le bloc Outputs: d’une Recipe est du CloudFormation rédigé par l’auteur, et une entrée de ce bloc peut porter son propre Export: avec un Name:. Ce nom atteint la stack assemblée exactement tel qu’il est écrit — le fournisseur ne le réécrit pas, ne lui ajoute pas de préfixe et n’exige pas qu’il ressemble à un nom dérivé.
En général, il n’y a rien de plus à en dire. Un nom d’export rédigé qui ne correspond à aucun nom que dérive le fournisseur est publié à côté des noms dérivés et ne fait jamais l’objet d’une remarque. Le rédiger est pris en charge ; seule une coïncidence ne l’est pas.
Le build s’arrête lorsqu’un nom d’export rédigé est égal à un nom que le fournisseur dérive pour un lien entre frontières dans le même build. Les deux déclarations atteindraient le template assemblé, laissant un même nom d’export déclaré deux fois dans une même stack — et un nom d’export doit être unique, donc les deux ne peuvent pas subsister. L’arrêt indique le nom d’export dérivé et les quatre parties à partir desquelles il a été construit, afin que vous puissiez voir quel lien l’a produit, et il nomme la sortie de stack sous laquelle se trouve la déclaration rédigée, marquée comme un nom que le fournisseur assemble plutôt qu’un nom écrit par une Recipe. Le nom d’export est le terme à rechercher dans vos Recipes. L’entrée rédigée l’écrit exactement comme l’arrêt — c’est cette identité qui fait des deux une collision —, c’est donc la seule chaîne qui apparaît à la fois dans le message et dans vos propres fichiers. Renommer le nom d’export que déclare cette entrée lève l’arrêt, tout comme supprimer le bloc Export: de cette entrée et laisser le câblage entre stacks publier l’export lui-même.
La vérification porte sur le build, et sa portée est une stack. Elle compare les noms d’export que déclare une stack assemblée aux noms que le fournisseur dérive pour les liens entre frontières qui publient dans cette même stack — la comparaison que le build peut faire à partir de ce qu’il a assemblé. Deux stacks ne sont pas comparées entre elles. Et ce qu’un nom rédigé rencontre parmi les exports déjà déployés dans un compte et une région est une propriété du déploiement, qui se situe au-delà de ce que toute dérivation au moment du build peut atteindre, pour la raison exposée sous Par rapport à quoi un nom d’export est unique, et où cela s’arrête : le compilateur ne s’authentifie pas auprès d’AWS, ne l’interroge pas et ne peut pas lire la sortie d’un autre build. Un nom d’export écrit sous forme de fonction intrinsèque plutôt que de chaîne simple se trouve de l’autre côté de la même ligne — il est résolu au moment du déploiement, et rien ici n’évalue une fonction intrinsèque, il n’y a donc aucun nom que le build puisse comparer.
Le build s’arrête aussi lorsque la sortie sur laquelle publie un lien entre frontières porte déjà un Export que le lien n’a pas écrit. Cette sortie est celle que le fournisseur assemble pour la clé fournie que lit un consommateur, de sorte qu’une Recipe dont le bloc Outputs: écrit une entrée sous cette même clé, avec son propre Export:, place son export exactement là où va celui du lien. À moins que le nom de cet export soit exactement celui que dérive le fournisseur — auquel cas c’est l’export du lien lui-même et chaque consommateur l’importe —, les deux ne peuvent pas subsister à cet endroit : écrire l’export du lien écraserait le vôtre, et conserver le vôtre laisserait chaque consommateur importer un nom que le lien n’a pas publié. L’arrêt indique le nom d’export dérivé et les quatre parties à partir desquelles il a été construit, et dit ce qu’il a trouvé à cette sortie : le nom d’export que déclare l’entrée, un nom écrit sous forme de fonction intrinsèque, un bloc Export: qui ne nomme rien, ou un Export: écrit comme valeur simple plutôt que comme bloc. Supprimer le bloc Export: de cette entrée le lève, et le câblage entre stacks publie alors l’export que chaque consommateur importe.
Ordre de déploiement
La valeur syncWave: d’une frontière de Release ordonne le provisionnement de la stack dans laquelle cette frontière s’assemble. Chaque composant de la frontière hérite de la vague de la frontière, et lorsque plusieurs frontières se résolvent vers le même répertoire de sortie — de sorte que leurs fragments s’assemblent en un seul template —, la stack contient plus d’une vague et le fournisseur exprime l’ordre entre elles sous forme de DependsOn.
Chaque ressource nomme chaque ressource de la vague immédiatement précédente qui contient des ressources, et aucune vague antérieure à celle-ci. CloudFormation enchaîne le reste : une ressource de la vague 2 dépend de la vague 1, qui dépend de la vague 0, de sorte que toute la séquence est ordonnée tandis que la liste propre à chaque ressource reste de la taille d’une seule vague plutôt que de la stack entière. Les vagues n’ont pas besoin d’être contiguës, et les valeurs négatives sont ordinaires — -1 est un choix courant pour un bucket ou un rôle que lit le reste de la stack. La vague la plus basse ne nomme rien, car rien ne la précède.
Ce qu’est l’ordre : l’ordre de création et, à l’inverse, l’ordre de suppression. CloudFormation opère sur les ressources en parallèle dans la mesure du possible, et DependsOn passe outre ce parallélisme pour opérer sur les ressources nommées dans un ordre déclaré. L’attribut régit les deux sens, de sorte qu’une vague qui crée une ressource plus tôt la supprime aussi plus tard — le bon séquencement du démantèlement découle de l’ordre sans rien exiger d’autre.
Ce n’est pas un ordre de disponibilité. Un template de stack n’exprime aucune notion de ressource opérationnelle, donc rien ici n’attend qu’une ressource devienne prête — seulement que CloudFormation finisse de la créer. C’est une vraie différence par rapport à la même vague sur compose, où un service qui déclare un healthcheck est attendu jusqu’à ce qu’il se signale en bonne santé : compose dispose d’une primitive de disponibilité sur laquelle s’appuyer et un template de stack n’en a aucune. L’ordre de création est ce que cette cible offre, et l’énoncer clairement est plus utile qu’une mise en garde attachée à une promesse qu’elle ne peut pas tenir.
Un DependsOn rédigé est étendu, jamais remplacé. Un fragment qui déclare sa propre contrainte d’ordre la conserve : les entrées qu’il a écrites restent en premier, dans l’ordre où il les a écrites, et les entrées de la vague suivent. Les deux exigences tiennent et aucune ne masque l’autre. Un ID logique unique et une liste sont tous deux lus, et la valeur fusionnée est émise sous forme de liste, qui est la seule écriture valable quel que soit le nombre d’entrées que produit la fusion.
Une stack dont les ressources portent toutes une même vague n’en retire rien. Il en va de même pour une Release qui ne déclare aucun syncWave : chaque contributeur porte la valeur par défaut du champ, 0, le template assemblé contient une seule vague, et la sortie est exactement ce qu’elle serait si le fournisseur n’exprimait aucun ordre de vagues.
L’ordre entre deux stacks n’est pas exprimable, et il n’est pas approximé. DependsOn nomme une ressource à l’intérieur du même template, et les composants qui s’assemblent dans une autre stack sont en dehors. Une vague ordonne donc chaque ressource de la stack dans laquelle elle s’assemble, et rien au-delà. Séquencer deux stacks relève de l’opérateur, de la même manière qu’une référence entre stacks est une résolution au moment du déploiement plutôt qu’au moment du build.
L’ordre que les vagues n’expriment pas reste l’affaire de CloudFormation lui-même, et les références entre ressources en portent déjà une grande partie : un Fn::GetAtt sur une ressource du producteur indique à CloudFormation de créer cette ressource en premier. Un fragment qui a besoin d’une contrainte que ni les références ni les vagues n’impliquent rédige lui-même DependsOn, ce qui est le cas que préserve la fusion ci-dessus.
Déterminisme
À entrées identiques, le fournisseur émet un template de stack identique octet pour octet d’une exécution à l’autre : les ID logiques, les clés de sortie, les noms d’export et l’ordre des ressources sont tous déterministes, de sorte qu’un template de stack CloudFormation produit des diffs propres en revue GitOps.