Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

Provider Terraform

Il provider terraform esegue il rendering delle Recipes di Aggrega in configurazione Terraform. Emette configurazione e non esegue mai Terraform: una build di Aggrega è una compilazione ahead-of-time, quindi non può risolvere gli ID delle risorse, gli indirizzi IP e gli output che esistono solo dopo terraform apply. Le interpolazioni ${ ... } di Terraform passano intatte come stringhe puntatore deterministiche che il runtime di Terraform risolve in seguito. Il provider è offline ed ermetico — non tocca mai la rete e non invoca mai terraform né tofu.

Come è organizzato un confine

Il provider terraform compone un confine anziché emetterne i componenti uno accanto all’altro. Ogni confine di cui esegue il rendering riceve una sola configurazione radice, aggrega.modules.tf, che dichiara ogni componente renderizzato lì come un blocco module il cui source è la sottodirectory propria di quel componente sotto modules/:

module "cache" {
source = "./modules/cache"
}
module "db" {
source = "./modules/db"
allocated_storage = 100
db_name = "appdb"
engine_version = "11.4"
}

I file propri di ciascun componente — il modulo copiato localmente (vendoring) o il corpo scritto dall’autore, e il timbro di provenienza — si trovano nella sottodirectory a cui punta il suo blocco. Questa è la struttura standard di Terraform in cui la radice compone i figli, la cui convenzione prevede che i moduli annidati si trovino sotto una sottodirectory modules/, ed è l’organizzazione che riceve ogni confine terraform, che contenga un solo componente o più d’uno. Una Feature associata a un componente o al confine viene dichiarata come un blocco module a sé nella stessa configurazione radice — vedi Dove finisce l’output di una Feature associata.

La forma è sostanziale, non estetica, per due ragioni.

Un grafo delle dipendenze di Terraform è per configurazione. I Components emessi in directory separate sono grafi separati, senza alcuna relazione: né un riferimento né un depends_on può arrivare dall’uno all’altro, e nessun singolo terraform plan li vede entrambi. Una sola radice che compone ogni componente come modulo figlio mette un intero confine in un solo grafo e in un solo piano.

I file di un componente sono indirizzati dalla sua directory. Due componenti di uno stesso confine possono copiare localmente moduli che scrivono file con nomi identici — main.tf, variables.tf — e ciascun insieme si trova sotto la directory del proprio componente anziché contendersi un unico percorso.

Dove viene configurato un provider

La configurazione di un provider — un blocco provider — viene scritta nella radice, mai all’interno del modulo di un componente. La documentazione di Terraform dice che un modulo destinato a essere chiamato da un altro non deve contenere blocchi provider, e che un modulo chiamato eredita la configurazione predefinita della radice per ogni provider che quel modulo usa. Un modulo che porta un proprio blocco provider non può essere chiamato con depends_on, count o for_each, e questo provider scrive depends_on sul blocco module di un componente ogni volta che un altro componente della stessa radice porta un syncWave precedente, come descrive più avanti Ordine di distribuzione; Terraform rifiuta allora l’intera configurazione mentre la carica, prima di pianificare qualsiasi cosa.

Quindi una Recipe il cui provider ha bisogno di configurazione scrive quella configurazione come file sotto spec.boundary.artifacts. Ciascuno di questi file viene scritto una sola volta accanto a aggrega.modules.tf, dove Terraform lo legge insieme alla configurazione radice, e il modulo del componente conserva solo la propria dichiarazione required_providers della sorgente e della versione del provider:

infra/terraform/
aggrega.modules.tf
provider-azurerm.tf
modules/
gateway/main.tf

I Components di una stessa radice che dichiarano lo stesso file con gli stessi byte ne condividono l’unica copia; lo stesso nome con byte diversi arresta la build. Le risorse dei moduli vengono registrate rispetto a quell’unica configurazione, quindi è anche ciò con cui Terraform le distrugge. Una Release che rimuove l’ultimo componente che dichiara il file rimuove con esso anche il file, e Terraform rifiuta allora di pianificare la distruzione di ciò che quei moduli hanno creato, chiedendo un blocco provider che configuri il provider. Distruggi quelle risorse prima di rimuovere l’ultimo di questi componenti.

Dove vengono forniti gli input di un componente

Gli input di un componente sono gli argomenti del suo blocco module nella configurazione radice, e quello è l’unico posto in cui vengono scritti. Un blocco porta argomenti quando è il compilatore a fornire gli input del modulo — una Recipe che copia localmente un modulo con source:. È vuoto quando la Recipe ha scritto da sé il corpo della configurazione e ne ha risolto i valori in quel corpo, così al compilatore non resta nulla da passare.

Un argomento di modulo è una posizione che Terraform valuta, ed è per questo che i valori vanno lì. Un puntatore ${ ... } fornito da una Recipe si risolve lì anziché arrivare al modulo come stringa letterale. Ciò rispetto a cui si risolve è la configurazione radice: un riferimento nomina qualcosa che quella configurazione dichiara — uno dei suoi blocchi module, come module.<name>.<output> — e un riferimento a qualsiasi cosa che essa non dichiara è un errore esplicito in fase di pianificazione che nomina il referente mancante.

