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

provides, inject, uses

O contrato de injeção e o mapa pré-resolvido

Como o Aggrega é um compilador estático de compilação antecipada (AOT), nenhum dado flui para trás a partir da infraestrutura em execução durante a compilação. É mecanicamente impossível o compilador obter ativamente uma credencial física (como um segredo da AWS) e passá-la «de volta» ao ambiente do contentor do Programador.

Em vez disso, a plataforma assenta na verdadeira inversão de controlo. Quando um programador escreve inject: { env: [{ in: ORACLE_PASSWORD, from: "password" }] }, não está a iniciar uma obtenção de dados; está a ditar um contrato estrito à infraestrutura.

  1. A intenção (Domínio 1): O Programador declara uma interface abstrata: «Preciso de um segredo. Não sei onde está. Basta injetá-lo no meu ambiente como ORACLE_PASSWORD, mapeado para a chave password do catálogo.»
  2. A transferência do compilador (na renderização): O compilador Go pega na entrada { in: ORACLE_PASSWORD, from: "password" } e entrega-a à Recipe de Ops. Nenhum segredo físico é obtido.
  3. A saída do Plugin (Domínio 3): O pipeline Wasm da FeatureRecipe de credenciais gera os artefactos precisos e interligados exigidos pela infraestrutura de destino. Por exemplo, no Kubernetes, produz o CRD ExternalSecret (que instrui o cluster a obter os dados do vault) E executa um JSONPatch no Pod de destino para mapear o Secret K8s local resultante especificamente para a variável de ambiente "ORACLE_PASSWORD" pedida pelo programador.
  4. A realidade em tempo de execução: Em tempo de execução, um operador no cluster limita-se a executar estes artefactos gerados—obtendo a credencial e montando-a fisicamente no contentor—, desacoplando completamente a mecânica física de segurança do compilador AOT.

Para entregar esta realidade física à aplicação sem violar a separação de responsabilidades, o Aggrega utiliza o contrato de injeção. No entanto, este contrato distingue estritamente entre o código de aplicação personalizado e a infraestrutura comercial pronta a usar (COTS):

  • White-Box (código personalizado): O componente é um worker genérico (por exemplo, um agente Python personalizado). O compilador Go e a Recipe de Ops não fazem ideia de que variáveis o script personalizado do programador espera. Por isso, o Programador dita a entrega através do bloco inject: sempre que o código leia nomes que a sua Recipe não entrega por predefinição — tanto para dependências entre componentes (através de uses[].inject com from: a referenciar os provides do destino) como para os valores próprios do componente (através de inject ao nível do componente com literais value: ou from: a referenciar os seus próprios provides). Os mecanismos permitidos são declarados por superfície, e as duas declarações são separadas: os valores próprios do componente são regidos pela allowlist spec.inject (por exemplo, inject: ["env", "file"]), enquanto uma aresta uses: é regida pela allowlist do socket através do qual está ligada, spec.usesSchema.<socket>.inject. Ditar um mecanismo que a allowlist aplicável não indica interrompe a compilação em qualquer uma das superfícies.
  • Black-Box (computação empacotada): O componente é um sistema fechado (por exemplo, Redis, um API Gateway gerido). A Recipe de Ops já sabe exatamente como o sistema consome os seus dados. Por isso, a entidade de catálogo do Component omite a allowlist, o que proíbe o ditado por completo em vez de o restringir — omitir spec.inject proíbe o self-inject ao nível do componente, e um socket declarado sem uma allowlist inject: proíbe qualquer bloco inject: numa aresta ligada através dele. O Programador limita-se a fornecer o destino da dependência através de uses, e a plataforma trata da ligação interna de forma nativa através do valuesMapping da Recipe.

A regra de endereçamento determinístico (física da rede interna) O pipe .context.uses do Aggrega injeta dinamicamente cadeias de destino nos contentores em tempo de compilação. Como o compilador Go central é totalmente agnóstico em relação à rede física, o que conta como cadeia de endereço válida depende inteiramente de um contrato social mantido por Platform Ops, e não de uma função do compilador — o compilador canaliza qualquer cadeia de ponteiro determinística que a Recipe de Ops tenha produzido para o contexto de template a jusante, sem a interpretar.

