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

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

ficheirodestino localdestino com repositório
aggregate.yamlo mesmo ficheiroo mesmo ficheiro
Manifestmanifest-local.yamlmanifest-store.yaml
Releaserelease-local.yamlrelease-store.yaml

Os dois Manifests diferem no próprio nome e numa 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. 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-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 — 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: 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 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/):

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 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-parameter escreve-o no Secret como o material.
  • k8s-external-secret lê-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-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, 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:

Terminal window
aggrega scaffold --example credential-shape-per-target

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

Terminal window
cd credential-shape-per-target

Compilação

Terminal window
aggrega build --release release-local.yaml --auto-pull
aggrega 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:

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, basta acrescentar --verify-determinism: cada nó é renderizado duas vezes e a compilação é interrompida 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-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 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 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.