Modelo de credenciais
Uma única família de anexações
Uma credencial no Aggrega é uma Feature. É anexada na mesma superfície, sob a mesma palavra-chave e com a mesma forma que qualquer outra Feature. Aqui, o programador anexa a credencial da base de dados no Aggregate, escrevendo o seu localizador em values:
# the Aggregate — its parameters and the components' own values left outspec: 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, na Release, um alvo de recolha de métricas, porque todas as entradas que core/prometheus-exporter recebe — a porta, o caminho e o intervalo da recolha — são operacionais, pelo que são escritas em infra:
# the Release — the api's own infra and the db's entry left outspec: components: api: features: metrics: # an operational Feature type: core/prometheus-exporter:1.0.0 infra: port: http # the named port of the api's ServiceExiste uma palavra-chave de anexação (features:), uma forma de contexto de renderização (.features.<name>, e a mesma forma sob uma ligação, .context.uses.<alias>.features.<slot>, para uma anexação escrita numa ligação), uma ordem de execução e um conjunto de coordenadas de saída — para uma anexação num componente, o componente a que está anexada e depois o nome sob o qual está anexada, quer a disposição do destino represente estes dois elementos como um diretório <component>--<instance>/ ao lado do diretório do próprio componente, quer como um prefixo de nome de ficheiro <component>--<instance>--. O que varia entre anexações é o que produzem — um valor injetado, um recurso referenciável, um sidecar, uma identidade cloud — e não a superfície em que são declaradas.
Uma Feature de credenciais transporta a etiqueta feature.aggrega.ai/kind: secret na sua entidade de catálogo. Essa etiqueta é metadado descritivo: diz a um leitor, a um site de catálogo e a um seletor de etiquetas para que serve a Feature. Nenhum ramo do compilador a lê, e nenhum comportamento depende dela. O comportamento vem da FeatureRecipe para a qual um operador mapeia o tipo da Feature.
O modelo mental numa frase: existe um único tipo de anexação; o que varia é o que produz.
Slots e anexações 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 deliveryUma anexação cujo nome de instância corresponde a um slot declarado preenche esse slot. Uma anexação com qualquer outro nome é uma anexação livre: a entidade não a pediu, e é renderizada ao lado de tudo o que a entidade pediu. O esquema gerado para um slot declarado permanece aberto, pelo que declarar um slot nunca fecha o bloco a anexações livres. Há uma forma que interrompe a compilação em vez de ser renderizada: uma anexação escrita no próprio componente cuja Feature satisfaz o selector de um slot que nada vincula aí, o que é um preenchimento escrito com o nome errado e não uma anexação 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 blackbox: a canalização da própria Recipe entrega-o (o controloexistingSecretde um chart, por exemplo), e um Workload não o pode referenciar a partir de um contentor.selector— uma cadeia de seletor de etiquetas que as etiquetas da Feature que preenche o slot têm de satisfazer. É aqui que a etiquetakind=secretmostra o seu valor: um autor de entidade que queira um slot preenchido apenas por uma credencial di-lo com um seletor, e a verificação é uma avaliação de conjunto de etiquetas 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-se durante a análise estática quando nada o vincula, com um diagnóstico que indica o slot e o tipo de componente que o declarou. A exigência é avaliada contra o conjunto de anexações com que o componente fica depois de todos os âmbitos terem descido em cascata, pelo que uma anexação contribuída acima do componente vincula o slot exatamente como um preenchimento criado no componente.
Uma segunda superfície exprime uma exigência diferente. A anotação repetível de Component features.aggrega.ai/requiredType.<label> declara um mandato de presença: pelo menos uma anexação tem de transportar o tipo de Feature que a anotação nomeia, com qualquer nome e em qualquer âmbito, e um mandato que nada satisfaz interrompe a compilação durante a mesma análise estática, com o 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 pergunta se alguma anexação transporta um tipo nomeado —, pelo que uma entidade que precisa de que a 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 não garante
Esta é a secção que sustenta tudo o resto. O Aggrega é um compilador ahead-of-time, e as suas garantias são mais restritas do que a palavra «segredo» convida o leitor a supor.
O compilador nunca resolve uma credencial. Não se autentica numa API cloud, não lê um cofre e não obtém material durante aggrega build. Os values e o infra de uma anexação de credencial viajam pelo grafo e até ao contexto de renderização como escalares opacos, e uma FeatureRecipe renderiza-os em qualquer artefacto que a plataforma de destino espere. A resolução acontece mais tarde, no cluster ou no gestor de estado de IaC, contra aquilo para que o artefacto renderizado aponta.
O compilador não consegue distinguir um ponteiro de um valor material. É agnóstico em relação ao que um escalar significa (ver 05-invariants.md). Uma anexação de credencial cujo localizador transporta uma coordenada de cofre (path, key, um ARN) renderiza uma referência a essa coordenada; uma anexação de credencial cujo localizador transporta o próprio material renderiza o material, tal como está, no ficheiro de saída. Ambos são legais, e o compilador trata-os de forma idêntica porque não tem forma de os distinguir.
Assim, 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 credenciais está anexada e do que o seu autor lá colocou, o programador em
valuesou o operador eminfra.
Duas consequências que vale a pena interiorizar:
- Uma árvore de artefactos renderizados é tão sensível como a sua anexação que mais material transporta. Tratar
dist/em conformidade: se alguma anexação transportar material inline, a árvore contém material. - As famílias
core/secret-valueecore/referenced-secretdo próprio catálogo incluem formas que aceitam um valor diretamente. Existem porque as implantações reais precisam de um caminho de desenvolvimento local, e são honestas quanto a isso: os exemplos trabalhados fornecidos usam marcadores de posição óbvios (dev-root-pw-change-me) precisamente para que o material num exemplo renderizado não seja, visivelmente, uma credencial real. Para uma implantação que não pode transportar material, anexar uma Feature de credenciais apoiada num cofre cuja FeatureRecipe emita um recurso de obtenção (umExternalSecret, um recurso personalizado de obtenção do cofre, uma referência de segredo nativa do fornecedor), em vez de uma que emita dados.
A convenção da biblioteca padrão é que uma credencial é pedida como anexação em vez de ser escrita num bloco values, para que trocar um preenchimento de desenvolvimento local por um apoiado num cofre seja uma alteração ao Manifest e não uma edição da intenção do programador. É 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, segundo a secção acima — mas um autor consegue, e pode dizê-lo. No Aggrega, a sensibilidade é uma anotação numa declaração: o autor de uma entidade de catálogo declara o que transporta material secreto, e o compilador deriva o resto dessa declaração e das ligações que já construiu. Nada é inferido de um valor, e nada é adivinhado a partir do nome de um campo.
É criada exatamente em dois sítios, e estes transportam afirmações genuinamente diferentes.
Numa folha de esquema — este dado é material secreto. Uma folha 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 materialNum slot de anexação — o que quer que vincule este ponto trata material secreto. Um slot 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 um duplicado de conveniência um do outro, e a forma de credencial referenciável é o caso trabalhado que mostra porquê. 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 Kubernetes é público, e a chave dentro dele também. Ambos são renderizados em claro no manifesto do próprio consumidor como um secretKeyRef. No entanto, o slot que essa credencial preenche trata indiscutivelmente material secreto. Um nível sozinho não consegue exprimir ambos os factos: marcar os localizadores publicados para que o slot seja lido como sensível afirmaria algo falso sobre eles e levaria esse erro a todo o lado onde a declaração é lida.
A partir dessas duas declarações, o compilador deriva, por anexação, se a anexação trata material declarado como sensível — verdadeiro quando a Feature anexada declara uma folha sensível, ou quando o slot que vincula declara um, bastando qualquer um dos dois. Deriva isto a partir da anexação tal como fica depois de todos os âmbitos de criação se terem fundido, pelo que uma declaração de âmbito mais amplo que um preenchimento mais restrito substituiu não persiste, e a exigência de um slot aplica-se ao preenchimento que efetivamente prevaleceu. Uma Feature de credenciais que não declara nenhuma folha sensível — porque o motor de destino detém o material e o autor não escreve nada — continua a produzir uma anexação sensível quando vincula um slot sensível.
O limite, dito com clareza
A palavra «sensível» convida o leitor a esperar um mecanismo de confidencialidade. Não o é, e a garantia é mais restrita do que o nome sugere em cinco aspetos específicos:
- Não cifra. Nada é envolvido, selado ou transformado.
- Não altera o veredicto da compilação, com uma exceção. Nenhuma compilação se interrompe porque falta uma declaração, e um catálogo cujas entidades de credenciais não tenham nenhuma declaração compila com êxito. Nenhum valor é aceite ou rejeitado por existir uma declaração, exceto quando o
valuesMappingde uma Recipe ou FeatureRecipe CloudFormation lê um valor declarado como sensível para preencher os parâmetros de um template obtido: aí, todos os literais que o mapeamento vincula são recusados, pelo que acrescentar uma declaração pode transformar uma compilação que tinha êxito numa que se interrompe — ver 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, acrescentar declarações a um catálogo existente deixa todas as compilações que tinham êxito a continuar a ter êxito. - Não garante que a saída renderizada esteja livre de material. A garantia enunciada acima mantém-se: se um artefacto transporta material depende de qual preenchimento foi anexado e do que o seu autor lá colocou. Um valor declarado como sensível fornecido inline é renderizado exatamente como um não declarado, onde quer que a compilação o renderize — a recusa do CloudFormation acima trava um literal em vez de o renderizar, e uma função intrínseca é escrita tal como foi dada, texto incluído — e
dist/continua tão sensível como a sua anexação que mais material transporta. - Não impõe um mecanismo de entrega. Uma declaração não consegue converter um valor inline numa referência a um cofre, e não restringe o que a allowlist
injectde um slot permite. Impor a entrega significaria emitir um recurso que o autor nunca declarou, que é precisamente o que o invariante da ausência de infraestrutura fantasma proíbe — ver 05-invariants.md. - Não altera nenhum byte renderizado na maioria dos destinos, e nesses nunca alterará. Dois caminhos de renderização fornecidos atuam sobre a declaração naquilo que produzem (os fornecedores Helm, Helm-Chart e Compose também a leem, apenas para manter um valor marcado fora do texto de uma falha): o fornecedor Terraform marca a entrada de um módulo incorporado que transporta material declarado como sensível com o próprio atributo de sensibilidade do Terraform — ver language-reference/providers/terraform.md «Entradas de módulo declaradas como sensíveis»; quando o
valuesMappingde uma Recipe, ou o da FeatureRecipe de uma Feature anexada a um componente, inventa os nomes das entradas, nenhuma entrada pode transportar o atributo e a compilação imprime um aviso a dizê-lo, ver A declared-sensitive value reaches the target through a values mapping (Um valor declarado como sensível chega ao destino através de um mapeamento de valores) — e o fornecedor CloudFormation recusa as vinculações literais descritas acima, o que interrompe uma compilação em vez de alterar os seus bytes. Em todos os outros casos, acrescentar declarações a um catálogo existente deixa todos os artefactos renderizados idênticos. O limite para além disso é estrutural, e não uma questão do que já foi construído: uma declaração só pode alguma vez chegar a um artefacto renderizado numa plataforma de destino cuja própria linguagem tenha uma noção de sensibilidade — uma declaração que essa plataforma compreende, que rege a forma como apresenta um valor e não a forma como o armazena. Num destino sem essa noção, não há nada em que uma declaração se possa tornar, pelo que uma entrada idêntica é renderizada de forma idêntica, com ou sem ela, permanentemente.
Uma coisa que uma declaração altera é o que a CLI imprime para uma pessoa ler. Um valor declarado como sensível é substituído por um marcador de posição fixo no rastreio por passagem e nas disposições de inspect, mantendo a chave e retendo apenas o valor. É uma decisão de apresentação em superfícies que ninguém implanta, e os artefactos renderizados são emitidos tal como estão 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 transporta material de uma chave provides declarada —, a substituição é exata. Um valor que um template já escreveu noutro documento não tem nenhuma chave onde fazer a substituição, porque um documento renderizado não regista nada sobre a declaração de onde veio cada carácter, e recuperar isso significaria inspecionar o conteúdo. Assim, o rastreio mostra esse documento avaliando o mesmo template uma segunda vez contra um contexto cujos dados declarados como sensíveis já se leem como o marcador de posição, e identifica o resultado como uma re-renderização e não como o que foi renderizado: um template que se ramifica com base no conteúdo de um valor renderiza de forma diferente contra um marcador de posição, e um dado que nenhuma declaração nomeia passa inalterado. As superfícies, essa identificação e os seus limites estão em language-reference/vocabulary/compact-form-authoring.md «Declarar uma folha como sensível».
Assim, a formulação honesta do que este eixo compra:
Uma declaração de sensibilidade é uma afirmação da intenção do autor que viaja com a entidade, para que as ferramentas e as políticas possam raciocinar sobre o que uma implantação trata. Não é um mecanismo que a proteja.
Proteger o material continua a ser tarefa do cofre de segredos, do cluster e da pipeline que trata a árvore renderizada — como diz o resto deste capítulo.
Como uma credencial chega a um contentor
Duas formas de entrega, escolhidas pela FeatureRecipe da anexação e não pelo programador:
Valor injetado. A FeatureRecipe declara um injectMapping e nenhum recurso. A sua saída é fundida em profundidade no pipe de entrega do componente consumidor antes de a Recipe base renderizar, pelo que uma Recipe que leia .context.inject.env.<KEY> recebe o valor. Nada autónomo é emitido.
Duas credenciais entregues sob uma mesma chave interrompem a compilação, indicando ambas as anexações: um mapeamento que escreva uma chave que outra Feature anexada já entregou — através do mapeamento dessa Feature ou do seu próprio bloco inject: — é recusado em vez de fundido, pelo que uma credencial nunca é apresentada no lugar de outra. A regra é a mesma para todas as anexações, onde quer que tenham sido anexadas e quer preencham um slot no componente ou numa ligação. Um mapeamento que substitua uma chave entregue pelo próprio bloco inject: do componente ou por uma das suas ligações é a interceção de que dependem as Features de encaminhamento, e continua a ser legal.
Recurso referenciável. A FeatureRecipe declara um source, workload, artifacts e/ou valuesMapping, pelo que emite um recurso — normalmente um Secret nativo da plataforma. Publica a identidade desse recurso através dos seus provides, e um consumidor lê-a de volta como .features.<name>.provides.name / .provides.key. O nome do próprio recurso é derivado dos mesmos provides publicados, pelo que o nome que o consumidor lê e o nome que o recurso tem são uma única cadeia avaliada, e não duas derivações que possam divergir.
O Workload de uma Recipe consome um preenchimento referenciável através do mapa attachments: de um contentor:
workload: | containers: main: attachments: DB_PASSWORD: from: root_password # a slot the Component declares as: envO sintetizador resolve a referência a partir dos provides publicados do slot — um secretKeyRef Kubernetes para as: env, um volume apoiado num segredo para as: file. O autor da Recipe escreve apenas o nome do slot e o mecanismo.
Uma FeatureRecipe pode fazer ambas as coisas: reescrever o pipe de entrega e emitir um recurso. Pode também declarar uma pipeline de passos Wasm, que são executados para todas as famílias de anexações por igual — uma anexação de credencial pode transformar, a convite, os documentos renderizados do componente anfitrião exatamente como uma anexação operacional.
Quem nomeia a credencial
O localizador de uma credencial — o nome do segredo, a entrada do cofre a obter, o valor a entregar — é escrito por quem o conhece, e esse nem sempre é o programador. Uma ligação que a Release estabelece não tem entrada no Aggregate, e a Release não escreve values em lado nenhum, pelo que uma credencial que obtivesse o seu localizador apenas de values nunca poderia ser nomeada numa dessas ligações, nem em nenhuma anexação que a Release faça.
Por isso, cada Feature de credenciais da biblioteca padrão que transporta o localizador de um chamador — core/referenced-secret, core/referenced-secret-set, core/secret-value e core/secret-provided — aceita-o de qualquer um dos autores: o programador nos values da anexação, no Aggregate, ou o operador no seu infra, na Release. A folha tem um nome, uma forma e uma declaração sensitive: true em ambos os pilares, e cada concretização lê o pilar que a contém. A proibição de values: na Release não é afetada: 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. Uma anexação transporta o localizador num pilar, nunca em ambos e nunca em nenhum. Nenhum esquema de pilar o consegue exprimir, porque cada pilar é validado isoladamente; o bloco assertions de cada Feature consegue, e uma anexação que o viole interrompe a compilação indicando a Feature, a anexação e o componente. Esse é o contrato da entidade do catálogo, mantido da forma como qualquer asserção de Feature o é: 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 o seu pilar — a chave de dados de uma credencial referenciável continua a ser escrita em values, pelo que uma anexação feita apenas pela Release lê o seu valor predefinido — e core/secret-provided continua a entregar apenas através do próprio bloco inject: da anexação, que só o Aggregate escreve e que a anexação de uma ligação nunca transporta.
Partilhar uma credencial entre consumidores
O consumidor pode deter a credencial. Um slot pertence à entidade que precisa da credencial, e essa é muitas vezes o chamador e não aquilo que é chamado: um componente que apresenta uma chave quando contacta outro declara o slot dessa chave na sua própria entidade de catálogo, no socket através do qual contacta, pelo que a chave é detida na ligação em que é apresentada — e nada numa aresta uses obriga o destino a fornecer uma. core/ai-agent/crewai é a forma fornecida — o seu socket model declara um slot credential opcional com o seletor feature.aggrega.ai/kind=secret, inject: [env] e sensitive: true, e um Aggregate preenche-o sob a ligação, em uses.model.<alias>.features.credential. O que os componentes de modelo da biblioteca padrão publicam para um consumidor ler é uma localização de serviço e um nome de modelo, não uma credencial, pelo que a chave que o agente apresenta quando chama esse endpoint é declarada pelo agente e detida na sua ligação. O slot é opcional, mas uma ligação a um modelo que o seu catálogo etiqueta com component.aggrega.ai/hosting: managed e que não transporte nenhuma credencial interrompe a compilação, a menos que os seus próprios values digam que o modelo não precisa de nenhuma, unauthenticated: true — uma asserção que a entidade de catálogo do agente transporta, e que o compilador avalia como avalia qualquer asserção, lendo a etiqueta como uma cadeia. O componente de modelo a que se liga pode deter uma chave própria para os 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: uma anexação vincula um slot pelo nome onde este é declarado, no componente ou na ligação, pelo que preencher um não diz nada sobre o outro.
É essa colocação que faz das duas formas abaixo escolhas de implantação: com o slot no consumidor, uma compilação pode dar a cada consumidor a sua própria chave e outra pode dar a todos a mesma, sem que nenhuma entidade de catálogo mude entre elas.
A mesma entidade de catálogo serve ambas as formas, e é o autor que escolhe qual:
- Por consumidor. Cada consumidor preenche o seu próprio slot com a sua própria anexação de credencial — no componente, ou na sua ligação, quando o slot pertence a um socket. Cada um obtém o seu próprio recurso renderizado.
- Partilhada. Para um slot que um componente declara, uma credencial é anexada uma vez num âmbito partilhado — um subsistema no Aggregate, uma fronteira na Release — e desce em cascata para todos os componentes desse âmbito. Um slot que um socket declara é preenchido por ligação, e nada desce em cascata para uma ligação, pelo que aí a forma partilhada é criada em cada ligação: a credencial de cada ligação lê um mesmo parâmetro. Quando os consumidores têm de referenciar um único recurso físico, esse parâmetro nomeia-o —
core/referenced-secretvinculado à concretização de Secret existente aponta todas as ligações para um Secret pelo nome, e uma credencial gerada é um pedido e muitas referências, como abaixo.
Convém descrever com precisão a renderização da forma partilhada, porque é fácil supor o contrário: uma anexação partilhada renderiza um recurso por consumidor, cada um com o mesmo material proveniente da única declaração. A renderização é feita por componente, e um nome de recurso derivado de {{ .context.instance_id }}-{{ .attachment_name }} difere, portanto, de consumidor para consumidor. O que é partilhado é a declaração única; os recursos emitidos não são deduplicados num só. Um parâmetro lido em cada ligação renderiza da mesma forma sob uma concretização que renderiza um recurso — um por ligação, sendo o nome da anexação o alias da ligação, um ponto e o slot.
Se uma implantação precisar de exatamente um Secret físico que vários consumidores leiam, exprimir isso com uma Feature de credenciais cuja FeatureRecipe é executada no âmbito da fronteira (executionScope: boundary), que renderiza uma vez para a fronteira em vez de uma vez por componente.
Uma chave que ambas as extremidades de uma ligação detêm
Um servidor que verifica uma chave e o componente que o chama detêm cada um essa chave, cada um do seu lado. O servidor detém a chave que verifica num slot do seu próprio Component — core/ai-model/vllm, core/ai-model/tei e core/ai-model/tgi declaram cada um api_key, tal como o modelo e o gateway LiteLLM para a chave a que o LiteLLM chama master key — e a sua Recipe entrega o que quer que preencha o slot como a variável que o servidor lê. O chamador detém a chave que apresenta do seu próprio lado: na ligação em que a apresenta, num slot que o seu socket declara — como o socket model de core/ai-agent/crewai declara credential — ou, quando o seu Component declara a chave em si próprio, nesse slot, para todas as ligações que faz. Nenhuma das extremidades vê as anexações da outra: uma anexação numa ligação recai apenas sobre o chamador, e a saída renderizada de um servidor é a mesma, seja o que for que as ligações que o alcançam transportem. O servidor nunca sabe que chave um chamador detém, e o chamador lê apenas o que o servidor publica — um endereço e um nome de modelo. As duas extremidades estão de acordo 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-keySe se trata de um segredo ou de dois decorre de onde as duas extremidades resolvem segredos. Um fornecedor resolve um segredo por referência dentro de um âmbito de segredos: um namespace Kubernetes em helm, um projeto Compose em compose, a configuração raiz de uma fronteira em terraform e, em cloudformation, uma stack, na conta e na região AWS em que é implantada. Quando ambas as extremidades estão num mesmo âmbito, referenciam um único recurso de segredo. Quando estão em âmbitos diferentes, cada extremidade detém um recurso de segredo próprio, concretizado a partir da mesma entrada do cofre. O Manifest escolhe a concretização de cada extremidade — por tipo de Feature ou, para uma anexação, pelo seu nome, que para a anexação de uma ligação é <alias>.<slot> (local.credential acima). Como um mesmo parâmetro alimenta ambas, as duas concretizações leem origin como o mesmo tipo de localizador: ambas o nome de um Secret, ambas a chave de uma entrada do cofre, ou ambas o próprio valor.
Em helm, com ambas as extremidades num mesmo namespace, vincular core/referenced-secret a helm/k8s-existing-secret e cumprir o parâmetro com o nome de um Secret que esse namespace contém, model-keys, faz com que ambas as extremidades o referenciem pelo nome e não renderiza nenhum Secret. O contentor do servidor transporta:
- name: VLLM_API_KEY valueFrom: secretKeyRef: name: model-keys key: api-keye a Recipe do router lê o mesmo nome e a mesma chave a partir da sua ligação, em .context.uses.local.features.credential.provides. Com as duas extremidades em namespaces diferentes, vinculá-lo a helm/k8s-external-secret e cumprir o parâmetro com a chave de uma entrada do cofre dá a cada extremidade um ExternalSecret próprio, no seu próprio namespace, ambos a obter essa mesma entrada. Em compose, ambas as extremidades transportam a mesma referência ${VAR}, que o Docker Compose substitui a partir do ambiente com que o projeto é iniciado. Esta colocação é uma convenção que o catálogo da biblioteca padrão segue; o compilador não compara nada entre as duas extremidades.
Uma chave serve todos os chamadores. O vLLM, o TEI e o TGI verificam cada um uma única chave, pelo que todos os chamadores apresentam a mesma chave e o servidor não consegue distinguir um chamador de outro, por muitas ligações que o alcancem. Esse é um limite do próprio servidor. O TGI compara a sua chave sem distinguir maiúsculas de minúsculas, pelo que duas chaves que só diferem nas maiúsculas são, para ele, uma só chave. O modelo e o gateway LiteLLM aceitam também as chaves que eles próprios emitem, enquanto a sua base de dados de contabilidade estiver anexada.
Uma credencial que o destino gera
Quando uma Release não fornece nenhuma credencial, uma entidade de catálogo recorre muitas vezes a uma predefinição de desenvolvimento — um valor inline numa Recipe, uma predefinição no parâmetro de um módulo. Esse valor é o mesmo para todos os leitores do catálogo, o que é aceitável para avaliação e para mais nada. core/random-password elimina essa necessidade: ninguém escreve a credencial, porque é o destino que a gera.
A compilação não pode ser o sítio onde a palavra-passe é criada. A sua saída é uma função pura da entrada e nunca transporta o valor de um segredo, pelo que uma palavra-passe gerada no momento da compilação mudaria em cada compilação e ficaria nos ficheiros renderizados. Em vez disso, a FeatureRecipe renderiza um pedido — um recurso gerador que nomeia o recurso de segredo que preenche — e o destino gera o valor no momento da implantação:
- em
helm, um controlador no cluster: o gerador de palavras-passe do External Secrets Operator, reconciliado através de umExternalSecret, ou o controlador kubernetes-secret-generator, que reconcilia umStringSecret; - em
terraform, orandom_passworddo fornecedor random, gerado quando a configuração é aplicada; - em
cloudformation, um segredo do Secrets Manager que gera a sua própria cadeia quando a stack o cria.
Em todos os casos, a saída renderizada nomeia o gerador e o recurso de segredo e não transporta nenhum valor. Isso é uma propriedade do que a compilação tem, não uma proteção que acrescenta: o valor nunca existe até o destino o criar. Onde o destino o guarda depois é com o destino — o Terraform guarda-o no plano e no estado, um cluster num Secret.
O que o destino precisa de ter em execução. Um pedido só é cumprido onde algo o cumpre. Em helm, esse algo é o controlador, e o compilador não consegue inspecionar o cluster para saber se há um em execução, pelo que as FeatureRecipes helm interrompem a compilação, a menos que a Release afirme o pré-requisito com infra.control_plane_present: true na anexação. Em terraform e cloudformation, a aplicação ou a stack geram elas próprias o valor e nada precisa de 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, pelo que nenhuma FeatureRecipe concretiza core/random-password aí, e uma compilação que o vincule em compose interrompe-se por falta de uma. Uma Release que vise compose fornece a sua credencial através de core/secret-value, normalmente como uma referência a variável que o Docker Compose substitui quando a stack arranca.
Como um consumidor o lê. core/random-password publica os mesmos provides.name e provides.key que core/referenced-secret e transporta a mesma etiqueta feature.aggrega.ai/kind: secret, pelo que um slot que selecione 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 partilham uma. Um gerador produz um valor novo para cada pedido, pelo que a regra de partilha da secção anterior se aplica com mais rigor: uma credencial gerada anexada num âmbito partilhado — ou em cada consumidor — renderiza um pedido por consumidor, e cada pedido gera uma palavra-passe diferente, que uma base de dados e os seus clientes não conseguem usar. Uma credencial gerada partilhada por vários consumidores exprime-se como um pedido e muitas referências: core/random-password num componente, com o seu valor name a fixar o Secret que preenche, e core/referenced-secret nos outros, vinculado à concretização de Secret existente e apontado para esse mesmo nome. Escritos a partir de um mesmo parâmetro, os dois não podem divergir, e a renderização contém exatamente um pedido que todos os consumidores referenciam.
core/random-password não é core/generated-secret. Essa Feature entrega uma credencial a um motor que já detém todo o seu ciclo de vida — uma base de dados gerida, um controlador de base de dados — e não renderiza nada. core/random-password renderiza o próprio pedido, para uma carga de trabalho cuja Recipe espera receber uma credencial.
Precedência das anexações
Uma anexação pode ser declarada em vários âmbitos ao mesmo tempo. A titularidade de um campo disputado resolve-se por três regras, aplicadas por esta ordem:
- Origem. Um campo criado explicitamente prevalece sobre um contribuído pela expansão orientada por anotações, seja qual for o âmbito de onde veio cada um.
- Autoridade de composição. Uma declaração no Aggregate que está a ser implantado prevalece sobre uma dentro de um Aggregate que este compõe, mesmo quando o documento composto a declarou no âmbito mais restrito.
- Especificidade. Dentro de um mesmo nível de criação, o âmbito mais restrito refina o mais amplo campo a campo: um preenchimento ao nível do componente substitui uma anexação com o mesmo nome de instância ao nível do subsistema ou da fronteira apenas nos campos que menciona, e os campos que omite mantêm os valores do âmbito mais amplo.
O lado do programador fornece values e o lado do operador fornece infra, pelo que os dois nunca disputam o mesmo campo. Uma Feature de credenciais que recebe o seu localizador de qualquer dos lados declara-o como dois campos, um por pilar, e a sua própria asserção recusa uma anexação que transporte ambos, pelo que também aí a precedência não tem nenhum empate a desfazer. A precedência rege apenas os valores dos campos; não reordena a avaliação, que segue a sequência de cascata em 10-compilation-pipeline.md.
Charts legados que exigem uma cadeia formatada
Por vezes, um chart quer uma única cadeia de ligação com material incorporado — oracle://admin:PASSWORD@HOST:1521/DB. Um compilador ahead-of-time não consegue construir essa cadeia a partir de uma coordenada de cofre, porque nunca detém o material. Dois caminhos suportados:
Templates do lado do cluster. A FeatureRecipe de credenciais emite um recurso que formata a cadeia no cluster, usando os próprios templates do operador do cofre. A aplicação referencia depois pelo nome o Secret de plataforma resultante, e o compilador estabeleceu a relação sem nunca deter 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" } } ] }}Parameter Hoisting. O Aggregate declara um parâmetro tipado e a pipeline de CI envolvente fornece o valor no momento da compilação através dos parameters: da Release — por exemplo, um ficheiro que a pipeline escreve e que a Release importa com parameters: { $import: ./ci-parameters.yaml }. Esta é a via de escape explícita, e torna visível o compromisso: o material passa agora pela compilação, pelo que a saída renderizada o transporta e tem de ser tratada em conformidade.
Desenvolvimento local
O caminho de referência para o desenvolvimento local mantém a intenção do programador inalterada e troca a vinculação. O Aggregate continua a anexar o mesmo tipo de Feature de credenciais; o Manifest local mapeia esse tipo para uma FeatureRecipe local em vez da apoiada num cofre. O compilador continua a não obter nada — a FeatureRecipe local limita-se a entregar sintaxe nativa do fornecedor que o runtime local resolve: no Compose, uma referência a variável como ${SECRET_NAME} escrita no ambiente do serviço, que o Docker Compose substitui a partir do ambiente da shell ou de um ficheiro .env quando a stack arranca. Trocar de ambiente é uma edição do Manifest.
Governação de dados em torno das credenciais
O Aggrega não modela esquemas de dados — linhas, colunas e ficheiros são preocupações da aplicação. Modela a identidade de governação dos dados com etiquetas, e a convenção da biblioteca padrão é:
- Os dados vivem em componentes cuja etiqueta de ontologia os marca como com estado ou semelhantes a recursos (
component.aggrega.ai/type: stateful-server,resource). Um message broker que contém payloads em fila também é um deles: temstateful-serverquando é dono do seu disco eresourcequando a Release liga um alojado, e a prateleiramessagingem que é listado é o eixo separadocomponent.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 os seus valores, não os componentes que a transportam: nenhum Component da biblioteca padrão a transporta, porque a classe dos dados que um componente contém é uma afirmação sobre a forma como um parque usa o componente e não uma propriedade do produto, pelo que um parque a declara nos seus próprios Components. É uma etiqueta comum: os seletores de etiquetas avaliam-na, e um plugin de governação que um operador anexe pode lê-la e rejeitar uma compilação. O próprio compilador não a interpreta e não classifica nenhuma classe acima de outra — que classes existem e como se ordenam são definições da própria 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. Estão lado a lado e é fácil confundi-los com uma única superfície, por isso convém manter a distinção:
compliance.aggrega.ai/data-class | sensitive | |
|---|---|---|
| Forma | graduada — public / internal / restricted | booleana |
| Granularidade | um nó inteiro | uma folha de esquema, ou um slot de anexação |
| Diz | que identidade de governação têm os dados que um componente contém | que este dado é material secreto, ou que este ponto de vinculação o trata |
| Criado como | uma etiqueta em metadata.labels | uma palavra-chave numa declaração |
Nenhum substitui o outro: forçar a sensibilidade na etiqueta graduada imporia uma ordenação a um facto que não tem nenhuma, e forçar uma classe de dados numa folha imporia uma granularidade que a classificação não tem. Uma entidade pode transportar ambos, e um componente que contém dados restricted cujo slot de credencial é declarado sensitive está a afirmar duas coisas verdadeiras e separadas. As palavras-chave de folha e de slot são explicadas em ../language-reference/vocabulary/compact-form-authoring.md «Declarar uma folha como sensível» e em ../language-reference/entities/component.md «Declarar um slot como sensível».
A cifragem em repouso está deliberadamente fora da intenção do programador e fora do compilador. Pertence à Recipe de Ops do componente com estado e ao plugin de renderização que lê as etiquetas do nó e emite a configuração de armazenamento cifrado. Essa colocação é uma orientação de design sobre o lugar a que a 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 enunciar o posicionamento público de forma clara e restrita, para que o leitor possa calibrar.
Distintivo: o contrato do socket é publicado, não declarado inline. O contrato que uma credencial tem de satisfazer — o slot, a sua allowlist de entrega, o seu seletor de etiquetas — é criado na entidade do catálogo por quem o publicou, e vive num catálogo que um terceiro mantém. Um consumidor não descreve o contrato inline na sua própria configuração; preenche um contrato que outra pessoa publicou, e o compilador verifica o preenchimento contra essa declaração publicada. O consumidor e o autor do contrato são pessoas diferentes, a trabalhar em repositórios diferentes, com cadências de lançamento diferentes.
Distintivo: o preenchimento é restringido por seletores de etiquetas. Um slot pode dizer que tipo de coisa o pode preencher (selector: "feature.aggrega.ai/kind=secret") em vez de nomear uma implementação específica. A verificação é uma avaliação de conjunto de etiquetas, pelo que uma entidade pode aceitar uma família de preenchimentos de que nunca ouviu falar, e um novo preenchimento torna-se elegível ao transportar as etiquetas certas.
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 exprimem a mesma ideia na sua própria sintaxe. A versão do Aggrega é um mapeamento avaliado antecipadamente e fundido num pipe de entrega, mas a ideia é do ecossistema, não nossa.
Não distintivo: a geração estática ahead-of-time. Gerar artefactos 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-no, e faziam-no antes de o Aggrega existir. O que o Aggrega acrescenta é a camada de contratos publicados por cima 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 ligações: decide de onde vem um ponteiro ou um valor, quem o pode restringir e como chega a um contentor. Proteger o material é tarefa do cofre de segredos, do cluster e da pipeline que trata a árvore renderizada.
Referências cruzadas
- 05-invariants.md — os invariantes ahead-of-time e do string pipe em que este capítulo assenta.
- 10-compilation-pipeline.md — onde a resolução de anexações e a geração de recursos se situam na pipeline.
- ../language-reference/entities/component.md — a criação de slots
featuresSchema, incluindo a declaraçãosensitiveao nível do slot, a palavra-chaverequirede o contraste ponto por ponto entre um slot e um mandato de presença. - ../language-reference/vocabulary/compact-form-authoring.md — a palavra-chave
sensitiveao nível da folha, onde a declaração é lida, e a assimetria deparameters:. - ../language-reference/entities/workload.md — o mapa
attachments:do contentor e as suas regras de validação. - ../language-reference/examples/04-secrets.md — a lista de verificação de criação e exemplos trabalhados transparentes / blackbox.
- ../language-reference/examples/05-credential-features.md — as famílias de Feature de credenciais e um percurso de ponta a ponta.
- ../language-reference/examples/model-api-key-sharing/ — um slot de credencial que o socket de um agente declara, preenchido em cada ligação de três formas a partir de uma única entidade de catálogo: uma chave por ligação, um Secret que todas as ligações referenciam e uma predefinição partilhada que uma ligação substitui, com a saída renderizada de cada forma.