La directory propria di un componente non è quindi una configurazione che si possa pianificare così come viene distribuita. I suoi input sono indicati un livello più su, nella radice, quindi posizionarsi in modules/<component> ed eseguire lì il motore pianifica qualcos’altro, e quale delle due cose faccia dipende dai blocchi variable del modulo stesso:

  • Quando almeno un input non dichiara alcun default, il piano fallisce in modo esplicito — No value for required variable, nominando ogni variabile non impostata e la sua riga, e proponendo il rimedio proprio di Terraform -var / -var-file.
  • Quando ogni input porta un default, il piano riesce e si costruisce a partire dai valori predefiniti del modulo anziché dai valori che fornisce la configurazione radice. Nulla avvisa, quindi questo è il caso da conoscere: un piano che sembra corretto descrive una configurazione che nessuno ha richiesto.

Pianifica invece la directory di output propria del confine — quella che contiene aggrega.modules.tf, immediatamente sopra modules/. È lì che si trovano i valori della distribuzione, ed è l’unico posto in cui un singolo piano vede l’intero confine.

Consumare il valore pubblicato da un altro componente

Un componente collegato a un altro con un arco uses legge i valori pubblicati di quel componente tramite la propria pipe .context.inject (o tramite .context.uses.<alias>.provides.<name>). Ciò che legge è una stringa che il compilatore convoglia senza interpretarla, e il punto in cui quella stringa finisce è testo che Terraform valuta nell’ambito in cui la Recipe lo ha scritto. Un confine terraform ha due di questi ambiti, e solo uno di essi dichiara le chiamate di modulo di cui ha bisogno un riferimento tra componenti:

  • la configurazione radice dichiara ogni contributore come un blocco module, quindi module.<name>.<output> si risolve lì;
  • la directory propria di un componente non dichiara alcuna chiamata di modulo, quindi module.<name>.<output> lì non nomina nulla — qualunque sia <name>. Sostituire il nome corretto non cambia nulla, perché ciò che manca è la dichiarazione, non l’ortografia.

Quindi è il tipo di input della Recipe consumatrice a decidere se un riferimento consumato può risolversi, e non il valore consumato.

Scrivi una Recipe consumatrice come Recipe source:. Il suo valuesMapping: diventa gli argomenti del suo blocco module nella configurazione radice — l’unica posizione che è sia valutata sia in un ambito in cui i suoi vicini sono dichiarati.

Una coppia svolta

Il produttore pubblica un indirizzo che nomina la propria chiamata di modulo, che è la forma che l’ambito del suo consumatore dichiara. .context.instance_id si trova sulla superficie di valutazione di provides, e per un componente dichiarato dall’Aggregate della distribuzione è il nome che porta il blocco module di quel 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}"

Il consumatore copia localmente un modulo che dichiara un input, e vi mappa il valore iniettato:

# 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 }}"

L’Aggregate li collega, nominando la chiave pubblicata che l’arco trasporta:

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

La build emette una sola configurazione radice in cui il riferimento e il suo referente sono dichiarati insieme:

module "api" {
source = "./modules/api"
store_endpoint = "${module.store.endpoint}"
}
module "store" {
source = "./modules/store"
bucket = "app-artifacts"
}

Terraform risolve module.store.endpoint perché la stessa configurazione dichiara module "store", e il valore raggiunge il modulo del consumatore come un normale input.

L’esempio aws-rds-and-ecs-service costruisce questa coppia a partire da Recipes della libreria standard: un database PostgreSQL predisposto dal modulo RDS pubblicato e un server eseguito su Amazon ECS, il cui argomento environment porta ${module.db.db_instance_address} nella configurazione radice che dichiara module "db".

Tre modi in cui questo va storto, e che aspetto ha ciascuno

Una Recipe che scrive il proprio corpo non può consumare un riferimento tra componenti. Una Recipe artifacts: risolve i propri valori nel corpo che scrive, e quel corpo viene emesso nella directory propria del componente. Il riferimento si trova allora in un ambito che non dichiara alcuna chiamata di modulo:

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.

Non esiste un’ortografia che risolva il problema, perché le espressioni di un modulo annidato non possono nominare affatto un modulo fratello — un modulo annidato riceve il valore di un vicino solo come input, che è l’argomento del blocco module che il percorso con sorgente fornisce già. Un componente che consuma il valore pubblicato da un altro componente si scrive come Recipe source:.

Un indirizzo che nomina qualcosa all’interno del modulo del produttore si risolve rispetto alla radice, non rispetto a quel modulo. Una voce provides che scrive aws_db_instance.this.endpoint nomina una risorsa che il modulo del produttore dichiara; scritta come interpolazione, viene valutata dove si trova l’argomento del consumatore, cioè nella radice:

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.

Pubblica ${module.<...>.<output>} e dai al modulo un blocco output per il valore, anziché raggiungerne le risorse.

