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

Provider CloudFormation

El proveedor cloudformation renderiza las Recipes de Aggrega en plantillas de stack de AWS CloudFormation. Cada componente que se renderiza en el mismo directorio de salida con este proveedor se ensambla en un único stack, emitido como una sola plantilla en JSON puro que usa funciones intrínsecas en forma larga. Un límite se convierte por tanto en un stack en el caso ordinario — y dos límites cuyo directory: se resuelve en la misma ruta se ensamblan juntos en un único stack, compartiendo los nombres de esa plantilla. Como todo proveedor de Aggrega, funciona sin conexión y es hermético — una compilación de Aggrega es una compilación anticipada, así que el proveedor nunca llama a AWS, nunca resuelve identificadores generados por la cuenta y nunca ejecuta CloudFormation. Los valores que solo existen en tiempo de ejecución permanecen como referencias intrínsecas de CloudFormation (Fn::GetAtt, Fn::ImportValue, Fn::GetStackOutput) que CloudFormation resuelve en el momento del despliegue.

Recipes de fragmentos ensambladas en un stack

Una Recipe cloudformation escribe un fragmento — los recursos de CloudFormation aportados por un solo componente — en lugar de una plantilla completa. Cuando los componentes de un límite se renderizan, el proveedor ensambla cada fragmento del grupo de despacho en una única plantilla de stack: los recursos se fusionan bajo un único mapa Resources, los valores provides de cada componente aparecen como Outputs del stack, y las demás secciones de nivel superior de la plantilla se tratan una por una en Secciones de nivel superior en el stack ensamblado. Se aceptan dos formas de autoría:

  • Entrada de fragmentos (artefactos). Una Recipe escribe directamente fragmentos de recursos; el proveedor los normaliza a JSON puro con funciones intrínsecas en forma larga y los fusiona en el stack ensamblado.
  • Entrada procedente de una fuente. Una Recipe hace referencia a una plantilla de CloudFormation existente (YAML o JSON); el proveedor la normaliza a JSON en forma larga y valida su estructura antes del ensamblado, rellena los parámetros que la plantilla declara a partir del valuesMapping de la Recipe — consulta Valores para los parámetros de una plantilla de origen — y deja fuera cualquier recurso que nombren las entradas omits: de la Recipe — consulta Dejar fuera recursos de una plantilla de origen.

La plantilla ensamblada es JSON puro. Las funciones intrínsecas se emiten literalmente y nunca se evalúan en tiempo de compilación — el compilador no puede resolver un valor que solo existe después de que se despliega el stack, y evaluar uno rompería el contrato de compilación anticipada.

Una Feature vinculada a un componente contribuye al mismo stack

Una Feature vinculada a un componente aporta sus recursos al stack en el que se ensambla su componente anfitrión, en las mismas condiciones que la propia Recipe del componente anfitrión. No hay ninguna plantilla separada junto a él: el stack ensamblado es la totalidad de lo que este proveedor emite para un directorio de salida, así que los recursos de una Feature vinculada o están en ese stack o no se despliegan en absoluto. Desvincular la Feature elimina exactamente esos recursos y deja intactos los propios del componente anfitrión.

Como acaban en el stack ensamblado, comparten sus nombres. Los ID lógicos de los recursos de una Feature vinculada están en el mismo espacio que los del componente anfitrión y que los de cualquier otra Feature vinculada junto a ella, así que Nombres en el stack ensamblado se aplica a ellos sin cambios. Donde dos contribuidores coinciden en un mismo nombre, la detención nombra el componente y la clave bajo la que está vinculada la Feature, de modo que ambos extremos de la colisión se pueden buscar en tus propios archivos.

Las salidas de una Feature vinculada se publican bajo el nombre de su componente anfitrión, y los ID lógicos de sus recursos no. Las dos mitades del stack se nombran según reglas distintas, así que responden a esto de forma distinta. El ID lógico de un recurso se emite exactamente como lo escribió la FeatureRecipe, como el de cualquier Recipe. Una salida se nombra a partir del componente que publica y de la entrada juntos — y para una Feature vinculada a un componente, el componente que publica es el anfitrión: una Feature vinculada a payments-db que publica alarm llega a paymentsXzhdbXXalarm, el mismo nombre al que llegaría si el componente anfitrión hubiera publicado esa entrada por sí mismo. Así que un nombre de entrada que el anfitrión también publica coincide con el de la vinculación en un mismo nombre de salida, y la compilación se detiene nombrando el componente y la clave bajo la que está vinculada la Feature junto al componente por sí solo. Elegir nombres de entrada que se lean como propios de la Feature — backup-alarm en lugar de alarm — los mantiene apartados de los del anfitrión.

Cada recurso que aporta una Feature conserva, en la procedencia que la compilación escribe en él, la identidad compuesta para esa vinculación en lugar de la del componente anfitrión, de modo que ambos siguen siendo distinguibles dentro de un stack al que ambos contribuyeron. Etiquetas y anotaciones explica cómo se construye esa identidad.

Secciones de nivel superior en el stack ensamblado

Varios componentes se ensamblan en un único stack, así que el ensamblado tiene que dar cuenta de cada sección de nivel superior que admite una plantilla de CloudFormation — incluidas Globals y Hooks, las dos secciones que una transformación alojada por CloudFormation añade al lenguaje de plantillas. Cada una cae exactamente en uno de los grupos de abajo, y una clave de nivel superior que escribe un componente y que no es ninguna sección recibe una advertencia que nombra el componente y la clave, así que nada se descarta sin decirlo.

Ensamblados bajo nombres a los que el proveedor da un ámbito, o leídos tal como están escritos. Resources y Outputs, que Nombres en el stack ensamblado trata por completo. AWSTemplateFormatVersion lo escribe el proveedor en lugar de leerlo de algún componente: el lenguaje de plantillas admite un único valor para él, así que no hay nada que un componente tenga que decidir.

Llevados con exactamente los nombres que escribiste. Parameters, Mappings, Conditions, Metadata y Rules. Cada una de ellas es un mapa con claves que elegiste tú, así que las entradas de cada componente llegan al stack ensamblado con esos nombres, sin reescribir — que es lo que permite que un Condition: de un recurso, un Fn::FindInMap o un Ref a un parámetro se resuelvan contra la declaración que llegó junto a ellos. Cada una se lleva por separado, porque cada una se escribe por separado: una regla hace aserciones sobre un parámetro del mismo documento, una condición puede no hacer referencia a ningún parámetro, y CloudFormation no permite una referencia a un parámetro dentro de un mapeo.

Una misma palabra cubre aquí dos lugares distintos, y solo el primero es tuyo. El Metadata de la lista anterior es la sección de nivel superior propia de la plantilla, un mapa de nombres que elegiste tú. Un recurso individual también lleva su propio atributo Metadata, y ahí es donde la compilación escribe la procedencia — bajo una única clave reservada aggrega.ai/, añadida junto a lo que hayas escrito ahí en lugar de sustituirlo. Así que una entrada de procedencia que aparece dentro de un recurso no es algo que escribiste tú ni algo que llevó la sección de nivel superior.

Parameters, Mappings, Conditions y Rules nombran sus entradas con un ID lógico. Como el proveedor lleva un nombre exactamente como lo escribiste, el alfabeto que admite un ID lógico alcanza también estas secciones: un nombre en una de las cuatro que contenga algo distinto de letras y dígitos detiene la compilación — consulta Un nombre de sección llevado fuera del alfabeto detiene la compilación. El proveedor no somete los nombres de la sección Metadata de nivel superior a ese alfabeto: nombran información que estás almacenando y no algo que la plantilla direccione.

