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

Modelo de credenciais

Uma única família de anexos

No Aggrega, uma credencial é uma Feature. Ela é anexada na mesma superfície, sob a mesma palavra-chave e na mesma forma que qualquer outra Feature. Aqui o desenvolvedor anexa a credencial do banco de dados no Aggregate, escrevendo seu localizador em values:

# the Aggregate — its parameters and the components' own values left out
spec:
components:
api:
type: core/compute/server
db:
type: core/datastore/mariadb
features:
root_password: # a credential Feature
type: core/secret-value:1.0.0
values:
key: MARIADB_ROOT_PASSWORD
origin: "{{ .parameters.db_root_pass }}"

e o operador anexa ao servidor um alvo de coleta de métricas na Release, porque cada entrada que core/prometheus-exporter recebe — a porta, o caminho e o intervalo da coleta — é operacional, então é escrita em infra:

# the Release — the api's own infra and the db's entry left out
spec:
components:
api:
features:
metrics: # an operational Feature
type: core/prometheus-exporter:1.0.0
infra:
port: http # the named port of the api's Service

Há uma única palavra-chave de anexo (features:), uma única forma de contexto de renderização (.features.<name>, e a mesma forma sob uma conexão, .context.uses.<alias>.features.<slot>, para um anexo escrito em uma), uma única ordem de execução e um único conjunto de coordenadas de saída — para um anexo em um componente, o componente ao qual está anexado e depois o nome sob o qual está anexado, quer o layout do destino carregue esses dois como um diretório <component>--<instance>/ ao lado do diretório do próprio componente, quer como um prefixo de nome de arquivo <component>--<instance>--. O que varia entre anexos é o que eles produzem — um valor injetado, um recurso referenciável, um sidecar, uma identidade de nuvem — e não a superfície em que são declarados.

Uma Feature de credencial carrega o rótulo feature.aggrega.ai/kind: secret em sua entidade de catálogo. Esse rótulo é metadado descritivo: diz a um leitor, a um site de catálogo e a um seletor de rótulos para que serve a Feature. Nenhum ramo do compilador o lê, e nenhum comportamento depende dele. O comportamento vem da FeatureRecipe à qual um operador associa o tipo de Feature.

O modelo mental em uma frase: existe um único tipo de anexo; o que varia é o que ele produz.

Slots e anexos livres

Um Component ou uma Feature pode declarar slots em featuresSchema:

spec:
featuresSchema:
root_password:
required: true
inject: [] # blackbox — the Recipe delivers it
selector: "feature.aggrega.ai/kind=secret"
user_password:
inject: [env, file] # transparent — the developer may dictate delivery

Um anexo cujo nome de instância corresponde a um slot declarado preenche esse slot. Um anexo sob qualquer outro nome é um anexo livre: a entidade não o pediu, e ele é renderizado junto com tudo o que a entidade pediu. O schema gerado para um slot declarado permanece aberto, então declarar um slot nunca fecha o bloco para anexos livres. Uma única forma interrompe em vez de renderizar: um anexo escrito no próprio componente cuja Feature satisfaz o selector de um slot que nada vincula ali, o que é um preenchimento escrito com o nome errado, e não um anexo livre.

Duas coisas que um slot pode restringir:

  • inject — os mecanismos de entrega que um Workload pode selecionar para o que preenche o slot. Uma lista vazia é um slot caixa-preta: a própria mecânica da Recipe o entrega (a opção existingSecret de um chart, por exemplo), e um Workload não pode referenciá-lo a partir de um contêiner.
  • selector — uma string de seletor de rótulos que os rótulos da Feature que preenche o slot devem satisfazer. É aqui que o rótulo kind=secret mostra seu valor: o autor de uma entidade que quer um slot preenchido apenas por uma credencial diz isso com um seletor, e a verificação é uma avaliação de conjunto de rótulos que o compilador realiza durante a análise estática.

Uma terceira coisa que um slot pode fazer é exigir que acabe vinculado. required: true torna obrigatório o nome do slot: o compilador interrompe durante a análise estática quando nada o vincula, com um diagnóstico que nomeia o slot e o tipo de componente que o declarou. A exigência é avaliada em relação ao conjunto de anexos com que o componente fica depois que cada escopo foi aplicado em cascata, então um anexo fornecido acima do componente vincula o slot exatamente como um preenchimento escrito no componente.

Uma segunda superfície expressa uma exigência diferente. A anotação repetível de Component features.aggrega.ai/requiredType.<label> declara um mandato de presença: pelo menos um anexo deve carregar o tipo de Feature que a anotação nomeia, sob qualquer nome e em qualquer escopo, e um mandato que nada satisfaz interrompe durante a mesma análise estática com seu próprio diagnóstico. Os dois nunca respondem um pelo outro — um slot pergunta se um ponto de vinculação nomeado está vinculado; um mandato, se algum anexo carrega um tipo nomeado —, então uma entidade que precisa que sua Recipe leia o que foi anexado declara um slot, enquanto uma cujo contrato simplesmente exige que uma capacidade esteja presente declara um mandato.

