Sensibilidade declarada, renderizada como o `sensitive` próprio do Terraform
A declaração de que um valor carrega material secreto é escrita uma única vez, no esquema de um Component. Onde o destino de renderização oferece uma primitiva própria correspondente, essa declaração é renderizada nela. Este exemplo é o caso do Terraform: o build acrescenta um arquivo de override que adiciona sensitive = true à entrada do módulo para a qual o valor declarado flui, e o mecanismo então oculta esse valor onde quer que, de outra forma, o exibiria.
O exemplo é deliberadamente pequeno e cada parte dele pode ser inspecionada: um componente, três entradas de módulo e uma marcação renderizada que nomeia exatamente uma delas.
O que o build emite
Em dist/infra/terraform/, a configuração raiz da fronteira:
aggrega.modules.tf— declarastorecomo um blocomodulecujosourceé./modules/storee cujos argumentos são as variáveis de entrada resolvidas do módulo, em ordem determinística de chaves. Toda fronteira terraform recebe um.
Em dist/infra/terraform/modules/store/, os arquivos próprios do componente store:
- os arquivos do módulo copiados byte a byte —
variables.tfemain.tf, exatamente como o autor do módulo os escreveu; aggrega_override.tf.json— a marcação de sensibilidade, descrita abaixo. Ele fica ao lado dos arquivos próprios do módulo porque o Terraform mescla um override à configuração do seu próprio diretório;aggrega.provenance.tf— um arquivo de comentários#que identifica o build (o arquivo JSON não pode conter um comentário, então a proveniência vai em um arquivo próprio).
A marcação, e as duas entradas que ela não nomeia
example/storage/external-object-store declara três folhas de values. Duas carregam identificadores públicos; uma carrega a credencial e declara sensitive: true:
values: bucket: { type: string, required: true } access_key_id: { type: string, required: true } secret_access_key: { type: string, required: true, sensitive: true }O bloco module associa as três entradas do módulo:
module "store" { source = "./modules/store"
access_key_id = "AKIAEXAMPLE0001" bucket = "app-artifacts" secret_access_key = "example-placeholder-not-a-real-credential"}e o override acrescentado nomeia exatamente uma:
{ "variable": { "secret_access_key": { "sensitive": true } }}O Terraform mescla um arquivo chamado override ou terminado em _override à configuração do mesmo diretório, então este arquivo adiciona o atributo à declaração secret_access_key existente do módulo e deixa o seu tipo, a sua descrição e o seu padrão como o módulo os escreveu. Cada byte incorporado permanece como foi escrito.
As duas entradas que o override não nomeia são o ponto do exemplo. A marcação segue a declaração e nada mais — nem o nome de uma variável, nem a forma do seu valor. access_key_id é um identificador de credencial e não material de credencial, então não é declarado sensível e não é marcado, mesmo estando ao lado do segredo e tendo um nome que parece o de um. Remova sensitive: true dessa única folha e faça o build de novo: o arquivo de override não é emitido de forma alguma.
Vendo funcionar
main.tf mantém as coordenadas públicas e a credencial em atributos separados de um mesmo recurso, então um plano mostra as duas direções ao mesmo tempo. Planeje a configuração raiz da fronteira — o diretório que contém aggrega.modules.tf, que é onde estão os valores desta Release:
cd dist/infra/terraformtofu init && tofu plan # or: terraform init && terraform plan # module.store.terraform_data.reference will be created + resource "terraform_data" "reference" { [… omitted: an id attribute, reported as known only after apply] + input = (sensitive value) [… omitted: an output attribute, reported as known only after apply] + triggers_replace = [ + "app-artifacts", + "AKIAEXAMPLE0001", ] }O seu próprio plano traz esses dois atributos entre as linhas mostradas. Eles estão marcados como omitidos em vez de ausentes, então uma linha que você não consegue explicar é uma diferença real, e não algo que esta página retirou.
A credencial é ocultada; os dois valores públicos ao lado dela, não. Exclua aggrega_override.tf.json e execute o plano de novo para ver a credencial impressa por inteiro — essa diferença é tudo o que a marcação faz. A marcação fica no bloco variable próprio do módulo, então ela acompanha o módulo e se aplica onde quer que esse módulo seja usado.
Execute-o na raiz, e não dentro de modules/store/. As entradas de um componente são os argumentos do seu bloco module, que fica um nível acima, então o diretório próprio do componente não é uma configuração que você possa planejar como implantada. O que o mecanismo faz ali depende dos blocos variable próprios do módulo, e apenas uma das duas respostas é visível:
- Este módulo declara as suas três entradas sem
default, então um plano emmodules/store/falha —No value for required variable, uma vez por entrada, cada uma nomeando a sua linha e oferecendo a solução-var/-var-file. - Um módulo cujas entradas tenham todas valores padrão seria, em vez disso, planejado com sucesso ali, a partir desses padrões e não dos valores que a configuração raiz fornece. Nada avisa. Esse é o caso que convém conhecer, porque um plano que parece correto está descrevendo uma configuração que ninguém pediu.
O que a marcação não faz
sensitive controla a exibição. Ele impede que um valor seja impresso na saída de plan e apply, e impede que o Terraform coloque esse valor em uma saída que não esteja ela própria marcada como sensível. Ele não criptografa o valor e não muda como o valor é armazenado: depois de um apply, o valor está presente no estado em texto claro. Trate o estado como portador da credencial, diga a marcação o que disser.
Além disso, a marcação só alcança uma entrada renderizada quando a identidade da entrada vem de uma declaração. Esta Recipe declara um source: e nenhum valuesMapping:, então os nomes dos argumentos são os caminhos das folhas de valor que o Component declarou e a correspondência é exata. Uma Recipe que declara um valuesMapping: inventa os seus nomes de saída dentro de um template, que nenhuma declaração nomeia, então essa Recipe renderiza os mesmos valores sem marcação — o arquivo de override está ausente em vez de aproximado. Marcar um nome que nenhuma declaração alcança afirmaria algo falso sobre uma entrada pública, e as próprias ferramentas do mecanismo então ocultariam um valor que nunca foi secreto.
Por que a credencial é uma entrada do módulo aqui
Um banco de dados gerenciado na nuvem costuma ser o outro caso: o provedor gera e rotaciona ele mesmo a senha mestre, então o módulo não precisa de nenhuma entrada de credencial e não há nada a marcar. Este bucket é operado fora da Release, então não existe tal provedor a quem delegar — a Release detém uma chave de acesso e precisa repassá-la. É por isso que este módulo declara uma variável de credencial e os módulos de banco de dados gerenciado da biblioteca padrão não.
O módulo declara essa variável sem o atributo sensitive do Terraform, e é isso que torna o exemplo legível: o atributo que um leitor vê aplicado no momento da renderização veio da declaração do Component, não do módulo.
Arquivos
aggregate.yaml— intenção do desenvolvedor: um componentestoredo tipoexample/storage/external-object-store, com o bucket nomeado diretamente e as duas metades da chave de acesso expostas comoparameterstipados.release.yaml— satisfaz esses parâmetros para este ambiente e define oendpointdo operador. Os valores aqui são espaços reservados, não credenciais de nenhum serviço real.manifest.yaml— associa o tipo de componente à Recipe do Terraformterraform/external-object-store, que obtém o seu módulo de uma fonte local..aggrega-config.yaml— nomeia o registro do hub a partir do qual as entidades do catálogo são resolvidas.
As duas metades da credencial são parameters e não valores escritos pelo autor porque são valores que um operador fornece e que diferem por ambiente. Uma Release não pode declarar values:, então um parâmetro tipado é a superfície exatamente para isso: o desenvolvedor declara o ponto de variação, a Release o satisfaz.
Gerar o exemplo
Você pode fazer o build deste exemplo com os comandos abaixo, ou pedir ao seu assistente de IA que faça o build por você.
Escreva o exemplo em uma nova pasta com o nome dele:
aggrega scaffold --example terraform-declared-sensitivityEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd terraform-declared-sensitivityBuild
aggrega build --release release.yaml --auto-pull--auto-pull grava durante o build o arquivo de bloqueio que falta a um clone recém-criado.
Com um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.
Use somente as ferramentas do Aggrega e não crie nenhuma pasta por conta própria. Se a pasta do espaço de trabalho ainda não contiver uma pasta `terraform-declared-sensitivity`, chame uma vez a ferramenta `scaffold` com `example` definido como `terraform-declared-sensitivity` e sem `dir`: ela grava o exemplo em uma nova pasta `terraform-declared-sensitivity`. Em seguida, chame a ferramenta `build` com `workspace_root` definido como `terraform-declared-sensitivity`, `release` definido como `release.yaml`, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos o build gravou; eles ficam em `terraform-declared-sensitivity/dist/`.