Una voce provides che non porta alcuna interpolazione viene consegnata come testo. Questo è il caso che non fallisce: il compilatore convoglia stringhe e non sa distinguere un puntatore da un letterale, quindi aws_db_instance.this.endpoint scritto senza ${ ... } viene renderizzato come stringa tra virgolette, la build riesce, il motore convalida e il consumatore riceve i caratteri aws_db_instance.this.endpoint. Scrivi l’involucro ${ ... } ogni volta che il valore è inteso come riferimento — è ciò che contrassegna la stringa come qualcosa che Terraform deve valutare.

Un limite da conoscere prima di farvi affidamento

.context.instance_id esprime l’identità del componente, e il nome di un blocco module deriva dalla directory in cui si trovano i file del componente. Per un componente dichiarato dall’Aggregate proprio della distribuzione, questi sono lo stesso nome. Per un componente incluso per composizione da un altro Aggregate non lo sono: l’identità composta e il nome del modulo vengono scritti nei rispettivi due alfabeti in modo diverso, e il riferimento fallisce allora in modo esplicito alla radice anziché in silenzio:

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.

Dichiara un produttore il cui indirizzo un altro componente risolve nell’Aggregate proprio della distribuzione, accanto al componente che lo consuma.

Dove finisce l’output di una Feature associata

Un’associazione di Feature che esegue il rendering di una configurazione propria riceve un modulo proprio, dichiarato nella stessa configurazione radice dei componenti accanto a essa. È questo che fa sì che la sua configurazione faccia parte della distribuzione: Terraform carica solo i file che si trovano direttamente in una directory e tratta una directory annidata come un modulo completamente separato che deve essere chiamato esplicitamente, quindi i file di un’associazione vengono letti perché la radice dichiara un blocco che nomina la directory in cui si trovano.

La directory del modulo di un’associazione si trova accanto a quella del componente, un livello sotto modules/, e prende il nome dalle due cose che la identificano — il componente che la ospita e il nome sotto cui è stata associata, unite con --. Quindi per un componente api che porta un’associazione chiamata aux, la configurazione radice dichiara due moduli:

module "api--aux" {
source = "./modules/api--aux"
}
module "api" {
source = "./modules/api"
}

Una Feature associata al confine anziché a un componente non ha un componente ospitante da nominare, quindi la sua directory è soltanto il suo nome: un’associazione chiamata aux su un confine che contiene il componente api produce ./modules/aux accanto a ./modules/api.

Perché accanto e non all’interno. Terraform unisce ogni file di primo livello di una directory di modulo in un unico namespace — output, variable, resource e locals allo stesso modo — quindi due contributori che condividono una directory entrano in collisione su qualsiasi nome dichiarino entrambi, comunque si chiamino i loro file. Una directory ciascuno è ciò che li tiene separati. Accanto anziché all’interno è anche ciò che chiede la guida di Terraform stesso per i moduli annidati: che siano componibili dal chiamante anziché chiamarsi direttamente l’un l’altro creando un albero di moduli profondamente annidato.

La giunzione è sottoposta a escape per coordinata. Ciascuna delle due coordinate viene scritta nell’alfabeto delle directory prima che vengano unite, così una coordinata che contiene a sua volta -- non può essere confusa con la giunzione: un ospitante chiamato a--b con un’associazione c è distinguibile da un ospitante a con un’associazione b--c. Le lettere ASCII, maiuscole e minuscole, le cifre, il punto e l’underscore passano così come sono scritti; un trattino che hai scritto viene mantenuto ovunque il carattere che lo segue sia uno di questi; qualsiasi altra cosa viene sottoposta a escape. La stessa regola e lo stesso alfabeto producono le directory figlie di una destinazione chart, così la directory di un’associazione si scrive allo stesso modo qualunque delle due destinazioni ne esegua il rendering.

Il nome di un blocco deriva dalla directory a cui punta il suo source, con ogni carattere al di fuori della grammatica di Terraform per un nome di modulo sostituito da un underscore. Questa corrispondenza non è biunivoca, quindi quando due contributori arriverebbero a uno stesso nome di modulo la build si arresta e li nomina entrambi, anziché emettere una configurazione che Terraform rifiuterebbe.

Dal fatto che un’associazione sia un modulo a sé derivano tre conseguenze.

I suoi input sono quelli della sua mappatura. Un’associazione la cui FeatureRecipe usa come sorgente un modulo e dichiara un valuesMapping ha i valori prodotti da quella mappatura scritti come argomenti del proprio blocco module, nello stesso modo in cui il modulo con sorgente di un componente riceve i suoi valori. Una FeatureRecipe che non dichiara alcun valuesMapping non passa al proprio modulo alcun argomento: una variabile che il modulo dichiara con un default lo assume, e una dichiarata senza valore predefinito resta non impostata, quindi Terraform rifiuta il piano.

Le sue risorse si trovano nell’unico grafo delle dipendenze del confine. Un riferimento o un depends_on arriva da un’associazione al componente a cui è associata e viceversa, e un solo terraform plan li vede entrambi — la stessa proprietà che la forma in cui la radice compone i figli dà ai componenti, per la stessa ragione.

I suoi nomi di primo livello sono suoi. Poiché l’unione dei namespace descritta sopra avviene per directory, un contributore che si trova in una directory propria dichiara i suoi nomi output, variable, resource e locals senza contenderli con quelli dei vicini — così un’associazione può riutilizzare un nome che il suo ospitante dichiara già, e nessuno dei due deve sapere come l’altro abbia chiamato qualsiasi cosa.

