Segredos
Esta página explica uma única ideia, como uma credencial chega ao componente que precisa dela, e não é um espaço de trabalho executável. Plataforma avançada — uma plataforma Kubernetes com várias fronteiras mostra os dois modelos de entrega em um espaço de trabalho que você constrói; grave-o em uma pasta sua com:
aggrega scaffold --example advanced-platformEm seguida ele imprime os próximos comandos a executar:
cd advanced-platformaggrega pull --release release.yamlaggrega build --release release.yamlA checklist de entrega de segredos
Uma credencial passa por seis superfícies antes de chegar a um contêiner em execução. Estes são os pontos de contato a verificar ao conectar uma nova:
| Etapa | Superfície | Ação |
|---|---|---|
| 1 | featuresSchema: do Component | Declarar o slot da credencial: seu nome, se ele é required, e sua lista de permissões inject: — os mecanismos de entrega que uma vinculação pode nomear, [env] ou [env, file] para um slot transparente, [] para um opaco. |
| 2 | schema: da Feature de credenciais | Definir o que um autor fornece: as Features de credenciais da biblioteca padrão carregam o rótulo feature.aggrega.ai/kind: secret e recebem o localizador da credencial como origin e a chave de dados como key. |
| 3 | Aggregate features: | Solicitar a credencial, sob a mesma palavra-chave features: de qualquer outra Feature: seu type, seus values e, apenas em um slot transparente, um bloco inject: dizendo como a aplicação a lê. |
| 4 | FeatureRecipe | Realizá-la para o destino: gravar o valor onde o componente o lê, renderizar um recurso que o contém ou renderizar um que o busca em um repositório de segredos. |
| 5 | mappings.features.type do Manifest | Vincular a Feature de credenciais à sua FeatureRecipe, no mesmo nível de qualquer outra Feature. |
| 6 | Recipe | Lê-la, em um slot opaco: a Recipe do componente lê o localizador que a credencial publica, .features.<slot>.provides.name, e o entrega ao mecanismo próprio do produto, como o existingSecret de um chart. |
Um slot transparente usa as cinco primeiras; um slot opaco usa todas as seis, que é o caso usual da infraestrutura empacotada, como o chart de um fornecedor.
Slots transparentes e opacos
Um slot transparente permite que o desenvolvedor diga como a aplicação lê a credencial. Um slot opaco deixa a entrega para a Recipe, e uma vinculação que escreva nele um bloco inject: interrompe o build. No exemplo, core/datastore/mariadb declara um de cada, e o Aggregate preenche ambos, a partir de aggregate.yaml sem os seus comentários:
db: type: core/datastore/mariadb features: root_password: type: core/secret-value values: key: MARIADB_ROOT_PASSWORD origin: dev-root-pw-change-me user_password: type: core/secret-provided values: origin: dev-app-pw-change-me inject: env: - in: MARIADB_PASSWORD from: valueroot_password é opaco: core/secret-value entrega o valor sob a chave que a vinculação nomeia, onde a Recipe do banco de dados o lê. user_password é transparente: core/secret-provided publica o valor como value, e o próprio bloco inject: da vinculação o entrega em MARIADB_PASSWORD. Um bloco inject: que nomeie um mecanismo que o slot não lista interrompe o build, assim como um que nomeie uma chave que nada publica nem lê.
Para um slot opaco preenchido por uma credencial referenciável, a Recipe do componente lê o localizador publicado em vez de derivar um nome, existingSecret: "{{ .features.root_password.provides.name }}", de modo que o Secret que uma FeatureRecipe emite e a referência a ele são uma única string. MariaDB (chart da Bitnami) — um único Secret de credenciais com várias chaves constrói esse fluxo sobre o chart de um fornecedor.
Realizar uma credencial: um recurso ou um pipeline de duas etapas
As realizações Kubernetes da biblioteca padrão renderizam o recurso da credencial a partir de um pequeno chart ao lado da FeatureRecipe: helm/k8s-secret-from-parameter um Secret que contém o valor fornecido por um autor, e helm/k8s-external-secret um ExternalSecret que o External Secrets Operator reconcilia a partir de um repositório de segredos. Features de credenciais apresenta cada uma.
Uma FeatureRecipe pode, em vez disso, realizar uma credencial com um pipeline: de duas etapas, cada uma um plugin. A primeira, o buscador, grava o recurso específico do repositório — um ExternalSecret, por exemplo — nomeando a entrada do repositório que os valores da vinculação indicam. A segunda, o injetor, aplica um patch à carga de trabalho renderizada do componente para montar o Secret resultante em seu contêiner, nas variáveis ou arquivos que o bloco inject: da vinculação nomeia, que a etapa lê em .inject. Mudar para outro repositório de segredos substitui o buscador; o injetor permanece. Uma etapa retorna os recursos que adiciona como efeitos colaterais e suas alterações nos documentos renderizados como patches; o contrato de plugins Wasm é a forma de ambos.
A credencial própria de uma Feature
Uma Feature pode precisar de uma credencial própria: um proxy de guardrails que se autentica em um serviço upstream, um enviador de logs com um token de ingestão. A Feature declara o slot no seu próprio featuresSchema, exatamente como um Component faz, e a FeatureRecipe vinculada a ela lê o que preenche esse slot quando renderiza a carga de trabalho da Feature.
Vinculações não se aninham. A credencial é vinculada ao lado da Feature, no mesmo componente, sob o nome que o slot da Feature declara; o nome do slot é o que liga as duas. A Feature de guarda e o componente abaixo são entidades próprias do espaço de trabalho; core/referenced-secret é da biblioteca padrão.
# The Feature declares the slotkind: Featuremetadata: name: local/guardspec: appliesTo: "component.aggrega.ai/type in (server, worker)" featuresSchema: guard_api_key: selector: "feature.aggrega.ai/kind=secret" sensitive: true inject: [env]---# The Aggregate fills it beside the Featurespec: components: finance-agent: type: local/compute/guarded-worker features: ai-guard: type: local/guard guard_api_key: type: core/referenced-secret values: origin: dev-guard-key-change-me key: api-keyA FeatureRecipe da guarda renderiza uma carga de trabalho cujo contêiner referencia o slot, attachments: { GUARD_API_KEY: { from: guard_api_key, as: env } }, de modo que a referência chega ao contêiner da guarda e a nenhum outro. A Recipe do componente hospedeiro não pode referenciar o slot, porque ele pertence à Feature: uma carga de trabalho que tente alcançá-lo interrompe o build nomeando o slot. Uma entrada de carga de trabalho que nomeie um slot que nada preenche também interrompe o build, pois não há localizador publicado a resolver.
O mesmo vale para as conexões que uma Feature traça: uma conexão no próprio bloco uses: da Feature não carrega vinculações, então uma credencial de que uma conexão assim precise é um slot que a Feature declara, preenchido ao lado da Feature.
A credencial própria de uma conexão
Um gateway que alcança dois modelos pode apresentar uma chave diferente a cada um, ou uma chave a um e nenhuma ao outro. Um slot no gateway contém uma única credencial para o componente inteiro, então a credencial vai, em vez disso, na conexão: o socket do gateway declara o slot que cada conexão que passa por ele pode preencher, e cada conexão o preenche, ou não, por conta própria.
spec: components: router: type: core/gateway/litellm uses: models: gpt: target: gpt features: credential: # a slot the models socket declares type: core/referenced-secret values: key: api-keyA Recipe do gateway lê a vinculação a partir da sua conexão, em .context.uses.gpt.features.credential, de modo que um gateway que alcança vários modelos lê a chave própria de cada modelo; core/gateway/litellm entrega cada uma como uma variável própria, que a entrada da conexão na sua tabela de roteamento nomeia. Uma vinculação sob um nome para o qual o socket não declara nenhum slot interrompe o build, nomeando os slots que ele declara. O Manifest pode realizar a credencial de uma conexão de forma diferente das demais, pela chave <connection>.credential no seu nível por instância. Credenciais em conexões — uma chave por conexão e uma única chave nas duas pontas constrói isso; uma Release também pode ligar uma conexão assim e nomear o segredo no infra da vinculação, como descreve Features de credenciais.