Dos componentes que declaran nombres distintos en una de estas secciones llegan ambos. Dos que declaran un mismo nombre con contenido idéntico se fusionan en una única entrada y la compilación continúa. Dos que declaran un mismo nombre con contenido distinto detienen la compilación, nombrando la sección, el nombre y ambos componentes — porque, de lo contrario, uno de los dos cuerpos se descartaría y el componente que lo escribió quedaría con una declaración que el stack no lleva. Es la misma conciliación que siguen los nombres de recursos y de salidas, y renombrar cualquiera de los dos la resuelve.

Nombrados en lugar de llevados. Description es una única afirmación sobre una plantilla entera y no un mapa de nombres que elegiste tú, así que un ensamblado que toma de varios componentes no tiene respuesta para ella: dos descripciones son dos respuestas a una misma pregunta y ninguna es la del stack. Hooks solo lo lee la transformación AWS::CodeDeployBlueGreen, que el stack ensamblado nunca lleva (ver más abajo). Por tanto, el stack ensamblado no lleva ninguna de las dos secciones, y cada componente que escribió una recibe una advertencia que nombra el componente y la sección. Lo mismo ocurre con un componente que escribe Globals sin declarar la transformación AWS::Serverless-2016-10-31 que la lee. La advertencia es orientativa y fuera de banda: la plantilla emitida es byte a byte lo que sería sin ella, y --no-unsupported-field-warnings la silencia junto con el resto de esa clase.

Transform se construye a partir del de cada componente. Una transformación es una macro que CloudFormation ejecuta sobre toda la plantilla antes de desplegar nada, así que el Transform del stack ensamblado es la unión de las transformaciones que declaran sus componentes — las de una plantilla de origen igual que las de un fragmento — en el orden que documenta CloudFormation: una macro que define tu cuenta antes de las transformaciones que aloja CloudFormation, y AWS::LanguageExtensions antes de AWS::Serverless-2016-10-31. Se conserva el orden propio de cada componente, y dos transformaciones que nada ordena se ejecutan en el orden en que los componentes las declaran por primera vez, así que los mismos componentes dan el mismo stack. Una sola transformación se escribe como cadena y varias como lista. Un stack con un solo componente, que declara su Transform en una plantilla o un fragmento, lo conserva exactamente como se escribió allí donde la tabla de abajo lo lleva, y un stack cuyos componentes no declaran ninguna no lleva ninguna. La transformación de un componente no genera ninguna advertencia: se lleva, o la compilación se detiene nombrándola.

Como una transformación procesa toda la plantilla, llevar una cambia cómo se despliega el contenido de cada uno de los demás componentes, a menos que lo que hace se limite al contenido escrito para ella. Así que cada transformación recibe el tratamiento que respalda la propia documentación de CloudFormation sobre ella, y una combinación que el stack no puede llevar detiene la compilación, nombrando la transformación y cada componente del stack:

transformaciónen el stack ensamblado
AWS::Serverless-2016-10-31llevada, con los Globals del componente que la declara. Detiene la compilación donde esos Globals alcanzarían los recursos serverless de otro componente, y donde uno de los orígenes de eventos de sus recursos nombra un recurso que declara otro componente, porque la transformación reescribe el recurso que nombra un evento.
AWS::LanguageExtensionsllevada sola, o junto a AWS::Serverless-2016-10-31 del mismo componente. Detiene la compilación junto al contenido serverless de otro componente, porque la transformación serverless nombra lo que genera de otra forma una vez que las extensiones del lenguaje han resuelto sus valores.
AWS::SecretsManager-2020-07-23, AWS::SecretsManager-2024-09-16llevadas: solo procesan las programaciones de rotación que las solicitan.
AWS::ServiceCatalogllevada en un stack con un solo componente. Junto a cualquier otro detiene la compilación, porque sustituye su patrón de referencia en cualquier parte de la plantilla.
AWS::CodeDeployBlueGreendetiene la compilación, incluso sola: CloudFormation rechaza Outputs y Fn::ImportValue en cualquier parte de una plantilla que la declare, y el stack ensamblado lleva las salidas que publican sus componentes.
AWS::Includedetiene la compilación, incluso sola: inserta contenido obtenido de S3 cuando se despliega el stack, que la compilación no puede leer.
una macro que define tu cuentallevada en un stack con un solo componente. Junto a cualquier otro detiene la compilación, porque lo que hace al resto de la plantilla es desconocido para la compilación.

Dos componentes que declaran un mismo par de transformaciones en órdenes opuestos también detienen la compilación, nombrando ambos órdenes y ambos componentes, ya que el stack las ejecuta en un único orden. Un componente que necesita una transformación que el stack no puede llevar va en un límite propio.

Nombres en el stack ensamblado

Un ID lógico de CloudFormation es único dentro de una plantilla y solo admite letras y dígitos, y cada componente que se ensambla en esa plantilla comparte sus nombres — incluidos componentes de un segundo límite, cuando ambos se resuelven en el mismo directorio de salida. Así que cada nombre con el que el stack direcciona algo tiene que ser distinto entre todos los componentes que contribuyeron a él, y el conjunto de contribuidores no siempre es un único límite.

Los ID lógicos de recurso proceden de la Recipe. El proveedor los emite exactamente como se escribieron y no reescribe ninguno, así que el nombre que lees en la plantilla ensamblada es el nombre que escribió la Recipe. Las Recipes de CloudFormation de la biblioteca estándar lo derivan del propio nombre de la instancia del componente, leyendo los separadores de ese nombre como límites de palabra: la instancia payments-db nombra su recurso PaymentsDb. Por tanto, dos instancias del mismo tipo describen dos recursos en lugar de competir por uno.

Los nombres de salida tienen el ámbito del componente que los publicó. Cada entrada de provides aparece como una salida nombrada por el componente que publica y la entrada juntos — el componente payments-db que publica host aparece como paymentsXzhdbXXhost — así que dos componentes que publican la misma entrada llegan a dos salidas separadas, y el significado de una salida no cambia cuando otro componente se une al stack. Un consumidor entre stacks en la misma cuenta y región importa por el nombre de export y no por este, así que el nombre de export no se ve afectado; una lectura entre cuentas o entre regiones nombra esta salida, tal como el proveedor la escribe por ti (consulta Conexión entre stacks).

Cómo se construye un nombre de salida

Un ID lógico no admite ningún carácter separador, así que un nombre construido a partir de algo que escribiste tiene que llevar tus separadores de alguna manera. Quitarlos supondría una pérdida: payments-db y payments_db son dos componentes, y un nombre que quitara la puntuación no identificaría a ninguno. Así que el proveedor codifica en su lugar lo que el alfabeto rechaza, escribiendo cada carácter rechazado por extenso con caracteres que el alfabeto sí admite.

El esquema reserva un carácter con el que abrir una secuencia de escape — una X mayúscula — y escribe todo lo demás tal como lo tecleaste, mayúsculas incluidas. Solo se reserva la mayúscula, así que la x minúscula de un nombre como nginx-proxy se lleva tal como la escribiste:

lo que escribisteen qué se conviertepor qué
una letra o un dígito, salvo Xel propio carácterel alfabeto lo admite
-Xzhel alfabeto rechaza el guion
_Xzuel alfabeto rechaza el guion bajo
.Xzdel alfabeto rechaza el punto
/Xzsel alfabeto rechaza la barra, que lleva una identidad de componente anidada
XXzx000058reservado para abrir una secuencia de escape, así que se escribe por extenso mediante su punto de código
cualquier otra cosaXzx y el punto de código del carácteruna sola regla cubre cada carácter restante
el encuentro de las dos mitadesXXdos caracteres de apertura seguidos, que ninguna de las dos mitades puede contener

