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
| arquivo | destino local | destino com repositório |
|---|---|---|
aggregate.yaml | o mesmo arquivo | o mesmo arquivo |
| Manifest | manifest-local.yaml | manifest-store.yaml |
| Release | release-local.yaml | release-store.yaml |
Os dois Manifests diferem no próprio nome e em uma entrada de mapeamento:
$ diff manifest-local.yaml manifest-store.yaml7c7< name: credential-shape-local-manifest---> name: credential-shape-store-manifest16c16< 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.0As duas Releases diferem no próprio nome e no Manifest para o qual apontam:
$ diff release-local.yaml release-store.yaml7c7< name: credential-shape-local---> name: credential-shape-store12c12< manifest: credential-shape-local-manifest---> manifest: credential-shape-store-manifestAs 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-passwordcore/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: v1kind: Secretmetadata: 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/v1kind: ExternalSecretmetadata: 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/):
$ diff -r local storeOnly in store/helm/helm: db--app-zuuser-zupassword--db-externalsecret-db-app-user-password.yamlOnly in local/helm/helm: db--app-zuuser-zupassword--db-secret-db-app-user-password.yamlOnly in store/helm/helm: db--password--db-externalsecret-db-password.yamlOnly in local/helm/helm: db--password--db-secret-db-password.yamlQuatro 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_PASSWORDEle é 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-parametero escreve no Secret como o material.k8s-external-secreto 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-passwordAs 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:
aggrega scaffold --example credential-shape-per-targetEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd credential-shape-per-targetBuild
aggrega build --release release-local.yaml --auto-pullaggrega 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:
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.
aggrega build --release release-local.yaml --verify-determinismaggrega build --release release-store.yaml --verify-determinismCom 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 componentedbdo tipocore/datastore/postgres, com os dois slots de credencial preenchidos porcore/referenced-secret. Usado sem alterações pelas duas Releases.manifest-local.yaml— vinculacore/referenced-secretak8s-secret-from-parameter, que renderiza um Secret do Kubernetes a partir do material escrito.manifest-store.yaml— vincula a mesma Feature ak8s-external-secret, que renderiza um ExternalSecret que nomeia a entrada do repositório. Idêntico amanifest-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.