Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Portugal)
Esta página foi traduzida automaticamente. Ler o original em inglês.

Provider Terraform

O fornecedor terraform renderiza Recipes de Aggrega em configuração do Terraform. Emite configuração e nunca executa o Terraform: uma compilação de Aggrega é ahead-of-time, pelo que 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 cadeias de ponteiro determinísticas que o runtime do Terraform resolve mais tarde. O fornecedor funciona offline e é hermético — nunca acede à rede e nunca invoca terraform nem tofu.

Como é organizada uma fronteira

O fornecedor terraform compõe uma fronteira em vez de emitir os seus componentes lado a lado. Cada fronteira que renderiza recebe uma única configuração raiz, aggrega.modules.tf, que declara cada componente aí renderizado 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 ficheiros 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 o seu bloco aponta. Esta é a estrutura típica 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 cada fronteira terraform recebe, quer contenha um componente, quer vários. Uma Feature anexada a um componente ou à fronteira é declarada como um bloco module próprio na mesma configuração raiz — ver Onde vai parar a saída de uma Feature anexada.

A forma é estrutural, e não cosmética, por duas razões.

Um grafo de dependências do Terraform é por configuração. Components emitidos em diretórios separados são grafos separados, sem qualquer relação: nem uma referência nem um depends_on consegue ir de um ao outro, e nenhum terraform plan individual vê ambos. Uma única raiz que compõe cada componente como módulo filho coloca uma fronteira inteira num só grafo e num só plano.

Os ficheiros de um componente são endereçados pelo seu próprio diretório. Dois componentes de uma mesma fronteira podem copiar localmente módulos que escrevem ficheiros 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 é configurado um fornecedor

A configuração de um fornecedor — 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 predefinida da raiz para cada fornecedor 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 fornecedor escreve depends_on no bloco module de um componente sempre que outro componente da mesma raiz traz um syncWave anterior, como descreve Ordem de implementação mais abaixo; o Terraform recusa então a configuração inteira enquanto a carrega, antes de planear o que quer que seja.

Assim, uma Recipe cujo fornecedor precisa de configuração escreve essa configuração como um ficheiro sob spec.boundary.artifacts. Cada um desses ficheiros é escrito uma única vez ao lado de aggrega.modules.tf, onde o Terraform o lê juntamente com a configuração raiz, e o módulo do componente mantém apenas a sua declaração required_providers da origem e da versão do fornecedor:

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

Os Components de uma mesma raiz que declaram o mesmo ficheiro com os mesmos bytes partilham a única cópia; o mesmo nome com bytes diferentes interrompe a compilação. Os recursos dos módulos são registados em relação a essa única configuração, pelo que é também com ela que o Terraform os destrói. Uma Release que remove o último componente que declara o ficheiro remove o ficheiro com ele, e o Terraform recusa-se então a planear a destruição do que esses módulos criaram, pedindo um bloco provider que configure o fornecedor. Convém destruir esses recursos antes de remover o último desses componentes.

Onde são fornecidas as entradas de um componente

As entradas de um componente são os argumentos do seu bloco module na configuração raiz, e esse é o único sítio 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:. Fica vazio quando a Recipe escreveu ela própria o corpo da configuração e resolveu os seus valores nesse corpo, pelo 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 é aí que os valores ficam. Um ponteiro ${ ... } fornecido por uma Recipe é resolvido aí em vez de chegar ao módulo como uma cadeia de caracteres literal. Aquilo em relação ao qual é resolvido é a configuração raiz: uma referência nomeia algo que essa configuração declara — um dos 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 em falta.

O diretório próprio de um componente não é, portanto, uma configuração que se possa planear tal como é implementada. As suas entradas são indicadas um nível acima, na raiz, pelo que posicionar-se em modules/<component> e executar aí o motor planeia 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 a sua linha, e oferecendo o remédio do próprio Terraform, -var / -var-file.
  • Quando todas as entradas trazem um default, o plano é bem-sucedido e é construído a partir dos valores predefinidos do módulo em vez dos valores que a configuração raiz fornece. Nada avisa, pelo que este é o caso a conhecer: um plano que parece correto está a descrever uma configuração que ninguém pediu.

