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

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:

Terminal window
aggrega scaffold --example advanced-platform

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

Terminal window
cd advanced-platform
aggrega pull --release release.yaml
aggrega build --release release.yaml

A 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:

EtapaSuperfícieAção
1featuresSchema: do ComponentDeclarar 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.
2schema: da Feature de credenciaisDefinir 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.
3Aggregate 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ê.
4FeatureRecipeRealizá-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.
5mappings.features.type do ManifestVincular a Feature de credenciais à sua FeatureRecipe, no mesmo nível de qualquer outra Feature.
6RecipeLê-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: value

root_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 slot
kind: Feature
metadata:
name: local/guard
spec:
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 Feature
spec:
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-key

A 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-key

A 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.