O que o compilador garante e o que não garante

Esta é a seção que sustenta tudo. O Aggrega é um compilador ahead-of-time, e suas garantias são mais estreitas do que a palavra “secret” leva um leitor a supor.

O compilador nunca resolve uma credencial. Ele não se autentica em uma API de nuvem, não lê um cofre e não busca material durante aggrega build. Os values e a infra de um anexo de credencial percorrem o grafo e chegam ao contexto de renderização como escalares opacos, e uma FeatureRecipe os renderiza no artefato que a plataforma de destino espera. A resolução acontece depois, no cluster ou no gerenciador de estado de IaC, em relação àquilo para que o artefato renderizado aponta.

O compilador não consegue distinguir um ponteiro de um valor material. Ele é agnóstico em relação ao que um escalar significa (veja 05-invariants.md). Um anexo de credencial cujo localizador carrega uma coordenada de armazenamento (path, key, um ARN) renderiza uma referência a essa coordenada; um anexo de credencial cujo localizador carrega o próprio material renderiza o material, literalmente, no arquivo de saída. Ambos são legais, e o compilador os trata de forma idêntica porque não tem como distingui-los.

Portanto, a formulação honesta da garantia é:

O Aggrega garante que o compilador não realiza nenhuma resolução. Não garante que a saída renderizada não contenha material — isso depende inteiramente de qual Feature de credencial está anexada e do que seu autor colocou nela, o desenvolvedor em values ou o operador em infra.

Duas consequências que vale a pena internalizar:

  • Uma árvore de artefatos renderizada é tão sensível quanto seu anexo que mais carrega material. Trate dist/ de acordo: se algum anexo carrega material inline, a árvore contém material.
  • As famílias core/secret-value e core/referenced-secret do próprio catálogo incluem formas que aceitam um valor diretamente. Elas existem porque implantações reais precisam de um caminho para desenvolvimento local, e são honestas quanto a isso: os exemplos fornecidos usam marcadores óbvios (dev-root-pw-change-me) justamente para que o material em um exemplo renderizado visivelmente não seja uma credencial real. Para uma implantação que não deve carregar material, anexe uma Feature de credencial apoiada em um armazenamento cuja FeatureRecipe emita um recurso de busca (um ExternalSecret, um recurso personalizado de busca em cofre, uma referência de segredo nativa do provider) em vez de uma que emita dados.

A convenção da biblioteca padrão é que uma credencial seja solicitada como anexo em vez de escrita em um bloco values, de modo que trocar um preenchimento de desenvolvimento local por um apoiado em armazenamento seja uma mudança no Manifest, e não uma edição da intenção do desenvolvedor. É uma convenção que o catálogo segue, não uma regra que o compilador impõe.

Sensibilidade declarada

O compilador não consegue distinguir um ponteiro de um valor material, conforme a seção acima — mas um autor consegue, e pode declarar isso. No Aggrega, a sensibilidade é uma anotação em uma declaração: o autor de uma entidade de catálogo afirma o que carrega material secreto, e o compilador deriva o resto dessa afirmação mais a fiação que já construiu. Nada é inferido de um valor, e nada é adivinhado a partir do nome de um campo.

Ela é escrita em exatamente dois lugares, que carregam afirmações genuinamente diferentes.

Em uma folha de schema — este dado é material secreto. Uma folha de values, infra ou provides declara sensitive: true:

spec:
schema:
values:
origin:
type: string
required: true
sensitive: true # the material
key:
type: string
default: value # a data key — a locator, not material

Em um slot de anexo — o que quer que vincule este ponto lida com material secreto. Um slot de featuresSchema declara sensitive: true:

spec:
featuresSchema:
password:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]

Os dois níveis não são uma duplicata de conveniência um do outro, e a forma da credencial referenciável é o caso prático que mostra por quê. Uma credencial referenciável publica provides.name e provides.key — o localizador do recurso e a chave de dados dentro dele — e nenhum dos dois é sensível: o nome de um Secret do Kubernetes é público, assim como a chave dentro dele. Ambos são renderizados às claras no próprio manifesto do consumidor como um secretKeyRef. Ainda assim, o slot que essa credencial preenche sem dúvida lida com material secreto. Um único nível não consegue expressar os dois fatos: marcar os localizadores publicados para que o slot seja lido como sensível afirmaria algo falso sobre eles e levaria esse erro a todo lugar onde a declaração é lida.

A partir dessas duas declarações, o compilador deriva, por anexo, se o anexo lida com material declarado sensível — verdadeiro quando a Feature anexada declara uma folha sensível, ou quando o slot que ela vincula declara uma, bastando qualquer um dos dois sozinho. Ele deriva isso do anexo como fica depois que cada escopo de autoria foi consolidado, então uma declaração de escopo mais amplo que um preenchimento mais estreito substituiu não permanece, e a exigência de um slot se aplica ao preenchimento que de fato prevaleceu. Uma Feature de credencial que não declara nenhuma folha sensível — porque o mecanismo de destino detém o material e o autor não escreve nada — ainda produz um anexo sensível quando vincula um slot sensível.