Convém planear, em vez disso, o diretório de saída próprio da fronteira — aquele que contém aggrega.modules.tf, imediatamente acima de modules/. É aí que estão os valores da implementação, e é o único sítio onde um único plano vê a fronteira inteira.

Consumir o valor publicado de outro componente

Um componente conectado a outro por uma aresta uses lê os valores publicados desse componente através do seu próprio pipe .context.inject (ou através de .context.uses.<alias>.provides.<name>). O que lê é uma cadeia de caracteres que o compilador encaminha sem a interpretar, e o sítio onde essa cadeia vai parar é texto que o Terraform avalia no âmbito em que a Recipe o escreveu. Uma fronteira terraform tem dois desses âmbitos, 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, pelo que module.<name>.<output> é resolvido aí;
  • o diretório próprio de um componente não declara qualquer chamada de módulo, pelo que module.<name>.<output> não nomeia nada aí — seja qual for <name>. Substituir pelo nome correto não muda nada, porque o que falta é a declaração, não a grafia.

Por isso é o tipo de entrada da Recipe consumidora que decide se uma referência consumida pode ser resolvida, e não o valor consumido.

Uma Recipe consumidora escreve-se como uma Recipe source:. O seu valuesMapping: torna-se os argumentos do seu próprio bloco module na configuração raiz — a única posição que é ao mesmo tempo avaliada e está num âmbito onde os seus vizinhos estão declarados.

Um par desenvolvido

O produtor publica um endereço que nomeia a sua própria chamada de módulo, que é a forma que o âmbito do seu consumidor declara. .context.instance_id está na superfície de avaliação de provides, e para um componente que o Aggregate da implementaçã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 faz corresponder a ela o valor injetado:

# 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 conecta-os, 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: endpoint

A compilação emite uma única configuração raiz na qual a referência e o seu referente são declarados em conjunto:

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 este par a partir de Recipes da biblioteca padrão: uma base de dados PostgreSQL aprovisionada 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 formas de isto correr mal, e como se apresenta cada uma

Uma Recipe que escreve o seu próprio corpo não pode consumir uma referência entre componentes. Uma Recipe artifacts: resolve os seus valores no corpo que escreve, e esse corpo é emitido no diretório próprio do componente. A referência fica então num âmbito que não declara qualquer 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 resolve isto, porque as expressões de um módulo aninhado não podem de todo nomear 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 escreve-se 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 interpolação, é avaliada onde fica o argumento do consumidor, ou seja, na 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.

Convém publicar ${module.<...>.<output>} e dar ao módulo um bloco output para o valor, em vez de aceder diretamente aos seus recursos.

Uma entrada provides sem interpolação é entregue como texto. Este é o caso que não falha: o compilador encaminha cadeias de caracteres e não consegue distinguir um ponteiro de um literal, pelo que aws_db_instance.this.endpoint escrito sem ${ ... } é renderizado como uma cadeia entre aspas, a compilação é bem-sucedida, o motor valida e o consumidor recebe os caracteres aws_db_instance.this.endpoint. O invólucro ${ ... } deve ser escrito sempre que o valor se destine a ser uma referência — é ele que marca a cadeia como algo que o Terraform deve avaliar.

Um limite que convém conhecer antes de confiar nele

.context.instance_id exprime a identidade do componente, e o nome de um bloco module é derivado do diretório onde ficam os ficheiros do componente. Para um componente que o próprio Aggregate da implementação declara, trata-se do mesmo nome. Para um componente incorporado por composição a partir de outro Aggregate, não é: a identidade composta e o nome do módulo são escritos de forma diferente nos seus dois alfabetos, e a referência falha então 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.

Convém declarar um produtor cujo endereço outro componente resolve no próprio Aggregate da implementação, ao lado do componente que o consome.

Onde vai parar a saída de uma Feature anexada

