Uma única intenção do programador, duas formas de entrega de credenciais
A forma como uma credencial chega a um contentor em execução é uma propriedade de onde se implementa, não da aplicação. Um cluster não tem repositório de segredos, pelo que a implementação entrega o próprio material num Secret do Kubernetes. Outro executa um operador de repositório de segredos, pelo que a implementaçã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 compila-o para dois destinos. O Aggregate não muda entre eles. Nem a referência da base de dados à sua palavra-passe. O que muda é uma linha num Manifest.
O que se move e o que se mantém fixo
| ficheiro | destino local | destino com repositório |
|---|---|---|
aggregate.yaml | o mesmo ficheiro | o mesmo ficheiro |
| Manifest | manifest-local.yaml | manifest-store.yaml |
| Release | release-local.yaml | release-store.yaml |
Os dois Manifests diferem no próprio nome e numa 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. Isto é deliberado: o nome do ambiente é carimbado em cada documento renderizado como etiqueta, pelo que mantê-lo fixo deixa exatamente uma coisa livre para mudar — a FeatureRecipe que o Manifest vincula. Um par real de Releases nomearia naturalmente os seus próprios ambientes, e as formas das credenciais difeririam exatamente da mesma maneira.
O lado do programador, 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 — através do seu contrato provides. A Recipe consumidora lê esse localizador. Nunca deriva um nome de recurso próprio, e nunca pergunta que FeatureRecipe o produziu.
O que cada destino emite
Cada compilação escreve seis ficheiros. 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 quem consiga ler os recursos implementados — e é por isso que 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 reconcilia-o num Secret chamado db-password.
Comparar as duas árvores de saída mostra a diferença e mostra onde termina (a secção Compilação 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 num único diretório, porque neste destino os ficheiros de um anexo ficam ao lado dos próprios ficheiros do componente em vez de num subdiretório. É o nome do ficheiro que traz as duas coordenadas: db--password-- é o anexo password em db, e db--app-zuuser-zupassword-- é o de app_user_password — o sublinhado codificado como -zu, porque aqui a coordenada e o próprio nome do ficheiro partilham 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 reporta nenhuma diferença de conteúdo em nenhum ficheiro que as duas árvores partilham, pelo que os quatro documentos comuns são idênticos, e não apenas semelhantes.
A referência que não se move
O contentor da base de dados lê as duas credenciais como variáveis de ambiente suportadas 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É idêntico porque a Recipe consumidora não se ramifica. Pede ao slot o name e a key publicados e escreve-os. As duas FeatureRecipes publicam as mesmas duas chaves porque a Feature as declara, pelo que qualquer uma delas satisfaz o consumidor — e no destino com repositório a referência resolve-se assim que o operador tiver reconciliado o ExternalSecret num Secret com esse nome.
Esta invariância é o que torna as duas formas substituíveis. Se o lado consumidor tivesse derivado ele próprio o nome do Secret, trocar o vínculo tê-lo-ia deixado a apontar para um recurso que já não existia 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 à FeatureRecipe:
k8s-secret-from-parameterescreve-o no Secret como o material.k8s-external-secretlê-o como a chave a obter do repositório.
O compilador encaminha a string sem alterações; é agnóstico em relação a qual das duas uma dada string é. É isso que permite que um único anexo sirva as duas formas sem nenhuma edição do lado do programador — e é o que se deve verificar antes de trocar um vínculo, porque a mesma string escrita tem de 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 um sublinhado, pelo que o provides.name publicado normaliza os sublinhados para hífenes, 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, do lado produtor, e tanto o recurso emitido como 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.
Que repositório um cluster executa, e com que nome, é uma propriedade do destino e não da aplicação, pelo que k8s-external-secret não traz nenhuma chave de autoria para isso. Um cluster cujo repositório tem outro nome é servido por uma FeatureRecipe que nomeia esse repositório.
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 credential-shape-per-targetDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:
cd credential-shape-per-targetCompilação
aggrega build --release release-local.yaml --auto-pullaggrega build --release release-store.yaml --auto-pull--auto-pull resolve o catálogo num lockfile ao lado da Release na primeira compilação; as compilações posteriores da mesma Release não precisam de nenhuma flag.
Os dois destinos escrevem em dist/, e aggrega build não o limpa, pelo que convém guardar à 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, basta acrescentar --verify-determinism: cada nó é renderizado duas vezes e a compilação é interrompida 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-lhe este prompt.
Utilize apenas as ferramentas do Aggrega e não crie nenhuma pasta por si. Se a pasta da área de trabalho ainda não contiver uma pasta `credential-shape-per-target`, chame uma vez a ferramenta `scaffold` com `example` definido como `credential-shape-per-target` e sem `dir`: esta escreve o exemplo numa nova pasta `credential-shape-per-target`. Em seguida, chame a ferramenta `build` uma vez para cada Release, por esta ordem — `release-local.yaml`, `release-store.yaml` — de cada vez com `workspace_root` definido como `credential-shape-per-target`, `release` definido como esse ficheiro, `auto_pull` definido como true e `write` definido como true. Indique-me que ficheiros cada build escreveu; encontram-se em `credential-shape-per-target/dist/`.Ficheiros
aggregate.yaml— intenção do programador: 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 no próprio nome e nessa única linha.release-local.yaml,release-store.yaml— as duas Releases. Idênticas, exceto nos próprios nomes e no Manifest para o qual cada uma aponta..aggrega-config.yaml— nomeia o registo do hub a partir do qual as entidades do catálogo são resolvidas.
Os valores de origin aqui são marcadores de posição. Não são credenciais de nenhum serviço real, e no destino local ambos são renderizados em claro na saída.