O teto, dito com clareza

A palavra “sensível” leva um leitor a esperar um mecanismo de confidencialidade. Não é um, e a garantia é mais estreita do que o nome sugere em cinco aspectos específicos:

  • Não criptografa. Nada é encapsulado, selado ou transformado.
  • Não muda o veredito do build, com uma exceção. Nenhum build é interrompido porque falta uma declaração, e um catálogo cujas entidades de credencial não carregam nenhuma declaração é construído com sucesso. Nenhum valor é aceito ou rejeitado porque existe uma declaração, exceto quando o valuesMapping de uma Recipe ou FeatureRecipe do CloudFormation lê um valor declarado sensível para preencher os parâmetros de um template obtido: ali, cada literal que o mapeamento vincula é recusado, então adicionar uma declaração pode transformar um build que tinha sucesso em um que é interrompido — veja A secret bound to a CloudFormation parameter would be written into the template (Um segredo vinculado a um parâmetro do CloudFormation seria escrito no template). Em todos os outros casos, adicionar declarações a um catálogo existente faz com que todo build que tinha sucesso continue tendo.
  • Não garante que a saída renderizada esteja livre de material. A garantia enunciada acima não muda: se um artefato carrega material depende de qual preenchimento foi anexado e do que seu autor colocou nele. Um valor declarado sensível fornecido inline é renderizado exatamente como um não declarado onde quer que o build o renderize — a recusa do CloudFormation descrita acima interrompe um literal em vez de renderizá-lo, e uma função intrínseca é escrita como dada, incluindo seu texto — e dist/ continua tão sensível quanto seu anexo que mais carrega material.
  • Não força um mecanismo de entrega. Uma declaração não pode converter um valor inline em uma referência de armazenamento, e não restringe o que a allowlist inject de um slot permite. Forçar a entrega significaria emitir um recurso que o autor nunca declarou, que é exatamente o que o invariante de ausência de infraestrutura fantasma proíbe — veja 05-invariants.md.
  • Não muda nenhum byte renderizado na maioria dos destinos, e nesses nunca mudará. Dois caminhos de renderização fornecidos agem sobre a declaração no que produzem (os providers Helm, Helm-Chart e Compose também a leem, apenas para manter um valor marcado fora do texto de uma falha): o provider Terraform marca a entrada de um módulo incorporado que carrega material declarado sensível com o atributo de sensibilidade do próprio Terraform — veja language-reference/providers/terraform.md “Entradas de módulo declaradas sensíveis”; quando o valuesMapping de uma Recipe, ou o da FeatureRecipe de uma Feature anexada a um componente, inventa os nomes das entradas, nenhuma entrada pode carregar o atributo e o build imprime um aviso dizendo isso, veja A declared-sensitive value reaches the target through a values mapping (Um valor declarado sensível chega ao destino por meio de um mapeamento de valores) — e o provider CloudFormation recusa as vinculações literais descritas acima, o que interrompe um build em vez de mudar seus bytes. Em todos os outros casos, adicionar declarações em um catálogo existente deixa cada artefato renderizado idêntico. O teto além disso é estrutural, e não uma questão do que foi construído: uma declaração só pode alcançar um artefato renderizado em uma plataforma de destino cuja própria linguagem tenha uma noção de sensibilidade — uma declaração que essa plataforma entende, que rege como ela exibe um valor e não como o armazena. Em um destino sem essa noção, não há nada em que uma declaração possa se transformar, então uma entrada idêntica é renderizada de forma idêntica com ou sem ela, permanentemente.

Uma coisa que uma declaração muda é o que a CLI imprime para uma pessoa ler. Um valor declarado sensível é substituído por um marcador fixo no rastreamento por passada e nos layouts de inspect, mantendo a chave e ocultando apenas o valor. É uma decisão de exibição em superfícies que ninguém implanta, e os artefatos renderizados são emitidos literalmente porque são o que se implanta.

Quando o compilador consegue identificar o valor pela chave — uma folha declarada, ou uma chave de entrega que carrega material de uma chave provides declarada —, a substituição é exata. Um valor que um template já escreveu em outro documento não carrega nenhuma chave em que substituir, porque um documento renderizado não registra nada sobre de qual declaração veio cada caractere, e recuperar isso significaria inspecionar conteúdo. Assim, o rastreamento mostra esse documento avaliando o mesmo template uma segunda vez em relação a um contexto cujos dados declarados sensíveis já são lidos como o marcador, e rotula o resultado como uma nova renderização, e não como o que foi renderizado: um template que se ramifica pelo conteúdo de um valor renderiza de forma diferente diante de um marcador, e um dado que nenhuma declaração nomeia passa inalterado. As superfícies, esse rótulo e seus limites estão em language-reference/vocabulary/compact-form-authoring.md “Declarar uma folha como sensível”.

Portanto, a formulação honesta do que esse eixo oferece:

Uma declaração de sensibilidade é uma afirmação da intenção do autor que viaja com a entidade, para que ferramentas e políticas possam raciocinar sobre o que uma implantação manipula. Não é um mecanismo que a protege.