A regra: a Recipe de Ops tem de exportar um ponteiro de endereço determinístico e estável. O fornecedor não calcula IPs. Em vez disso, a Recipe de Ops do destino deveria formular uma cadeia previsível e expô-la através do seu contrato provides: (por exemplo, publicando provides.internal_host: "http://agent-b.namespace.svc.cluster.local" no Kubernetes, ou uma cadeia de interpolação como "${module.db.endpoint}" no Terraform, em que o módulo declara um output correspondente para o valor).

Depender do compilador para obter IPs dinâmicos pós-aprovisionamento viola diretamente o modelo de execução AOT. Como o compilador avalia a topologia antes de a nuvem aprovisionar qualquer computação real, não pode fisicamente obter dados que ainda não existem. Se um serviço exigir um IP aleatório que só é gerado depois de a computação arrancar, o compilador não o pode obter fisicamente. A única tarefa do compilador é canalizar a cadeia de ponteiro determinística fornecida pela Recipe de Ops, tal como está, para as variáveis de ambiente do contentor chamador, deixando a resolução final para o DNS do cluster ou para o gestor de estado de IaC ativo.

Impor nativamente o endereçamento determinístico resolve as dependências cíclicas (por exemplo, o Agente A delega no Agente B, e o Agente B delega de volta no Agente A). Como o URL estável ou o ponteiro de IaC é calculável como cadeia antes de qualquer um dos contentores arrancar efetivamente, o compilador liga os dois agentes em segurança, sem introduzir condições de corrida temporais.

(Nota: esta regra também se aplica ao ingress externo. Se uma arquitetura expuser um API Gateway público e exigir que esse URL seja injetado de volta num contentor interno, o compilador Go não consegue obter o URL aleatório gerado pela nuvem (por exemplo, xyz123.execute-api.aws.com) porque este não existe em tempo de compilação. Ops tem de criar a sua Recipe de modo a mapear um domínio personalizado determinístico (por exemplo, api.enterprise.com) ou exportar a cadeia de interpolação nativa de IaC, garantindo que o compilador AOT tem uma referência conhecida para injetar em segurança).

A mecânica de implementação (o catálogo como contrato de API) Para implementar isto sem acoplar fortemente os Programadores a Ops, o Aggrega usa o catálogo da plataforma (Domínio 2) como contrato de API estrito, recorrendo a três camadas distintas de validação:

  1. O schema da Feature de credenciais (etiquetado feature.aggrega.ai/kind: secret): Valida APENAS a consulta ao vault (path, key). É totalmente agnóstico em relação à forma como o contentor consome os dados.
  2. O schema Component (allowlist spec.inject): Impõe a regra Black-Box/White-Box através do campo spec.inject. Se spec.inject estiver presente (por exemplo, inject: ["env", "file"]), o programador pode usar self-inject ao nível do componente com esses mecanismos de entrega. Se spec.inject for omitido, o compilador proíbe estruturalmente o self-inject — os componentes Black-Box dependem inteiramente do valuesMapping da Recipe para a ligação interna. A compilação impõe-no quando resolve o Aggregate, recusando o bloco inject: do componente e indicando o mecanismo, separadamente da validação de conteúdo por pilar em schema:.
  3. O mapa featuresSchema: Definido no catálogo do Component, declara explicitamente os slots de credenciais que o Programador tem de (ou pode) usar. Cada entrada especifica required (predefinição false), a allowlist inject ([] = blackbox, [env, file] = transparente) e description. Como estas chaves são estáveis e garantidas por contrato, o engenheiro de Ops pode confiar diretamente nelas para ditar de forma fiável destinos determinísticos no seu template Go (por exemplo, existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_admin_password }}" no destino helm), exportando explicitamente o sufixo do nome através de .locals — um local não pode ler .context.rendered_name —, pelo que a FeatureRecipe de credenciais a jusante junta as mesmas duas partes e cumpre o requisito sem violar a ordem de execução AOT. Consulte entities/component.md para o design completo de featuresSchema.