Um anexo 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. É isto que faz com que a sua configuração faça parte da implementação: o Terraform carrega apenas os ficheiros que ficam diretamente num diretório e trata um diretório aninhado como um módulo completamente separado, que tem de ser chamado explicitamente, pelo que os ficheiros de um anexo são lidos porque a raiz declara um bloco que nomeia o diretório onde eles ficam.

O diretório de módulo de um anexo fica ao lado do diretório do componente, um nível abaixo de modules/, e tem o nome das duas coisas que o identificam — o componente que acolhe o anexo e o nome sob o qual foi anexado, unidos por --. Assim, para um componente api que traz um anexo chamado aux, a configuração raiz declara dois módulos:

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

Uma Feature anexada à fronteira em vez de a um componente não tem um componente anfitrião para nomear, pelo que o seu diretório é apenas o seu próprio nome: um anexo chamado aux numa fronteira que contém o componente api produz ./modules/aux ao lado de ./modules/api.

Porquê ao lado e não dentro. O Terraform funde todos os ficheiros de nível superior de um diretório de módulo num único namespace — output, variable, resource e locals por igual — pelo que dois contribuidores que partilham um diretório colidem em qualquer nome que ambos declarem, seja qual for o nome dos seus ficheiros. Um diretório para cada um é o que os mantém separados. Ao lado e não dentro é também o que pede a própria orientação do Terraform para módulos aninhados: que possam ser compostos pelo chamador em vez de se chamarem diretamente uns aos outros, 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 contenha ela própria -- não pode ser confundida com a junção: um anfitrião chamado a--b com um anexo c é distinguível de um anfitrião a com um anexo b--c. As letras ASCII, maiúsculas e minúsculas, os dígitos, o ponto e o sublinhado passam tal como foram escritos; um hífen que tenha sido escrito é mantido sempre que o carácter seguinte for um destes; tudo o resto é escapado. A mesma regra e o mesmo alfabeto produzem os diretórios filhos de um destino chart, de modo que o diretório de um anexo é 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 aponta o seu source, com cada carácter fora da gramática do Terraform para um nome de módulo substituído por um sublinhado. Esse mapeamento não é biunívoco, pelo que, onde dois contribuidores chegariam a um único nome de módulo, a compilação é interrompida e nomeia ambos, em vez de emitir uma configuração que o Terraform rejeitaria.

Do facto de um anexo ser um módulo próprio decorrem três coisas.

As suas entradas são as do seu próprio mapeamento. Um anexo 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 os 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 assume-o, e uma declarada sem valor predefinido fica por definir, pelo que o Terraform recusa o plano.

Os seus recursos ficam no único grafo de dependências da fronteira. Uma referência ou um depends_on alcança, nos dois sentidos, um anexo e o componente ao qual foi anexado, e um único terraform plan vê ambos — a mesma propriedade que a forma em que a raiz compõe os filhos dá aos componentes, pela mesma razão.

Os seus nomes de nível superior são seus. Como a fusão de namespaces descrita acima é feita por diretório, um contribuidor que fica num diretório próprio declara os seus nomes output, variable, resource e locals sem os disputar com os dos seus vizinhos — assim um anexo pode reutilizar um nome que o seu anfitrião já declara, e nenhum dos dois precisa de saber como o outro chamou o que quer que seja.

Note-se o que este destino não exige, porque a restrição de um destino chart é diferente e a organização partilhada pode ser lida como implicando mais do que implica: um módulo aninhado dentro do diretório de outro contribuidor continua a ser alcançável aqui, já que a configuração raiz lê o source de cada contribuidor a partir da posição que a compilação compôs, em vez de o reconstruir a partir de um identificador. O que este destino recusa é que dois contribuidores partilhem 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 mais além.

Tipos de entrada suportados