Proteger o material continua sendo tarefa do armazenamento de segredos, do cluster e do pipeline que manipula a árvore renderizada — como diz o restante deste capítulo.

Como uma credencial chega a um contêiner

Duas formas de entrega, escolhidas pela FeatureRecipe do anexo, e não pelo desenvolvedor:

Valor injetado. A FeatureRecipe declara um injectMapping e nenhum recurso. Sua saída é mesclada em profundidade no pipe de entrega do componente consumidor antes que a Recipe base seja renderizada, então uma Recipe que lê .context.inject.env.<KEY> recebe o valor. Nada independente é emitido.

Duas credenciais entregues sob uma mesma chave interrompem o build, nomeando ambos os anexos: um mapeamento que escreve uma chave que outra Feature anexada já entregou — pelo próprio mapeamento dessa Feature ou por seu próprio bloco inject: — é recusado em vez de mesclado, de modo que uma credencial nunca é apresentada no lugar de outra. A regra é a mesma para todo anexo, onde quer que tenha sido anexado e quer preencha um slot no componente ou em uma conexão. Um mapeamento que substitui uma chave entregue pelo próprio bloco inject: do componente ou por uma de suas conexões é a interceptação de que as Features de roteamento dependem, e continua legal.

Recurso referenciável. A FeatureRecipe declara source, workload, artifacts e/ou valuesMapping, então emite um recurso — normalmente um Secret nativo da plataforma. Ela publica a identidade desse recurso por meio de seus provides, e um consumidor a lê de volta como .features.<name>.provides.name / .provides.key. O próprio nome do recurso é derivado dos mesmos provides publicados, de modo que o nome que o consumidor lê e o nome que o recurso carrega são uma única string avaliada, e não duas derivações que poderiam divergir.

O Workload de uma Recipe consome um preenchimento referenciável pelo mapa attachments: de um contêiner:

workload: |
containers:
main:
attachments:
DB_PASSWORD:
from: root_password # a slot the Component declares
as: env

O sintetizador resolve a referência a partir dos provides publicados do slot — um secretKeyRef do Kubernetes para as: env, um volume apoiado em segredo para as: file. O autor da Recipe escreve apenas o nome do slot e o mecanismo.

Uma FeatureRecipe pode fazer as duas coisas: reescrever o pipe de entrega e emitir um recurso. Ela também pode declarar um pipeline de etapas Wasm, que são executadas igualmente para toda família de anexos — um anexo de credencial pode transformar os documentos renderizados do componente hospedeiro, mediante convite, exatamente como um anexo operacional pode.

Quem nomeia a credencial

O localizador de uma credencial — o nome do segredo, a entrada do armazenamento a buscar, o valor a entregar — é escrito por quem o conhece, e nem sempre é o desenvolvedor. Uma conexão que a Release conecta não tem entrada no Aggregate, e a Release não escreve values em lugar nenhum, então uma credencial que tirasse seu localizador apenas de values nunca poderia ser nomeada em tal conexão, nem em nenhum anexo que a Release crie.

Por isso, cada Feature de credencial da biblioteca padrão que carrega o localizador de um chamador — core/referenced-secret, core/referenced-secret-set, core/secret-value e core/secret-provided — o aceita de qualquer um dos autores: o desenvolvedor nos values do anexo, no Aggregate, ou o operador em sua infra, na Release. A folha tem um único nome, uma única forma e uma única declaração sensitive: true em ambos os pilares, e cada realização lê o pilar que a carrega. A proibição de values: na Release permanece intacta: o localizador do operador é infra. As Features que não recebem localizador — core/random-password, core/generated-secret — não são afetadas.

Exatamente um, garantido pela Feature. Um anexo carrega o localizador em um único pilar, nunca em ambos e nunca em nenhum. O schema de nenhum pilar consegue expressar isso, porque cada pilar é validado isoladamente; o próprio bloco assertions de cada Feature o faz, e um anexo que o viola interrompe o build nomeando a Feature, o anexo e o componente. Esse é o contrato da entidade de catálogo, mantido como toda asserção de Feature: o compilador avalia o template que o autor da Feature escreveu e não tem nenhuma regra própria sobre credenciais, pilares ou localizadores.

O que fica onde estava. Todos os outros campos mantêm seu pilar — a chave de dados de uma credencial referenciável ainda é escrita em values, então um anexo que apenas a Release cria lê seu valor padrão — e core/secret-provided ainda entrega apenas pelo próprio bloco inject: do anexo, que só o Aggregate escreve e que o anexo de uma conexão nunca carrega.

Compartilhar uma credencial entre vários consumidores