La relectura no es ambigua, y ese es el objetivo y no un detalle de cortesía. Una X se conserva como tal solo cuando el carácter que la sigue es uno que el alfabeto admite, así que una mitad codificada nunca termina con una ni lleva nunca dos seguidas — lo que deja XX libre para significar la unión, y solo la unión.

Así, tres nombres que solo difieren en dónde está su puntuación siguen separados:

component payments-db publishing host → paymentsXzhdbXXhost
component payments_db publishing host → paymentsXzudbXXhost
component payments publishing db-host → paymentsXXdbXzhhost

Los nombres son más largos y menos legibles a primera vista que el nombre de componente que escribiste, y ese es el compromiso. Un nombre que identifica exactamente una entrada vale más que uno más corto que no identifica a ninguna de dos — y direccionas una salida mediante el nombre de export en lugar de teclear este, así que lo que cuesta es un segundo vistazo al leer una plantilla emitida.

Los ID lógicos de recurso siguen una regla distinta, porque el proveedor no los construye: emite lo que escribió la Recipe. Las Recipes de CloudFormation de la biblioteca estándar derivan uno leyendo los separadores del nombre de la instancia como límites de palabra — la instancia payments-db nombra su recurso PaymentsDb — y esa derivación quita los separadores, así que dos nombres de instancia que solo difieren en la puntuación, o solo en las mayúsculas y minúsculas de una letra, derivan aun así un único nombre de recurso. La compilación se detiene, nombrando cada instancia que llegó al nombre junto con el nombre al que llegaron, en lugar de emitir un solo recurso donde se declararon dos componentes. Se nombran todas y no solo algunas, porque nada en una colisión convierte la derivación de una instancia en la intencionada. Renombrar todas menos una resuelve la detención.

Un ID lógico de recurso fuera del alfabeto detiene la compilación

La unicidad y el alfabeto son dos requisitos separados, y un conjunto de nombres puede cumplir el primero e incumplir el segundo. Como el proveedor emite un ID lógico de recurso exactamente como lo escribió la Recipe, el ID que escribe una Recipe tiene que ser uno que una plantilla de CloudFormation pueda contener por sí sola: letras y dígitos, y nada más.

Aquí es donde un nombre derivado y uno que se pasa tal cual se separan. Un nombre de salida lo construye el proveedor, que codifica el componente que publica y la entrada, así que un nombre de salida queda dentro del alfabeto se escriba como se escriba cualquiera de las dos mitades. Un ID lógico de recurso se pasa tal cual, así que lo que haya escrito la Recipe es lo que recibe la plantilla.

Eso lo convierte también en una restricción sobre los nombres de componente, siempre que una Recipe escribe el nombre de una instancia de componente directamente en el ID lógico. Un nombre de componente puede llevar un guion o un guion bajo; un ID lógico no. Un componente que diriges a este proveedor mediante una Recipe así se nombra, por tanto, solo con letras y dígitos — paymentsdb en lugar de payments-db — y cualquier otra cosa detiene la compilación.

La detención nombra el contribuidor cuya Recipe escribió el ID, el propio ID y cada carácter de él que no puede estar ahí, y dice qué puedes escribir en su lugar. Dos cosas la resuelven, y la primera es la que siempre tienes a tu alcance:

  • Haz que la Recipe escriba un ID lógico propio en lugar de pasar un nombre tal cual. Las Recipes de CloudFormation de la biblioteca estándar siguen este camino — leen los separadores del nombre de la instancia como límites de palabra, así que la instancia payments-db nombra su recurso PaymentsDb y conservas el nombre de componente que elegiste. Derivar un ID de esta forma cambia esta detención por la regla de colisión de arriba: dos nombres de instancia que solo difieren en la puntuación derivan un único nombre de recurso.
  • Donde una Recipe sí pasa un nombre tal cual, renombra lo que pasa usando solo letras y dígitos. Para la Recipe propia de un componente, eso es el nombre del componente. Una Feature vinculada a un componente nombra sus recursos a partir de su propia FeatureRecipe, así que renombrar el componente anfitrión no los alcanza — lo que tiene que cambiar es el ID que escribe esa Recipe.

El proveedor rechaza; no repara en silencio. Reescribir el ID por ti parecería lo útil, y no lo es. Un ID lógico es la forma en que CloudFormation identifica un recurso a través de las actualizaciones, así que cambiar uno no es un cambio de nombre — direcciona un recurso distinto. Un ID que el proveedor hubiera sustituido apuntaría a otro sitio que no es el recurso ya desplegado con el ID que escribiste, y la sustitución es una que nunca pediste y que tendrías que descubrir en la plantilla emitida. Una compilación que se detiene nombra el problema mientras todavía te corresponde corregirlo.

Un nombre de sección llevado fuera del alfabeto detiene la compilación

Los ID lógicos de recurso no son los únicos nombres que el proveedor lleva exactamente como los escribiste. Parameters, Mappings, Conditions y Rules también nombran sus entradas con un ID lógico, y cada una de las cuatro llega al stack ensamblado con el nombre que eligió su autor. Así que el requisito es el mismo, en cuatro superficies más: el nombre tiene que ser uno que una plantilla de CloudFormation pueda contener por sí sola — letras y dígitos, y nada más — y cualquier otra cosa detiene la compilación.

Hay una consecuencia que va más allá de la sección que lleva el nombre, y es la razón por la que esto detiene la compilación en lugar de advertir. Estos nombres son aquello contra lo que se resuelven el Condition: de un recurso, un Fn::FindInMap o un Ref a un parámetro. Por tanto, un nombre que el alfabeto no admite saca de la plantilla desplegable la referencia que apunta a él junto con la propia declaración, así que un único nombre escrito deja ambos fuera de alcance a la vez — y sin la detención eso se descubre en el momento del despliegue, por quien está desplegando y no por quien escribió el nombre.

La detención nombra el contribuidor cuya Recipe escribió el nombre, la sección en la que se escribió, el propio nombre y cada carácter de él que no puede estar ahí. La sección es el término que debes buscar en tus Recipes: estos nombres se llevan exactamente bajo la sección en la que los escribiste, así que es la única palabra que aparece tanto en el mensaje como en tus propios archivos. Renombrar la entrada solo con letras y dígitos la resuelve, y ese es todo el remedio — un ID lógico de recurso ofrece la alternativa de que la Recipe derive un ID en lugar de pasar un nombre tal cual, y aquí no hay nada que derivar, porque el nombre de la sección es lo que escribiste.

Solo los nombres propios de una sección están sujetos al alfabeto, nunca las claves dentro de una entrada. Las claves de segundo nivel de un mapeo las eliges libremente — us-east-1 bajo un mapa RegionCidr es el caso habitual, y llega intacta a la plantilla emitida. Las claves dentro del cuerpo de un parámetro, una condición o una regla nombran atributos, aserciones y funciones intrínsecas, no algo que el stack direccione: los Assertions de una regla, y un Fn::Contains escrito dentro de ella, son claves de ese tipo. Ninguna de ellas es un ID lógico, y ninguna se comprueba.

Dos nombres de entrada que escribiste por separado siguen separados

Tres tipos de nombres de entrada están lo bastante cerca como para encontrarse en un único nombre de salida, y ninguno es exótico. Como las dos mitades se codifican en lugar de compactarse, y se encuentran en una secuencia que ninguna de las dos mitades puede contener, los tres llegan a nombres propios:

  • Entradas que solo difieren en la puntuación. Un componente que publica tanto db-host como db_host llega a dbXzhhost y dbXzuhost.
  • Entradas que solo difieren en las mayúsculas y minúsculas de una letra. host y Host llegan a host y Host, porque una letra se lleva tal como la escribiste, en mayúscula o en minúscula.
  • Entradas que se encuentran a través de la unión. El Component payments-db que publica host llega a paymentsXzhdbXXhost; el componente payments que publica db-host llega a paymentsXXdbXzhhost.

