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

Features de credenciais

Esta página explica uma única ideia, as Features de credenciais da biblioteca padrão e como um Manifest escolhe o que realiza cada uma, e não é um espaço de trabalho executável. Uma intenção do desenvolvedor, dois formatos de entrega de credenciais faz o build de um Aggregate com duas realizações da mesma credencial; escreva-o em uma pasta sua com:

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

Em seguida ele imprime os próximos comandos a executar:

Terminal window
cd credential-shape-per-target
aggrega build --release release-local.yaml --auto-pull
aggrega build --release release-store.yaml --auto-pull

Uma credencial preenche um slot que um Component declara no seu featuresSchema (veja entities/component.md); o slot, a Feature que o preenche e a FeatureRecipe que o Manifest vincula formam todo o caminho, da vinculação de um autor até uma carga de trabalho em execução.

A família de Feature de credenciais

Uma Feature de credenciais carrega o rótulo feature.aggrega.ai/kind: secret. O rótulo é um metadado do catálogo que descreve o que a vinculação produz; nenhum ramo do compilador o lê, e uma Feature de credenciais é vinculada em features: como qualquer outra Feature, pelo desenvolvedor no Aggregate ou pelo operador na Release.

A biblioteca padrão divide as Features de credenciais pelo que a realização faz com o segredo:

  • core/secret-value entrega um valor no canal de injeção do componente, onde a sua Recipe o lê — um valor do chart, uma variável de ambiente.
  • core/secret-provided também produz um valor, mas o publica em vez disso como uma chave provides, de modo que o próprio bloco inject: da vinculação, em um slot transparente, diz para onde ele vai.
  • core/referenced-secret nomeia um recurso de segredo — um Secret do Kubernetes, um segredo do AWS Secrets Manager, uma entrada do Vault — que a sua realização cria ou que já existe, e publica o name e o key desse recurso, que um consumidor lê como .features.<slot>.provides.name e .features.<slot>.provides.key.
  • core/referenced-secret-set materializa um desses recursos contendo um conjunto de chaves de dados que o autor fornece, e publica apenas o seu localizador, para um consumidor cujo destino já fixa os nomes de chave que lê. O Docker Compose não tem um recurso desse tipo, então lá a sua realização entrega as chaves como valores, conforme descrito abaixo. MariaDB (chart Bitnami) — um único Secret de credenciais com várias chaves a usa.
  • core/generated-secret não produz nada: o motor de destino gera e gerencia ele mesmo a credencial, como faz um banco de dados gerenciado com a sua senha de administrador. O operador a vincula na Release, porque saber se o motor é dono da credencial decorre da Recipe que o Manifest escolhe; Terraform RDS (artefato HCL inline) vincula um slot obrigatório dessa forma.
  • core/random-password renderiza uma solicitação para que o destino gere uma senha em um recurso de segredo, e publica o localizador desse recurso como core/referenced-secret faz. Ninguém escreve a credencial e a saída renderizada não carrega nenhuma.

Elas são pares — mesmo rótulo, mesma superfície de vinculação, mesmo slot —, de modo que um slot está sempre preenchido, e o que muda entre Releases é o que o preenche. Uma Feature de credenciais que declara um contrato provides obriga toda FeatureRecipe que a implementa a publicar essas chaves, e o build é interrompido se uma delas não o fizer; é isso que torna segura a leitura do consumidor.

core/random-password precisa de algo no destino para gerar o valor, já que o build nunca o faz: no Kubernetes, um controlador (o External Secrets Operator, ou o kubernetes-secret-generator) cuja presença a Release afirma com infra.control_plane_present: true; no Terraform, um recurso random_password; no CloudFormation, um segredo do Secrets Manager que gera a sua própria string. Nenhuma realização é distribuída para o Docker Compose, então um build que a vincula ali é interrompido. Cada solicitação gera o seu próprio valor, então dois componentes compartilham uma única senha gerada vinculando-a uma vez, com name fixado, e lendo-a em outro lugar por meio de core/referenced-secret vinculada a helm/k8s-existing-secret.

Quem nomeia a credencial: values ou infra, exatamente um

core/secret-value, core/secret-provided, core/referenced-secret e core/referenced-secret-set aceitam o localizador da credencial de qualquer um dos autores: o desenvolvedor o escreve nos values da vinculação no Aggregate, o operador na infra da vinculação na Release. A folha é a mesma nos dois — origin, ou entries para o conjunto — e toda realização lê o pilar que o carregar.

O formato do operador é o que torna uma credencial utilizável onde o desenvolvedor não pode escrevê-la: em uma conexão que a Release conecta, e em uma vinculação que só a Release faz, já que uma Release não escreve values em lugar nenhum.