O consumidor pode manter a credencial. Um slot pertence à entidade que precisa da credencial, e muitas vezes essa é o chamador e não aquilo que é chamado: um componente que apresenta uma chave ao se conectar declara o slot dessa chave em sua própria entidade de catálogo, no socket pelo qual se conecta, de modo que a chave é mantida na conexão em que é apresentada — e nada em uma aresta uses obriga o destino a fornecer uma. core/ai-agent/crewai é a forma fornecida — seu socket model declara um slot credential opcional com o seletor feature.aggrega.ai/kind=secret, inject: [env] e sensitive: true, e um Aggregate o preenche sob a conexão, em uses.model.<alias>.features.credential. O que os componentes de modelo da biblioteca padrão publicam para um consumidor ler é um local de serviço e um nome de modelo, não uma credencial, então a chave que o agente apresenta ao chamar esse endpoint é declarada pelo agente e mantida em sua conexão. O slot é opcional, mas uma conexão que alcança um modelo que seu catálogo rotula como component.aggrega.ai/hosting: managed e que não carrega nenhuma credencial interrompe o build, a menos que seus próprios values digam que o modelo não exige nenhuma, unauthenticated: true — uma asserção que a entidade de catálogo do agente carrega e que o compilador avalia como avalia qualquer asserção, lendo o rótulo como uma string. O componente de modelo ao qual ele se conecta pode manter uma chave própria para seus próprios chamadores — core/ai-model/vllm declara um slot api_key exatamente para isso — e os dois são pontos de vinculação separados: um anexo vincula um slot pelo nome onde ele é declarado, no componente ou na conexão, então preencher um não diz nada sobre o outro.

É esse posicionamento que torna as duas formas abaixo verdadeiras escolhas de implantação: com o slot no consumidor, um build pode dar a cada consumidor sua própria chave e outro pode dar a todos a mesma, sem que nenhuma entidade de catálogo mude entre eles.

A mesma entidade de catálogo atende às duas formas, e é o autor quem escolhe qual:

  • Por consumidor. Cada consumidor preenche seu próprio slot com seu próprio anexo de credencial — no componente, ou em sua conexão quando o slot é de um socket. Cada um recebe seu próprio recurso renderizado.
  • Compartilhada. Para um slot que um componente declara, uma credencial é anexada uma única vez em um escopo compartilhado — um subsistema no Aggregate, uma fronteira na Release — e se propaga em cascata para cada componente nesse escopo. Um slot que um socket declara é preenchido por conexão, e nada se propaga em cascata para dentro de uma conexão, então ali a forma compartilhada é escrita em cada conexão: a credencial de cada conexão lê um mesmo parâmetro. Onde os consumidores precisam referenciar um único recurso físico, esse parâmetro o nomeia — core/referenced-secret vinculado à realização existing-Secret aponta cada conexão para um único Secret pelo nome, e uma credencial gerada é uma solicitação e muitas referências, como abaixo.

Vale descrever com precisão a renderização da forma compartilhada, porque é fácil supor o contrário: um anexo compartilhado renderiza um recurso por consumidor, cada um carregando o mesmo material da única declaração. A renderização é executada por componente, e um nome de recurso derivado de {{ .context.instance_id }}-{{ .attachment_name }} portanto difere por consumidor. O que é compartilhado é a declaração única; os recursos emitidos não são deduplicados em um só. Um parâmetro lido em cada conexão é renderizado da mesma forma sob uma realização que renderiza um recurso — um por conexão, sendo o nome do anexo o alias da conexão, um ponto e o slot.

Se uma implantação precisa de exatamente um Secret físico que vários consumidores leem, expresse isso com uma Feature de credencial cuja FeatureRecipe é executada no escopo da fronteira (executionScope: boundary), que renderiza uma vez para a fronteira em vez de uma vez por componente.

Uma chave que as duas pontas de uma conexão mantêm

Um servidor que verifica uma chave e o componente que o chama mantêm cada um essa chave, cada um do seu lado. O servidor mantém a chave que verifica em um slot do seu próprio Component — core/ai-model/vllm, core/ai-model/tei e core/ai-model/tgi declaram cada um api_key, assim como o modelo e o gateway do LiteLLM para a chave que o LiteLLM chama de master key — e sua Recipe entrega o que preenche o slot como a variável que o servidor lê. O chamador mantém a chave que apresenta do seu próprio lado: na conexão em que a apresenta, em um slot que seu socket declara — como o socket model de core/ai-agent/crewai declara credential — ou, quando seu Component declara a chave em si mesmo, nesse slot, para cada conexão que faz. Nenhuma das pontas vê os anexos da outra: um anexo em uma conexão recai apenas sobre o chamador, e a saída renderizada de um servidor é a mesma, seja o que for que as conexões que o alcançam carreguem. O servidor nunca sabe qual chave um chamador mantém, e o chamador lê apenas o que o servidor publica — um endereço e um nome de modelo. As duas pontas concordam porque o Aggregate alimenta ambas a partir de um mesmo parâmetro:

spec:
parameters:
model_key_secret: { type: string }
components:
model:
type: core/ai-model/vllm
values: { model: Qwen/Qwen2.5-0.5B-Instruct }
features:
api_key: # the key the server verifies
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key
router:
type: local/gateway/model-router # its `models` socket declares a `credential` slot
uses:
models:
local:
target: model
features:
credential: # the key the caller presents
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key