Dos entradas se siguen encontrando donde de verdad nombran una misma cosa. El nombre de salida se construye a partir del componente que publica y de la entrada, así que todo lo que comparte ambos llega a un único nombre, se codifique como se codifique. El caso con el que es más probable que te encuentres es una misma Feature vinculada dos veces a un único componente: una vinculación publica bajo su anfitrión, así que dos vinculaciones de una Feature en un componente publican ambas alarm-id desde payments-db, y no hay nada en el par que permita distinguirlas. La compilación se detiene en lugar de emitir una única salida donde se escribieron dos, nombrando el componente y la clave de vinculación que llevaba cada lado, así que ambos extremos se pueden buscar en tus propios archivos. Vincula la Feature una sola vez, o usa una Feature cuyos nombres de entrada publicados se lean como propios de esa vinculación.

Esto se cumple tanto si las dos entradas llevan el mismo valor como si no. Dos entradas con el mismo valor siguen describiendo dos salidas que un autor pidió, así que fusionarlas en una dejaría una de las dos salidas escritas ausente del stack.

Un nombre que una Recipe compone en una plantilla no queda cubierto por esto

La codificación anterior es la del proveedor, y se aplica a los nombres de salida que construye el proveedor. No está disponible para ti dentro de una plantilla de Recipe, y un nombre que compone tu plantilla no lleva, por tanto, ninguna de sus garantías. Decirlo claramente importa porque el riesgo es invisible desde dentro de la plantilla: la compactación disponible allí lee su argumento como palabras y quita todo lo que hay entre ellas, así que unir dos valores antes de compactarlos pierde la unión junto con la puntuación.

Una FeatureRecipe que nombra un recurso a partir de una instancia y una clave de vinculación, unidas por un espacio y luego compactadas, es la forma que hay que vigilar — app con cache y app-cache sin nada se compactan ambas en AppCache, y las dos colisionan antes de que se aplique ninguna propiedad de la compactación. Dos cosas mantienen distinto un nombre así, y ambas te corresponden a ti y no al proveedor:

  • Mantén las partes compuestas en letras y dígitos, para que no se quite nada y no haya nada que distinguir.
  • No unas dos valores que puedan contener cada uno el separador del otro. Donde un nombre tenga que llevar dos partes, haz que una de ellas sea un literal fijo que la otra no pueda contener.

Donde un nombre compuesto sí colisiona, colisiona como ID lógico de recurso y no como nombre de salida, así que la detención con la que te encuentras es la de nombres de recurso descrita arriba.

Una clave escrita dos veces en un mismo mapeo detiene la compilación

Un fragmento de CloudFormation se lee como un mapeo, y un mapeo contiene un valor por clave, así que una clave escrita dos veces conservaría el cuerpo que llegó último y descartaría el otro. Donde el mapeo es un bloque Resources o Outputs, el cuerpo descartado es un recurso o una salida que se escribió y que simplemente no estaría en el stack.

En su lugar, la compilación se detiene, nombrando la clave repetida y las dos líneas en las que se escribió. Es una regla sobre el fragmento entero y no una regla sobre los nombres del stack: se aplica a cualquier mapeo del fragmento, incluidas las Properties de un recurso. La forma más común de llegar a ella es una Recipe que deriva un ID lógico de un valor escrito por un autor, donde dos valores escritos solo difieren en la puntuación — app-cache y app_cache derivan ambos AppCache, así que el fragmento escribe AppCache dos veces.

Un nombre de clave que se repite en distintos lugares del documento es habitual y no se toca: Type aparece una vez por recurso, y Value una vez por salida, por muchos recursos y salidas que lleve el fragmento. Solo una repetición dentro de un mismo mapeo pierde un cuerpo.

Un único componente puede reclamar un mismo nombre dos veces. Una Recipe aporta varios fragmentos — varias entradas de artifacts:, o un directorio de origen que contiene varias plantillas — y cada uno de ellos se ensambla en el mismo stack, así que los fragmentos propios de un componente comparten entre sí los nombres del stack exactamente como los comparten entre componentes. Dos fragmentos que dan a un mismo nombre dos cuerpos distintos detienen la compilación, y la detención nombra el espacio de claves en el que está el nombre — ID lógicos de recurso o nombres de salida — junto con el componente y el propio nombre. Ambos espacios se alcanzan de esta forma: dos fragmentos pueden escribir un mismo ID lógico de recurso sobre recursos distintos, y un componente llega a sus nombres de salida por dos vías, un bloque Outputs: explícito y sus entradas de provides:, así que una entrada de cada una que lleve un mismo nombre también se encuentra ahí.

Repetir un nombre no es en sí un conflicto. Un nombre escrito más de una vez con contenido idéntico direcciona una sola cosa de todos modos, así que las repeticiones se fusionan en una única entrada y la compilación continúa — una repetición habitual no cuesta nada. Lo que detiene la compilación es el caso que pierde contenido: uno de los dos cuerpos tendría que descartarse, y el recurso o la salida que declaró la Recipe faltaría entonces en el stack. Renombrar cualquiera de los dos lo resuelve.

Validación estructural de la entrada

Una plantilla de CloudFormation de origen se valida estructuralmente antes de renderizarse: el proveedor analiza la plantilla y normaliza sus funciones intrínsecas, deteniendo la compilación con un mensaje claro que nombra el nodo problemático cuando una plantilla está mal formada. El análisis comprueba la forma, no la semántica — no contacta con AWS, no resuelve referencias ni evalúa funciones intrínsecas.

Una plantilla que pasa el análisis no se lleva por ello entera. El análisis dice que el documento está bien formado; lo que llega al stack ensamblado se decide por separado y sección por sección, en Secciones de nivel superior en el stack ensamblado — una plantilla de origen pasa por el mismo recuento que un fragmento.

Tampoco pregunta el análisis si las referencias de la plantilla se resuelven. Si un Ref nombra un parámetro, o un Fn::FindInMap un mapa, es una pregunta sobre el stack ensamblado y no sobre un documento de entrada concreto, y le corresponde a CloudFormation responderla en el momento del despliegue. La compilación declara lo que no llevó en lugar de juzgar a qué se refiere el resultado. Las referencias que sí juzga son las que la propia compilación dejó colgando: una a un parámetro que rellenó el enlace de una plantilla de origen, que trata la sección siguiente, y una a un recurso que una entrada de omits: dejó fuera de la plantilla, que trata la sección posterior.

Valores para los parámetros de una plantilla de origen

Una plantilla de origen recibe valores del mismo modo en que CloudFormation da valores a una plantilla: a través de los Parameters que declara. El valuesMapping de aquello que la usa como fuente — la Recipe de un componente, o la FeatureRecipe de una Feature vinculada — escribe una clave por cada parámetro que rellena, y el proveedor enlaza cada una en cada plantilla de la fuente — cada Ref al parámetro en Resources, Outputs, Conditions, Rules y los Globals de SAM se convierte en el valor, cada Fn::Sub que nombra el parámetro como variable recibe el valor a través de su mapa de variables, y el parámetro sale de los Parameters de cada plantilla que lo declara. Un parámetro que ninguna clave nombra se deja exactamente como lo escribió la plantilla, para un valor que se pase cuando se despliegue el stack o para su Default.

