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

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 — declara store como um bloco module cujo source é ./modules/store e 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.tf e main.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:

Terminal window
cd dist/infra/terraform
tofu 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 em modules/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 componente store do tipo example/storage/external-object-store, com o bucket nomeado diretamente e as duas metades da chave de acesso expostas como parameters tipados.
  • release.yaml — satisfaz esses parâmetros para este ambiente e define o endpoint do 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 Terraform terraform/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:

Terminal window
aggrega scaffold --example terraform-declared-sensitivity

Em seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:

Terminal window
cd terraform-declared-sensitivity

Build

Terminal window
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/`.