Provider Terraform
El proveedor terraform renderiza las Recipes de Aggrega en configuración de Terraform. Emite configuración y nunca ejecuta Terraform: una compilación de Aggrega es ahead-of-time, así que no puede resolver los ID de recursos, las direcciones IP y las salidas que solo existen después de terraform apply. Las interpolaciones ${ ... } de Terraform pasan intactas como cadenas de puntero deterministas que el runtime de Terraform resuelve más tarde. El proveedor funciona sin conexión y es hermético — nunca toca la red y nunca invoca terraform ni tofu.
Cómo se organiza un límite
El proveedor terraform compone un límite en lugar de emitir sus componentes uno al lado del otro. Cada límite que renderiza recibe una única configuración raíz, aggrega.modules.tf, que declara cada componente renderizado allí como un bloque module cuyo source es el subdirectorio propio de ese componente bajo modules/:
module "cache" { source = "./modules/cache"}
module "db" { source = "./modules/db"
allocated_storage = 100 db_name = "appdb" engine_version = "11.4"}Los archivos propios de cada componente — el módulo copiado localmente (vendoring) o el cuerpo escrito por el autor, y el sello de procedencia — se encuentran en el subdirectorio al que apunta su bloque. Esta es la estructura estándar de Terraform en la que la raíz compone a los hijos, cuya convención es que los módulos anidados se ubiquen bajo un subdirectorio modules/, y es la organización que recibe todo límite terraform, tanto si contiene un componente como varios. Una Feature vinculada a un componente o al límite se declara como un bloque module propio en la misma configuración raíz — consulta Dónde acaba la salida de una Feature vinculada.
La forma es estructural y no cosmética, por dos razones.
Un grafo de dependencias de Terraform es por configuración. Los Components emitidos en directorios separados son grafos separados sin relación alguna: ni una referencia ni un depends_on pueden llegar de uno a otro, y ningún terraform plan individual ve ambos. Una única raíz que compone cada componente como módulo hijo pone un límite entero en un solo grafo y un solo plan.
Los archivos de un componente se direccionan por su propio directorio. Dos componentes de un mismo límite pueden copiar localmente módulos que escriben archivos con nombres idénticos — main.tf, variables.tf — y cada conjunto se encuentra bajo el directorio de su propio componente en lugar de disputarse una misma ruta.
Dónde se configura un proveedor
La configuración de un proveedor — un bloque provider — se escribe en la raíz, nunca dentro del módulo de un componente. La documentación de Terraform dice que un módulo pensado para ser llamado por otro no debe contener bloques provider, y que un módulo llamado hereda la configuración predeterminada de la raíz para cada proveedor que ese módulo usa. Un módulo que lleva un bloque provider propio no puede llamarse con depends_on, count o for_each, y este proveedor escribe depends_on en el bloque module de un componente siempre que otro componente de la misma raíz lleve un syncWave anterior, como describe Orden de despliegue más abajo; Terraform rechaza entonces toda la configuración mientras la carga, antes de planificar nada.
Así, una Recipe cuyo proveedor necesita configuración escribe esa configuración como un archivo bajo spec.boundary.artifacts. Cada uno de esos archivos se escribe una sola vez junto a aggrega.modules.tf, donde Terraform lo lee junto con la configuración raíz, y el módulo del componente conserva solo su declaración required_providers del origen y la versión del proveedor:
infra/terraform/ aggrega.modules.tf provider-azurerm.tf modules/ gateway/main.tfLos Components de una misma raíz que declaran el mismo archivo con los mismos bytes comparten la única copia; el mismo nombre con bytes distintos detiene la compilación. Los recursos de los módulos se registran respecto a esa única configuración, así que también es con ella con lo que Terraform los destruye. Una Release que elimina el último componente que declara el archivo elimina el archivo con él, y Terraform se niega entonces a planificar la destrucción de lo que esos módulos crearon, y pide un bloque provider que configure el proveedor. Destruye esos recursos antes de eliminar el último de esos componentes.
Dónde se suministran las entradas de un componente
Las entradas de un componente son los argumentos de su bloque module en la configuración raíz, y ese es el único lugar donde se escriben. Un bloque lleva argumentos cuando el compilador suministra las entradas del módulo — una Recipe que copia localmente un módulo con source:. Está vacío cuando la Recipe escribió por sí misma el cuerpo de la configuración y resolvió sus valores en ese cuerpo, de modo que al compilador no le queda nada que pasar.
Un argumento de módulo es una posición que Terraform evalúa, y por eso es ahí donde van los valores. Un puntero ${ ... } que suministra una Recipe se resuelve ahí en lugar de llegar al módulo como una cadena literal. Aquello respecto a lo que se resuelve es la configuración raíz: una referencia nombra algo que esa configuración declara — uno de sus bloques module, como module.<name>.<output> — y una referencia a cualquier cosa que no declare es un error explícito en el momento del plan que nombra el referente que falta.
El directorio propio de un componente no es, por tanto, una configuración que puedas planificar tal como se despliega. Sus entradas se indican un nivel más arriba, en la raíz, así que situarte en modules/<component> y ejecutar allí el motor planifica otra cosa, y cuál de dos cosas ocurre depende de los bloques variable propios del módulo:
- Cuando al menos una entrada no declara ningún
default, el plan falla de forma explícita —No value for required variable, nombrando cada variable sin asignar y su línea, y ofreciendo el remedio propio de Terraform,-var/-var-file. - Cuando cada entrada lleva un
default, el plan tiene éxito y se construye a partir de los valores predeterminados del módulo en lugar de los valores que suministra la configuración raíz. Nada avisa, así que este es el caso que hay que conocer: un plan que parece correcto describe una configuración que nadie pidió.
Planifica en su lugar el directorio de salida propio del límite — el que contiene aggrega.modules.tf, inmediatamente encima de modules/. Ahí están los valores del despliegue, y es el único lugar donde un solo plan ve el límite entero.
Consumir el valor publicado de otro componente
Un componente conectado a otro con una arista uses lee los valores publicados de ese componente a través de su propio pipe .context.inject (o a través de .context.uses.<alias>.provides.<name>). Lo que lee es una cadena que el compilador canaliza sin interpretarla, y el lugar donde acaba esa cadena es texto que Terraform evalúa en el ámbito en el que la Recipe lo escribió. Un límite terraform tiene dos de esos ámbitos, y solo uno de ellos declara las llamadas a módulos que necesita una referencia entre componentes:
- la configuración raíz declara cada contribuidor como un bloque
module, así quemodule.<name>.<output>se resuelve allí; - el directorio propio de un componente no declara ninguna llamada a módulos, así que
module.<name>.<output>no nombra nada allí — sea cual sea<name>. Sustituir el nombre correcto no cambia nada, porque lo que falta es la declaración, no la ortografía.
Así que es el tipo de entrada de la Recipe consumidora lo que decide si una referencia consumida puede resolverse, y no el valor que se consume.
Escribe una Recipe consumidora como una Recipe source:. Su valuesMapping: se convierte en los argumentos de su propio bloque module en la configuración raíz — la única posición que es a la vez evaluada y está en un ámbito donde sus vecinos están declarados.
Un par desarrollado
El productor publica una dirección que nombra su propia llamada a módulo, que es la forma que declara el ámbito de su consumidor. .context.instance_id está en la superficie de evaluación de provides, y para un componente que declara el Aggregate del despliegue es el nombre que lleva el bloque module de ese componente:
# Recipe — the producer. Its vendored module declares `output "endpoint"`.spec: capability: terraform implements: example/storage/object-store:1.0.0 source: ./module valuesMapping: | bucket: "{{ .values.bucket }}" provides: endpoint: "${module.{{ .context.instance_id }}.endpoint}"El consumidor copia localmente un módulo que declara una entrada, y asigna a ella el valor inyectado:
# Recipe — the consumer. Its vendored module declares `variable "store_endpoint"`.spec: capability: terraform implements: example/compute/reporting-api:1.0.0 source: ./module valuesMapping: | store_endpoint: "{{ .context.inject.env.STORE_ENDPOINT }}"El Aggregate los conecta, nombrando la clave publicada que lleva la arista:
spec: components: store: type: example/storage/object-store values: bucket: app-artifacts
api: type: example/compute/reporting-api uses: store: store: target: store inject: env: - in: STORE_ENDPOINT from: endpointLa compilación emite una única configuración raíz en la que la referencia y su referente se declaran juntos:
module "api" { source = "./modules/api"
store_endpoint = "${module.store.endpoint}"}
module "store" { source = "./modules/store"
bucket = "app-artifacts"}Terraform resuelve module.store.endpoint porque la misma configuración declara module "store", y el valor llega al módulo del consumidor como una entrada ordinaria.
El ejemplo aws-rds-and-ecs-service construye este par a partir de Recipes de la biblioteca estándar: una base de datos PostgreSQL aprovisionada por el módulo RDS publicado y un servidor ejecutado en Amazon ECS, cuyo argumento environment lleva ${module.db.db_instance_address} en la configuración raíz que declara module "db".
Tres formas en que esto sale mal, y qué aspecto tiene cada una
Una Recipe que escribe su propio cuerpo no puede consumir una referencia entre componentes. Una Recipe artifacts: resuelve sus valores en el cuerpo que escribe, y ese cuerpo se emite en el directorio propio del componente. La referencia queda entonces en un ámbito que no declara ninguna llamada a módulos:
Error: Reference to undeclared module on modules/api/main.tf line 11, in output "seen": 11: value = "${module.store.endpoint}"No module call named "store" is declared in module.api.No hay ortografía que lo arregle, porque las expresiones de un módulo anidado no pueden nombrar en absoluto a un módulo hermano — un módulo anidado recibe el valor de un vecino solo como entrada, que es el argumento del bloque module que la ruta con fuente ya suministra. Un componente que consume el valor publicado de otro componente se escribe como una Recipe source:.
Una dirección que nombra algo dentro del propio módulo del productor se resuelve respecto a la raíz, no respecto a ese módulo. Una entrada provides que escribe aws_db_instance.this.endpoint nombra un recurso que declara el módulo del productor; escrita como interpolación, se evalúa donde está el argumento del consumidor, que es la raíz:
Error: Reference to undeclared resource on aggrega.modules.tf line 19, in module "api": 19: store_endpoint = "${aws_db_instance.this.endpoint}"There is no managed resource "aws_db_instance" "this" definition in the root module.Publica ${module.<...>.<output>} y da al módulo un bloque output para el valor, en lugar de acceder a sus recursos.
Una entrada provides que no lleva interpolación se entrega como texto. Este es el caso que no falla: el compilador canaliza cadenas y no puede distinguir un puntero de un literal, así que aws_db_instance.this.endpoint escrito sin ${ ... } se renderiza como una cadena entre comillas, la compilación tiene éxito, el motor valida y el consumidor recibe los caracteres aws_db_instance.this.endpoint. Escribe el envoltorio ${ ... } siempre que el valor se pretenda como referencia — es lo que marca la cadena como algo que Terraform debe evaluar.
Una restricción que conviene conocer antes de confiar en ella
.context.instance_id expresa la identidad del componente, y el nombre de un bloque module se deriva del directorio en el que se encuentran los archivos del componente. Para un componente que declara el Aggregate propio del despliegue, son el mismo nombre. Para un componente incorporado por composición desde otro Aggregate no lo son: la identidad compuesta y el nombre del módulo se escriben de forma distinta en sus dos alfabetos, y la referencia falla entonces de forma explícita en la raíz en lugar de hacerlo en silencio:
Error: Reference to undeclared module on aggrega.modules.tf line 25, in module "api": 25: store_endpoint = "${module.nested-zdinner.endpoint}"No module call named "nested-zdinner" is declared in the root module.Declara un productor cuya dirección resuelve otro componente en el Aggregate propio del despliegue, junto al componente que lo consume.
Dónde acaba la salida de una Feature vinculada
Una vinculación de Feature que renderiza configuración propia recibe un módulo propio, declarado en la misma configuración raíz que los componentes junto a ella. Esto es lo que hace que su configuración forme parte del despliegue: Terraform carga solo los archivos situados directamente en un directorio y trata un directorio anidado como un módulo completamente separado que debe llamarse explícitamente, de modo que los archivos de una vinculación se leen porque la raíz declara un bloque que nombra el directorio en el que se encuentran.
El directorio de módulo de una vinculación se encuentra junto al del componente, un nivel bajo modules/, y recibe el nombre de las dos cosas que lo identifican — el componente que aloja la vinculación y el nombre con el que se vinculó, unidos con --. Así, para un componente api que lleva una vinculación llamada aux, la configuración raíz declara dos módulos:
module "api--aux" { source = "./modules/api--aux"}
module "api" { source = "./modules/api"}Una Feature vinculada al límite en lugar de a un componente no tiene un componente anfitrión que nombrar, así que su directorio es solo su propio nombre: una vinculación llamada aux en un límite que contiene el componente api produce ./modules/aux junto a ./modules/api.
Por qué junto y no dentro. Terraform combina cada archivo de nivel superior de un directorio de módulo en un único espacio de nombres — output, variable, resource y locals por igual — de modo que dos contribuidores que comparten un directorio colisionan en cualquier nombre que ambos declaren, se llamen como se llamen sus archivos. Un directorio para cada uno es lo que los mantiene separados. Junto y no dentro es también lo que pide la propia guía de Terraform para los módulos anidados: que el llamador pueda componerlos en lugar de que se llamen directamente entre sí creando un árbol de módulos profundamente anidado.
La unión se escapa por coordenada. Cada una de las dos coordenadas se escribe en el alfabeto de directorios antes de unirlas, de modo que una coordenada que a su vez contiene -- no puede confundirse con la unión: un anfitrión llamado a--b con una vinculación c se distingue de un anfitrión a con una vinculación b--c. Las letras ASCII, mayúsculas y minúsculas, los dígitos, el punto y el guion bajo pasan tal como se escriben; un guion que hayas escrito se conserva siempre que el carácter que lo sigue sea uno de esos; todo lo demás se escapa. La misma regla y el mismo alfabeto producen los directorios hijos de un destino chart, de modo que el directorio de una vinculación se escribe igual sea cual sea el destino de los dos que lo renderice.
El nombre de un bloque se deriva del directorio al que apunta su source, sustituyendo por un guion bajo cada carácter fuera de la gramática de Terraform para un nombre de módulo. Esa correspondencia no es biunívoca, así que donde dos contribuidores llegarían a un mismo nombre de módulo la compilación se detiene y nombra a ambos, en lugar de emitir una configuración que Terraform rechazaría.
Del hecho de que una vinculación sea un módulo propio se derivan tres cosas.
Sus entradas son las de su propio mapeo. Una vinculación cuya FeatureRecipe toma como fuente un módulo y declara un valuesMapping tiene los valores que produce ese mapeo escritos como argumentos de su propio bloque module, del mismo modo en que el módulo con fuente de un componente recibe sus valores. Una FeatureRecipe que no declara ningún valuesMapping no pasa ningún argumento a su módulo: una variable que el módulo declara con un default lo toma, y una declarada sin valor predeterminado queda sin asignar, así que Terraform rechaza el plan.
Sus recursos están en el único grafo de dependencias del límite. Una referencia o un depends_on conecta una vinculación con el componente al que está vinculada, en ambos sentidos, y un solo terraform plan ve ambos — la misma propiedad que la forma en la que la raíz compone a los hijos da a los componentes, por la misma razón.
Sus nombres de nivel superior son suyos. Como la combinación de espacios de nombres descrita arriba es por directorio, un contribuidor situado en un directorio propio declara sus nombres output, variable, resource y locals sin competir con los de sus vecinos — así una vinculación puede reutilizar un nombre que su anfitrión ya declara, y ninguno de los dos tiene que saber cómo llamó el otro a nada.
Observa lo que este destino no requiere, porque la restricción de un destino chart es distinta y la organización compartida puede leerse como si implicara más de lo que implica: un módulo anidado dentro del directorio de otro contribuidor sigue siendo alcanzable aquí, ya que la configuración raíz lee el source de cada contribuidor a partir de la posición que compuso la compilación en lugar de reconstruirlo a partir de un identificador. Lo que este destino rechaza es que dos contribuidores compartan un directorio. Un destino chart rechaza de plano la posición anidada, porque descubre un chart hijo un nivel más abajo y no más allá.
Tipos de entrada admitidos
El proveedor terraform acepta dos de los tres tipos de entrada de Recipe:
- Modo artefactos. Una Recipe escribe configuración de Terraform como un cuerpo basado en plantillas; el proveedor evalúa la plantilla de Aggrega y emite el resultado sin reescribirlo. HCL (
main.tf) es la opción predeterminada más ergonómica, y Terraform JSON (.tf.json) se acepta de forma equivalente. La procedencia de la compilación se estampa como un bloque de comentarios de Terraform al principio de un cuerpo HCL; para un cuerpo JSON — que no tiene sintaxis de comentarios — la procedencia se escribe en un archivo complementario,aggrega.provenance.tf, en lugar de en línea. - Modo con fuente. Una Recipe hace referencia a un módulo de Terraform con
source:. Los archivos del módulo se copian localmente (vendoring) tal cual en el directorio de ese componente, y elvaluesMapping:de la Recipe se convierte en los argumentos del bloquemodulede ese componente en la configuración raíz del límite. El cuerpo del módulo se conserva exactamente como se escribió y no se escribe nada en él; los valores se indican una sola vez, en la raíz, donde Terraform los evalúa. Cuando las hojasvaluesdeclaradas del nodo se convierten directamente en las entradas del módulo — una Recipesource:sinvaluesMapping:— una entrada que lleva material que un autor declaró sensible recibe además un archivo de sobrescritura generado que lleva el atributo de sensibilidad propio de Terraform; una plantillavaluesMapping:inventa sus nombres de salida, así que ese caso no lleva ninguna marca y la compilación lo notifica con un aviso orientativo. Ambos se describen en Entradas de módulo declaradas sensibles.
Un null en un valuesMapping: es un argumento null. Una clave que el mapeo establece en null se escribe como <name> = null en el bloque module, y el motor da a la variable del módulo el valor null, que sustituye a su default, salvo que la variable declare nullable = false, en cuyo caso se aplica su default; para dar a una entrada el valor predeterminado del módulo, deja la clave fuera del mapeo.
El tipo de entrada sintetizado no se ofrece. No existe una correspondencia fiel y agnóstica respecto a las capacidades entre el tipo Workload de la plataforma y recursos arbitrarios de Terraform, así que una Recipe que declara workload: con el proveedor terraform es un error explícito en lugar de una traducción inventada.
Una Recipe que declara omits: se rechaza. La clave omits: deja fuera de la compilación documentos que una fuente renderiza, y este proveedor no renderiza nada a partir de un módulo con fuente en tiempo de compilación: copia localmente los archivos del módulo tal cual, y Terraform los evalúa cuando la configuración se planifica y se aplica. Sin nada renderizado no hay nada que dejar fuera, así que este proveedor no declara que respete la clave, y una Recipe o una FeatureRecipe que la declare se rechaza antes de que se copie localmente nada — consulta The provider does not support omits (El proveedor no admite omits). Para un módulo que guardas junto a la Recipe, una línea en el .aggregaignore que hay allí deja fuera, en su lugar, un archivo del módulo, a partir del siguiente pin de la Recipe.
Usar como fuente un módulo que publica un registro
Un registro de módulos publica cada versión de un módulo como una etiqueta del repositorio git propio del módulo, y lo que responde cuando se le pide descargar una versión es una fuente git fijada al commit que nombra esa etiqueta. Así, una Recipe toma como fuente un módulo publicado desde ese repositorio en esa etiqueta, con el tipo de fuente git-repository:
spec: capability: terraform implements: example/storage/database:1.0.0 source: kind: git-repository url: https://github.com/terraform-aws-modules/terraform-aws-rds.git ref: v7.2.2 valuesMapping: | identifier: "{{ .values.identifier }}" provides: host: "${module.{{ .context.instance_id }}.db_instance_address}" port: "${module.{{ .context.instance_id }}.db_instance_port}"ref: es la etiqueta de versión exactamente como la nombra el repositorio. valuesMapping: suministra las entradas del módulo, con los nombres que declaran sus bloques variable — Terraform exige un valor para cada entrada que no declara ningún default — y se convierten en los argumentos del bloque module de este componente en la configuración raíz, como para cualquier módulo con fuente.
Qué queda fijado. aggrega pin y el pull resuelven la etiqueta al commit que nombra y archivan el repositorio en ese commit. El archivo de bloqueo de la Release registra entonces ese commit como la versión fijada de la fuente, la etiqueta como la referencia que escribiste y el digest del archivo comprimido. Cada compilación posterior lee el archivo comprimido de la caché y lo verifica contra ese digest antes de copiar localmente nada, así que no necesita red, y un archivo comprimido en caché cuyos bytes ya no coinciden detiene la compilación. Una etiqueta es un nombre que un repositorio puede mover a otro commit; un pull posterior que encuentra la tuya resuelta en otro lugar se detiene en lugar de adoptar el nuevo commit, y aggrega pull --upgrade lo adopta deliberadamente. Es una fijación más estricta que el archivo de bloqueo de dependencias propio de Terraform, que registra los proveedores que seleccionó una configuración y ningún módulo, así que un módulo escrito en una configuración como fuente git en una etiqueta solo está tan fijado como la etiqueta. Aquí el commit del módulo y el digest de sus bytes quedan fijados en el archivo de bloqueo, los bytes se copian localmente en la salida y la configuración raíz los llama mediante una ruta local, así que el motor no descarga nada para cargar el propio módulo — un módulo al que el módulo copiado localmente llama mediante una fuente de registro o remota se sigue descargando, y la compilación notifica cada una de esas llamadas, como describe Una llamada a módulo que el motor descarga al inicializarse.
Qué se copia localmente. El repositorio entero en el commit fijado, excepto su directorio .git/, llega al directorio propio del componente bajo modules/, byte a byte — los archivos de configuración y los módulos hijos propios del módulo, y también todo lo demás que lleve el repositorio: sus directorios examples/ y wrappers/, su documentación, su configuración de CI y cualquier fixture de prueba, incluidos los binarios. El motor lee solo lo que llama el módulo: cuando la configuración raíz llama al directorio del componente, el motor carga los archivos de configuración situados directamente en él y en cada directorio al que llega desde allí un source local. Un directorio de ejemplo que llama a otros módulos de registro se copia por tanto localmente y nunca se carga, y no se descarga nada de lo que llama.
Acotar lo que se copia localmente. Una fuente descargada es el archivo comprimido como el que se descargó, así que la única forma de acotarla es module_subdir:, que convierte un directorio del repositorio en el artefacto. Eso solo ayuda cuando el módulo que quieres está en un subdirectorio: un módulo en la raíz del repositorio que llama a sus propios ./modules/* necesita el árbol entero. Ni un .terraformignore que lleve el repositorio ni un .aggregaignore junto a la Recipe cambian lo que copia localmente una fuente descargada — ambos dan forma a un módulo guardado junto a la Recipe, y ninguno se lee para uno descargado de un repositorio.
Leer lo que publica el módulo. Un valor que publica el módulo es uno de sus bloques output, y un consumidor lo lee como ${module.<name>.<output>}, donde <name> es el bloque module del productor — por eso el productor de arriba publica ${module.{{ .context.instance_id }}.<output>}. El motor resuelve la referencia respecto a los bloques output propios del módulo cuando valida la configuración raíz, así que un nombre de salida que el módulo no declara se rechaza allí, nombrándolo:
Error: Unsupported attribute on aggrega.modules.tf line 9, in module "api": 9: db_host = "${module.db.db_instance_addresz}"This object does not have an attribute named "db_instance_addresz".La compilación no lee ninguno de los bloques variable ni output del módulo, no escribe nada en el módulo y no le añade ninguna configuración de proveedor, así que un nombre de salida mal escrito lo detecta el motor en lugar de la compilación. Consulta Consumir el valor publicado de otro componente para el lado del consumidor.
Emisión sin cambios y copia local (vendoring)
El proveedor terraform no transpila, no reformatea ni reescribe cuerpos de Terraform. Un cuerpo HCL o .tf.json escrito por el autor se emite exactamente como lo evalúa su plantilla, con un cuerpo HCL que empieza por los comentarios de procedencia, y un módulo con fuente se copia localmente archivo por archivo. Esto es lo que mantiene la salida de terraform determinista y reproducible: con las mismas entradas, la configuración renderizada es idéntica byte a byte entre ejecuciones, y un módulo copiado localmente hace el viaje de ida y vuelta sin cambios. Como el proveedor nunca resuelve el estado de ejecución, todo lo que depende del tiempo de ejecución sigue siendo una cadena de interpolación que Terraform vincula en el momento del apply.
Anotaciones de plataforma
El proveedor terraform no lee ninguna de las anotaciones aggrega.ai/. Un módulo copiado localmente, los archivos de artefactos de una Recipe y la configuración raíz que escribe el proveedor no tienen sitio para un espacio de nombres, un prefijo de registro, un secreto de pull ni una cuenta de servicio, así que un valor establecido para uno de ellos no cambia nada en la configuración renderizada; un módulo que necesita ese valor lo recibe como una de sus propias entradas, a través de los values del componente.
El proveedor lo declara en su entidad Plugin, con readsNoWellKnownAnnotations: true (consulta la entidad Plugin), y por eso la compilación emite una advertencia por cada anotación aggrega.ai/ que llega a un renderizado a través de él — una vez por clave y por renderizado, nombrando los tipos de entrada que declara ese renderizado:
warning: node "db" (provider "terraform"): target "terraform" does not support annotation aggrega.ai/namespace on sourced input and ignored itEl valor sigue pasando intacto por la compilación, y la compilación no se detiene: una anotación de límite se propaga en cascada a cada componente que hay debajo, y un límite cuyos componentes se renderizan mediante destinos distintos es algo normal y no un error. La advertencia pertenece a la clase unsupported-field y se silencia con el indicador de esa clase.
Entradas de módulo declaradas sensibles
Terraform es el único destino de la biblioteca estándar con una primitiva nativa de sensibilidad por valor, así que un dato que un autor declaró sensible puede renderizarse en los términos propios de Terraform en lugar de solo registrarse en los de Aggrega.
Cuando la entrada de un módulo copiado localmente lleva material que un autor declaró sensible, el proveedor añade un archivo más junto al módulo, aggrega_override.tf.json, que declara sensitive = true para esa entrada:
{ "variable": { "db_password": { "sensitive": true } }}Terraform combina un archivo de configuración cuyo nombre es simplemente override o termina en _override con la configuración del mismo directorio, así que el bloque variable propio del módulo adquiere el atributo mientras cada byte copiado localmente sigue exactamente como se escribió. El tipo declarado, el valor predeterminado y la descripción de la entrada no se tocan — la sobrescritura lleva el atributo de sensibilidad y nada más. Un nodo sin marcar no recibe ningún archivo así.
Esa restricción es deliberada y no algo que imponga el formato de archivo: nada en una sobrescritura rechaza un segundo atributo, y el default de un bloque variable es el hueco más cercano al que recurrir si quisieras llevar un valor a un módulo copiado localmente sin editar sus bytes — pero no llegaría. Un default en la sintaxis de configuración JSON en la que está escrito este archivo no es una posición que Terraform evalúe, así que un valor que lleva un puntero ${ ... } escrito ahí llega al módulo como los caracteres literales del puntero, en un plan que tiene éxito y no dice nada. El mismo puntero escrito en un default en HCL nativo se rechaza de plano, lo que sitúa ese silencio en esta sintaxis y no en los archivos de sobrescritura como tales. Por eso la sobrescritura lleva solo sensitive: su significado no depende de que se evalúe.
Qué entrada se marca viene de una declaración, nunca de un nombre. El proveedor lee la marca que calculó la compilación y no inspecciona nada por sí mismo: no reconoce password, secret ni token, y no lee el texto del módulo para adivinar. Una entrada de módulo llamada db_password cuyo valor no lleva ninguna declaración se emite sin marcar, y una entrada declarada llamada region se marca.
La marca viaja solo donde la identidad de la entrada puede recuperarse a partir de la declaración. Una Recipe que copia localmente un módulo con source: y deja que las hojas values declaradas del nodo se conviertan directamente en las entradas del módulo da a cada entrada el mismo nombre que declaró el autor, así que el vínculo es exacto — y lo mismo hace la FeatureRecipe de una Feature vinculada a un componente que copia localmente un módulo de la misma manera, sobre las hojas que declara su Feature. Una Recipe o una FeatureRecipe así que remodela esos valores mediante una plantilla valuesMapping: inventa sus nombres de salida, y ninguna declaración los nombra — así que la marca está ausente en lugar de aproximada, y la compilación lo notifica con un aviso orientativo por cada hoja declarada, nombrando la hoja y la entidad de la que es el mapeo (una Feature vinculada a un límite se renderiza sin ningún values, así que no tiene nada que marcar y no provoca ninguno); 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). La ausencia es deliberada: adivinar qué entrada remodelada llevaba el dato declarado marcaría como secreta una entrada pública, y Terraform suprimiría entonces de la salida del plan un valor que nunca fue sensible.
El ejemplo práctico terraform-declared-sensitivity construye esto de principio a fin y es lo bastante pequeño como para leerlo entero: un componente que declara tres hojas values, de las que dos llevan identificadores públicos y una lleva la credencial. Su salida renderizada muestra los argumentos del bloque module llevando las tres entradas del módulo y la sobrescritura nombrando solo la declarada, así que las dos mitades de la regla son visibles en la misma compilación — incluido que un identificador de la credencial situado junto al secreto se deja sin marcar. Eliminar esa única declaración y volver a compilar no emite ningún archivo de sobrescritura.
Qué garantiza y qué no garantiza el sensitive de Terraform
Aggrega promete exactamente lo que ofrece el atributo propio de Terraform, y nada más.
Acota la visualización. Un valor sensible se muestra como (sensitive value) en la salida del plan y como <sensitive> en la salida del apply. La marca se propaga a través de las expresiones, así que un valor derivado de una entrada sensible también es sensible, y Terraform se niega a exportar uno desde un output raíz que no esté marcado a su vez como sensible — un error explícito en lugar de una divulgación silenciosa.
No cambia el almacenamiento, y no es cifrado. Terraform registra un valor sensible en el estado en texto plano. Leer sensitive = true como una promesa de que el estado es seguro para hacer commit o compartir es la única mala interpretación que hay que evitar: proteger el estado sigue siendo cuestión de cómo está configurado el backend de estado, exactamente igual que para un módulo que no lleva ninguna marca. El atributo tampoco restringe quién puede leer el valor, no afecta a lo que transmite un proveedor y no cambia de ninguna otra forma la configuración renderizada.
Así que la marca hace más difícil divulgar por accidente una entrada declarada sensible cuando alguien lee un plan. No hace que sea seguro publicar lo que se despliega. Consulta Declarar sensible una hoja para la palabra clave y para lo que consigue una declaración en todos los destinos.
Validación estructural de la entrada
El proveedor terraform valida la estructura de un módulo con fuente antes de renderizarlo. Analiza los archivos HCL y .tf.json del módulo y notifica los errores de análisis, deteniendo la compilación con un mensaje claro que nombra el nodo afectado y el proveedor. El análisis comprueba la forma, no la semántica — no resuelve proveedores, no evalúa expresiones ni contacta con un registro. La validación es hermética: usa un analizador HCL autónomo compilado dentro del proveedor, sin binario terraform y sin acceso a la red. Un módulo mal formado se detecta en el límite de la autoría en lugar de aparecer como un error confuso en una ejecución posterior de terraform.
Una llamada a módulo que el motor descarga al inicializarse
La misma lectura notifica, como una advertencia que no rechaza nada, cada bloque module cuya fuente descarga Terraform cuando se inicializa la configuración. El commit y el digest del archivo comprimido de un módulo copiado localmente quedan fijados en el archivo de bloqueo, pero un bloque module dentro de él cuyo source es una dirección de registro, una URL de git, Mercurial o de archivo comprimido HTTP, un bucket de S3 o GCS, o una ruta absoluta nombra un módulo que el motor descarga en la inicialización, en la versión que seleccione en ese momento — y el archivo de bloqueo de dependencias propio de Terraform registra solo proveedores, así que nada fija ese módulo. También se notifica un source local que sale del módulo copiado localmente, porque nombra archivos que la compilación no copió localmente. Cada hallazgo nombra el nodo y el proveedor, luego el bloque, el archivo y la línea en que se encuentra, y la fuente tal como está escrita:
warning: node "app" (provider "terraform"): module "vpc" (main.tf, line 2) has the source "terraform-aws-modules/vpc/aws", which Terraform downloads when the configuration is initialised, at whatever version it then selects, so no commit or digest this build records covers that moduleQué se lee. Los archivos que carga el motor cuando se llama al módulo: los archivos de configuración situados directamente en el directorio propio del módulo, y luego los de cada directorio al que llega desde allí un source local — uno que empieza por ./ o ../, o sus grafías con barra invertida —, seguidos de directorio en directorio y leídos una sola vez cada uno. Un directorio al que nada llama no se lee, así que no se notifican las llamadas que hacen los directorios examples/ o tests/ de un módulo: el motor nunca los carga cuando se llama al módulo, y no se descarga nada de lo que llaman. La comprobación de análisis descrita arriba sigue analizando cada archivo de configuración copiado localmente. El cuerpo escrito de una Recipe se lee de la misma forma cuando se renderiza, empezando por el directorio en el que se escribe el cuerpo, así que también se notifica un bloque module que un cuerpo escrito por el autor escribe con una fuente de registro. Un archivo bajo spec.boundary.artifacts lo evalúa y escribe el propio compilador y no se entrega a ningún proveedor, así que un bloque module escrito en uno de ellos no se lee y no provoca ninguna advertencia.
Qué no se lee. Solo se lee lo que dice un source. La compilación no lee el módulo que nombra una llamada, no juzga lo que hace ese módulo y no decide si la llamada es aceptable. Un source que el motor evalúa en lugar de leerlo tal como está escrito — uno que lleva una interpolación, o una referencia — se juzga por su texto inicial: uno que empieza por una dirección se notifica tal como está escrito, mientras que uno que empieza por un prefijo local, o por la propia interpolación, ni se notifica ni se sigue, porque adónde lleva no está en el texto. Un source dentro de required_providers nombra un proveedor en lugar de un módulo y no es una llamada a módulo.
Por qué se notifica en lugar de rechazarse. Un módulo que llama a otro módulo es una entrada legítima: Terraform descarga el módulo llamado y la configuración funciona. Lo que el autor cede es la fijación que la compilación ejerce sobre el módulo llamado, lo cual es un hecho que conviene conocer y no un fallo que corregir, y si esa descarga es aceptable es juicio del autor. Una configuración que debe permanecer completamente fijada copia localmente solo módulos que no hacen ninguna llamada así. La advertencia, su código de clase y adónde más llega se describen en Advertencias y salida del linter.
Límite de parches de FeatureRecipe
Un paso pipeline posterior al renderizado de una FeatureRecipe solo aplica parches a la salida que el proveedor renderiza en un árbol estructurado. Para terraform, esto significa:
- El Terraform escrito en JSON admite parches. Un módulo
.tf.jsones un documento estructurado, así que el JSONPatch de un paso del pipeline edita en el lugar los valores direccionados y deja intacto cualquier otro byte — orden, formato, claves circundantes. - El HCL nativo es opaco. Un cuerpo en HCL nativo (
main.tf) no es un destino de parche estructurado. Un parche contra un cuerpo opaco detiene la compilación con un diagnóstico en lugar de modificar texto que no puede direccionar estructuralmente; escribir un paso del pipeline contra un cuerpo HCL es un error de diseño que aflora como una detención explícita, no como una operación nula silenciosa. - Las entradas de un módulo con fuente no son en absoluto un destino de parche. Son los argumentos del bloque
moduledel componente, que está en la configuración raíz: HCL nativo, y por tanto opaco, y un artefacto de todo el límite y no de un nodo concreto. Un pasopipelineaplica parches a la salida renderizada propia de un nodo, así que no existe ninguna posición desde la que direccionarlas.
Un autor que necesita que un cuerpo de Terraform admita parches del pipeline lo escribe, por tanto, como .tf.json. Consulta FeatureRecipe para el límite general de los destinos de parche entre proveedores.
Orden de despliegue
El valor syncWave: del límite de una Release ordena los bloques module de la configuración raíz en la 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 componentes se componen en una única configuración raíz —, esa raíz contiene más de una oleada y el proveedor expresa el orden entre ellas como depends_on en los bloques module.
Cada módulo nombra todos los módulos de la oleada inmediatamente anterior que tenga componentes, y ninguna oleada anterior a esa. Terraform encadena el resto: un módulo 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 módulo mantiene el tamaño de una oleada y no el de todo el límite. Las oleadas no tienen por qué ser contiguas, y los valores negativos son habituales — -1 es una elección común para un bucket o un rol que lee el resto de la configuración. La oleada más baja no nombra nada, porque nada la precede.
Qué es el orden: el orden en que Terraform realiza sus acciones. Terraform construye un grafo de dependencias y lo recorre en paralelo en la medida en que el grafo lo permite. depends_on añade una arista a ese grafo, de modo que Terraform completa sus acciones sobre los módulos nombrados antes de empezar las del módulo que declara la dependencia. Por tanto, una oleada escalona la ejecución: se actúa sobre los componentes de la oleada anterior antes de empezar con los de la oleada posterior.
No es un orden por disponibilidad. Una configuración de Terraform no expresa ninguna noción de que un recurso esté operativo, así que aquí nada espera a que uno esté listo — solo a que Terraform termine de actuar sobre él. 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 en la que apoyarse y una configuración de Terraform no tiene ninguna. El orden de las acciones es lo que ofrece este destino, y decirlo claramente es más útil que una advertencia ligada a una promesa que no puede cumplir.
No se promete ningún orden de desmantelamiento. Lo que depends_on afirma es que Terraform completa las acciones de la dependencia antes de empezar las del dependiente; el orden en que un destroy los elimina no forma parte de esa afirmación, así que aquí no se afirma nada sobre la secuencia de desmantelamiento. Es una promesa más estrecha que la que lleva la misma oleada en cloudformation, cuyo atributo rige ambas direcciones — conviene saberlo si confías en una oleada para ordenar un desmantelamiento, porque en este destino no lo hace.
Un límite cuyos componentes llevan todos una misma oleada no obtiene nada de esto. Lo mismo ocurre con una Release que no declara ningún syncWave: cada contribuidor lleva el valor predeterminado del campo, 0, la configuración raíz contiene una sola oleada y los bytes emitidos son exactamente los que serían si el proveedor no expresara ningún orden por oleadas.
El orden entre dos configuraciones raíz no se puede expresar, y no se aproxima. Un grafo de dependencias de Terraform es por configuración y depends_on nombra un módulo dentro de la configuración que lo declara, así que una oleada ordena cada componente compuesto en esa raíz y nada más allá. Ordenar dos configuraciones es asunto del operador, del mismo modo que una referencia a un estado remoto es una resolución en el momento del despliegue y no en el de la compilación.
La oleada se registra además de aplicarse: viaja con el resto de la procedencia de la compilación del nodo, como aggrega.ai/sync-wave en el bloque de comentarios sellado, o en el archivo de procedencia complementario cuando el cuerpo es JSON o un módulo copiado localmente. Así, una configuración renderizada registra qué oleada declaró su límite, además de estar ordenada por ella.
El orden que las oleadas no expresan sigue siendo asunto del propio Terraform, y las referencias entre recursos ya cubren gran parte de él: una referencia a un atributo de otro recurso indica a Terraform que actúe primero sobre ese recurso. Un módulo que necesita una restricción que ni las referencias ni las oleadas implican escribe su propio depends_on dentro del módulo, que el proveedor emite tal cual, como cualquier otra parte del cuerpo.
Referencias relacionadas
- Arquitectura de Provider — cómo encajan los proveedores en el pipeline de compilación y el despacho por proveedor.
- Índice de referencia de Provider — qué produce cada proveedor de la biblioteca estándar, y qué página responde a qué pregunta.
- Entidad Recipe — la superficie de autoría de la Recipe y los tres tipos de entrada.
- FeatureRecipe — el modelo de parches
pipelineposterior al renderizado y su límite entre estructurado y opaco. - Composición de entradas de Recipe — la Matriz de capacidades por Provider canónica.