O fornecedor terraform aceita dois dos três tipos de entrada de Recipe:

  • Modo artefactos. Uma Recipe escreve configuração do Terraform como um corpo baseado em template; o fornecedor avalia o template do Aggrega e emite o resultado sem o reescrever. HCL (main.tf) é a predefinição mais ergonómica, e Terraform JSON (.tf.json) é aceite de forma equivalente. A proveniência da compilação é 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 num ficheiro complementar, aggrega.provenance.tf, em vez de em linha.
  • Modo com fonte. Uma Recipe referencia um módulo do Terraform com source:. Os ficheiros do módulo são copiados localmente (vendoring) sem alterações para o diretório desse componente, e o valuesMapping: da Recipe torna-se os argumentos do bloco module desse 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. Quando as folhas values declaradas do nó se tornam diretamente as entradas do módulo — uma Recipe source: sem valuesMapping: —, uma entrada que traz material que um autor declarou sensível recebe também um ficheiro de override gerado que traz o atributo de sensibilidade do próprio Terraform; um template valuesMapping: inventa os seus nomes de saída, pelo que esse caso não traz qualquer marcação e a compilação assinala-o com um aviso consultivo. Ambos são descritos em Entradas de módulo declaradas sensíveis.

Um null num 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 o seu default, a não ser que a variável declare nullable = false, caso em que se aplica o seu default; para dar a uma entrada o valor predefinido do módulo, deixa-se 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, pelo que uma Recipe que declara workload: com o fornecedor terraform é um erro explícito em vez de uma tradução inventada.

Uma Recipe que declara omits: é recusada. A chave omits: deixa de fora da compilação documentos que uma fonte renderiza, e este fornecedor não renderiza nada a partir de um módulo com fonte no momento da compilação: copia localmente os ficheiros do módulo sem alterações, e o Terraform avalia-os quando a configuração é planeada e aplicada. Sem nada renderizado, não há nada a deixar de fora, pelo que este fornecedor não declara que respeita a chave, e uma Recipe ou FeatureRecipe que a declare é recusada antes de qualquer coisa ser copiada localmente — ver The provider does not support omits (O fornecedor não suporta omits). Para um módulo mantido ao lado da Recipe, uma linha no .aggregaignore que aí se encontra deixa de fora, em alternativa, um ficheiro do módulo, a partir do pin seguinte da Recipe.

Usar como fonte um módulo publicado por um registo

Um registo 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 responde quando lhe é pedido para descarregar 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 os seus blocos variable declaram — o Terraform exige um valor para cada entrada que não declare nenhum default — e estas tornam-se os argumentos do bloco module deste componente na configuração raiz, como para qualquer módulo com fonte.

O que fica fixado. aggrega pin e o pull resolvem a tag para o commit que ela nomeia e arquivam o repositório nesse commit. O ficheiro de bloqueio da Release regista então esse commit como a versão fixada da fonte, a tag como a referência que foi escrita e o digest do arquivo. Cada compilação posterior lê o arquivo a partir da cache e verifica-o com esse digest antes de copiar localmente o que quer que seja, pelo que não precisa de rede, e um arquivo em cache cujos bytes já não correspondam interrompe a compilação. Uma tag é um nome que um repositório pode mover para outro commit; um pull posterior que encontre a tag resolvida noutro sítio é interrompido em vez de adotar o novo commit, e aggrega pull --upgrade adota-o deliberadamente. É uma fixação mais rigorosa do que o ficheiro de bloqueio de dependências do próprio Terraform, que regista os fornecedores que uma configuração selecionou e nenhum módulo, pelo que um módulo escrito numa configuração como fonte git numa tag só fica tão fixo quanto a tag. Aqui, o commit do módulo e o digest dos seus bytes ficam fixados no ficheiro de bloqueio, os bytes são copiados localmente para a saída e a configuração raiz chama-os por um caminho local, pelo que o motor não obtém nada para carregar o próprio módulo — um módulo que o módulo copiado localmente chama através de uma fonte de registo ou remota continua a ser obtido, e a compilação assinala cada uma dessas chamadas, como descreve Uma chamada de módulo que o motor obtém ao inicializar.