La fuente es la unidad que declara un parámetro. Las plantillas de una fuente de directorio se ensamblan en un único stack, así que una plantilla puede hacer referencia a un parámetro que declara otra plantilla de la misma fuente. Rellenar el parámetro lo rellena también ahí: una plantilla que solo hace referencia a él recibe el valor tal como lo convirtió la primera plantilla de la fuente que lo declara, y nada en la fuente sigue haciendo referencia a un parámetro cuya declaración quitó el enlace.

Nada más en el stack puede hacer referencia a un parámetro rellenado. El contenido fuera de la fuente — el fragmento o la plantilla de origen de otro componente en el mismo stack — que nombra un parámetro que rellenó el enlace de la fuente, mediante Ref, una variable de Fn::Sub o el Fn::ValueOf de una regla, nombraría algo que el stack ensamblado ya no declara, cosa que CloudFormation rechaza cuando se despliega el stack. Así que la compilación se detiene, nombrando cada componente, su plantilla y el parámetro, y el componente cuyo valuesMapping lo rellenó — el de una Recipe, o el de la FeatureRecipe de una Feature vinculada; una Feature vinculada a un componente se nombra por ese componente, y una vinculada a un límite por la identidad que sus recursos llevan como aggrega.ai/component-id, compuesta a partir de la ruta del límite y el nombre de la vinculación (bfr--stack--aux para una vinculación aux en el límite stack). El fragmento del componente al que está vinculada una Feature, o de un componente del límite al que está vinculada, que hace referencia a un parámetro que rellenó el enlace de la vinculación también detiene la compilación. Un nombre que el stack todavía declara no se ve afectado: donde otro componente declara él mismo un parámetro con ese nombre, o un recurso lo lleva como su ID lógico, sus referencias se resuelven contra esa declaración y se dejan tal como están escritas. Para transmitir el valor, haz que el componente que lo rellena lo publique, declara el parámetro en la plantilla que hace referencia a él, o quita la clave del 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 }}"

Solo un valuesMapping rellena parámetros. Las claves que escribe son los nombres de parámetro que querías para la plantilla, así que cada una tiene que nombrar un parámetro que declare alguna plantilla de la fuente: una clave que no nombra ninguno detiene la compilación, nombrando la clave y los parámetros que sí declara cada plantilla — el fallo que CloudFormation notificaría para un parámetro desconocido, notificado mientras todavía te corresponde corregirlo. Una Recipe o una FeatureRecipe que no declara ningún valuesMapping no rellena nada: los valores propios del componente o de la vinculación llegan al proveedor con sus propios nombres, escritos para sus otras entradas, y quedan sin leer.

Lo que es un valor decide lo que llega a la plantilla.

  • Un literal — una cadena, un número, un booleano o una lista de ellos — se escribe en la plantilla, convertido del modo en que CloudFormation convierte el mismo valor pasado para el Type del parámetro cuando se despliega el stack: un Number se convierte en la cadena que devuelve un Ref a él, así que 7 llega como "7"; un tipo CommaDelimitedList o List<…> se convierte en una lista de cadenas, y acepta una lista o una cadena separada por comas cuyos miembros se recortan; cualquier otro tipo acepta una sola cadena. Un literal se comprueba contra los propios AllowedValues, AllowedPattern, MinLength, MaxLength, MinValue y MaxValue del parámetro, y uno que estos rechacen detiene la compilación, nombrando el parámetro y la restricción, así que rellenar un parámetro no elimina ninguna comprobación que la plantilla haya declarado. Un patrón escrito en una sintaxis de expresiones regulares que la compilación no sabe leer se deja para que CloudFormation lo compruebe cuando se despliegue el stack.
  • Un valor que es por completo una función intrínseca de CloudFormation llega al punto de la referencia como esa función intrínseca, para que CloudFormation la evalúe cuando se despliegue el stack: un mapeo en forma larga como {"Fn::GetAtt": [Queue, Arn]}, o una cadena que es exactamente una forma corta — !GetAtt Queue.Arn, !Ref Bucket, !Sub … y las demás formas que define CloudFormation. Así es como la referencia publicada por otro componente llega a un parámetro: las Recipes de CloudFormation del catálogo publican una referencia así como texto en forma corta, y un valuesMapping que la lee del contexto de inyección la transmite. Una referencia insertada se lee igual entre comillas o sin ellas. Entre comillas — "{{ .context.inject.env.BUCKET_NAME }}" — el mapeo transmite la cadena !GetAtt Queue.Arn; sin comillas, el propio YAML del mapeo lee !GetAtt Queue.Arn como un tag, y el tag se conserva con su argumento en lugar de descartarse. Cualquiera de las dos llega al parámetro como la función intrínseca. Un valor que solo empieza con un signo de exclamación, o que no nombra ninguna forma corta de CloudFormation, sigue siendo texto.
  • Una referencia dinámica — {{resolve:ssm:…}}, {{resolve:ssm-secure:…}} o {{resolve:secretsmanager:…}} — llega al punto de la referencia tal como está escrita, para que CloudFormation la resuelva cuando se despliegue el stack, así que el valor que nombra nunca está en la plantilla.
  • Un valor que otro componente publica desde un stack distinto llega a la plantilla como una referencia entre stacks, el mismo Fn::ImportValue o Fn::GetStackOutput que recibe un fragmento (consulta Conexión entre stacks), en cada lugar donde la plantilla hacía referencia al parámetro.

Un parámetro cuyo tipo CloudFormation lee de Parameter Store — AWS::SSM::Parameter::Value<…> — no tiene ningún literal que reproduzca lo que CloudFormation haría con él, así que un literal enlazado a uno de ellos detiene la compilación; enlaza una referencia {{resolve:ssm:…}} o una función intrínseca, o déjalo sin enlazar. Una lista enlazada a un parámetro que la plantilla nombra como variable de Fn::Sub también detiene la compilación, porque una variable sustituye una sola cadena. Una clave que el valuesMapping establece en null detiene igualmente la compilación, nombrando el parámetro, porque un parámetro acepta un valor y null no lo es; para dejar un parámetro a un valor que se pase cuando se despliegue el stack o a su Default, deja su clave fuera del mapeo.

Una regla que lee un parámetro por su nombre lo mantiene sin enlazar. Fn::ValueOf en las Rules de una plantilla nombra un parámetro declarado por su ID lógico en lugar de mediante Ref, y rellenar el parámetro elimina su declaración, así que enlazar uno que una regla lee de ese modo detiene la compilación, nombrando la regla y el parámetro.

Un literal que puede llevar un secreto se rechaza; una función intrínseca se escribe tal como se da. Un valor que se escribe en la plantilla es legible para cualquiera que pueda leer la plantilla del stack:

  • Un parámetro que la plantilla declara NoEcho acepta una referencia dinámica o una función intrínseca, y un literal enlazado a él detiene la compilación.
  • Donde el valuesMapping lee un valor que un autor declaró sensible, nada de su salida puede rastrearse hasta el valor del que procede, así que cada literal que enlaza detiene la compilación. Una referencia dinámica y una función intrínseca que enlaza se escriben tal como se dan — incluido el texto dentro de una función intrínseca. Un secreto que el mapeo inserta en el texto de un Fn::Sub, por ejemplo, llega por tanto a la plantilla como ese texto: solo una referencia dinámica mantiene el propio secreto fuera de la plantilla. Donde una compilación así continúa, también imprime un aviso por cada hoja declarada, tanto para el mapeo de una Recipe como para el de la FeatureRecipe de una Feature vinculada a un componente, nombrando la hoja y la entidad a la que pertenece el mapeo — consulta A declared-sensitive value reaches the target through a values mapping (Un valor declarado sensible llega al destino a través de un mapeo de values).
  • Una referencia dinámica detiene la compilación donde su parámetro se referencia en la propiedad UserData de un recurso, en los metadatos de AWS::CloudFormation::Init o en Outputs: CloudFormation no resuelve una referencia dinámica en los datos de usuario de EC2 ni en esos metadatos, y muestra Outputs a quien lea el stack.