Se isso é um segredo ou dois depende de onde as duas pontas resolvem segredos. Um provider resolve um segredo por referência dentro de um escopo de segredos: um namespace do Kubernetes no helm, um projeto do Compose no compose, a configuração raiz de uma fronteira no terraform e, no cloudformation, uma stack, na conta e na região da AWS em que ela é implantada. Onde as duas pontas ficam em um mesmo escopo, elas referenciam um único recurso de segredo. Onde ficam em escopos diferentes, cada ponta mantém um recurso de segredo próprio, realizado a partir da mesma entrada do armazenamento. O Manifest escolhe a realização de cada ponta — por tipo de Feature ou, para um anexo específico, pelo seu nome, que para o anexo de uma conexão é <alias>.<slot> (local.credential acima). Como um mesmo parâmetro alimenta ambas, as duas realizações leem origin como o mesmo tipo de localizador: ambas o nome de um Secret, ambas a chave de uma entrada do armazenamento, ou ambas o próprio valor.

No helm, com as duas pontas em um mesmo namespace, vincular core/referenced-secret a helm/k8s-existing-secret e atender ao parâmetro com o nome de um Secret que esse namespace contém, model-keys, faz com que as duas pontas o referenciem pelo nome e não renderiza nenhum Secret. O contêiner do servidor carrega:

- name: VLLM_API_KEY
valueFrom:
secretKeyRef:
name: model-keys
key: api-key

e a Recipe do roteador lê o mesmo nome e a mesma chave da sua conexão, em .context.uses.local.features.credential.provides. Com as duas pontas em namespaces diferentes, vinculá-lo a helm/k8s-external-secret e atender ao parâmetro com a chave de uma entrada do armazenamento dá a cada ponta um ExternalSecret próprio, no seu próprio namespace, ambos buscando essa mesma entrada. No compose, as duas pontas carregam a mesma referência ${VAR}, que o Docker Compose substitui a partir do ambiente com que o único projeto é iniciado. Esse posicionamento é uma convenção que o catálogo da biblioteca padrão segue; o compilador não compara nada entre as duas pontas.

Uma chave atende a todos os chamadores. vLLM, TEI e TGI verificam cada um uma única chave, então todo chamador apresenta a mesma chave e o servidor não consegue distinguir um chamador de outro, por mais conexões que o alcancem. Esse é um limite do próprio servidor. O TGI compara sua chave sem diferenciar maiúsculas de minúsculas, então duas chaves que diferem apenas nisso são para ele uma só chave. O modelo e o gateway do LiteLLM também aceitam as chaves que eles próprios emitem, enquanto seu banco de dados de contabilidade estiver anexado.

Uma credencial que o destino gera

Onde uma Release não fornece nenhuma credencial, uma entidade de catálogo muitas vezes recorre a um padrão de desenvolvimento — um valor inline em uma Recipe, um padrão no parâmetro de um módulo. Esse valor é o mesmo para cada leitor do catálogo, o que é aceitável para avaliação e para nada mais. core/random-password elimina essa necessidade: ninguém escreve a credencial, porque o destino a gera.

O build não pode ser o lugar onde a senha é criada. Sua saída é uma função pura da sua entrada e nunca carrega o valor de um segredo, então uma senha sorteada no momento do build mudaria a cada build e ficaria nos arquivos renderizados. Em vez disso, a FeatureRecipe renderiza uma solicitação — um recurso gerador que nomeia o recurso de segredo que ele preenche — e o destino sorteia o valor no momento da implantação:

  • no helm, um controlador no cluster: o gerador de senhas do External Secrets Operator, reconciliado por meio de um ExternalSecret, ou o controlador kubernetes-secret-generator, reconciliando um StringSecret;
  • no terraform, o random_password do provider random, sorteado quando a configuração é aplicada;
  • no cloudformation, um segredo do Secrets Manager que gera sua própria string quando a stack o cria.

Em todos os casos, a saída renderizada nomeia o gerador e o recurso de segredo e não carrega nenhum valor. Isso é uma propriedade do que o build tem, não uma proteção que ele acrescenta: o valor nunca existe até que o destino o crie. Onde o destino o guarda depois é assunto do destino — o Terraform o guarda no plano e no estado, um cluster em um Secret.

O que o destino precisa ter em execução. Uma solicitação só é atendida onde algo a atende. No helm isso é o controlador, e o compilador não pode inspecionar o cluster para saber se há um em execução, então as FeatureRecipes do helm interrompem o build, a menos que a Release afirme o pré-requisito com infra.control_plane_present: true no anexo. No terraform e no cloudformation, o apply ou a stack gera o próprio valor e nada precisa estar em execução antes.

Onde não pode ser usado. O Compose não executa nenhum controlador e não tem nenhum recurso que gere um valor, então nenhuma FeatureRecipe realiza core/random-password ali, e um build que o vincula no compose é interrompido por falta de uma. Uma Release que tem o compose como destino fornece sua credencial por meio de core/secret-value, normalmente como uma referência de variável que o Docker Compose substitui quando a stack é iniciada.