O que é copiado localmente. O repositório inteiro no commit fixado, à exceção do seu diretório .git/, vai parar ao diretório próprio do componente sob modules/, byte a byte — os ficheiros de configuração e os módulos filhos do próprio módulo, e também tudo o resto que o repositório contenha: os seus diretórios examples/ e wrappers/, a sua documentação, a sua configuração de CI e quaisquer fixtures de teste, incluindo 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 ficheiros de configuração que ficam diretamente nele e em cada diretório que um source local alcança a partir daí. Um diretório de exemplo que chama outros módulos de registo é, por isso, copiado localmente e nunca carregado, e nada do que chama é obtido.

Restringir o que é copiado localmente. Uma fonte obtida é o arquivo com que foi obtida, pelo que a única forma de a restringir é module_subdir:, que faz de um diretório do repositório o artefacto. Isso só ajuda quando o módulo pretendido fica num subdiretório: um módulo na raiz do repositório que chama os seus próprios ./modules/* precisa da árvore inteira. Nem um .terraformignore que o repositório contenha nem um .aggregaignore ao lado da Recipe alteram o que uma fonte obtida copia localmente — ambos moldam um módulo mantido ao lado da Recipe, e nenhum deles é lido para um módulo obtido de um repositório.

Ler o que o módulo publica. Um valor que o módulo publica é um dos seus blocos output, e um consumidor lê-o 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, pelo que um nome de saída que o módulo não declara é aí recusado, com indicação do 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".

A compilação não lê nenhum dos blocos variable ou output do módulo, não escreve nada no módulo e não lhe acrescenta qualquer configuração de fornecedor, pelo que um nome de saída mal escrito é detetado pelo motor e não pela compilação. Ver Consumir o valor publicado de outro componente para o lado do consumidor.

Emissão sem alterações e cópia local (vendoring)

O fornecedor terraform não transpila, não reformata nem reescreve corpos do Terraform. Um corpo HCL ou .tf.json escrito pelo autor é emitido exatamente como o seu template é avaliado, com um corpo HCL a abrir com os comentários de proveniência, e um módulo com fonte é copiado localmente ficheiro a ficheiro. É isto que mantém a saída do terraform determinística e reprodutível: com 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 fornecedor nunca resolve o estado de runtime, tudo o que depende do runtime permanece uma cadeia de caracteres de interpolação que o Terraform associa no momento do apply.

Anotações de plataforma

O fornecedor terraform não lê nenhuma das anotações aggrega.ai/. Um módulo copiado localmente, os ficheiros de artefacto de uma Recipe e a configuração raiz que o fornecedor escreve não têm lugar para um namespace, um prefixo de registo, um pull secret ou uma service account, pelo que um valor definido para um deles não altera nada na configuração renderizada; um módulo que precise de um valor desses recebe-o como uma das suas próprias entradas, através dos values do componente.

O fornecedor declara-o na sua entidade Plugin, com readsNoWellKnownAnnotations: true (ver a entidade Plugin), e a compilação emite, por isso, um aviso para cada anotação aggrega.ai/ que chega a uma renderização através 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 it

O valor continua a atravessar a compilação intacto, e a compilação não é interrompida: uma anotação de fronteira propaga-se em cascata a cada componente que lhe está subordinado, e uma fronteira cujos componentes são renderizados através de destinos diferentes é algo normal, e não um erro. O aviso pertence à classe unsupported-field e é silenciado com a opção 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, pelo que um dado que um autor declarou sensível pode ser renderizado nos termos do próprio Terraform em vez de ser apenas registado nos do Aggrega.

Quando a entrada de um módulo copiado localmente traz material que um autor declarou sensível, o fornecedor acrescenta mais um ficheiro ao lado do módulo, aggrega_override.tf.json, que declara sensitive = true para essa entrada:

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

O Terraform funde um ficheiro de configuração cujo nome é simplesmente override ou termina em _override com a configuração do mesmo diretório, pelo 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 predefinido e a descrição da entrada ficam intactos — o override traz o atributo de sensibilidade e nada mais. Um nó não marcado não recebe nenhum ficheiro desse tipo.

Esse limite é deliberado, e não algo que o formato do ficheiro imponha: nada num 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 para um módulo copiado localmente sem editar os seus bytes — mas este não chegaria. Um default na sintaxe de configuração JSON em que este ficheiro é escrito não é uma posição que o Terraform avalie, pelo que um valor que traga um ponteiro ${ ... } aí escrito chega ao módulo como os caracteres literais do ponteiro, num plano que é bem-sucedido e não diz nada. O mesmo ponteiro escrito num default em HCL nativo é rejeitado à partida, o que situa esse silêncio nesta sintaxe, e não nos ficheiros de override enquanto tais. Por isso o override traz apenas sensitive: o seu significado não depende de ser avaliado.

A entrada que é marcada decorre de uma declaração, nunca de um nome. O fornecedor lê a marcação que a compilação calculou e não inspeciona nada por si próprio: não reconhece password, secret nem token, e não lê o texto do módulo para adivinhar. Uma entrada de módulo chamada db_password cujo valor não traga 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 que as folhas values declaradas do nó se tornem diretamente as entradas do módulo dá a cada entrada o mesmo nome que o autor declarou, pelo que a ligação é exata — e o mesmo acontece com a FeatureRecipe de uma Feature anexada a um componente que copia localmente um módulo da mesma forma, sobre as folhas que a sua Feature declara. Uma Recipe ou uma FeatureRecipe desse tipo que remodela esses valores através de um template valuesMapping: inventa os seus nomes de saída, e nenhuma declaração os nomeia — pelo que a marcação está ausente em vez de aproximada, e a compilação assinala-o com um aviso consultivo por folha declarada, nomeando a folha e a entidade a que pertence o mapeamento (uma Feature anexada a uma fronteira é renderizada sem quaisquer values, pelo que não tem nada a marcar e não gera nenhum); ver A declared-sensitive value reaches the target through a values mapping (Um valor declarado sensível chega ao destino através de um mapeamento de values). A ausência é deliberada: adivinhar qual a entrada remodelada que trazia o dado declarado marcaria uma entrada pública como secreta, e o Terraform suprimiria então da saída do plano um valor que nunca foi sensível.

O exemplo prático terraform-declared-sensitivity constrói isto de ponta a ponta e é suficientemente pequeno para ser lido na íntegra: um componente que declara três folhas values, das quais duas trazem identificadores públicos e uma traz a credencial. A sua saída renderizada mostra os argumentos do bloco module a trazer as três entradas do módulo e o override a nomear apenas a declarada, pelo que as duas metades da regra ficam visíveis na mesma compilação — incluindo o facto de um identificador da credencial que fica ao lado do segredo ser deixado sem marcação. Remover a única declaração e recompilar não emite qualquer ficheiro 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 proporciona, e nada mais.

Limita a apresentaçã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 propaga-se através das expressões, pelo que um valor derivado de uma entrada sensível também é sensível, e o Terraform recusa-se 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.

Não altera o armazenamento, e não é cifragem. O Terraform regista um valor sensível no estado em texto simples. Ler sensitive = true como uma promessa de que o estado é seguro para fazer commit ou partilhar é a única leitura errada a evitar: proteger o estado continua a ser uma questão de como o backend de estado está configurado, exatamente como para um módulo que não traz qualquer marcação. O atributo também não restringe quem pode ler o valor, não afeta o que um fornecedor transmite e não altera 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. Não torna seguro publicar o que é implementado. Ver 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 fornecedor terraform valida a estrutura de um módulo com fonte antes de o renderizar. Analisa os ficheiros HCL e .tf.json do módulo e assinala erros de análise, interrompendo a compilação com uma mensagem clara que nomeia o nó em causa e o fornecedor. A análise verifica a forma, não a semântica — não resolve fornecedores, não avalia expressões nem contacta um registo. A validação é hermética: usa um analisador HCL autónomo compilado no fornecedor, sem nenhum binário terraform e sem acesso à rede. Um módulo malformado é detetado na fronteira da autoria em vez de surgir como um erro confuso numa execução posterior de terraform.

Uma chamada de módulo que o motor obtém ao inicializar

A mesma leitura assinala, como um aviso que não recusa nada, cada bloco module cuja fonte o Terraform descarrega quando a configuração é inicializada. O commit e o digest do arquivo de um módulo copiado localmente ficam fixados no ficheiro de bloqueio, mas um bloco module dentro dele cujo source seja um endereço de registo, um URL git, Mercurial ou de arquivo HTTP, um bucket S3 ou GCS, ou um caminho absoluto nomeia um módulo que o motor obtém na inicialização, na versão que então selecionar — e o ficheiro de bloqueio de dependências do próprio Terraform regista apenas fornecedores, pelo que nada fixa esse módulo. Um source local que sai do módulo copiado localmente também é assinalado, porque nomeia ficheiros que a compilação não copiou localmente. Cada constatação nomeia o nó e o fornecedor, depois o bloco, o ficheiro e a linha em que se encontra, e a fonte tal 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 module

O que é lido. Os ficheiros que o motor carrega quando o módulo é chamado: os ficheiros de configuração diretamente no diretório do próprio módulo, depois os de cada diretório que um source local — um que comece por ./ ou ../, ou as suas grafias com barra invertida — alcança a partir daí, seguidos de diretório em diretório e cada um lido uma única vez. Um diretório que nada chama não é lido, pelo que as chamadas que o diretório examples/ ou tests/ de um módulo faz não são assinaladas: o motor nunca os carrega quando o módulo é chamado, e nada do que chamam é obtido. A verificação de análise acima continua a analisar cada ficheiro 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, pelo que um bloco module que um corpo escrito pelo autor escreva com uma fonte de registo também é assinalado. Um ficheiro sob spec.boundary.artifacts é avaliado e escrito pelo próprio compilador e não é entregue a nenhum fornecedor, pelo que um bloco module escrito num deles não é lido e não gera qualquer aviso.

O que não é lido. Só é lido o que um source diz. A compilação 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 o ler tal como foi escrito — um que traga uma interpolação, ou uma referência — é julgado pelo seu texto inicial: um que comece por um endereço é assinalado tal como foi escrito, enquanto um que comece por um prefixo local, ou pela própria interpolação, não é assinalado nem seguido, porque para onde leva não está no texto. Um source dentro de required_providers nomeia um fornecedor em vez de um módulo e não é uma chamada de módulo.

Porque é assinalado em vez de recusado. Um módulo que chama outro módulo é uma entrada legítima: o Terraform obtém o módulo chamado e a configuração funciona. Aquilo de que o autor abdica é a fixação que a compilação exerce sobre o módulo chamado, o que é um facto que vale a pena conhecer, e não uma falha a corrigir, e se essa obtenção é aceitável é um juízo do autor. Uma configuração que tenha de permanecer totalmente fixada copia localmente apenas módulos que não façam nenhuma chamada desse tipo. O aviso, o seu código de classe e onde mais chega são descritos em Avisos e saída do linter.

Fronteira de patches da FeatureRecipe

Um passo pipeline pós-renderização de uma FeatureRecipe só aplica patches à saída que o fornecedor renderiza numa árvore estruturada. Para o terraform, isto significa:

  • O Terraform escrito em JSON aceita patches. Um módulo .tf.json é um documento estruturado, pelo que o JSONPatch de um passo do pipeline edita no local os valores endereçados e deixa intactos todos os outros bytes — ordenação, formatação, chaves circundantes.
  • O HCL nativo é opaco. Um corpo em HCL nativo (main.tf) não é um alvo de patch estruturado. Um patch contra um corpo opaco interrompe a compilação com um diagnóstico em vez de alterar texto que não consegue endereçar estruturalmente; escrever um passo do pipeline contra um corpo HCL é um erro de conceção que surge como uma interrupção explícita, e não como uma operação nula silenciosa.
  • As entradas de um módulo com fonte não são de todo um alvo de patch. São os argumentos do bloco module do componente, que fica na configuração raiz: HCL nativo, e portanto opaco, e um artefacto da fronteira inteira e não de um único nó. Um passo pipeline aplica patches à saída renderizada própria de um nó, pelo que não existe nenhuma posição a partir da qual endereçá-las.

Um autor que precisa que um corpo Terraform aceite patches do pipeline escreve-o, portanto, como .tf.json. Ver FeatureRecipe para a fronteira geral dos alvos de patch entre fornecedores.

Ordem de implementação

O valor syncWave: da fronteira de uma Release ordena os blocos module da configuração raiz em que essa fronteira é montada. Cada componente da fronteira herda a wave da fronteira e, onde várias fronteiras se resolvem para o mesmo diretório de saída — de modo que os seus componentes são compostos numa única configuração raiz —, essa raiz contém mais do que uma wave e o fornecedor exprime a ordem entre elas como depends_on nos blocos module.

Cada módulo nomeia todos os módulos da wave imediatamente anterior que tenha componentes, e nenhuma wave anterior a essa. O Terraform encadeia o resto: um módulo na wave 2 depende da wave 1, que depende da wave 0, pelo que toda a sequência fica ordenada enquanto a lista própria de cada módulo mantém o tamanho de uma wave e não o da fronteira inteira. As waves não têm de ser contíguas, e os valores negativos são comuns — -1 é uma escolha frequente para um bucket ou um papel que o resto da configuração lê. A wave mais baixa não nomeia nada, porque nada a precede.

O que é a ordem: a ordem pela qual o Terraform executa as suas ações. O Terraform constrói um grafo de dependências e percorre-o em paralelo na medida em que o grafo o permite. depends_on acrescenta uma aresta a esse grafo, pelo que o Terraform conclui as suas ações nos módulos nomeados antes de começar as do módulo que declara a dependência. Uma wave escalona, portanto, a execução: os componentes da wave anterior são tratados antes de os da wave posterior serem iniciados.

Não é uma ordem de prontidão. Uma configuração Terraform não exprime nenhuma noção de um recurso estar operacional, pelo que nada aqui espera que um fique pronto — apenas que o Terraform termine de agir sobre ele. Esta é uma diferença real em relação à mesma wave no compose, onde um serviço que declara um healthcheck é aguardado até se reportar saudável: o compose tem uma primitiva de prontidão em que se apoiar e uma configuração Terraform não tem nenhuma. A ordem das ações é o que este destino oferece, e afirmá-la claramente é mais útil do que uma ressalva associada a uma promessa que não pode cumprir.

Não é prometida nenhuma ordem de destruição. O que depends_on afirma é que o Terraform conclui as ações da dependência antes de começar as do dependente; a ordem pela qual um destroy os remove não faz parte dessa afirmação, pelo que nada é afirmado aqui sobre a sequência de destruição. Esta é uma promessa mais estreita do que a que a mesma wave tem no cloudformation, cujo atributo rege as duas direções — convém sabê-lo se depender de uma wave para sequenciar uma destruição, porque neste destino ela não o faz.

Uma fronteira cujos componentes têm todos uma mesma wave não ganha nada com isto. O mesmo acontece com uma Release que não declara nenhum syncWave: cada contribuidor tem o valor predefinido do campo, 0, a configuração raiz contém uma única wave, e os bytes emitidos são exatamente os que seriam se o fornecedor não exprimisse nenhuma ordem por waves.

A ordem entre duas configurações raiz não é exprimí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, pelo que uma wave 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 implementação e não no momento da compilação.

A wave é registada além de aplicada: viaja com o resto da proveniência da compilação do nó, como aggrega.ai/sync-wave no bloco de comentários carimbado, ou no ficheiro de proveniência complementar quando o corpo é JSON ou um módulo copiado localmente. Assim, uma configuração renderizada regista que wave a sua fronteira declarou, além de ser ordenada por ela.

A ordem que as waves não exprimem continua a ser responsabilidade do próprio Terraform, e as referências entre recursos já asseguram boa parte dela: uma referência a um atributo de outro recurso diz ao Terraform que atue primeiro sobre esse recurso. Um módulo que precise de uma restrição que nem as referências nem as waves impliquem escreve o seu próprio depends_on dentro do módulo, que o fornecedor emite tal como está, como qualquer outra parte do corpo.