Cada uno de estos rechazos nombra los parámetros y no cita ningún valor.

Dejar recursos fuera de una plantilla de origen

Los recursos de una plantilla de origen son suyos: los valores solo la alcanzan a través de los parámetros que declara, así que una plantilla obtenida de un repositorio git que declara un recurso que la Release no debe crear — un bucket que el operador ya proporciona, una clave que la plataforma gestiona en otro lugar — no puede cambiarse con un valor. Para eso sirven las entradas omits: de una Recipe o de una FeatureRecipe. Este proveedor las respeta en una plantilla de origen y en nada más: los fragmentos que escribe una entrada artifacts: se renderizan sin ellas.

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: StoreLogs

Una entrada nombra un recurso por su Type y su ID lógico. El kind de la entrada es el Type del recurso, como AWS::S3::Bucket, y su name es el ID lógico del recurso, su clave bajo Resources; ambos se comparan exactamente como están escritos, y ambos tienen que coincidir, así que una entrada cuyo Type es correcto y cuyo ID lógico no lo es no deja nada fuera. Una plantilla no tiene espacios de nombres, así que una entrada que lleva un namespace detiene la compilación cuando se renderiza el componente, nombrando la entrada; cada entrada se comprueba antes de dejar nada fuera.

Se compara cada plantilla de la fuente. Una fuente de un solo archivo tiene una plantilla. Una fuente de directorio — una fuente obtenida de un repositorio git siempre lo es — tiene cada archivo que termina en .yaml, .yml, .json o .template, y una entrada deja fuera cada recurso que nombra en cualquiera de ellos; un archivo que acompaña a las plantillas nunca se lee. El proveedor informa de cuántos recursos dejó fuera cada entrada en todas ellas, y una entrada que no dejó ninguno fuera detiene la compilación; consulta An omits entry left out nothing the source rendered (Una entrada omits no dejó fuera nada de lo que renderizó la fuente).

Un recurso que se deja fuera desaparece antes de que cualquier otra cosa lea la plantilla. No se marca con procedencia, no se cuenta entre los nombres que lleva el stack — así que otro componente puede aportar un recurso con el mismo ID lógico sin que ambos se encuentren — y nunca llega al stack ensamblado. Todo lo demás de la plantilla se escribe exactamente como se habría escrito si la plantilla se hubiera creado sin el recurso, y una plantilla de la que se dejan fuera todos los recursos conserva una sección Resources vacía.

Un recurso que se deja fuera no debe seguir nombrado por lo que queda, porque CloudFormation rechaza una plantilla que nombra un recurso que no declara. Una vez eliminados los recursos, cada referencia que las plantillas restantes todavía hacen a uno de ellos detiene la compilación, y el mensaje nombra la plantilla, el recurso, cómo lo nombra la referencia y dónde se encuentra la referencia, como una ruta desde la raíz de la plantilla — /Resources/Store/Properties/LoggingConfiguration/DestinationBucketName, por ejemplo. Una referencia es lo que la referencia de plantillas de CloudFormation define como nombrar un recurso por su ID lógico, leído en el cuerpo de cada recurso — incluidas sus propiedades, sus metadatos y sus políticas — y en cada salida:

  • Ref, con el ID lógico como argumento;
  • Fn::GetAtt, como una lista cuyo primer elemento es el ID lógico, o como una cadena — !GetAtt StoreLogs.Arn — cuyo texto antes del primer punto lo es;
  • el DependsOn de un recurso, como un ID lógico o una lista de ellos;
  • cada variable de Fn::Sub, en su forma de cadena y en su forma de lista: ${StoreLogs} y ${StoreLogs.Arn} nombran ambas StoreLogs.

Algunos valores solo parecen referencias y no se leen como tales. ${!StoreLogs} es texto literal, y una variable que nombra el mapa de la forma de lista es el valor de ese mapa. La Condition de un recurso y el primer argumento de Fn::If nombran una condición, Fn::FindInMap nombra un mapeo, Fn::ImportValue un export de otro stack y Fn::GetAZs una región. Las secciones Conditions, Mappings, Parameters y Rules no pueden nombrar un recurso, y la sección Metadata de nivel superior propia de la plantilla es información que CloudFormation almacena en lugar de leer, así que ninguna de ellas se comprueba. Un Ref o un Fn::GetAtt cuyo ID lógico está escrito a su vez como una función intrínseca solo es válido bajo la transformación AWS::LanguageExtensions, que lo resuelve cuando se despliega el stack (consulta Secciones de nivel superior en el stack ensamblado), así que no nombra ningún recurso que la comprobación pueda leer y se deja como está; lo mismo ocurre con una referencia a un recurso que la fuente nunca declaró.

La comprobación lee juntas las plantillas propias de la Recipe o la FeatureRecipe que declara. Se ensamblan en un solo stack, así que una referencia a un ID lógico que otra de esas plantillas todavía declara no se detiene. No se lee nada más: una referencia a un recurso que se deja fuera detiene la compilación incluso donde otro componente declara un recurso con ese ID lógico, y una referencia hecha por cualquier otra cosa que se ensambla en el stack — otro componente, una Feature vinculada o las propias entradas artifacts: de la Recipe — queda fuera de lo que esta comprobación ve, así que CloudFormation rechaza el stack cuando se despliega. Para conservar una referencia, conserva el recurso. Un valor vinculado a un parámetro sustituye solo una referencia a ese parámetro, así que una referencia a un recurso es propia de la plantilla y no puede cambiarse con un valor: deja fuera también el recurso que la hace, o elimina la entrada. Una salida no es un recurso y ninguna entrada nombra una, así que un recurso que nombran las Outputs de la plantilla no puede dejarse fuera de ella: dejarlo fuera detiene la compilación.

Anotaciones de destino en la nube

Tres anotaciones de límite indican al proveedor dónde se despliega un stack, para que pueda conectar correctamente las referencias entre stacks:

  • aggrega.ai/aws-account — la cuenta de AWS en la que se despliega el stack.
  • aggrega.ai/aws-region — la región de AWS en la que se despliega el stack.
  • aggrega.ai/aws-assume-role-arn — el ARN del rol de IAM que asume una lectura de stack entre cuentas para llegar a los valores exportados de un stack homólogo.

Estas anotaciones son opacas para el compilador — canaliza sus valores hasta el proveedor sin interpretarlos (consulta well-known-annotations.md). Se escriben en el límite del productor — el stack que posee el valor exportado. Una lectura entre cuentas asume un rol en la cuenta del productor, así que la cuenta, la región y el rol que describen la lectura provienen todos de las anotaciones del límite del productor, no de las del consumidor.

Referencias dentro del stack

Cuando una arista uses conecta dos componentes que caen en el mismo límite — el mismo stack — el valor consumido se conecta como un Fn::GetAtt contra el ID lógico del recurso del productor dentro de la única plantilla. El valor provides del productor fluye a la entrada renderizada del consumidor como una referencia nativa dentro del stack; no se necesita ningún export ni import. El fragmento del consumidor puede escribir ese valor sin comillas — Value: {{ .context.inject.env.DB_HOST }} — o entre comillas — Value: "{{ .context.inject.env.DB_HOST }}": en ambos casos la plantilla lee !GetAtt Db.Endpoint.Address como la función intrínseca, porque una cadena que es exactamente una forma corta llega al stack como esa función intrínseca en un fragmento igual que en un valuesMapping. El ejemplo aws-rds-and-ecs-service lo muestra en una definición de tarea de Amazon ECS que lee la dirección de una instancia de RDS en un solo stack.