A regra de colocação estrita: O mecanismo inject: está disponível em três locais no Aggregate do Programador:

  1. Self-inject ao nível do Component: Como irmão direto de values: numa instância de componente. Injeta os valores literais do próprio componente ou as suas próprias chaves provides no pipe de entrega. Só é permitido se o catálogo do Component declarar spec.inject com os mecanismos correspondentes.
  2. Cross-inject ao nível de uses: Dentro de definições explícitas de destino no bloco uses:. Injeta as chaves provides de um destino de dependência no pipe de entrega.
  3. Inject ao nível de Feature/secret: Como irmão de values: ao anexar funcionalidades e segredos. Injeta as chaves provides resolvidas do próprio anexo — a credencial resolvida de um segredo, ou os valores fornecidos por uma funcionalidade — no pipe de entrega.

As três formas preenchem o mesmo pipe .context.inject. A Recipe lê um único pipe unificado, independentemente de quantas fontes contribuíram para ele.

O schema de inject define enums padrão (env, file, arg) para as ferramentas, mas deixa additionalProperties aberto, pelo que é possível indicar um mecanismo personalizado (por exemplo, ssm_param para o AWS Systems Manager Parameter Store). Um nome está reservado: all é a vista combinada de todos os mecanismos que uma Recipe lê em .context.inject.all, pelo que um bloco inject que dê a um mecanismo o nome all interrompe a compilação no envelope do documento, indicando-o.

Sintaxe das entradas de inject: Num bloco inject, cada mecanismo de entrega — env, file, arg ou um personalizado — é uma lista de entradas, e todas as colocações usam a mesma forma de entrada. É a palavra-chave que uma entrada contém, e não a colocação em que se encontra, que indica o que é a sua cadeia, pelo que uma entrada se lê da mesma forma onde quer que apareça. Um mecanismo escrito como mapa em vez de lista, ou uma entrada que contém ambas as palavras-chave, interrompe a compilação no envelope do documento do Aggregate, indicando o caminho no Aggregate onde a forma está errada.

Palavras-chave das entradas (from: e value:): Cada entrada usa a palavra-chave in para o identificador local — um nome de variável de ambiente, um caminho de ficheiro, uma flag de argumento — mais exatamente um de from: (referência a uma chave de provides) ou value: (cadeia literal). Um from: é resolvido em relação aos provides do nó que a sua colocação indica: os do próprio componente em component.inject, os do destino em uses[target].inject e os do próprio anexo em features[<name>].inject:

Palavra-chaveSignificadoPermitido em component.injectPermitido em uses[].injectPermitido em features[<name>].inject
from:É resolvido em relação a provides✅ provides do próprio nó✅ provides do nó de destino✅ provides do próprio anexo
value:Cadeia literal (suporta templates Go)✅❌ (value: não é válido em uses[].inject; para self-inject, utilize inject ao nível do componente)❌ (value: interrompe a compilação no inject de um anexo; usa-se inject ao nível do componente para self-inject)

Exemplos:

# Component-level self-inject (White-Box custom code)
components:
my-worker:
type: core/python-worker:1.0.0
values:
app_token: "xyz"
inject:
env:
- in: MY_TOKEN
value: "xyz" # Literal value
- in: LOG_LEVEL
value: "debug" # Literal value
- in: CALLBACK_HOST
from: "host" # From own provides (already evaluated)
- in: APP_VERSION
value: '{{"{{"}} .values.app_token }}' # Go template expanding own values
uses:
databases:
my_db:
target: postgres-db
inject:
env:
- in: DB_HOST
from: "host" # Provides key from target
- in: DB_PORT
from: "port" # Provides key from target
- in: DB_URL
from: "dsn" # From target's provides