Como um consumidor a lê. core/random-password publica os mesmos provides.name e provides.key que core/referenced-secret e carrega o mesmo rótulo feature.aggrega.ai/kind: secret, então um slot que seleciona a família de credenciais o admite e um consumidor lê uma credencial gerada exatamente como lê uma que já existe.

Como vários consumidores compartilham uma. Um gerador sorteia um novo valor para cada solicitação, então a regra de compartilhamento da seção anterior se aplica de forma mais aguda: uma credencial gerada anexada em um escopo compartilhado — ou em cada consumidor — renderiza uma solicitação por consumidor, e cada solicitação sorteia uma senha diferente, que um banco de dados e seus clientes não podem usar. Uma credencial gerada compartilhada por vários consumidores é expressa como uma solicitação e muitas referências: core/random-password em um componente, com seu valor name fixando o Secret que ele preenche, e core/referenced-secret nos demais, vinculado à realização existing-Secret e apontado para esse mesmo nome. Escritos a partir de um mesmo parâmetro, os dois não podem divergir, e a renderização carrega exatamente uma solicitação que todo consumidor referencia.

core/random-password não é core/generated-secret. Essa Feature entrega uma credencial a um mecanismo que já detém todo o seu ciclo de vida — um banco de dados gerenciado, um controlador de banco de dados — e não renderiza nada. core/random-password renderiza a própria solicitação, para um workload cuja Recipe espera receber uma credencial.

Precedência de anexos

Um anexo pode ser declarado em vários escopos ao mesmo tempo. A titularidade de um campo disputado é resolvida por três regras, aplicadas nesta ordem:

  1. Origem. Um campo escrito explicitamente prevalece sobre um contribuído por expansão orientada por anotações, seja qual for o escopo de onde cada um veio.
  2. Autoridade de composição. Uma declaração no Aggregate que você está implantando prevalece sobre uma dentro de um Aggregate que ele compõe, mesmo quando o documento composto a declarou no escopo mais restrito.
  3. Especificidade. Dentro de um mesmo nível de autoria, o escopo mais restrito refina o mais amplo campo a campo: um preenchimento no nível do componente substitui um anexo de todo o subsistema ou de toda a fronteira com o mesmo nome de instância apenas nos campos que menciona, e os campos que omite mantêm os valores do escopo mais amplo.

O lado do desenvolvedor fornece values e o lado do operador fornece infra, então os dois nunca disputam o mesmo campo. Uma Feature de credencial que obtém seu localizador de qualquer um dos lados o declara como dois campos, um por pilar, e sua própria asserção recusa um anexo que carregue ambos, então ali também a precedência não tem empate a desfazer. A precedência rege apenas os valores dos campos; ela não reordena a avaliação, que segue a sequência de cascata em 10-compilation-pipeline.md.

Charts legados que exigem uma string formatada

Um chart às vezes quer uma única string de conexão com material embutido — oracle://admin:PASSWORD@HOST:1521/DB. Um compilador ahead-of-time não pode construir essa string a partir de uma coordenada do armazenamento, porque nunca mantém o material. Dois caminhos suportados:

Templating no cluster. A FeatureRecipe da credencial emite um recurso que formata a string no cluster, usando o templating próprio do operador do cofre. A aplicação então referencia pelo nome o Secret de plataforma resultante, e o compilador conectou a relação sem nunca manter o material:

{
"apiVersion": "external-secrets.io/v1beta1",
"kind": "ExternalSecret",
"metadata": { "name": "oracle-dsn-secret" },
"spec": {
"target": {
"name": "oracle-formatted-dsn",
"template": {
"engineVersion": "v2",
"data": { "ORACLE_DSN": "oracle://admin:{{ .password }}@10.0.5.55:1521/PROD_DB" }
}
},
"data": [
{ "secretKey": "password", "remoteRef": { "key": "arn:aws:secretsmanager:prod/oracle" } }
]
}
}

Elevação de parâmetros. O Aggregate declara um parâmetro tipado e o pipeline de CI ao redor fornece o valor no momento do build por meio dos parameters: da Release — por exemplo, um arquivo que o pipeline grava e que a Release importa com parameters: { $import: ./ci-parameters.yaml }. Esta é a via de escape explícita, e ela torna visível o compromisso: o material agora passa pelo build, então a saída renderizada o carrega e deve ser tratada de acordo.

Desenvolvimento local

O caminho de referência para o desenvolvimento local mantém inalterada a intenção do desenvolvedor e troca o vínculo. O Aggregate continua anexando o mesmo tipo de Feature de credencial; o Manifest local mapeia esse tipo para uma FeatureRecipe local em vez da baseada no armazenamento. O compilador continua sem buscar nada — a FeatureRecipe local simplesmente entrega a sintaxe nativa do provider que o runtime local resolve: para o Compose, uma referência de variável como ${SECRET_NAME} escrita no ambiente do serviço, que o Docker Compose substitui a partir do ambiente do shell ou de um arquivo .env quando a stack é iniciada. Trocar de ambiente é uma edição do Manifest.

Governança de dados em torno de credenciais