# Release: the operator wires the connection and names the secret.
spec:
components:
router:
uses:
models:
gpt:
target: gpt
features:
credential:
type: core/referenced-secret
infra:
origin: openai-team-a

Exatamente um dos dois. Cada pilar é validado isoladamente, então nenhum dos esquemas pode exigir o localizador; em vez disso, as próprias assertions de cada Feature contêm a regra, e uma vinculação que carrega o localizador em ambos os pilares, ou em nenhum, interrompe o build (E0033) nomeando a Feature, a vinculação e o componente. Esse é o contrato das entidades do catálogo: o compilador avalia a asserção delas como avalia a de qualquer Feature.

Todo o resto mantém o seu pilar. key continua sendo uma folha de values, então uma vinculação que só a Release faz lê a chave de dados padrão, value. Declarar origin em ambos os pilares é exatamente o que o aviso de sobreposição de pilares procura, então carregar essas Features o reporta — LINT: Feature "core/referenced-secret" ... declares property "origin" in both values: and infra: pillars. Aqui a sobreposição é o contrato; o aviso não muda nenhum veredito nem nenhum byte renderizado.

O Manifest escolhe a realização

Várias FeatureRecipes podem implementar uma Feature para o mesmo destino, e o Manifest escolhe. core/referenced-secret tem três no Kubernetes, e o que decide entre elas é onde a credencial reside:

  • helm/k8s-secret-from-parameter escreve o valor que um autor forneceu em um Secret que ela emite, então o material fica na saída renderizada: para avaliação e trabalho local.
  • helm/k8s-external-secret renderiza um ExternalSecret que nomeia uma entrada em um armazenamento de segredos, que o External Secrets Operator no cluster reconcilia em um Secret.
  • helm/k8s-existing-secret não emite nada: ela lê origin como o nome de um Secret que já existe e o publica como escrito.

As duas primeiras derivam o nome do Secret da mesma forma, a partir do nome renderizado do host e do nome do slot, então um consumidor lê o mesmo localizador de qualquer uma delas e a sua referência renderizada não muda; é isso que o exemplo mostra. A terceira publica o próprio nome do Secret existente, então vinculá-la muda de propósito a referência do consumidor.

core/secret-value é realizada no Docker Compose por compose/dotenv-secret, que escreve o valor no ambiente do serviço exatamente como foi redigido: um origin escrito como ${DB_PASSWORD} chega como essa referência, que o Docker Compose preenche a partir do seu shell ou de um arquivo .env quando a stack é iniciada. No Kubernetes, helm/env-secret entrega o valor no canal de injeção, e helm/k8s-secret-from-value também o escreve em um Secret e publica o seu localizador, para um consumidor que lê a credencial por referência. Nenhuma das realizações do Kubernetes aceita uma referência a variável do Compose, que nada ali preencheria.

core/referenced-secret é realizada no Docker Compose por compose/dotenv-referenced-secret. O Compose não tem um recurso de segredo para referenciar, então origin é a própria credencial, e não o nome de um Secret: ela é entregue no pipe de injeção sob a key do anexo, e uma Recipe do Compose que lê o slot a escreve no arquivo emitido exatamente como foi escrita, de modo que um origin escrito como ${DB_PASSWORD} chega como essa referência. Ela não cria nenhum recurso, então o nome que publica é vazio e a chave que publica é values.key.

core/referenced-secret-set é realizada no Docker Compose por compose/dotenv-secret-set, que entrega cada entrada no pipe de injeção como uma variável com o nome da sua chave, escrita no ambiente do serviço exatamente como foi escrita, de modo que uma entrada cujo valor é ${GITHUB_TOKEN} chega como essa referência. Ela não cria nenhum recurso, então o localizador que publica é vazio: um consumidor no Compose lê as entradas do seu pipe de injeção em vez de referenciar um Secret pelo nome, como fazem compose/mcp e compose/mcp-stdio-bridge a partir da 1.1.0 para o server_env de um servidor Model Context Protocol.

Um nome de FeatureRecipe distribuído para mais de um destino, como provided-secret, é escrito com o seu destino no Manifest, compose/provided-secret:1.0.0, já que o nome sem prefixo corresponde a ambos.

Um nome, publicado uma vez

A Recipe de um consumidor nunca deriva o nome do Secret que uma credencial produz: ela lê o localizador que a credencial publica, existingSecret: "{{ .features.root_password.provides.name }}". O nome é escrito uma única vez, no provides da FeatureRecipe, então mudar a forma como ele é composto é uma edição apenas ali. Entrega de credenciais — secretKeyRef de ponta a ponta constrói o caminho referenciável no Kubernetes e o injetado no Docker Compose, e Compartilhando uma credencial — por consumidor, compartilhada e ambas ao mesmo tempo mostra vários consumidores com a sua própria chave ou compartilhando uma.