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

Uma única intenção do desenvolvedor, duas formas de entrega de credenciais

Como uma credencial chega a um contêiner em execução é uma propriedade de onde você implanta, não da aplicação. Um cluster não tem repositório de segredos, então a implantação entrega o próprio material em um Secret do Kubernetes. Outro executa um operador de repositório de segredos, então a implantação entrega apenas um ponteiro e o cluster obtém o material no momento da reconciliação.

Este espaço de trabalho contém um Aggregate e o compila para dois destinos. O Aggregate não muda entre eles. Nem a referência do banco de dados à sua senha. O que muda é uma linha em um Manifest.

O que se move e o que fica fixo

arquivodestino localdestino com repositório
aggregate.yamlo mesmo arquivoo mesmo arquivo
Manifestmanifest-local.yamlmanifest-store.yaml
Releaserelease-local.yamlrelease-store.yaml

Os dois Manifests diferem no próprio nome e em uma entrada de mapeamento:

Terminal window
$ diff manifest-local.yaml manifest-store.yaml
7c7
< name: credential-shape-local-manifest
---
> name: credential-shape-store-manifest
16c16
< core/referenced-secret:1.0.0: helm/k8s-secret-from-parameter:1.0.0
---
> core/referenced-secret:1.0.0: helm/k8s-external-secret:1.0.0

As duas Releases diferem no próprio nome e no Manifest para o qual apontam:

Terminal window
$ diff release-local.yaml release-store.yaml
7c7
< name: credential-shape-local
---
> name: credential-shape-store
12c12
< manifest: credential-shape-local-manifest
---
> manifest: credential-shape-store-manifest

As duas Releases declaram o mesmo environment. Isso é deliberado: o nome do ambiente é carimbado em todo documento renderizado como um rótulo, então mantê-lo fixo deixa exatamente uma coisa livre para mudar — a FeatureRecipe que o Manifest vincula. Um par real de Releases naturalmente nomearia os próprios ambientes, e as formas das credenciais difeririam exatamente da mesma maneira.

O lado do desenvolvedor, uma única vez

aggregate.yaml preenche os dois slots de credencial do Component do PostgreSQL com a mesma Feature de credencial referenciável:

features:
password:
type: core/referenced-secret
values:
key: POSTGRES_PASSWORD
origin: postgres-superuser-password
app_user_password:
type: core/referenced-secret
values:
key: APP_USER_PASSWORD
origin: postgres-app-password

core/referenced-secret nomeia um recurso de segredo, um que a saída da sua FeatureRecipe cria ou um que já existe, e publica o localizador desse recurso — o seu name e a key de dados dentro dele — por meio do seu contrato provides. A Recipe consumidora lê esse localizador. Ela nunca deriva um nome de recurso próprio, e nunca pergunta qual FeatureRecipe o produziu.

O que cada destino emite

Cada build escreve seis arquivos. Quatro deles — o StatefulSet, os dois Services e o ConfigMap de inicialização — saem idênticos byte a byte nos dois destinos. Os outros dois são os recursos de credencial, um por slot preenchido, e é neles que os destinos diferem.

Destino local, de k8s-secret-from-parameter, em dist/helm/helm/db--password--db-secret-db-password.yaml:

apiVersion: v1
kind: Secret
metadata:
name: db-password
[… omitted: the labels and annotations naming the aggregate, component, environment, compiler and provider versions, boundary and Recipe — the same set every rendered document carries]
stringData:
POSTGRES_PASSWORD: "postgres-superuser-password"

Destino com repositório, de k8s-external-secret, em dist/helm/helm/db--password--db-externalsecret-db-password.yaml:

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
name: db-password
[… omitted: the same label and annotation set as above]
spec:
refreshInterval: "1h"
secretStoreRef:
name: platform-secret-store
kind: ClusterSecretStore
target:
name: db-password
creationPolicy: Owner
data:
- secretKey: POSTGRES_PASSWORD
remoteRef:
key: "postgres-superuser-password"

Grupo de API diferente, kind diferente, corpo diferente. No destino local, o material da credencial está no documento renderizado, legível por qualquer pessoa que possa ler os recursos implantados — por isso essa forma serve para clusters locais e de desenvolvimento, e não para um de produção. No destino com repositório, o documento renderizado traz apenas o nome da entrada; o material fica no repositório de segredos e o operador o reconcilia em um Secret chamado db-password.

Comparar as duas árvores de saída mostra a diferença e mostra onde ela termina (a seção Build abaixo tem os comandos que produzem local/ e store/):

Terminal window
$ diff -r local store
Only in store/helm/helm: db--app-zuuser-zupassword--db-externalsecret-db-app-user-password.yaml
Only in local/helm/helm: db--app-zuuser-zupassword--db-secret-db-app-user-password.yaml
Only in store/helm/helm: db--password--db-externalsecret-db-password.yaml
Only in local/helm/helm: db--password--db-secret-db-password.yaml

Quatro linhas, todas em um único diretório, porque neste destino os arquivos de uma vinculação ficam ao lado dos próprios arquivos do componente em vez de em um subdiretório. É o nome do arquivo que traz as duas coordenadas: db--password-- é a vinculação password em db, e db--app-zuuser-zupassword-- é a de app_user_password — o sublinhado codificado como -zu, porque aqui a coordenada e o próprio nome do arquivo compartilham uma única string.

Quatro linhas, e nada mais: dois recursos de credencial presentes apenas na árvore do destino local, dois presentes apenas na do destino com repositório. diff -r não relata nenhuma diferença de conteúdo em nenhum arquivo que as duas árvores compartilham, então os quatro documentos em comum são idênticos, e não apenas parecidos.

A referência que não se move

