Sensibilidade declarada, renderizada como o `sensitive` próprio do Terraform
A declaração de que um valor contém 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: a compilação acrescenta um ficheiro de override que adiciona sensitive = true à entrada do módulo para a qual flui o valor declarado, e o motor oculta então esse valor onde quer que, de outro modo, o mostraria.
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 a compilação 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. Cada fronteira terraform recebe um.
Em dist/infra/terraform/modules/store/, os ficheiros próprios do componente store:
- os ficheiros 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. Fica ao lado dos ficheiros próprios do módulo porque o Terraform funde um override na configuração do seu próprio diretório;aggrega.provenance.tf— um ficheiro de comentários#que identifica a compilação (o ficheiro JSON não pode conter um comentário, pelo que a proveniência segue num ficheiro próprio).
A marcação, e as duas entradas que não nomeia
example/storage/external-object-store declara três folhas de values. Duas contêm identificadores públicos; uma contém 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 funde um ficheiro chamado override ou terminado em _override na configuração do mesmo diretório, pelo que este ficheiro acrescenta o atributo à declaração secret_access_key existente do módulo e deixa o seu tipo, a sua descrição e o seu valor predefinido tal como o módulo os escreveu. Cada byte incorporado permanece tal como foi escrito.
As duas entradas que o override não nomeia são o essencial 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, pelo que não é declarado sensível e não é marcado, ainda que esteja ao lado do segredo e o seu nome pareça o de um. Remova sensitive: true dessa única folha e volte a compilar: o ficheiro de override não é emitido de todo.
Vê-lo a funcionar
main.tf mantém as coordenadas públicas e a credencial em atributos separados de um mesmo recurso, pelo que um plano mostra as duas direções ao mesmo tempo. Planeie 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 contém esses dois atributos entre as linhas mostradas. Estão marcados como omitidos e não em falta, pelo que uma linha que não consiga 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. Elimine aggrega_override.tf.json e volte a executar o plano para ver a credencial impressa por inteiro — essa diferença é tudo o que a marcação faz. A marcação está no bloco variable próprio do módulo, pelo que acompanha o módulo e aplica-se 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 está um nível acima, pelo que o diretório próprio do componente não é uma configuração que se possa planear tal como implementada. O que o motor faz aí 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, pelo que um plano emmodules/store/falha —No value for required variable, uma vez por entrada, cada uma a nomear a sua linha e a propor a solução-var/-var-file. - Um módulo cujas entradas tenham todas valores predefinidos seria, em vez disso, planeado com sucesso aí, a partir desses valores predefinidos e não dos valores que a configuração raiz fornece. Nada avisa. É esse o caso a conhecer, porque um plano que parece correto está a descrever uma configuração que ninguém pediu.
O que a marcação não faz
sensitive rege a apresentação. Impede que um valor seja impresso na saída de plan e apply, e impede que o Terraform coloque esse valor numa saída que não esteja ela própria marcada como sensível. Não cifra o valor e não altera a forma como o valor é armazenado: depois de um apply, o valor está presente no estado em claro. Trate o estado como contendo a 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 provém de uma declaração. Esta Recipe declara um source: e nenhum valuesMapping:, pelo que 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, pelo que uma tal Recipe renderiza os mesmos valores sem marcação — o ficheiro 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 motor ocultariam então um valor que nunca foi secreto.
Porque é que a credencial é aqui uma entrada do módulo
Uma base de dados gerida na cloud é normalmente o outro caso: o fornecedor gera e roda ele próprio a palavra-passe mestra, pelo que o módulo não precisa de nenhuma entrada de credencial e não há nada a marcar. Este bucket é operado fora da Release, pelo que não existe tal fornecedor em quem delegar — a Release detém uma chave de acesso e tem de a passar. É por isso que este módulo declara uma variável de credencial e os módulos de bases de dados geridas da biblioteca standard 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 provém da declaração do Component, não do módulo.
Ficheiros
aggregate.yaml— intenção do programador: 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 marcadores de posição, não credenciais para 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 origem local..aggrega-config.yaml— nomeia o registo 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:, pelo que um parâmetro tipado é a superfície precisamente para isto: o programador declara o ponto de variação, a Release satisfá-lo.
Gerar o exemplo
É possível compilar este exemplo com os comandos abaixo, ou pedir ao assistente de IA que o compile.
Escreva o exemplo numa nova pasta com o nome dele:
aggrega scaffold --example terraform-declared-sensitivityDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:
cd terraform-declared-sensitivityCompilação
aggrega build --release release.yaml --auto-pull--auto-pull escreve durante a compilação o ficheiro de bloqueio que falta a um clone acabado de criar.
Com um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole-lhe este prompt.
Utilize apenas as ferramentas do Aggrega e não crie nenhuma pasta por iniciativa própria. Se a pasta da área 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`: esta escreve o exemplo numa 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. Indique-me que ficheiros a compilação escreveu; encontram-se em `terraform-declared-sensitivity/dist/`.