Provider Terraform
O provedor terraform renderiza Recipes de Aggrega em configuração do Terraform. Ele emite configuração e nunca executa o Terraform: um build de Aggrega é uma compilação ahead-of-time, então não consegue resolver os IDs de recursos, os endereços IP e as saídas que só existem depois de terraform apply. As interpolações ${ ... } do Terraform passam intactas como strings de ponteiro determinísticas que o runtime do Terraform resolve depois. O provedor é offline e hermético — nunca acessa a rede e nunca invoca terraform nem tofu.
Como uma fronteira é organizada
O provedor terraform compõe uma fronteira em vez de emitir seus componentes lado a lado. Cada fronteira que ele renderiza recebe uma única configuração raiz, aggrega.modules.tf, que declara cada componente renderizado ali como um bloco module cujo source é o subdiretório próprio desse componente sob modules/:
module "cache" { source = "./modules/cache"}
module "db" { source = "./modules/db"
allocated_storage = 100 db_name = "appdb" engine_version = "11.4"}Os arquivos próprios de cada componente — o módulo copiado localmente (vendoring) ou o corpo escrito pelo autor, e o carimbo de proveniência — ficam no subdiretório para o qual seu bloco aponta. Essa é a estrutura padrão do Terraform em que a raiz compõe os filhos, cuja convenção é que os módulos aninhados fiquem sob um subdiretório modules/, e é a organização que toda fronteira terraform recebe, contenha ela um componente ou vários. Uma Feature vinculada a um componente ou à fronteira é declarada como um bloco module próprio na mesma configuração raiz — veja Onde a saída de uma Feature vinculada vai parar.
A forma é estrutural, e não cosmética, por dois motivos.
Um grafo de dependências do Terraform é por configuração. Components emitidos em diretórios separados são grafos separados, sem nenhuma relação: nem uma referência nem um depends_on consegue ir de um ao outro, e nenhum terraform plan isolado vê ambos. Uma única raiz que compõe cada componente como módulo filho coloca uma fronteira inteira em um só grafo e um só plano.
Os arquivos de um componente são endereçados por seu próprio diretório. Dois componentes de uma mesma fronteira podem copiar localmente módulos que escrevem arquivos com nomes idênticos — main.tf, variables.tf — e cada conjunto fica sob o diretório do seu próprio componente em vez de disputar um mesmo caminho.
Onde um provedor é configurado
A configuração de um provedor — um bloco provider — é escrita na raiz, nunca dentro do módulo de um componente. A documentação do Terraform diz que um módulo destinado a ser chamado por outro não deve conter blocos provider, e que um módulo chamado herda a configuração padrão da raiz para cada provedor que esse módulo usa. Um módulo que traz um bloco provider próprio não pode ser chamado com depends_on, count ou for_each, e este provedor escreve depends_on no bloco module de um componente sempre que outro componente da mesma raiz traz um syncWave anterior, como descreve Ordem de implantação abaixo; o Terraform então recusa a configuração inteira enquanto a carrega, antes de planejar qualquer coisa.
Assim, uma Recipe cujo provedor precisa de configuração escreve essa configuração como um arquivo sob spec.boundary.artifacts. Cada um desses arquivos é escrito uma única vez ao lado de aggrega.modules.tf, onde o Terraform o lê junto com a configuração raiz, e o módulo do componente mantém apenas sua declaração required_providers da origem e da versão do provedor:
infra/terraform/ aggrega.modules.tf provider-azurerm.tf modules/ gateway/main.tfComponents de uma mesma raiz que declaram o mesmo arquivo com os mesmos bytes compartilham a única cópia; o mesmo nome com bytes diferentes interrompe o build. Os recursos dos módulos são registrados em relação a essa única configuração, então é também com ela que o Terraform os destrói. Uma Release que remove o último componente que declara o arquivo remove o arquivo junto, e o Terraform então se recusa a planejar a destruição do que esses módulos criaram, pedindo um bloco provider que configure o provedor. Destrua esses recursos antes de remover o último desses componentes.
Onde as entradas de um componente são fornecidas
As entradas de um componente são os argumentos do seu bloco module na configuração raiz, e esse é o único lugar onde são escritas. Um bloco traz argumentos quando é o compilador que fornece as entradas do módulo — uma Recipe que copia localmente um módulo com source:. Ele fica vazio quando a Recipe escreveu ela mesma o corpo da configuração e resolveu seus valores nesse corpo, de modo que não resta nada para o compilador passar.
Um argumento de módulo é uma posição que o Terraform avalia, e é por isso que os valores vão ali. Um ponteiro ${ ... } fornecido por uma Recipe é resolvido ali em vez de chegar ao módulo como uma string literal. Aquilo em relação a que ele é resolvido é a configuração raiz: uma referência nomeia algo que essa configuração declara — um de seus blocos module, como module.<name>.<output> — e uma referência a qualquer coisa que ela não declare é um erro explícito no momento do plano que nomeia o referente ausente.
O diretório próprio de um componente não é, portanto, uma configuração que você possa planejar tal como é implantada. Suas entradas são indicadas um nível acima, na raiz, então posicionar-se em modules/<component> e executar o motor ali planeja outra coisa, e qual de duas coisas acontece depende dos blocos variable do próprio módulo:
- Quando pelo menos uma entrada não declara nenhum
default, o plano falha de forma explícita —No value for required variable, nomeando cada variável não definida e sua linha, e oferecendo o remédio do próprio Terraform,-var/-var-file. - Quando toda entrada traz um
default, o plano é bem-sucedido e é construído a partir dos valores padrão do módulo em vez dos valores que a configuração raiz fornece. Nada avisa, então esse é o caso a conhecer: um plano que parece correto está descrevendo uma configuração que ninguém pediu.
Em vez disso, planeje o diretório de saída próprio da fronteira — aquele que contém aggrega.modules.tf, imediatamente acima de modules/. É ali que estão os valores da implantação, e é o único lugar onde um único plano vê a fronteira inteira.
Consumindo o valor publicado de outro componente
Um componente conectado a outro por uma aresta uses lê os valores publicados desse componente por meio do seu próprio pipe .context.inject (ou por meio de .context.uses.<alias>.provides.<name>). O que ele lê é uma string que o compilador encaminha sem interpretá-la, e o lugar onde essa string vai parar é texto que o Terraform avalia no escopo em que a Recipe o escreveu. Uma fronteira terraform tem dois desses escopos, e só um deles declara as chamadas de módulo de que uma referência entre componentes precisa:
- a configuração raiz declara cada contribuidor como um bloco
module, entãomodule.<name>.<output>é resolvido ali; - o diretório próprio de um componente não declara nenhuma chamada de módulo, então
module.<name>.<output>não nomeia nada ali — seja qual for<name>. Substituir pelo nome correto não muda nada, porque o que falta é a declaração, não a grafia.
Então é o tipo de entrada da Recipe consumidora que decide se uma referência consumida pode ser resolvida, e não o valor consumido.
Escreva uma Recipe consumidora como uma Recipe source:. O seu valuesMapping: se torna os argumentos do seu próprio bloco module na configuração raiz — a única posição que é ao mesmo tempo avaliada e está em um escopo em que seus vizinhos são declarados.
Um par detalhado
O produtor publica um endereço que nomeia sua própria chamada de módulo, que é a forma que o escopo do seu consumidor declara. .context.instance_id está na superfície de avaliação de provides, e para um componente que o Aggregate da implantação declara, é o nome que o bloco module desse componente traz:
# 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}"O consumidor copia localmente um módulo que declara uma entrada e mapeia o valor injetado para ela:
# 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 }}"O Aggregate os conecta, nomeando a chave publicada que a aresta transporta:
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: endpointO build emite uma única configuração raiz na qual a referência e seu referente são declarados juntos:
module "api" { source = "./modules/api"
store_endpoint = "${module.store.endpoint}"}
module "store" { source = "./modules/store"
bucket = "app-artifacts"}O Terraform resolve module.store.endpoint porque a mesma configuração declara module "store", e o valor chega ao módulo do consumidor como uma entrada comum.
O exemplo aws-rds-and-ecs-service constrói esse par a partir de Recipes da biblioteca padrão: um banco de dados PostgreSQL provisionado pelo módulo RDS publicado e um servidor executado no Amazon ECS, cujo argumento environment traz ${module.db.db_instance_address} na configuração raiz que declara module "db".
Três maneiras de isso dar errado, e como cada uma se apresenta
Uma Recipe que escreve o próprio corpo não pode consumir uma referência entre componentes. Uma Recipe artifacts: resolve seus valores no corpo que escreve, e esse corpo é emitido no diretório próprio do componente. A referência fica então em um escopo que não declara nenhuma chamada de módulo:
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.Nenhuma grafia corrige isso, porque as expressões de um módulo aninhado não podem nomear de forma alguma um módulo irmão — um módulo aninhado recebe o valor de um vizinho apenas como entrada, que é o argumento do bloco module que o caminho com fonte já fornece. Um componente que consome o valor publicado de outro componente é escrito como uma Recipe source:.
Um endereço que nomeia algo dentro do próprio módulo do produtor é resolvido em relação à raiz, não em relação a esse módulo. Uma entrada provides que escreve aws_db_instance.this.endpoint nomeia um recurso que o módulo do produtor declara; escrita como uma interpolação, ela é avaliada onde fica o argumento do consumidor, que é a raiz:
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.Publique ${module.<...>.<output>} e dê ao módulo um bloco output para o valor, em vez de acessar diretamente seus recursos.
Uma entrada provides sem interpolação é entregue como texto. Esse é o caso que não falha: o compilador encaminha strings e não consegue distinguir um ponteiro de um literal, então aws_db_instance.this.endpoint escrito sem ${ ... } é renderizado como uma string entre aspas, o build é bem-sucedido, o motor valida e o consumidor recebe os caracteres aws_db_instance.this.endpoint. Escreva o invólucro ${ ... } sempre que o valor for pensado como uma referência — é ele que marca a string como algo para o Terraform avaliar.
Um limite que vale a pena conhecer antes de depender dele
.context.instance_id expressa a identidade do componente, e o nome de um bloco module é derivado do diretório em que ficam os arquivos do componente. Para um componente que o próprio Aggregate da implantação declara, esses são o mesmo nome. Para um componente incorporado por composição a partir de outro Aggregate, não são: a identidade composta e o nome do módulo são escritos de forma diferente em seus dois alfabetos, e a referência então falha de forma explícita na raiz em vez de silenciosamente:
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.Declare um produtor cujo endereço outro componente resolve no próprio Aggregate da implantação, ao lado do componente que o consome.
Onde a saída de uma Feature vinculada vai parar
Uma vinculação de Feature que renderiza configuração própria recebe um módulo próprio, declarado na mesma configuração raiz que os componentes ao seu lado. É isso que faz sua configuração fazer parte da implantação: o Terraform carrega apenas os arquivos que ficam diretamente em um diretório e trata um diretório aninhado como um módulo completamente separado, que precisa ser chamado explicitamente, então os arquivos de uma vinculação são lidos porque a raiz declara um bloco que nomeia o diretório em que eles ficam.
O diretório de módulo de uma vinculação fica ao lado do diretório do componente, um nível abaixo de modules/, e recebe o nome das duas coisas que o identificam — o componente que hospeda a vinculação e o nome sob o qual ela foi vinculada, unidos por --. Assim, para um componente api que traz uma vinculação chamada aux, a configuração raiz declara dois módulos:
module "api--aux" { source = "./modules/api--aux"}
module "api" { source = "./modules/api"}Uma Feature vinculada à fronteira em vez de a um componente não tem um componente hospedeiro para nomear, então seu diretório é apenas o seu próprio nome: uma vinculação chamada aux em uma fronteira que contém o componente api produz ./modules/aux ao lado de ./modules/api.
Por que ao lado, e não dentro. O Terraform mescla todo arquivo de nível superior de um diretório de módulo em um único namespace — output, variable, resource e locals igualmente — então dois contribuidores que compartilham um diretório colidem em qualquer nome que ambos declarem, seja qual for o nome de seus arquivos. Um diretório para cada um é o que os mantém separados. Ao lado, e não dentro, é também o que a própria orientação do Terraform para módulos aninhados pede: que eles possam ser compostos pelo chamador em vez de chamarem uns aos outros diretamente, criando uma árvore de módulos profundamente aninhada.
A junção é escapada por coordenada. Cada uma das duas coordenadas é escrita no alfabeto de diretórios antes de serem unidas, de modo que uma coordenada que contém ela mesma -- não pode ser confundida com a junção: um hospedeiro chamado a--b com uma vinculação c é distinguível de um hospedeiro a com uma vinculação b--c. Letras ASCII maiúsculas e minúsculas, dígitos, o ponto e o sublinhado passam como foram escritos; um hífen que você escreveu é mantido sempre que o caractere depois dele for um desses; qualquer outra coisa é escapada. A mesma regra e o mesmo alfabeto produzem os diretórios filhos de um destino chart, de modo que o diretório de uma vinculação é escrito da mesma forma, seja qual for o dos dois destinos que o renderiza.
O nome de um bloco é derivado do diretório para o qual seu source aponta, com cada caractere fora da gramática do Terraform para um nome de módulo substituído por um sublinhado. Esse mapeamento não é biunívoco, então, onde dois contribuidores chegariam a um único nome de módulo, o build é interrompido e nomeia ambos, em vez de emitir uma configuração que o Terraform rejeitaria.
Três coisas decorrem de uma vinculação ser um módulo próprio.
Suas entradas são as do seu próprio mapeamento. Uma vinculação cuja FeatureRecipe usa um módulo como fonte e declara um valuesMapping tem os valores que esse mapeamento produz escritos como os argumentos do seu próprio bloco module, da mesma forma que o módulo com fonte de um componente recebe seus valores. Uma FeatureRecipe que não declara nenhum valuesMapping não passa nenhum argumento ao seu módulo: uma variável que o módulo declara com um default o assume, e uma declarada sem valor padrão fica sem definição, então o Terraform recusa o plano.
Seus recursos ficam no único grafo de dependências da fronteira. Uma referência ou um depends_on alcança, nos dois sentidos, uma vinculação e o componente ao qual ela foi vinculada, e um único terraform plan vê ambos — a mesma propriedade que a forma em que a raiz compõe os filhos dá aos componentes, pelo mesmo motivo.
Seus nomes de nível superior são seus. Como a mesclagem de namespace descrita acima é por diretório, um contribuidor que fica em um diretório próprio declara seus nomes output, variable, resource e locals sem disputá-los com os de seus vizinhos — assim uma vinculação pode reutilizar um nome que seu hospedeiro já declara, e nenhum dos dois precisa saber como o outro chamou qualquer coisa.
Observe o que este destino não exige, porque a restrição de um destino chart é diferente e a organização compartilhada pode ser lida como se implicasse mais do que implica: um módulo aninhado dentro do diretório de outro contribuidor ainda é alcançável aqui, já que a configuração raiz lê o source de cada contribuidor a partir da posição que o build compôs, em vez de reconstruí-lo a partir de um identificador. O que este destino recusa é que dois contribuidores compartilhem um diretório. Um destino chart recusa por completo a posição aninhada, porque descobre um chart filho um nível abaixo e não além.
Tipos de entrada suportados
O provedor terraform aceita dois dos três tipos de entrada de Recipe:
- Modo artefatos. Uma Recipe escreve configuração do Terraform como um corpo baseado em template; o provedor avalia o template do Aggrega e emite o resultado sem reescrevê-lo. HCL (
main.tf) é o padrão mais ergonômico, e Terraform JSON (.tf.json) é aceito de forma equivalente. A proveniência do build é carimbada como um bloco de comentários do Terraform no topo de um corpo HCL; para um corpo JSON — que não tem sintaxe de comentários — a proveniência é escrita em um arquivo complementar,aggrega.provenance.tf, em vez de em linha. - Modo com fonte. Uma Recipe referencia um módulo do Terraform com
source:. Os arquivos do módulo são copiados localmente (vendoring) sem alterações para o diretório desse componente, e ovaluesMapping:da Recipe se torna os argumentos do blocomoduledesse componente na configuração raiz da fronteira. O corpo do módulo é preservado exatamente como foi escrito e nada é escrito nele; os valores são indicados uma única vez, na raiz, onde o Terraform os avalia. Onde as folhasvaluesdeclaradas do nó se tornam diretamente as entradas do módulo — uma Recipesource:semvaluesMapping:—, uma entrada que traz material que um autor declarou sensível também recebe um arquivo de override gerado que traz o atributo de sensibilidade do próprio Terraform; um templatevaluesMapping:inventa seus nomes de saída, então esse caso não traz nenhuma marcação e o build o relata com um aviso consultivo. Ambos são descritos em Entradas de módulo declaradas sensíveis.
Um null em um valuesMapping: é um argumento null. Uma chave que o mapeamento define como null é escrita como <name> = null no bloco module, e o motor dá à variável do módulo o valor null, substituindo seu default, a menos que a variável declare nullable = false, caso em que seu default se aplica; para dar a uma entrada o valor padrão do módulo, deixe a chave fora do mapeamento.
O tipo de entrada sintetizado não é oferecido. Não existe um mapeamento fiel e agnóstico em relação às capacidades do tipo Workload da plataforma para recursos arbitrários do Terraform, então uma Recipe que declara workload: com o provedor terraform é um erro explícito em vez de uma tradução inventada.
Uma Recipe que declara omits: é recusada. A chave omits: deixa fora do build documentos que uma fonte renderiza, e este provedor não renderiza nada a partir de um módulo com fonte no momento do build: ele copia localmente os arquivos do módulo sem alterações, e o Terraform os avalia quando a configuração é planejada e aplicada. Sem nada renderizado, não há nada a deixar de fora, então este provedor não declara que respeita a chave, e uma Recipe ou FeatureRecipe que a declare é recusada antes que qualquer coisa seja copiada localmente — veja The provider does not support omits (O provedor não oferece suporte a omits). Para um módulo que você mantém ao lado da Recipe, uma linha no .aggregaignore ali presente deixa, em vez disso, um arquivo do módulo de fora, a partir do próximo pin da Recipe.
Usar como fonte um módulo publicado por um registro
Um registro de módulos publica cada versão de um módulo como uma tag do repositório git do próprio módulo, e o que ele responde quando solicitado a baixar uma versão é uma fonte git fixada no commit que essa tag nomeia. Assim, uma Recipe usa como fonte um módulo publicado a partir desse repositório nessa tag, com o tipo de fonte 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: é a tag de versão exatamente como o repositório a nomeia. valuesMapping: fornece as entradas do módulo, pelos nomes que seus blocos variable declaram — o Terraform exige um valor para cada entrada que não declara nenhum default — e elas se tornam os argumentos do bloco module deste componente na configuração raiz, como para qualquer módulo com fonte.
O que é fixado. aggrega pin e o pull resolvem a tag para o commit que ela nomeia e arquivam o repositório nesse commit. O arquivo de bloqueio da Release registra então esse commit como a versão fixada da fonte, a tag como a referência que você escreveu e o digest do arquivo compactado. Cada build posterior lê o arquivo compactado do cache e o verifica contra esse digest antes de copiar localmente qualquer coisa, então não precisa de rede, e um arquivo compactado em cache cujos bytes não correspondem mais interrompe o build. Uma tag é um nome que um repositório pode mover para outro commit; um pull posterior que encontra a sua resolvida em outro lugar é interrompido em vez de adotar o novo commit, e aggrega pull --upgrade o adota deliberadamente. Essa é uma fixação mais rígida que o arquivo de bloqueio de dependências do próprio Terraform, que registra os provedores que uma configuração selecionou e nenhum módulo, de modo que um módulo escrito em uma configuração como fonte git em uma tag só fica tão fixo quanto a tag. Aqui, o commit do módulo e o digest dos seus bytes ficam fixados no arquivo de bloqueio, os bytes são copiados localmente para a saída e a configuração raiz os chama por um caminho local, então o motor não baixa nada para carregar o próprio módulo — um módulo que o módulo copiado localmente chama por uma fonte de registro ou remota ainda é baixado, e o build relata cada uma dessas chamadas, como descreve Uma chamada de módulo que o motor baixa ao inicializar.
O que é copiado localmente. O repositório inteiro no commit fixado, exceto seu diretório .git/, vai parar no diretório próprio do componente sob modules/, byte a byte — os arquivos de configuração e os módulos filhos do próprio módulo, e também tudo o mais que o repositório traz: seus diretórios examples/ e wrappers/, sua documentação, sua configuração de CI e quaisquer fixtures de teste, inclusive binárias. O motor lê apenas o que o módulo chama: quando a configuração raiz chama o diretório do componente, o motor carrega os arquivos de configuração que ficam diretamente nele e em cada diretório que um source local alcança a partir dali. Um diretório de exemplo que chama outros módulos de registro é, portanto, copiado localmente e nunca carregado, e nada do que ele chama é baixado.
Restringir o que é copiado localmente. Uma fonte baixada é o arquivo compactado como o qual foi baixada, então a única forma de restringi-la é module_subdir:, que torna um diretório do repositório o artefato. Isso só ajuda quando o módulo que você quer fica em um subdiretório: um módulo na raiz do repositório que chama seus próprios ./modules/* precisa da árvore inteira. Nem um .terraformignore que o repositório traga nem um .aggregaignore ao lado da Recipe mudam o que uma fonte baixada copia localmente — ambos moldam um módulo mantido ao lado da Recipe, e nenhum dos dois é lido para um módulo baixado de um repositório.
Ler o que o módulo publica. Um valor que o módulo publica é um de seus blocos output, e um consumidor o lê como ${module.<name>.<output>}, onde <name> é o bloco module do produtor — e é por isso que o produtor acima publica ${module.{{ .context.instance_id }}.<output>}. O motor resolve a referência em relação aos blocos output do próprio módulo quando valida a configuração raiz, então um nome de saída que o módulo não declara é recusado ali, com o nome indicado:
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".O build não lê nenhum dos blocos variable ou output do módulo, não escreve nada no módulo e não adiciona a ele nenhuma configuração de provedor, então um nome de saída digitado errado é detectado pelo motor em vez de pelo build. Veja Consumindo o valor publicado de outro componente para o lado do consumidor.
Emissão sem alterações e cópia local (vendoring)
O provedor terraform não transpila, não reformata nem reescreve corpos do Terraform. Um corpo HCL ou .tf.json escrito pelo autor é emitido exatamente como seu template é avaliado, com um corpo HCL abrindo com os comentários de proveniência, e um módulo com fonte é copiado localmente arquivo por arquivo. É isso que mantém a saída do terraform determinística e reproduzível: dadas as mesmas entradas, a configuração renderizada é idêntica byte a byte entre execuções, e um módulo copiado localmente faz o percurso de ida e volta sem alterações. Como o provedor nunca resolve o estado de runtime, tudo o que depende do runtime permanece uma string de interpolação que o Terraform vincula no momento do apply.
Anotações de plataforma
O provedor terraform não lê nenhuma das anotações aggrega.ai/. Um módulo copiado localmente, os arquivos de artefato de uma Recipe e a configuração raiz que o provedor escreve não têm espaço para um namespace, um prefixo de registro, um pull secret ou uma service account, então um valor definido para um deles não muda nada na configuração renderizada; um módulo que precisa de um valor assim o recebe como uma de suas próprias entradas, por meio dos values do componente.
O provedor declara isso em sua entidade Plugin, com readsNoWellKnownAnnotations: true (veja a entidade Plugin), e o build, portanto, emite um aviso para cada anotação aggrega.ai/ que chega a uma renderização por meio dele — uma vez por chave e por renderização, nomeando os tipos de entrada que essa renderização declara:
warning: node "db" (provider "terraform"): target "terraform" does not support annotation aggrega.ai/namespace on sourced input and ignored itO valor ainda passa pelo build intacto, e o build não é interrompido: uma anotação de fronteira se propaga em cascata para cada componente abaixo dela, e uma fronteira cujos componentes renderizam por meio de destinos diferentes é algo normal, e não um erro. O aviso pertence à classe unsupported-field e é silenciado com a flag dessa classe.
Entradas de módulo declaradas sensíveis
O Terraform é o único destino da biblioteca padrão com uma primitiva nativa de sensibilidade por valor, de modo que um dado que um autor declarou sensível pode ser renderizado nos termos do próprio Terraform em vez de ser apenas registrado nos do Aggrega.
Quando a entrada de um módulo copiado localmente traz material que um autor declarou sensível, o provedor acrescenta mais um arquivo ao lado do módulo, aggrega_override.tf.json, declarando sensitive = true para essa entrada:
{ "variable": { "db_password": { "sensitive": true } }}O Terraform mescla um arquivo de configuração cujo nome é simplesmente override ou termina em _override à configuração do mesmo diretório, de modo que o bloco variable do próprio módulo adquire o atributo enquanto cada byte copiado localmente permanece exatamente como foi escrito. O tipo declarado, o valor padrão e a descrição da entrada não são tocados — o override traz o atributo de sensibilidade e nada mais. Um nó não marcado não recebe nenhum arquivo desse tipo.
Esse limite é deliberado, e não algo que o formato do arquivo imponha: nada em um override recusa um segundo atributo, e o default de um bloco variable é o espaço mais próximo a que se recorreria para levar um valor a um módulo copiado localmente sem editar seus bytes — mas ele não chegaria. Um default na sintaxe de configuração JSON em que este arquivo é escrito não é uma posição que o Terraform avalia, então um valor que traz um ponteiro ${ ... } escrito ali chega ao módulo como os caracteres literais do ponteiro, em um plano que é bem-sucedido e não diz nada. O mesmo ponteiro escrito em um default em HCL nativo é rejeitado de imediato, o que situa esse silêncio nesta sintaxe, e não em arquivos de override como tais. Por isso o override traz apenas sensitive: seu significado não depende de ser avaliado.
Qual entrada é marcada vem de uma declaração, nunca de um nome. O provedor lê a marcação que a compilação calculou e não inspeciona nada por conta própria: não reconhece password, secret ou token, e não lê o texto do módulo para adivinhar. Uma entrada de módulo chamada db_password cujo valor não traz nenhuma declaração é emitida sem marcação, e uma entrada declarada chamada region é marcada.
A marcação só viaja onde a identidade da entrada pode ser recuperada a partir da declaração. Uma Recipe que copia localmente um módulo com source: e deixa as folhas values declaradas do nó se tornarem diretamente as entradas do módulo dá a cada entrada o mesmo nome que o autor declarou, então o vínculo é exato — e o mesmo vale para a FeatureRecipe de uma Feature vinculada a um componente que copia localmente um módulo da mesma forma, sobre as folhas que sua Feature declara. Uma Recipe ou uma FeatureRecipe desse tipo que remodela esses valores por meio de um template valuesMapping: inventa seus nomes de saída, e nenhuma declaração os nomeia — então a marcação está ausente em vez de aproximada, e o build relata isso com um aviso consultivo por folha declarada, nomeando a folha e a entidade a que pertence o mapeamento (uma Feature vinculada a uma fronteira renderiza sem nenhum values, então não tem nada a marcar e não gera nenhum); veja A declared-sensitive value reaches the target through a values mapping (Um valor declarado sensível chega ao destino por meio de um mapeamento de values). A ausência é deliberada: adivinhar qual entrada remodelada trouxe o dado declarado marcaria uma entrada pública como secreta, e o Terraform então suprimiria da saída do plano um valor que nunca foi sensível.
O exemplo prático terraform-declared-sensitivity constrói isso de ponta a ponta e é pequeno o bastante para ser lido por inteiro: um componente que declara três folhas values, das quais duas trazem identificadores públicos e uma traz a credencial. Sua saída renderizada mostra os argumentos do bloco module trazendo as três entradas do módulo e o override nomeando apenas a declarada, de modo que as duas metades da regra ficam visíveis no mesmo build — inclusive que um identificador da credencial que fica ao lado do segredo é deixado sem marcação. Remover a única declaração e reconstruir não emite nenhum arquivo de override.
O que o sensitive do Terraform garante e não garante
O Aggrega promete exatamente o que o atributo do próprio Terraform entrega, e nada mais.
Ele limita a exibição. Um valor sensível aparece como (sensitive value) na saída do plano e como <sensitive> na saída do apply. A marcação se propaga pelas expressões, então um valor derivado de uma entrada sensível também é sensível, e o Terraform se recusa a exportar um deles a partir de um output raiz que não esteja ele próprio marcado como sensível — um erro explícito em vez de uma divulgação silenciosa.
Ele não muda o armazenamento, e não é criptografia. O Terraform registra um valor sensível no estado em texto claro. Ler sensitive = true como uma promessa de que o estado é seguro para fazer commit ou compartilhar é a única leitura equivocada a evitar: proteger o estado continua sendo uma questão de como o backend de estado está configurado, exatamente como para um módulo que não traz nenhuma marcação. O atributo também não restringe quem pode ler o valor, não afeta o que um provedor transmite e não muda a configuração renderizada de nenhuma outra forma.
Assim, a marcação torna mais difícil divulgar por acidente uma entrada declarada sensível quando alguém lê um plano. Ela não torna seguro publicar o que é implantado. Veja Declarar uma folha sensível para a palavra-chave e para o que uma declaração alcança em todos os destinos.
Validação estrutural da entrada
O provedor terraform valida a estrutura de um módulo com fonte antes de renderizá-lo. Ele analisa os arquivos HCL e .tf.json do módulo e relata erros de análise, interrompendo o build com uma mensagem clara que nomeia o nó em questão e o provedor. A análise verifica a forma, não a semântica — não resolve provedores, não avalia expressões nem contata um registro. A validação é hermética: usa um parser HCL autocontido compilado no provedor, sem nenhum binário terraform e sem acesso à rede. Um módulo malformado é detectado na fronteira da autoria em vez de surgir como um erro confuso em uma execução posterior de terraform.
Uma chamada de módulo que o motor baixa ao inicializar
A mesma leitura relata, como um aviso que não recusa nada, cada bloco module cuja fonte o Terraform baixa quando a configuração é inicializada. O commit e o digest do arquivo compactado de um módulo copiado localmente ficam fixados no arquivo de bloqueio, mas um bloco module dentro dele cujo source é um endereço de registro, uma URL git, Mercurial ou de arquivo compactado HTTP, um bucket S3 ou GCS, ou um caminho absoluto nomeia um módulo que o motor baixa na inicialização, na versão que ele selecionar naquele momento — e o arquivo de bloqueio de dependências do próprio Terraform registra apenas provedores, então nada fixa esse módulo. Um source local que sai do módulo copiado localmente também é relatado, porque nomeia arquivos que o build não copiou localmente. Cada constatação nomeia o nó e o provedor, depois o bloco, o arquivo e a linha em que ele fica, e a fonte como foi 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 moduleO que é lido. Os arquivos que o motor carrega quando o módulo é chamado: os arquivos de configuração diretamente no diretório do próprio módulo, depois os de cada diretório que um source local — um que começa com ./ ou ../, ou suas grafias com barra invertida — alcança a partir dali, seguidos de diretório em diretório e cada um lido uma única vez. Um diretório que nada chama não é lido, então as chamadas que o diretório examples/ ou tests/ de um módulo faz não são relatadas: o motor nunca os carrega quando o módulo é chamado, e nada do que eles chamam é baixado. A verificação de análise acima ainda analisa cada arquivo de configuração copiado localmente. O corpo escrito de uma Recipe é lido da mesma forma quando é renderizado, a partir do diretório em que o corpo é escrito, então um bloco module que um corpo escrito pelo autor escreve com uma fonte de registro também é relatado. Um arquivo sob spec.boundary.artifacts é avaliado e escrito pelo próprio compilador e não é entregue a nenhum provedor, então um bloco module escrito em um deles não é lido e não gera nenhum aviso.
O que não é lido. Só é lido o que um source diz. O build não lê o módulo que uma chamada nomeia, não julga o que esse módulo faz e não decide se a chamada é aceitável. Um source que o motor avalia em vez de ler como foi escrito — um que traz uma interpolação, ou uma referência — é julgado pelo seu texto inicial: um que começa com um endereço é relatado como foi escrito, enquanto um que começa com um prefixo local, ou com a própria interpolação, não é relatado nem seguido, porque para onde ele leva não está no texto. Um source dentro de required_providers nomeia um provedor em vez de um módulo e não é uma chamada de módulo.
Por que é relatado em vez de recusado. Um módulo que chama outro módulo é uma entrada legítima: o Terraform baixa o módulo chamado e a configuração funciona. Aquilo de que o autor abre mão é a fixação que o build exerce sobre o módulo chamado, o que é um fato que vale a pena conhecer, e não uma falha a corrigir, e se esse download é aceitável é um julgamento do autor. Uma configuração que precisa permanecer totalmente fixada copia localmente apenas módulos que não fazem nenhuma chamada desse tipo. O aviso, seu código de classe e aonde mais ele chega são descritos em Avisos e saída do linter.
Fronteira de patches da FeatureRecipe
Uma etapa pipeline pós-renderização de uma FeatureRecipe só aplica patches à saída que o provedor renderiza em uma árvore estruturada. Para o terraform, isso significa:
- Terraform escrito em JSON aceita patches. Um módulo
.tf.jsoné um documento estruturado, então o JSONPatch de uma etapa do pipeline edita no lugar os valores endereçados e deixa intactos todos os outros bytes — ordem, formatação, chaves ao redor. - HCL nativo é opaco. Um corpo em HCL nativo (
main.tf) não é um alvo de patch estruturado. Um patch contra um corpo opaco interrompe o build com um diagnóstico em vez de modificar texto que ele não consegue endereçar estruturalmente; escrever uma etapa do pipeline contra um corpo HCL é um erro de design que aparece como uma interrupção explícita, não como uma operação nula silenciosa. - As entradas de um módulo com fonte não são de forma alguma um alvo de patch. Elas são os argumentos do bloco
moduledo componente, que fica na configuração raiz: HCL nativo, e portanto opaco, e um artefato da fronteira inteira, e não de um único nó. Uma etapapipelineaplica patches à saída renderizada própria de um nó, então não existe posição a partir da qual endereçá-las.
Um autor que precisa que um corpo Terraform aceite patches do pipeline o escreve, portanto, como .tf.json. Veja FeatureRecipe para a fronteira geral dos alvos de patch entre provedores.
Ordem de implantação
O valor syncWave: da fronteira de uma Release ordena os blocos module da configuração raiz na qual essa fronteira é montada. Cada componente da fronteira herda a onda da fronteira e, onde várias fronteiras são resolvidas para o mesmo diretório de saída — de modo que seus componentes são compostos em uma única configuração raiz —, essa raiz contém mais de uma onda e o provedor expressa a ordem entre elas como depends_on nos blocos module.
Cada módulo nomeia todos os módulos da onda imediatamente anterior que tenha algum componente, e nenhuma onda anterior a essa. O Terraform encadeia o resto: um módulo na onda 2 depende da onda 1, que depende da onda 0, então toda a sequência fica ordenada enquanto a lista própria de cada módulo mantém o tamanho de uma onda, e não o da fronteira inteira. As ondas não precisam ser contíguas, e valores negativos são comuns — -1 é uma escolha frequente para um bucket ou um papel que o resto da configuração lê. A onda mais baixa não nomeia nada, porque nada a precede.
O que a ordem é: a ordem em que o Terraform executa suas ações. O Terraform constrói um grafo de dependências e o percorre em paralelo na medida em que o grafo permite. depends_on adiciona uma aresta a esse grafo, então o Terraform conclui suas ações nos módulos nomeados antes de começar as do módulo que declara a dependência. Uma onda, portanto, escalona a execução: os componentes da onda anterior são tratados antes que os da onda posterior sejam iniciados.
Não é uma ordem de prontidão. Uma configuração Terraform não expressa nenhuma noção de um recurso estar operacional, então nada aqui espera que um fique pronto — apenas que o Terraform termine de agir sobre ele. Essa é uma diferença real em relação à mesma onda no compose, onde um serviço que declara um healthcheck é aguardado até se reportar saudável: o compose tem uma primitiva de prontidão na qual se basear, e uma configuração Terraform não tem nenhuma. A ordem das ações é o que este destino oferece, e declará-la claramente é mais útil do que uma ressalva presa a uma promessa que ele não pode cumprir.
Nenhuma ordem de destruição é prometida. O que depends_on afirma é que o Terraform conclui as ações da dependência antes de começar as do dependente; a ordem em que um destroy os remove não faz parte dessa afirmação, então nada é afirmado aqui sobre a sequência de destruição. Essa é uma promessa mais estreita do que a que a mesma onda carrega no cloudformation, cujo atributo rege as duas direções — vale saber disso se você depende de uma onda para sequenciar uma destruição, porque neste destino ela não faz isso.
Uma fronteira cujos componentes carregam todos uma mesma onda não ganha nada com isso. O mesmo vale para uma Release que não declara nenhum syncWave: cada contribuidor carrega o valor padrão do campo, 0, a configuração raiz contém uma única onda, e os bytes emitidos são exatamente os que seriam se o provedor não expressasse nenhuma ordem por ondas.
A ordem entre duas configurações raiz não é expressável, e não é aproximada. Um grafo de dependências do Terraform é por configuração e depends_on nomeia um módulo dentro da configuração que o declara, então uma onda ordena cada componente composto nessa raiz e nada além dela. Sequenciar duas configurações é responsabilidade do operador, da mesma forma que uma referência a um estado remoto é uma resolução no momento da implantação, e não no momento do build.
A onda é registrada além de aplicada: ela viaja com o resto da proveniência do build do nó, como aggrega.ai/sync-wave no bloco de comentários carimbado, ou no arquivo de proveniência complementar quando o corpo é JSON ou um módulo copiado localmente. Assim, uma configuração renderizada registra qual onda sua fronteira declarou, além de ser ordenada por ela.
A ordem que as ondas não expressam continua sendo responsabilidade do próprio Terraform, e as referências entre recursos já carregam boa parte dela: uma referência a um atributo de outro recurso diz ao Terraform para agir primeiro sobre esse recurso. Um módulo que precisa de uma restrição que nem as referências nem as ondas implicam escreve seu próprio depends_on dentro do módulo, que o provedor emite tal como está, como qualquer outra parte do corpo.
Referências relacionadas
- Arquitetura de Provider — como os provedores se encaixam no pipeline de compilação e no despacho por provedor.
- Índice de referência de Provider — o que cada provedor da biblioteca padrão produz, e qual página responde a qual pergunta.
- Entidade Recipe — a superfície de autoria da Recipe e os três tipos de entrada.
- FeatureRecipe — o modelo de patch
pipelinepós-renderização e sua fronteira entre estruturado e opaco. - Composição de entradas de Recipe — a Matriz de capacidades por Provider canônica.