Conexión entre stacks

Cuando una arista uses pasa de un límite a otro — los dos componentes se ensamblan en stacks diferentes — la referencia no puede ser un valor simple, porque el valor producido no existe hasta que se despliega el stack del productor. El proveedor la conecta como una referencia entre stacks de CloudFormation. El stack productor publica el valor como un Output del stack con un Export bajo un nombre de export determinista (derivado de la release, el límite, el componente y la clave proporcionada). El stack consumidor lo lee con una de dos funciones intrínsecas, elegida comparando la ubicación declarada de los dos límites:

  • Fn::ImportValue — el caso de la misma cuenta y la misma región. CloudFormation resuelve el import contra el nombre de export correspondiente dentro de la cuenta y la región.
  • Fn::GetStackOutput — una lectura auténtica entre cuentas o entre regiones. El consumidor lee directamente la salida del stack productor, asumiendo el rol aws-assume-role-arn del límite del productor en la cuenta y la región del productor.

Semántica de detección. El proveedor dirige a Fn::GetStackOutput solo cuando ambos extremos declaran una ubicación (cuenta/región) y esas ubicaciones difieren. En cualquier otro caso — ninguno la declara, solo uno la declara, o ambos declaran la misma ubicación — usa Fn::ImportValue. Es una regla conservadora: una lectura entre stacks en la misma cuenta sigue siendo un import simple, y la función intrínseca de lectura directa se reserva para un salto real entre cuentas o entre regiones.

El stack productor siempre publica el Export, incluso cuando un consumidor concreto lo lee entre cuentas mediante Fn::GetStackOutput. Un export sin usar es inerte, y publicarlo incondicionalmente mantiene la plantilla del productor independiente de cómo elige cada consumidor leer el valor.

Varios consumidores de un valor leen un único export. Cuando más de un componente lee el mismo valor proporcionado a través de un límite — dos consumidores en un stack, o consumidores en varios stacks — el stack productor publica el Export de ese valor una sola vez, y cada consumidor lee el único nombre: cada Fn::ImportValue importa el mismo export, y un consumidor situado en otra cuenta o región lee la misma salida mediante Fn::GetStackOutput. Un consumidor que además lee un valor que ningún otro consumidor lee añade solo el export de ese valor.

El ejemplo aws-rds-and-ecs-service construye el caso de la misma cuenta: el stack de una instancia de RDS exporta cada entrada que consume la arista de un servidor, y el stack del servidor vuelve a leer cada una con Fn::ImportValue.

Nota de versión. Fn::GetStackOutput es una función intrínseca nativa de CloudFormation. Una referencia entre cuentas renderizada con ella requiere herramientas de CloudFormation que reconozcan la función intrínseca. La ruta de la misma cuenta usa Fn::ImportValue, que está disponible en todas partes.

Un valor leído de la conexión en lugar de inyectado

La Recipe de un consumidor puede leer los valores de un productor directamente de la conexión, mediante .context.uses.<alias>.provides, en lugar de recibirlos a través del bloque inject de la conexión. A través de un borde de stack, esa lectura se conecta del mismo modo que un valor inyectado:

  • Un valor que es una función intrínseca de CloudFormation — una etiqueta de forma corta como !GetAtt Db.Endpoint.Address, o un Ref o un mapeo Fn:: de forma larga — nombra algo que solo declara el stack del productor, así que el consumidor recibe la misma referencia entre stacks que recibe un valor inyectado: el stack productor publica un Export para esa clave, y el consumidor lo lee con Fn::ImportValue, o con Fn::GetStackOutput donde los dos límites declaran ubicaciones que difieren.
  • Un valor que es texto plano — un puerto, un protocolo, un nombre de base de datos — significa lo mismo en cualquiera de los dos stacks, así que el consumidor recibe el valor en sí y no se publica ningún export para él. Llega en la forma en que CloudFormation lo lee: un valor escrito entero se renderiza como lo habría hecho sin el límite, y un valor con forma de número escrito entre comillas llega como un número.

Si un valor es una función intrínseca lo decide este proveedor, leyendo el valor del modo en que lee el bloque provides propio del productor. El compilador entrega el valor tal como lo escribió la Recipe del productor y no lo interpreta.

Una plantilla solo puede copiar un valor así. Puede escribir el valor entero, o dentro de una cadena más larga, o pasarlo por una función que lo deja como está, como quote. Una comparación, una bifurcación, una longitud o una función que cambia el valor — eq, if, len, upper — se decidiría contra algo distinto del valor, porque en una conexión así la plantilla recibe un sustituto que el proveedor reemplaza una vez ensamblados ambos stacks. En su lugar, la compilación se detiene, nombrando la plantilla y cada valor que leyó, con la conexión de la que lo leyó y el componente en cada extremo; bifurca sobre un valor propio del componente consumidor. Lo mismo vale para el injectMapping de una FeatureRecipe vinculada y para una FeatureRecipe de ámbito de límite que lee las conexiones del límite. Un valor escrito dentro de una cadena más larga se topa además con la restricción propia del proveedor: una referencia entre stacks solo puede figurar como un valor entero, así que una función intrínseca escrita dentro de una cadena más larga detiene la compilación, como ocurre con un valor inyectado.

Cómo se construye un nombre de export

Las cuatro partes se unen con un doble guion, y cada parte se escribe con las letras, los dígitos y los guiones de los que se compone un nombre de export. Una letra o un dígito se lleva tal como está escrito, y también un guion dentro de una parte — payments-db sigue siendo payments-db. Cualquier otro carácter se escribe como un escape corto que empieza por -z: una barra como -zs, un guion bajo como -zu, un punto como -zd. Una parte sin ningún valor se escribe -ze. Un nombre de stack se construye del mismo modo a partir de la release y el límite.

Así que el export que publica host del componente db, en el límite cuyo directorio de salida bajo dist/ es stack-a/cloudformation, de la release orders, es:

aggrega--orders--stack-a-zscloudformation--db--host

La relectura es inequívoca, y ese es el objetivo y no un detalle de cortesía: como una parte nunca contiene dos guiones seguidos y nunca termina en uno, los guiones dobles son siempre las uniones. Por tanto, dos conjuntos de partes diferentes siempre producen dos nombres diferentes. payments-db y payments_db llegan a dos exports separados en lugar de converger en uno, y un guion en el borde de una parte no puede leerse como perteneciente a su vecina.

Frente a qué es único un nombre de export, y dónde termina eso

Dentro de una compilación, un nombre de export identifica exactamente una release, un límite, un componente y una clave proporcionada — no hay dos de ellos que converjan en un mismo nombre, así que una compilación no puede perder un valor exportado detrás de otro.

CloudFormation exige además que un nombre de export sea único entre todo lo ya desplegado en la cuenta y la región en las que cae el stack. Esa es una propiedad del despliegue y no de la compilación, y queda fuera del alcance de cualquier derivación en tiempo de compilación: el compilador no se autentica ante AWS, no lo consulta y no puede leer la salida de otra compilación, así que nada calculado de antemano puede observar lo que ya está desplegado allí.

Lo que lleva la distinción más allá de esa línea es la identidad de la release que encabeza cada nombre de export y de stack. Dos despliegues que comparten una cuenta y una región mantienen separados sus exports al publicarse con nombres diferentes — esa es la palanca que tienes en la mano, y la razón por la que la identidad de la release encabeza el nombre en lugar de cerrarlo.