Aggrega não modela esquemas de dados — linhas, colunas e arquivos são questões da aplicação. Ele modela a identidade de governança dos dados com rótulos, e a convenção da biblioteca padrão é:

  • Os dados residem em componentes cujo rótulo de ontologia os marca como stateful ou semelhantes a recursos (component.aggrega.ai/type: stateful-server, resource). Um message broker que guarda payloads enfileirados também é um deles: ele carrega stateful-server quando possui o próprio disco e resource quando a Release conecta um hospedado, e a prateleira messaging sob a qual ele é navegado é o eixo separado component.aggrega.ai/category.
  • compliance.aggrega.ai/data-class (public, internal, restricted) dá a esses dados uma identidade semântica. A convenção fixa a chave e seus valores, não quais componentes a carregam: nenhum Component da biblioteca padrão a carrega, porque a classe dos dados que um componente guarda é uma afirmação sobre como uma organização usa o componente, e não uma propriedade do produto, então uma organização a declara em seus próprios Components. É um rótulo comum: seletores de rótulos o avaliam, e um plugin de governança que um operador anexa pode lê-lo e rejeitar um build. O próprio compilador não o interpreta e não coloca nenhuma classe acima de outra — quais classes existem e como se ordenam são configurações próprias da política anexada, como em ../language-reference/examples/policy-data-class-route/.

data-class e sensitive são dois eixos, e fundi-los perde informação. Eles ficam lado a lado e é fácil confundi-los com uma única superfície, então mantenha a distinção:

compliance.aggrega.ai/data-classsensitive
Formagraduado — public / internal / restrictedbooleano
Granularidadeum nó inteirouma folha de esquema, ou um slot de anexo
Dizque identidade de governança têm os dados que um componente guardaque esse dado é material secreto, ou que esse ponto de vinculação o manipula
Escrito comoum rótulo em metadata.labelsuma palavra-chave em uma declaração

Nenhum substitui o outro: forçar a sensibilidade no rótulo graduado imporia uma ordem a um fato que não tem nenhuma, e forçar uma classe de dados em uma folha imporia uma granularidade que a classificação não tem. Uma entidade pode carregar os dois, e um componente que guarda dados restricted cujo slot de credencial é declarado sensitive está afirmando duas coisas verdadeiras distintas. As palavras-chave de folha e de slot são ensinadas em ../language-reference/vocabulary/compact-form-authoring.md “Declarar uma folha como sensível” e ../language-reference/entities/component.md “Declarar um slot como sensível”.

A criptografia em repouso fica deliberadamente fora da intenção do desenvolvedor e fora do compilador. Ela pertence à Recipe de Ops do componente stateful e ao plugin de renderização que lê os rótulos do nó e emite a configuração de armazenamento criptografado. Esse posicionamento é uma orientação de design sobre onde essa preocupação pertence — o compilador não verifica se alguma Recipe a respeita.

O que é distintivo aqui, e o que não é

Vale a pena declarar o posicionamento público de forma simples e restrita, para que o leitor possa se calibrar.

Distintivo: o contrato do socket é publicado, não declarado inline. O contrato que uma credencial precisa satisfazer — o slot, sua allowlist de entrega, seu seletor de labels — é escrito na entidade de catálogo por quem a publicou, e fica em um catálogo mantido por terceiros. Um consumidor não descreve o contrato inline em sua própria configuração; ele preenche um contrato que outra pessoa publicou, e o compilador verifica o preenchimento em relação a essa declaração publicada. O consumidor e o autor do contrato são pessoas diferentes, que trabalham em repositórios diferentes, com cadências de lançamento diferentes.

Distintivo: o preenchimento é restringido por seletor de labels. Um slot pode dizer que tipo de coisa pode preenchê-lo (selector: "feature.aggrega.ai/kind=secret") em vez de nomear uma implementação específica. A verificação é uma avaliação de conjunto de labels, de modo que uma entidade pode aceitar uma família de preenchimentos dos quais nunca ouviu falar, e um novo preenchimento se torna elegível ao carregar os labels certos.

Não distintivo: o mapeamento de injeção. Mapear “este nome de variável de ambiente local recebe aquele valor produzido” é um padrão bem conhecido; várias ferramentas de configuração e de implantação expressam a mesma ideia em sua própria sintaxe. A versão do Aggrega é um mapeamento avaliado antecipadamente e mesclado em um canal de entrega, mas a ideia é do ecossistema, não nossa.

Não distintivo: a geração estática antecipada. Gerar artefatos de implantação estaticamente a partir de uma descrição de nível mais alto, sem acesso a um cluster ativo no momento da geração, não é uma invenção do Aggrega. Outras ferramentas fazem isso, e já faziam antes de o Aggrega existir. O que o Aggrega acrescenta é a camada de contratos publicados acima disso, não a geração estática em si.

Não é uma fronteira de segurança. Nada neste capítulo é um mecanismo de confidencialidade. O modelo de credenciais é um modelo de cabeamento: ele decide de onde vem um ponteiro ou um valor, quem pode restringi-lo e como ele chega a um contêiner. Proteger o material é tarefa do cofre de segredos, do cluster e do pipeline que manipula a árvore renderizada.

Referências cruzadas