O contêiner do banco de dados lê as duas credenciais como variáveis de ambiente apoiadas por um secretKeyRef. Este bloco é idêntico byte a byte nos dois destinos:

- name: POSTGRES_PASSWORD
valueFrom:
secretKeyRef:
name: db-password
key: POSTGRES_PASSWORD
- name: APP_USER_PASSWORD
valueFrom:
secretKeyRef:
name: db-app-user-password
key: APP_USER_PASSWORD

Ele é idêntico porque a Recipe consumidora não se ramifica. Ela pede ao slot o name e a key publicados e os escreve. As duas FeatureRecipes publicam as mesmas duas chaves porque a Feature as declara, então qualquer uma delas satisfaz o consumidor — e no destino com repositório a referência se resolve assim que o operador tiver reconciliado o ExternalSecret em um Secret com esse nome.

Essa invariância é o que torna as duas formas substituíveis. Se o lado consumidor tivesse derivado ele mesmo o nome do Secret, trocar o vínculo o teria deixado apontando para um recurso que não existia mais com esse nome.

origin significa o que a FeatureRecipe diz que significa

core/referenced-secret declara origin como o lugar de onde vem o material, e deixa a sua interpretação para a FeatureRecipe:

  • k8s-secret-from-parameter o escreve no Secret como o material.
  • k8s-external-secret o lê como a chave a obter do repositório.

O compilador encaminha a string sem alterações; ele é agnóstico em relação a qual das duas uma dada string é. É isso que permite que uma única vinculação sirva às duas formas sem nenhuma edição do lado do desenvolvedor — e é o que se deve verificar antes de trocar um vínculo, porque a mesma string escrita precisa fazer sentido para qualquer FeatureRecipe que a leia.

O nome publicado e o sublinhado no nome de um slot

O Component nomeia o seu segundo slot de credencial app_user_password. O nome de um objeto do Kubernetes não pode conter sublinhado, então o provides.name publicado normaliza sublinhados para hifens, e o recurso fica como db-app-user-password:

- name: APP_USER_PASSWORD
valueFrom:
secretKeyRef:
name: db-app-user-password

As duas FeatureRecipes normalizam de forma idêntica, e é por isso que trocar o vínculo não move a referência do consumidor. O nome é publicado uma única vez, no lado produtor, e tanto o recurso emitido quanto a referência do consumidor se resolvem a partir desse único valor publicado.

O que o destino com repositório espera do cluster

ExternalSecret é um recurso personalizado. Aplicar a saída do destino com repositório a um cluster exige que um operador de repositório de segredos esteja em execução nele, e que exista um ClusterSecretStore chamado platform-secret-store. Nada neste espaço de trabalho instala nenhum dos dois: o exemplo renderiza o que um cluster assim consome, e ensina como a forma é escolhida.

Qual repositório um cluster executa, e com que nome, é uma propriedade do destino e não da aplicação, então k8s-external-secret não traz nenhuma chave de autoria para isso. Um cluster cujo repositório tem outro nome é atendido por uma FeatureRecipe que nomeia esse repositório.

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 credential-shape-per-target

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

Terminal window
cd credential-shape-per-target

Build

Terminal window
aggrega build --release release-local.yaml --auto-pull
aggrega build --release release-store.yaml --auto-pull

--auto-pull resolve o catálogo em um lockfile ao lado da Release no primeiro build; builds posteriores da mesma Release não precisam de nenhuma flag.

Os dois destinos escrevem em dist/, e aggrega build não o limpa, então guarde à parte a saída de cada execução para comparar as duas:

Terminal window
out=$(mktemp -d)
rm -rf dist && aggrega build --release release-local.yaml --auto-pull && cp -r dist "$out/local"
rm -rf dist && aggrega build --release release-store.yaml --auto-pull && cp -r dist "$out/store"
( cd "$out" && diff -r local store )

Para confirmar que cada destino renderiza de forma determinística, adicione --verify-determinism: cada nó é renderizado duas vezes e o build é interrompido se as duas renderizações de algum nó diferirem.

Terminal window
aggrega build --release release-local.yaml --verify-determinism
aggrega build --release release-store.yaml --verify-determinism

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 contém uma pasta `credential-shape-per-target`, chame uma vez a ferramenta `scaffold` com `example` definido como `credential-shape-per-target` e sem `dir`: ela grava o exemplo em uma nova pasta `credential-shape-per-target`. Em seguida, chame a ferramenta `build` uma vez para cada Release, nesta ordem — `release-local.yaml`, `release-store.yaml` — cada vez com `workspace_root` definido como `credential-shape-per-target`, `release` definido como esse arquivo, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos cada build gravou; eles ficam em `credential-shape-per-target/dist/`.

Arquivos

  • aggregate.yaml — intenção do desenvolvedor: um componente db do tipo core/datastore/postgres, com os dois slots de credencial preenchidos por core/referenced-secret. Usado sem alterações pelas duas Releases.
  • manifest-local.yaml — vincula core/referenced-secret a k8s-secret-from-parameter, que renderiza um Secret do Kubernetes a partir do material escrito.
  • manifest-store.yaml — vincula a mesma Feature a k8s-external-secret, que renderiza um ExternalSecret que nomeia a entrada do repositório. Idêntico a manifest-local.yaml, exceto pelo próprio nome e por essa única linha.
  • release-local.yaml, release-store.yaml — as duas Releases. Idênticas, exceto pelos próprios nomes e pelo Manifest para o qual cada uma aponta.
  • .aggrega-config.yaml — nomeia o registro do hub a partir do qual as entidades do catálogo são resolvidas.

Os valores de origin aqui são placeholders. Eles não são credenciais de nenhum serviço real, e no destino local ambos são renderizados em texto claro na saída.