Una entrada de Outputs puede declarar su propio nombre de export

El bloque Outputs: de una Recipe es CloudFormation escrito por el autor, y una entrada en él puede llevar su propio Export: con un Name:. Ese nombre llega al stack ensamblado exactamente como está escrito — el proveedor no lo reescribe, no le añade un prefijo y no exige que se parezca a uno derivado.

Normalmente no hay nada más que decir al respecto. Un nombre de export escrito por el autor que no coincide con ningún nombre que derive el proveedor se publica junto a los derivados y nunca se señala. Escribirlo está admitido; solo una coincidencia no lo está.

La compilación se detiene cuando un nombre de export escrito por el autor es igual a uno que el proveedor deriva para un enlace entre límites en la misma compilación. Ambas declaraciones llegarían a la plantilla ensamblada, dejando un nombre de export declarado dos veces en un mismo stack — y un nombre de export tiene que ser único, así que las dos no pueden coexistir. La detención indica el nombre de export derivado y las cuatro partes a partir de las que se construyó, para que puedas ver qué enlace lo produjo, y nombra la salida del stack bajo la que está la declaración escrita por el autor, marcada como un nombre que el proveedor ensambla y no uno que escribió una Recipe. El nombre de export es el término que debes buscar en tus Recipes. La entrada escrita por el autor lo escribe exactamente como la detención — esa identidad es lo que convierte a ambos en una colisión —, así que es la única cadena que aparece tanto en el mensaje como en tus propios archivos. Renombrar el nombre de export que declara esa entrada elimina la detención, y también lo hace quitar el bloque Export: de esa entrada y dejar que la conexión entre stacks publique el export por sí misma.

La comprobación tiene ámbito de compilación, y su ámbito es un stack. Compara los nombres de export que declara un stack ensamblado con los nombres que el proveedor deriva para los enlaces entre límites que publican en ese mismo stack — la comparación que la compilación puede hacer a partir de lo que ha ensamblado. Dos stacks no se comparan entre sí. Y lo que un nombre escrito por el autor encuentra entre los exports ya desplegados en una cuenta y una región es una propiedad del despliegue, que queda fuera del alcance de cualquier derivación en tiempo de compilación, por la razón expuesta en Frente a qué es único un nombre de export, y dónde termina eso: el compilador no se autentica ante AWS, no lo consulta y no puede leer la salida de otra compilación. Un nombre de export escrito como función intrínseca en lugar de como cadena simple queda al otro lado de la misma línea — se resuelve en tiempo de despliegue, y nada aquí evalúa una función intrínseca, así que no hay ningún nombre que la compilación pueda comparar.

La compilación también se detiene cuando la salida en la que publica un enlace entre límites ya lleva un Export que el enlace no escribió. Esa salida es la que el proveedor ensambla para la clave proporcionada que lee un consumidor, así que una Recipe cuyo bloque Outputs: escribe una entrada bajo esa misma clave, con un Export: propio, pone su export exactamente donde va el del enlace. A menos que el nombre de ese export sea exactamente el que deriva el proveedor — en cuyo caso es el propio export del enlace y todo consumidor lo importa —, los dos no pueden coexistir ahí: escribir el export del enlace sobrescribiría el tuyo, y conservar el tuyo dejaría a todo consumidor importando un nombre que el enlace no publicó. La detención indica el nombre de export derivado y las cuatro partes a partir de las que se construyó, y dice qué encontró en esa salida: el nombre de export que declara la entrada, un nombre escrito como función intrínseca, un bloque Export: que no nombra nada, o un Export: escrito como valor simple en lugar de como bloque. Quitar el bloque Export: de esa entrada la elimina, y la conexión entre stacks publica entonces el export que importa todo consumidor.

Orden de despliegue

El valor syncWave: de un límite de una Release ordena el aprovisionamiento del stack en el que se ensambla ese límite. Cada componente del límite hereda la oleada del límite, y donde varios límites se resuelven en el mismo directorio de salida — de modo que sus fragmentos se ensamblan en una sola plantilla —, el stack contiene más de una oleada y el proveedor expresa el orden entre ellas como DependsOn.

Cada recurso nombra todos los recursos de la oleada inmediatamente anterior que tenga recursos, y ninguna oleada anterior a esa. CloudFormation encadena el resto: un recurso de la oleada 2 depende de la oleada 1, que depende de la oleada 0, así que toda la secuencia queda ordenada mientras la lista propia de cada recurso se mantiene del tamaño de una oleada y no de todo el stack. Las oleadas no tienen que ser contiguas, y los valores negativos son normales — -1 es una elección habitual para un bucket o un rol que lee el resto del stack. La oleada más baja no nombra nada, porque nada la precede.

Qué es el orden: orden de creación y, a la inversa, orden de eliminación. CloudFormation opera sobre los recursos en paralelo en la medida en que puede, y DependsOn anula ese paralelismo para operar sobre los recursos nombrados en un orden establecido. El atributo rige ambas direcciones, así que una oleada que crea un recurso antes también lo elimina después — la secuencia correcta de desmontaje viene con el orden sin necesitar nada más.

No es un orden de disponibilidad. Una plantilla de stack no expresa ninguna noción de que un recurso esté operativo, así que nada aquí espera a que uno esté listo — solo a que CloudFormation termine de crearlo. Esa es una diferencia real respecto a la misma oleada en compose, donde se espera a un servicio que declara un healthcheck hasta que informa de que está sano: compose tiene una primitiva de disponibilidad sobre la que esperar y una plantilla de stack no tiene ninguna. El orden de creación es lo que ofrece este destino, y decirlo claramente es más útil que una advertencia adjunta a una promesa que no puede cumplir.

Un DependsOn escrito por el autor se amplía, nunca se sustituye. Un fragmento que declara su propia restricción de orden la conserva: las entradas que escribió quedan primero, en el orden en que las escribió, y siguen las entradas de la oleada. Ambos requisitos se cumplen y ninguno oculta al otro. Se leen tanto un ID lógico único como una lista, y el valor combinado se emite como lista, que es la única forma de escribirlo que vale para cualquier número de entradas que produzca la combinación.

Un stack cuyos recursos llevan todos una misma oleada no obtiene nada de esto. Tampoco una Release que no declara ningún syncWave: cada contribuidor lleva el valor predeterminado del campo, 0, la plantilla ensamblada contiene una sola oleada, y la salida es exactamente la que sería si el proveedor no expresara ningún orden de oleadas.

El orden entre dos stacks no es expresable, y no se aproxima. DependsOn nombra un recurso dentro de la misma plantilla, y los componentes que se ensamblan en otro stack quedan fuera de ella. Así, una oleada ordena cada recurso del stack en el que se ensambla y nada más allá. Secuenciar dos stacks es asunto del operador, del mismo modo que una referencia entre stacks es una resolución en tiempo de despliegue y no en tiempo de compilación.

El orden que las oleadas no expresan sigue siendo asunto del propio CloudFormation, y las referencias entre recursos ya llevan buena parte de él: un Fn::GetAtt sobre un recurso del productor indica a CloudFormation que cree primero ese recurso. Un fragmento que necesita una restricción que ni las referencias ni las oleadas implican escribe DependsOn por sí mismo, que es el caso que conserva la combinación descrita arriba.

Determinismo

Con las mismas entradas, el proveedor emite una plantilla de stack idéntica byte a byte en cada ejecución: los ID lógicos, las claves de salida, los nombres de export y el orden de los recursos son todos deterministas, así que una plantilla de stack de CloudFormation produce diffs limpios en la revisión GitOps.