Nota ciò che questa destinazione non richiede, perché il vincolo di una destinazione chart è diverso e l’organizzazione condivisa può essere letta come se implicasse più di quanto implichi: un modulo annidato all’interno della directory di un altro contributore è comunque raggiungibile qui, poiché la configurazione radice legge il source di ciascun contributore dalla posizione che la build ha composto anziché ricostruirlo da un identificatore. Ciò che questa destinazione rifiuta è che due contributori condividano una directory. Una destinazione chart rifiuta del tutto la posizione annidata, perché individua un chart figlio un livello più in basso e non oltre.

Tipi di input supportati

Il provider terraform accetta due dei tre tipi di input delle Recipe:

  • Modalità artefatti. Una Recipe scrive la configurazione Terraform come corpo basato su template; il provider valuta il template di Aggrega ed emette il risultato senza riscriverlo. HCL (main.tf) è la scelta predefinita più comoda, e Terraform JSON (.tf.json) è accettato in modo equivalente. La provenienza della build viene apposta come un blocco di commenti Terraform in cima a un corpo HCL; per un corpo JSON — che non ha una sintassi per i commenti — la provenienza viene scritta in un file di accompagnamento, aggrega.provenance.tf, anziché inline.
  • Modalità con sorgente. Una Recipe fa riferimento a un modulo Terraform con source:. I file del modulo vengono copiati localmente (vendoring) così come sono nella directory di quel componente, e il valuesMapping: della Recipe diventa gli argomenti del blocco module di quel componente nella configurazione radice del confine. Il corpo del modulo viene conservato esattamente come è stato scritto e non vi viene scritto nulla; i valori sono indicati una sola volta, nella radice, dove Terraform li valuta. Dove le foglie values dichiarate del nodo diventano direttamente gli input del modulo — una Recipe source: senza valuesMapping: — un input che porta materiale che un autore ha dichiarato sensibile riceve anche un file di override generato che porta l’attributo di sensibilità proprio di Terraform; un template valuesMapping: inventa i nomi del proprio output, quindi quel caso non porta alcuna marcatura e la build lo segnala con un avviso consultivo. Entrambi sono descritti in Input di modulo dichiarati sensibili.

Un null in un valuesMapping: è un argomento null. Una chiave che la mappatura imposta a null viene scritta come <name> = null nel blocco module, e il motore assegna alla variabile del modulo il valore null, sovrascrivendone il default, a meno che la variabile non dichiari nullable = false, nel qual caso si applica il suo default; per dare a un input il valore predefinito del modulo, lascia la chiave fuori dalla mappatura.

Il tipo di input sintetizzato non è offerto. Non esiste una corrispondenza fedele e agnostica rispetto alle capacità dal tipo Workload della piattaforma a risorse Terraform arbitrarie, quindi una Recipe che dichiara workload: con il provider terraform è un errore esplicito anziché una traduzione inventata.

Una Recipe che dichiara omits: viene rifiutata. La chiave omits: esclude dalla build documenti che una sorgente renderizza, e questo provider non renderizza nulla da un modulo con sorgente in fase di build: copia localmente i file del modulo così come sono, e Terraform li valuta quando la configurazione viene pianificata e applicata. Se non viene renderizzato nulla, non c’è nulla da escludere, quindi questo provider non dichiara di rispettare la chiave, e una Recipe o una FeatureRecipe che la dichiara viene rifiutata prima che venga copiato localmente alcunché — vedi The provider does not support omits (Il provider non supporta omits). Per un modulo che tieni accanto alla Recipe, una riga nel .aggregaignore che si trova lì esclude invece un file del modulo, a partire dal pin successivo della Recipe.

Usare come sorgente un modulo pubblicato da un registry

Un registry di moduli pubblica ogni versione di un modulo come tag del repository git proprio del modulo, e ciò che risponde quando gli si chiede di scaricare una versione è una sorgente git fissata al commit indicato da quel tag. Quindi una Recipe usa come sorgente un modulo pubblicato da quel repository a quel tag, con il tipo di sorgente 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: è il tag di release esattamente come lo nomina il repository. valuesMapping: fornisce gli input del modulo, con i nomi dichiarati dai suoi blocchi variable — Terraform richiede un valore per ogni input che non dichiara alcun default — e questi diventano gli argomenti del blocco module di questo componente nella configurazione radice, come per qualsiasi modulo con sorgente.

