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

Features de credenciais

Esta página explica uma única ideia, as Features de credenciais da biblioteca standard e a forma como um Manifest escolhe o que realiza cada uma, e não é um espaço de trabalho executável. Uma intenção do programador, duas formas de entrega de credenciais compila um Aggregate com duas realizações da mesma credencial; pode escrevê-lo numa pasta própria com:

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

Depois, 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 (ver entities/component.md); o slot, a Feature que o preenche e a FeatureRecipe que o Manifest associa formam todo o caminho, desde o anexo de um autor até uma carga de trabalho em execução.

A família de Feature de credenciais

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

A biblioteca standard 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 publica-o antes como uma chave provides, pelo que é o próprio bloco inject: do anexo, num slot transparente, que indica para onde 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 com um conjunto de chaves de dados fornecido pelo autor, 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, pelo que aí a sua realização entrega antes as chaves como valores, conforme descrito abaixo. MariaDB (chart Bitnami) — um único Secret de credenciais com várias chaves utiliza-a.
  • core/generated-secret não produz nada: o motor de destino gera e gere ele próprio a credencial, como faz uma base de dados gerida com a sua palavra-passe de administrador. O operador anexa-a na Release, porque saber se a credencial pertence ao motor decorre da Recipe que o Manifest escolhe; Terraform RDS (artefacto HCL inline) associa assim um slot obrigatório.
  • core/random-password renderiza um pedido para que o destino gere uma palavra-passe num 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 contém nenhuma.

São pares — mesmo rótulo, mesma superfície de anexo, mesmo slot —, pelo 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 cada FeatureRecipe que a implementa a publicar essas chaves, e a compilação é interrompida se alguma não o fizer; é isso que torna segura a leitura do consumidor.

core/random-password precisa de algo no destino que gere o valor, uma vez que a compilação 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 cadeia. Não é distribuída nenhuma realização para o Docker Compose, pelo que uma compilação que a associe aí é interrompida. Cada pedido gera o seu próprio valor, pelo que dois componentes partilham uma única palavra-passe gerada anexando-a uma vez, com name fixado, e lendo-a noutro lado através de core/referenced-secret associada 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 programador escreve-o nos values do anexo no Aggregate, o operador na infra do anexo na Release. A folha é a mesma em ambos — origin, ou entries para o conjunto — e cada realização lê o pilar que o transportar.

A forma do operador é o que torna uma credencial utilizável onde o programador não a pode escrever: numa ligação que a Release estabelece, e num anexo que só a Release faz, já que uma Release não escreve values em lado 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, pelo que nenhum dos esquemas pode exigir o localizador; em vez disso, são as próprias assertions de cada Feature que contêm a regra, e um anexo que transporte o localizador em ambos os pilares, ou em nenhum, interrompe a compilação (E0033) nomeando a Feature, o anexo e o componente. Este é o contrato das entidades do catálogo: o compilador avalia a asserção delas como avalia a de qualquer Feature.

Tudo o resto mantém o seu pilar. key continua a ser uma folha de values, pelo que um anexo que só a Release faz lê a chave de dados predefinida, value. Declarar origin em ambos os pilares é exatamente o que o aviso de sobreposição de pilares procura, pelo que o carregamento destas 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 altera nenhum veredicto 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 local onde a credencial reside que decide entre elas:

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

As duas primeiras derivam o nome do Secret da mesma forma, a partir do nome renderizado do host e do nome do slot, pelo que 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, pelo que associá-la altera propositadamente 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 da sua shell ou de um ficheiro .env quando a stack arranca. No Kubernetes, helm/env-secret entrega o valor no canal de injeção, e helm/k8s-secret-from-value também o escreve num 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 uma variável do Compose, que nada aí preencheria.

core/referenced-secret é realizada no Docker Compose por compose/dotenv-referenced-secret. O Compose não tem um recurso de segredo a referenciar, pelo que origin é a própria credencial e não o nome de um Secret: é entregue no canal de injeção sob a key do anexo, e uma Recipe do Compose que lê o slot escreve-a no ficheiro emitido exatamente como foi escrita, pelo que um origin escrito como ${DB_PASSWORD} chega como essa referência. Não cria nenhum recurso, pelo que o nome que publica está 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 canal de injeção como uma variável com o nome da sua chave, escrita no ambiente do serviço exatamente como foi escrita, pelo que uma entrada cujo valor é ${GITHUB_TOKEN} chega como essa referência. Não cria nenhum recurso, pelo que o localizador que publica está vazio: um consumidor no Compose lê as entradas do seu canal 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, escreve-se no Manifest com o seu destino, 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: lê o localizador que a credencial publica, existingSecret: "{{ .features.root_password.provides.name }}". O nome é redigido uma única vez, no provides da FeatureRecipe, pelo que alterar a forma como é composto é uma edição apenas aí. Entrega de credenciais — secretKeyRef de ponta a ponta constrói o caminho referenciável no Kubernetes e o injetado no Docker Compose, e Partilhar uma credencial — por consumidor, partilhada e ambas ao mesmo tempo mostra vários consumidores que têm a sua própria chave ou partilham uma.