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

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 — 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. 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.tf e main.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:

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 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 em modules/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 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 marcadores de posição, não credenciais para 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 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:

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

Depois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:

Terminal window
cd terraform-declared-sensitivity

Compilação

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