Che cosa viene fissato. aggrega pin e il pull risolvono il tag nel commit che esso nomina e archiviano il repository a quel commit. Il file di lock della Release registra poi quel commit come versione fissata della sorgente, il tag come riferimento che hai scritto e il digest dell’archivio. Ogni build successiva legge l’archivio dalla cache e lo verifica rispetto a quel digest prima di copiare localmente qualsiasi cosa, quindi non ha bisogno di rete, e un archivio in cache i cui byte non corrispondono più arresta la build. Un tag è un nome che un repository può spostare su un altro commit; un pull successivo che trova il tuo risolto altrove si arresta anziché adottare il nuovo commit, e aggrega pull --upgrade lo adotta deliberatamente. Questo è un pin più stretto del file di lock delle dipendenze proprio di Terraform, che registra i provider selezionati da una configurazione e nessun modulo, quindi un modulo scritto in una configurazione come sorgente git a un tag è fissato solo quanto lo è il tag. Qui il commit del modulo e il digest dei suoi byte sono fissati nel file di lock, i byte vengono copiati localmente nell’output e la configurazione radice li chiama tramite un percorso locale, quindi il motore non scarica nulla per caricare il modulo stesso — un modulo che quello copiato localmente chiama tramite una sorgente di registry o remota viene comunque scaricato, e la build segnala ciascuna di queste chiamate, come descrive Una chiamata di modulo che il motore scarica durante l’inizializzazione.

Che cosa viene copiato localmente. L’intero repository al commit fissato, a parte la sua directory .git/, finisce nella directory propria del componente sotto modules/, byte per byte — i file di configurazione e i moduli figli propri del modulo, e anche tutto il resto che il repository contiene: le sue directory examples/ e wrappers/, la sua documentazione, la sua configurazione di CI e qualsiasi fixture di test, comprese quelle binarie. Il motore legge solo ciò che il modulo chiama: quando la configurazione radice chiama la directory del componente, il motore carica i file di configurazione che si trovano direttamente in essa e in ogni directory raggiunta da lì da un source locale. Una directory di esempio che chiama altri moduli di registry viene quindi copiata localmente e mai caricata, e nulla di ciò che chiama viene scaricato.