O template no value: de APP_VERSION começa com {{"{{"}} em vez de {{: todo o texto do Aggregate é lido uma vez como template, para a interpolação de parâmetros, antes de ser executada a resolução do self-inject, e .values não existe nesse momento, pelo que o escape repõe {{ para que a resolução do self-inject o avalie. Consulte Texto que contém as suas próprias chavetas duplas.

Nota específica do Provider (compose). Quando arestas uses: são resolvidas entre nós destinados ao compose, o fornecedor compose deriva entradas depends_on dessas arestas. Essas entradas usam sempre a semântica service_started, independentemente do bloco health: de qualquer destino; condicioná-las ao estado de saúde do destino não está implementado. Consulte providers/compose.md para as regras de inferência completas.

A regra de colisão de chaves de inject: Um programador que pede a mesma chave de entrega (por exemplo, o mesmo nome de variável de ambiente) a duas fontes diferentes é um erro fatal, não uma fusão. O compilador deteta a colisão e interrompe a compilação:

Fonte AFonte BResultado
component.injectuses[].inject❌ paragem fatal — chave de entrega duplicada
uses[target_A].injectuses[target_B].inject❌ paragem fatal — chave de entrega duplicada
component.injectfeatures[<name>].inject❌ paragem fatal — chave de entrega duplicada
uses[].injectfeatures[<name>].inject❌ paragem fatal — chave de entrega duplicada
features[A].injectfeatures[B].inject❌ paragem fatal — chave de entrega duplicada
component.inject (a mesma chave duas vezes)—❌ paragem fatal — chave de entrega duplicada
injectMapping da FeatureRecipe de features[A]injectMapping da FeatureRecipe de features[B]❌ paragem fatal — chave de entrega duplicada entre dois anexos
features[A].injectinjectMapping da FeatureRecipe de features[B]❌ paragem fatal — chave de entrega duplicada entre dois anexos
component.inject ou uses[].injectinjectMapping da FeatureRecipe✅ Legal — interceção por design: o valor do mapeamento substitui essa entrada

A tabela aplica-se da mesma forma a cada Feature anexada, onde quer que tenha sido anexada — no componente, num subsistema ou numa fronteira da Release, pela expansão de uma anotação, ou numa ligação. O injectMapping de uma FeatureRecipe é renderizado depois de todos os blocos inject: terem feito a entrega, pelo que é sempre a posterior de duas reivindicações: pode reescrever o que o componente ou uma das suas ligações entregou, e pode reescrever o que o bloco inject: do seu próprio anexo entregou, mas uma chave que outra Feature anexada já entregou interrompe a compilação, indicando ambas.

Uma Feature anexada a uma fronteira da Release cuja FeatureRecipe é renderizada uma vez para a fronteira (executionScope: boundary) chega aos componentes que a fronteira contém pela mesma via: o seu injectMapping é executado uma vez para cada um deles, no contexto desse componente, e está sujeito às linhas acima como qualquer outro mapeamento. A ponte do compose que reescreve a variável de anfitrião de um consumidor para que este chegue ao seu destino através do seu gateway é um desses mapeamentos, pelo que outra Feature anexada que tenha entregado a mesma variável interrompe a compilação, indicando ambas.

Para evitar código repetitivo de template Go nas Recipes, o compilador fornece ambos:

  • .context.uses: O mapa enriquecido de arestas topológicas (para lógica complexa, referências a segredos e rastreio da origem).
  • .context.inject: Um dicionário pré-resolvido e achatado no qual o compilador já resolveu todas as fontes de inject (literais de self-inject, referências a provides de self-inject e referências a provides entre componentes) em valores de cadeia finais e, em seguida, aplicou as interceções injectMapping de FeatureRecipe.

O contexto de injeção de estado duplo (segurança contra nulos vs. pureza da intenção) Ao gerar configurações para os Modificadores (a FeatureRecipe associada a qualquer anexo, de credenciais ou não), o compilador tem de equilibrar a segurança contra ponteiros nulos para templates Go, o encaminhamento dinâmico de rede e a preservação de um grafo agnóstico em relação a capacidades. Para o conseguir, o compilador fornece ao template um contexto de estado duplo:

  • .inject_raw (a intenção imutável): Representa o bloco inject: do próprio componente exatamente como o programador o escreveu no Domínio 1. É imutável. Se o programador omitiu o bloco, é avaliado como null. Ops utiliza-o especificamente para verificações lógicas (por exemplo, {{ if not .inject_raw }} para aplicar comportamentos alternativos). Por ser imutável, protege os templates de Ops contra falsos positivos se funcionalidades de encaminhamento intercetarem e alterarem o pipe de entrega físico.
  • .context.inject (o pipe pré-hidratado e intercetado): Uma struct paralela, gerada pelo compilador, que representa a realidade física da entrega. Começa como um mapa pré-hidratado (por exemplo, a mapear API_HOST para a cadeia base do destino "backend-instance"). Fundamentalmente, este pipe foi concebido para ser intercetado e fundido em profundidade pelas Features (por exemplo, o encaminhamento de rede) que utilizam o bloco injectMapping. Quando a Recipe base é renderizada, este pipe contém as cadeias totalmente formatadas e fisicamente corretas (por exemplo, um nome de rede completo e correto como "backend-instance.backend-zone.svc.cluster.local"). O seu conteúdo está estruturado como env, file, arg (mais quaisquer mecanismos de entrega personalizados permitidos pelas allowlists de inject do Component), com um dicionário .all pré-fundido que combina todos os mecanismos para uma serialização prática do pipe inteiro.
  • .context.self_inject (Que valor próprio cada nome entrega): Lido do mesmo bloco inject: ao nível do componente que .inject_raw, na forma em que .context.uses.<alias>.inject apresenta os nomes de uma ligação: por mecanismo, cada nome que o programador escreveu corresponde à chave própria do componente que a sua entrada entrega — provides.<key> para uma entrada from:, values.<key> para um modelo value: que lê exatamente um dos valores próprios do componente e nada mais, e uma cadeia vazia para qualquer outro caso (um literal, dois valores, uma leitura de qualquer coisa além dos valores). Permite que uma Recipe que executa a imagem própria do programador trate os seus próprios nomes de variáveis como predefinições — entregando um valor próprio sob o seu nome predefinido apenas quando nenhuma entrada já corresponde a values.<key>, pelo que um programador que muda o nome de um valor mantém todas as outras predefinições. Essa é a convenção do catálogo da biblioteca padrão, não uma regra do compilador; um catálogo empresarial pode entregar os valores próprios dos seus componentes como entender.

Ops utiliza a struct .context.inject exclusivamente para a serialização segura (por exemplo, {{ toJson .context.inject.all }}) e para a geração do encaminhamento, garantindo que a infraestrutura física recebe as coordenadas totalmente resolvidas enquanto a intenção original do programador permanece perfeitamente intacta em .inject_raw.

Exemplo de YAML do programador (mapa granular):

uses:
databases:
my-postgres-cluster:
target: db-main
inject:
ssm_param: # Agnostic injection paradigm (AWS Systems Manager)
- in: MY_DB_HOST # Local identifier
from: "host" # Target provides key

O compilador resolve isto em tempo de compilação (mapeando para cadeias estáticas ou nomes DNS internos) e passa os dois objetos à Recipe:

"context": {
"uses": { ... raw graph ... },
"inject": {
"all": { "MY_DB_HOST": "db-main.internal" },
"ssm_param": { "MY_DB_HOST": "db-main.internal" }
}
}

Configuração com âmbito de ligação (values e infra). Além de entregar os provides de um destino através de inject, uma aresta pode conter a sua própria configuração — definições por ligação que a Recipe consumidora lê do pipe de topologia enriquecido:

  • .context.uses.<alias>.values — escrito pelo programador, declarado na entrada uses detalhada do Aggregate, validado em relação ao valueSchema do socket.
  • .context.uses.<alias>.infra — escrito pelo operador, declarado na Release, validado em relação ao infraSchema do socket.

O socket (usesSchema[<socket>]) é o contrato do Arquiteto sobre que ligações são possíveis e que configuração podem conter; values e infra dividem essa configuração por domínio de autoria, espelhando a divisão values/infra nos componentes. Assim, uma aresta tem dois autores: o programador liga a topologia e ajusta-a com values no Aggregate, enquanto o operador define infra por ligação na Release, dentro dos sockets que o Arquiteto declarou. A Release também pode ligar uma aresta num socket declarado, mas não associado, a um componente existente; não pode redirecionar uma aresta declarada pelo programador — consulte entities/release.md §«Per-edge connection configuration (Configuração de ligações por aresta)».

A configuração por aresta tem âmbito do consumidor: só aparece no contexto do nó que escreveu a aresta (a origem da ligação), nunca no contexto do destino. A saída renderizada do próprio destino é, por isso, invariante em relação aos consumidores que se ligam a ele. Uma Feature anexada ao destino é o único sítio onde as ligações são visíveis: a sua FeatureRecipe lê que componentes usam o destino em .context.used_by — de cada um, a identidade, o socket, os provides publicados, o namespace e a fronteira em que está colocado e, para uma FeatureRecipe que declara que os lê, os factos de renderização que os seus fornecedores comunicaram — nunca os values ou a infra da própria ligação. Uma Feature anexada ao consumidor lê, da mesma forma, o que as renderizações de cada um dos seus destinos comunicaram, na entrada dessa ligação em .context.uses.<alias>.render_facts, onde a sua FeatureRecipe declara que os lê.

Anexos de ligação (features). Uma ligação também pode conter anexos próprios — por exemplo, uma credencial que o consumidor apresenta ao componente a que esta ligação chega — em features: na sua entrada, indexados por um slot que o socket declara no seu featuresSchema. Os mesmos dois autores dividem-nos: o programador anexa na entrada de ligação do Aggregate com type e values, e o operador dimensiona esse anexo com infra, ou anexa um próprio com type e infra, na entrada da Release. Um anexo numa ligação não contém nenhum bloco inject próprio, razão pela qual está ausente da regra de colocação acima: não é um dos sítios onde um programador dita a entrega.

Cada um torna-se um anexo do componente consumidor com o nome <alias>.<slot>, pelo que tem âmbito do consumidor exatamente como a configuração por aresta: a sua FeatureRecipe é renderizada do lado do consumidor, e a saída do destino não muda com ele. É mantido fora dos .features da Recipe consumidora, que contém apenas os anexos que o bloco do próprio componente declara; em vez disso, a Recipe lê-o sob a sua ligação, em .context.uses.<alias>.features.<slot>. Uma ligação traçada por um anexo de Feature não contém anexos. Consulte entities/aggregate.md §«A connection’s own attachments (Os anexos próprios de uma ligação)» e entities/component.md §«Topology Sockets (Sockets de topologia)».

A. Variáveis de ambiente (env) e resolução dinâmica do destino O mecanismo de entrega padrão para aplicações cloud-native modernas. Para arestas topológicas explícitas (por exemplo, um agente que comunica com uma base de dados), o Aggrega usa .context.uses para injetar o mapeamento de variáveis de ambiente.

  • Caso de utilização: Receber nomes DNS internos determinísticos, cadeias de interpolação de Infrastructure-as-Code (por exemplo, ${module.db.endpoint}) ou ponteiros estáticos do Vault. O compilador liga estas referências estáticas em AOT para que a infraestrutura de tempo de execução ou o controlador GitOps possa resolver os valores reais.

B. Montagens de ficheiros (file) Muitas frameworks empresariais de IA esperam que um config.json estruturado ou um certificado .pem exista num caminho específico no disco, em vez de dependerem de variáveis de ambiente.

  • Caso de utilização: Injetar configurações JSON complexas ou satisfazer SDK legados que leem do disco.

  • Intenção do programador:

    features:
    openai_key:
    type: core/aws-secrets-manager
    values:
    path: /prod/ai/openai
    key: "api_token"
    inject:
    file:
    - in: "/etc/secrets/openai.json" # Local path
    from: "api_token" # The attachment's provides key
  • Realidade de Ops: A Recipe de Ops gera dinamicamente os Volume, VolumeMount e ExternalSecret do Kubernetes necessários para obter de forma segura os dados do cofre e montá-los em /etc/secrets/openai.json.

C. Argumentos da linha de comandos (arg) Os binários pré-compilados (como nós worker em Rust ou Go) contornam muitas vezes por completo as variáveis de ambiente, esperando que os valores sejam passados como flags de tempo de execução no seu comando de execução.

  • Caso de utilização: Acrescentar realidades físicas ao comando de arranque do contentor.

  • Intenção do programador:

    features:
    public-ingress:
    type: core/external-ingress
    inject:
    arg:
    - in: "--callback-url=" # Local flag
    from: "hostname" # The attachment's provides key
  • Realidade de Ops: O nome de anfitrião é o nome que o ambiente dá ao componente, pelo que o operador o escreve, api.enterprise.com, na infra deste anexo na entrada da Release para o componente. O plugin Wasm da Feature recebe o URL público resolvido através do contrato de injeção e emite um JSONPatch para acrescentar dinamicamente elementos ao array args do Kubernetes: ["/app/binary", "--callback-url=https://api.enterprise.com"], contornando completamente a Recipe base do Component.