Restringere ciò che viene copiato localmente. Una sorgente scaricata è l’archivio con cui è stata scaricata, quindi l’unico modo per restringerla è module_subdir:, che rende una directory del repository l’artefatto. Questo aiuta solo quando il modulo che vuoi si trova in una sottodirectory: un modulo nella radice del repository che chiama i propri ./modules/* ha bisogno dell’intero albero. Né un .terraformignore contenuto nel repository né un .aggregaignore accanto alla Recipe cambiano ciò che una sorgente scaricata copia localmente — entrambi danno forma a un modulo tenuto accanto alla Recipe, e nessuno dei due viene letto per uno scaricato da un repository.

Leggere ciò che il modulo pubblica. Un valore che il modulo pubblica è uno dei suoi blocchi output, e un consumatore lo legge come ${module.<name>.<output>}, dove <name> è il blocco module del produttore — ed è per questo che il produttore sopra pubblica ${module.{{ .context.instance_id }}.<output>}. Il motore risolve il riferimento rispetto ai blocchi output propri del modulo quando convalida la configurazione radice, quindi un nome di output che il modulo non dichiara viene rifiutato lì, con il suo nome:

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 build non legge nessuno dei blocchi variable o output del modulo, non scrive nulla nel modulo e non vi aggiunge alcuna configurazione di provider, quindi un nome di output digitato male viene intercettato dal motore anziché dalla build. Vedi Consumare il valore pubblicato da un altro componente per il lato del consumatore.

Emissione invariata e copia locale (vendoring)

Il provider terraform non transpila, non riformatta e non riscrive i corpi Terraform. Un corpo HCL o .tf.json scritto dall’autore viene emesso esattamente come lo valuta il suo template, con un corpo HCL che si apre con i commenti di provenienza, e un modulo con sorgente viene copiato localmente file per file. È questo che mantiene l’output terraform deterministico e riproducibile: a parità di input, la configurazione renderizzata è identica byte per byte da un’esecuzione all’altra, e un modulo copiato localmente fa il giro di andata e ritorno senza modifiche. Poiché il provider non risolve mai lo stato di runtime, tutto ciò che dipende dal runtime resta una stringa di interpolazione che Terraform vincola al momento dell’apply.

Annotazioni di piattaforma

Il provider terraform non legge nessuna delle annotazioni aggrega.ai/. Un modulo copiato localmente, i file artefatto di una Recipe e la configurazione radice che il provider scrive non hanno uno spazio per un namespace, un prefisso di registry, un pull secret o un service account, quindi un valore impostato per uno di questi non cambia nulla nella configurazione renderizzata; un modulo che ha bisogno di un tale valore lo riceve come uno dei propri input, tramite i values del componente.

Il provider lo dichiara nella sua entità Plugin, con readsNoWellKnownAnnotations: true (vedi l’entità Plugin), e la build emette quindi un avvertimento per ogni annotazione aggrega.ai/ che raggiunge un rendering attraverso di esso — una volta per chiave e per rendering, nominando i tipi di input che quel rendering dichiara:

warning: node "db" (provider "terraform"): target "terraform" does not support annotation aggrega.ai/namespace on sourced input and ignored it

Il valore attraversa comunque la build intatto, e la build non si arresta: un’annotazione di confine si propaga a cascata su ogni componente sottostante, e un confine i cui componenti eseguono il rendering attraverso destinazioni diverse è normale e non un errore. L’avvertimento appartiene alla classe unsupported-field e si silenzia con il flag di quella classe.

Input di modulo dichiarati sensibili

Terraform è l’unica destinazione della libreria standard con una primitiva nativa di sensibilità per singolo valore, quindi un dato che un autore ha dichiarato sensibile può essere renderizzato nei termini propri di Terraform anziché essere soltanto registrato in quelli di Aggrega.

Quando l’input di un modulo copiato localmente porta materiale che un autore ha dichiarato sensibile, il provider aggiunge un ulteriore file accanto al modulo, aggrega_override.tf.json, che dichiara sensitive = true per quell’input:

{
"variable": {
"db_password": {
"sensitive": true
}
}
}

Terraform unisce un file di configurazione il cui nome è semplicemente override o termina con _override alla configurazione della stessa directory, quindi il blocco variable proprio del modulo acquisisce l’attributo mentre ogni byte copiato localmente resta esattamente come è stato scritto. Il tipo dichiarato, il valore predefinito e la descrizione dell’input restano intatti — l’override porta l’attributo di sensibilità e nient’altro. Un nodo non marcato non riceve alcun file di questo tipo.

Questo limite è deliberato e non qualcosa che il formato del file impone: nulla in un override rifiuta un secondo attributo, e il default di un blocco variable è lo spazio più vicino a cui ricorrere se si volesse portare un valore in un modulo copiato localmente senza modificarne i byte — ma non arriverebbe. Un default nella sintassi di configurazione JSON in cui è scritto questo file non è una posizione che Terraform valuta, quindi un valore che porta un puntatore ${ ... } scritto lì raggiunge il modulo come i caratteri letterali del puntatore, in un piano che riesce e non dice nulla. Lo stesso puntatore scritto in un default in HCL nativo viene rifiutato senza appello, il che colloca quel silenzio in questa sintassi e non nei file di override in quanto tali. Quindi l’override porta soltanto sensitive: il suo significato non dipende dall’essere valutato.

Quale input viene marcato deriva da una dichiarazione, mai da un nome. Il provider legge la marcatura calcolata dalla compilazione e non ispeziona nulla da sé: non riconosce password, secret o token, e non legge il testo del modulo per indovinare. Un input di modulo chiamato db_password il cui valore non porta alcuna dichiarazione viene emesso senza marcatura, e un input dichiarato chiamato region viene marcato.

La marcatura viaggia solo dove l’identità dell’input è ricostruibile a partire dalla dichiarazione. Una Recipe che copia localmente un modulo con source: e lascia che le foglie values dichiarate del nodo diventino direttamente gli input del modulo dà a ciascun input lo stesso nome che l’autore ha dichiarato, quindi il collegamento è esatto — e lo stesso vale per la FeatureRecipe di una Feature associata a un componente che copia localmente un modulo nello stesso modo, sulle foglie che la sua Feature dichiara. Una Recipe o una tale FeatureRecipe che rimodella quei valori tramite un template valuesMapping: inventa i nomi del proprio output, e nessuna dichiarazione li nomina — quindi la marcatura è assente anziché approssimata, e la build lo segnala con un avviso consultivo per ogni foglia dichiarata, nominando la foglia e l’entità di cui è la mappatura (una Feature associata a un confine esegue il rendering senza alcun values, quindi non ha nulla da marcare e non ne genera nessuno); vedi A declared-sensitive value reaches the target through a values mapping (Un valore dichiarato sensibile raggiunge la destinazione attraverso una mappatura di values). L’assenza è deliberata: indovinare quale input rimodellato abbia portato il dato dichiarato marcherebbe come segreto un input pubblico, e Terraform nasconderebbe allora dall’output del piano un valore che non è mai stato sensibile.

L’esempio svolto terraform-declared-sensitivity costruisce tutto questo da un capo all’altro ed è abbastanza piccolo da leggerlo per intero: un componente che dichiara tre foglie values, di cui due portano identificatori pubblici e una porta la credenziale. Il suo output renderizzato mostra gli argomenti del blocco module che portano tutti e tre gli input del modulo e l’override che nomina solo quello dichiarato, così entrambe le metà della regola sono visibili nella stessa build — compreso il fatto che un identificatore di credenziale che si trova accanto al segreto resta senza marcatura. Rimuovere l’unica dichiarazione e ricostruire non emette alcun file di override.

Che cosa garantisce e che cosa non garantisce il sensitive di Terraform

Aggrega promette esattamente ciò che fornisce l’attributo proprio di Terraform, e niente di più.

Limita la visualizzazione. Un valore sensibile appare come (sensitive value) nell’output del piano e come <sensitive> nell’output dell’apply. La marcatura si propaga attraverso le espressioni, quindi anche un valore derivato da un input sensibile è sensibile, e Terraform si rifiuta di esportarne uno da un output radice che non sia a sua volta marcato come sensibile — un errore esplicito anziché una divulgazione silenziosa.

Non cambia l’archiviazione, e non è cifratura. Terraform registra un valore sensibile nello stato in chiaro. Leggere sensitive = true come una promessa che lo stato sia sicuro da committare o condividere è l’unico fraintendimento da evitare: proteggere lo stato resta una questione di come è configurato il backend dello stato, esattamente come per un modulo che non porta alcuna marcatura. L’attributo inoltre non limita chi può leggere il valore, non influisce su ciò che un provider trasmette e non cambia in nessun altro modo la configurazione renderizzata.

Quindi la marcatura rende più difficile divulgare per errore un input dichiarato sensibile quando qualcuno legge un piano. Non rende sicuro pubblicare ciò che viene distribuito. Vedi Dichiarare sensibile una foglia per la parola chiave e per ciò che una dichiarazione ottiene su ogni destinazione.

Validazione strutturale dell’input

Il provider terraform convalida la struttura di un modulo con sorgente prima di eseguirne il rendering. Analizza i file HCL e .tf.json del modulo e segnala gli errori di parsing, arrestando la build con un messaggio chiaro che nomina il nodo in questione e il provider. Il parsing verifica la forma, non la semantica — non risolve i provider, non valuta espressioni e non contatta un registry. La validazione è ermetica: usa un parser HCL autonomo compilato nel provider, senza alcun binario terraform e senza accesso alla rete. Un modulo malformato viene intercettato al confine dell’authoring anziché emergere come un errore confuso in una successiva esecuzione di terraform.

Una chiamata di modulo che il motore scarica durante l’inizializzazione

La stessa lettura segnala, come avvertimento che non rifiuta nulla, ogni blocco module la cui sorgente Terraform scarica quando la configurazione viene inizializzata. Il commit e il digest dell’archivio di un modulo copiato localmente sono fissati nel file di lock, ma un blocco module al suo interno il cui source è un indirizzo di registry, un URL git, Mercurial o di archivio HTTP, un bucket S3 o GCS, o un percorso assoluto nomina un modulo che il motore scarica all’inizializzazione, in qualunque versione selezioni in quel momento — e il file di lock delle dipendenze proprio di Terraform registra solo i provider, quindi nulla fissa quel modulo. Viene segnalato anche un source locale che risale fuori dal modulo copiato localmente, perché nomina file che la build non ha copiato localmente. Ogni rilevamento nomina il nodo e il provider, poi il blocco, il file e la riga in cui si trova, e la sorgente così come è scritta:

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 module

Che cosa viene letto. I file che il motore carica quando il modulo viene chiamato: i file di configurazione che si trovano direttamente nella directory propria del modulo, poi quelli in ogni directory raggiunta da lì da un source locale — uno che inizia con ./ o ../, o con le loro grafie con la barra rovesciata — seguiti di directory in directory e ciascuno letto una sola volta. Una directory che nulla chiama non viene letta, quindi le chiamate fatte dalla directory examples/ o tests/ di un modulo non vengono segnalate: il motore non le carica mai quando il modulo viene chiamato, e nulla di ciò che chiamano viene scaricato. Il controllo di parsing descritto sopra analizza comunque ogni file di configurazione copiato localmente. Il corpo scritto da una Recipe viene letto nello stesso modo quando viene renderizzato, a partire dalla directory in cui il corpo viene scritto, quindi viene segnalato anche un blocco module che un corpo scritto dall’autore scrive con una sorgente di registry. Un file sotto spec.boundary.artifacts viene valutato e scritto dal compilatore stesso e non viene passato ad alcun provider, quindi un blocco module scritto in uno di questi file non viene letto e non genera alcun avvertimento.

Che cosa non viene letto. Viene letto solo ciò che dice un source. La build non legge il modulo che una chiamata nomina, non giudica che cosa faccia quel modulo e non decide se la chiamata sia accettabile. Un source che il motore valuta anziché leggere così come è scritto — uno che porta un’interpolazione, o un riferimento — viene giudicato dal suo testo iniziale: uno che inizia con un indirizzo viene segnalato così come è scritto, mentre uno che inizia con un prefisso locale, o con l’interpolazione stessa, non viene né segnalato né seguito, perché dove porta non è nel testo. Un source all’interno di required_providers nomina un provider anziché un modulo e non è una chiamata di modulo.

Perché viene segnalato anziché rifiutato. Un modulo che chiama un altro modulo è un input legittimo: Terraform scarica il modulo chiamato e la configurazione funziona. Ciò a cui l’autore rinuncia è il pin della build sul modulo chiamato, che è un fatto che vale la pena conoscere e non un difetto da correggere, e se quello scaricamento sia accettabile è un giudizio dell’autore. Una configurazione che deve restare completamente fissata copia localmente solo moduli che non fanno chiamate di questo tipo. L’avvertimento, il suo codice di classe e dove altro arriva sono descritti in Avvertimenti e output del linter.

Confine delle patch della FeatureRecipe

Un passo pipeline post-rendering di una FeatureRecipe applica patch solo all’output che il provider renderizza in un albero strutturato. Per terraform questo significa:

  • Il Terraform scritto in JSON è modificabile tramite patch. Un modulo .tf.json è un documento strutturato, quindi il JSONPatch di un passo della pipeline modifica sul posto i valori indirizzati e lascia intatto ogni altro byte — ordinamento, formattazione, chiavi circostanti.
  • L’HCL nativo è opaco. Un corpo in HCL nativo (main.tf) non è una destinazione strutturata per le patch. Una patch su un corpo opaco arresta la build con una diagnostica anziché modificare testo che non può indirizzare strutturalmente; scrivere un passo della pipeline contro un corpo HCL è un errore di progettazione che emerge come arresto esplicito, non come un’operazione nulla silenziosa.
  • Gli input di un modulo con sorgente non sono affatto una destinazione per le patch. Sono gli argomenti del blocco module del componente, che si trova nella configurazione radice: HCL nativo, e quindi opaco, e un artefatto dell’intero confine anziché di un singolo nodo. Un passo pipeline applica patch all’output renderizzato proprio di un nodo, quindi non esiste una posizione da cui indirizzarli.

Un autore che ha bisogno che un corpo Terraform sia modificabile tramite patch della pipeline lo scrive quindi come .tf.json. Vedi FeatureRecipe per il confine generale delle destinazioni delle patch tra i provider.

Ordine di distribuzione

Il valore syncWave: del confine di una Release ordina i blocchi module della configurazione radice in cui quel confine viene assemblato. Ogni componente del confine eredita l’ondata del confine e, dove più confini si risolvono nella stessa directory di output — così che i loro componenti vengono composti in un’unica configurazione radice — quella radice contiene più di un’ondata e il provider esprime l’ordinamento tra di esse come depends_on sui blocchi module.

Ogni modulo nomina ogni modulo dell’ondata immediatamente precedente che abbia dei componenti, e nessuna ondata anteriore a quella. Terraform concatena il resto: un modulo nell’ondata 2 dipende dall’ondata 1, che dipende dall’ondata 0, così l’intera sequenza è ordinata mentre l’elenco proprio di ciascun modulo resta della dimensione di un’ondata anziché dell’intero confine. Le ondate non devono essere contigue, e i valori negativi sono normali — -1 è una scelta comune per un bucket o un ruolo che il resto della configurazione legge. L’ondata più bassa non nomina nulla, perché nulla la precede.

Che cos’è l’ordinamento: l’ordine in cui Terraform esegue le sue azioni. Terraform costruisce un grafo delle dipendenze e lo percorre in parallelo nella misura in cui il grafo lo consente. depends_on aggiunge un arco a quel grafo, così Terraform completa le proprie azioni sui moduli nominati prima di iniziare quelle sul modulo che dichiara la dipendenza. Un’ondata scandisce quindi l’esecuzione in fasi: si agisce sui componenti dell’ondata precedente prima di iniziare quelli dell’ondata successiva.

Non è un ordinamento per prontezza. Una configurazione Terraform non esprime alcuna nozione di risorsa utilizzabile, quindi qui nulla attende che una risorsa diventi pronta — solo che Terraform finisca di agire su di essa. Questa è una differenza reale rispetto alla stessa ondata su compose, dove un servizio che dichiara un healthcheck viene atteso finché non risulta integro: compose ha una primitiva di prontezza su cui basarsi e una configurazione Terraform non ne ha nessuna. L’ordine delle azioni è ciò che offre questa destinazione, e dichiararlo apertamente è più utile di un’avvertenza allegata a una promessa che non può mantenere.

Non viene promesso alcun ordine di smantellamento. Ciò che depends_on afferma è che Terraform completa le azioni della dipendenza prima di iniziare quelle del dipendente; l’ordine in cui un destroy li rimuove non fa parte di questa affermazione, quindi qui non si afferma nulla sulla sequenza di smantellamento. Questa è una promessa più ristretta di quella che la stessa ondata porta su cloudformation, il cui attributo governa entrambe le direzioni — un aspetto da conoscere se fai affidamento su un’ondata per mettere in sequenza uno smantellamento, perché su questa destinazione non lo fa.

Un confine i cui componenti portano tutti una stessa ondata non ne ricava nulla. Lo stesso vale per una Release che non dichiara alcun syncWave: ogni contributore porta il valore predefinito del campo, 0, la configurazione radice contiene un’unica ondata e i byte emessi sono esattamente quelli che sarebbero se il provider non esprimesse alcun ordinamento per ondate.

L’ordinamento tra due configurazioni radice non è esprimibile, e non viene approssimato. Un grafo delle dipendenze di Terraform è per configurazione e depends_on nomina un modulo all’interno della configurazione che lo dichiara, quindi un’ondata ordina ogni componente composto in quella radice e nulla al di là di essa. Mettere in sequenza due configurazioni è compito dell’operatore, nello stesso modo in cui un riferimento a uno stato remoto è una risoluzione al momento della distribuzione anziché al momento della build.

L’ondata viene registrata oltre che applicata: viaggia con il resto della provenienza della build del nodo, come aggrega.ai/sync-wave nel blocco di commenti apposto, oppure nel file di provenienza di accompagnamento dove il corpo è JSON o un modulo copiato localmente. Così una configurazione renderizzata registra quale ondata ha dichiarato il suo confine, oltre a esserne ordinata.

L’ordinamento che le ondate non esprimono resta compito di Terraform stesso, e i riferimenti tra le risorse ne portano già gran parte: un riferimento a un attributo di un’altra risorsa dice a Terraform di agire prima su quella risorsa. Un modulo che ha bisogno di un vincolo che né i riferimenti né le ondate implicano scrive il proprio depends_on all’interno del modulo, che il provider emette così com’è, come ogni altra parte del corpo.