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

Contrato do contexto de templates

Esta página documenta a visão de runtime que o compilador injeta nos templates Go de Recipe e FeatureRecipe: a forma do contexto de template, a disponibilidade por campo ao longo do pipeline de compilação e o contrato canônico de que os autores avançados precisam ao escrever templates que consomem estado entre componentes. A disponibilidade por local de template (quais campos estão presentes em qual local de avaliação) fica em expansion-matrix.md; esta página documenta as formas dos campos e sua semântica.

Visão geral

O compilador monta um contexto de template por nó durante a renderização e o injeta em todo template Go que o renderizador avalia para esse nó. O contexto existe apenas em memória — nunca é persistido em disco e nunca atravessa a ABI Wasm como um único payload. Cada local de template recebe uma visão do mesmo objeto de contexto; alguns campos são preenchidos tardiamente (.workload chega na síntese do workload; .source, na resolução da origem; .steps é preenchido pela execução de pipeline: à medida que cada etapa é concluída, veja Status da linguagem → Fases do pipeline de compilação).

O esquema da forma de runtime é template-context-v1beta1.schema.json (distribuído com a distribuição de esquemas do Aggrega).

Campos de nível superior

Os campos de nível superior ficam na raiz do contexto de template — acessados como .field de dentro de um template.

  • .values (mapa). Payload cognitivo escrito pelo desenvolvedor, vindo do Aggregate. Os valores por componente fluem até a Recipe renderizada neste campo. Validado pelo schema: do catálogo (a declaração JSON Schema 2020-12 do Component ou da Feature) na resolução. Quando o zero / vazio / falso escrito para um campo é semanticamente distinto da ausência do campo, use optional (veja sprig-functions.md) em vez de default.
  • .infra (mapa). Dimensionamento físico escrito por Ops, vindo da Release. Validado pelo schema: do catálogo (a declaração JSON Schema 2020-12 do Component ou da Feature) na resolução. A mesma orientação optional-vs-default dada para .values se aplica — prefira optional quando um zero ou um falso escrito pelo autor for uma intenção legítima (scale-to-zero, sem novas tentativas, feature flag desativada).
  • .locals (mapa com valores string). Estado privado da Recipe — nomes declarados no bloco locals: da Recipe, resolvidos no preâmbulo de locals e publicados neste pilar na resolução da origem. As entradas são resolvidas na ordem do autor e uma entrada pode ler uma entrada irmã definida acima dela, então a ordem é determinante sempre que uma entrada lê outra. Acessível apenas dentro dos templates da própria Recipe; nunca exposto aos chamadores.
  • .provides (mapa com valores string). As strings de saída públicas da Recipe — o contrato contra o qual os blocos inject: dos chamadores resolvem as referências from:. Preenchido na avaliação de provides.
  • .features (mapa de vinculações). Itera as Features vinculadas a este Component (nível do Aggregate + nível do subsistema + nível da Release + orientadas por anotações do Manifest, conforme o modelo de cebola de 5 camadas), tendo como chave o nome de instância que o autor deu à vinculação. Toda entrada carrega os mesmos campos — veja a forma da vinculação abaixo. Uma vinculação escrita em uma das conexões do Component não está entre elas: ela é lida sob essa conexão, em .context.uses.<alias>.features.<slot>, de modo que um template que percorre .features encontra apenas as vinculações próprias do Component.
  • .metadata (struct). Identidade da Release para nomeação determinística: release_name, release_version, environment, aggregate_name. Preenchido em toda renderização; os valores vêm do bloco metadata: da Release.
  • .source. O source: da Recipe, resolvido pela avaliação de template da resolução da origem. nil para Recipes sem origem; nil antes de a resolução da origem ser executada. Nos templates de uma FeatureRecipe, é o próprio source: dessa FeatureRecipe, nunca o do componente host — consulte Superfície da FeatureRecipe de uma vinculação.
  • .workload. O objeto Workload analisado, preenchido depois que o documento workload: renderizado foi decodificado e passou pela validação que o condiciona: o esquema do Workload, o featuresSchema do Component para cada vinculação que seus contêineres declaram e a resolubilidade do que cada vinculação referencia. nil para Recipes não sintetizadas; nil antes de a síntese do workload ser executada.
  • .steps (mapa de saídas de etapas). Preenchido pela execução de pipeline: à medida que os plugins Wasm são executados, expondo as saídas retornadas por uma etapa concluída às etapas seguintes por meio de .steps.<id>.outputs. Uma etapa lê as saídas de uma etapa anterior a partir do seu próprio template with; os outputs de uma etapa só ficam visíveis para as etapas declaradas depois dela. Vazio quando o nó não declara nenhum pipeline, e antes de a primeira etapa do nó ser concluída.

Um campo de nível superior que não contém nada para este nó — .workload em uma Recipe que não sintetiza nenhum, .source em uma Recipe sem origem, .features em um Component sem vinculações — é lido como vazio em um template de valor, exatamente como uma chave não definida em .values: {{ .workload }} não renderiza nada, um default sobre ele fornece seu valor alternativo, e um if ou with sobre ele segue seu ramo falso. Um range sobre ele não itera nada. Uma leitura abaixo dele — {{ .workload.containers }} — ainda assim interrompe, porque não há nada em que descer. E um template que tanto imprime esse campo onde sempre é executado — fora de todo if, with e range — quanto o percorre interrompe nomeando o campo, como faz com qualquer caminho que não contém nada e é lido das duas formas, porque nenhum valor único é impresso como nada e itera como nada: veja A template reads and iterates a path that holds nothing (Um template lê e itera um caminho que não contém nada).

A forma da vinculação

.features.<name> e .features.<slot> têm a mesma forma — uma vinculação, lida de uma única maneira:

  • .type (string). A URI de catálogo da Feature vinculada.
  • .resolved_version (string). A versão da Feature vinculada após a resolução do Manifest — a versão efetivamente associada a este build, em vez de uma versão fixada repetida no lado consumidor. Espelha .context.uses.<alias>.resolved_version. Vazio quando o type da vinculação não se resolve em nenhuma entidade de catálogo.
  • .labels (mapa com valores string). Os rótulos de catálogo da Feature vinculada, transmitidos literalmente na ordem em que a Feature os declara — nada é filtrado, renomeado ou despojado de prefixo, de modo que um template lê exatamente o que o autor da Feature escreveu. Espelha .context.uses.<alias>.labels. Ausente quando a Feature não declara rótulos, e quando o type da vinculação não se resolve em nenhuma entidade de catálogo.
  • .values (mapa). O pilar próprio da intenção do desenvolvedor da vinculação, escrito na declaração da vinculação no Aggregate. Distinto do .values de nível superior do componente host.
  • .infra (mapa). O pilar próprio do dimensionamento operacional da vinculação, escrito na declaração da vinculação na Release. Distinto do .infra de nível superior do componente host.
  • .provides (mapa com valores string). O contrato público resolvido da FeatureRecipe associada a esta vinculação — o nome do recurso emitido, sua chave de dados, uma identidade de nuvem e quaisquer chaves adicionais que a FeatureRecipe publique. Lido como .features.<name>.provides.<key>, espelhando .context.uses.<alias>.provides: o consumidor lê o que o produtor publicou em vez de derivá-lo novamente. Uma vinculação cuja FeatureRecipe associada não publica nada não carrega nenhuma chave provides, em vez de um mapa vazio, então verifique antes de acessar uma chave individual.

.provides é o que torna uma vinculação consumível, e não apenas presente. Uma Feature que declara um contrato schema.provides tem esse contrato aplicado à FeatureRecipe que a realiza — a FeatureRecipe deve publicar cada chave declarada — e o consumidor lê o resultado aqui. Assim, uma Feature de identidade que emite uma ServiceAccount e publica seu nome permite que a Recipe consumidora se vincule a ela:

workload: |
serviceAccount: "{{ .features.identity.provides.name }}"

O nome emitido é declarado uma única vez, pelo produtor, e consumido — nunca repetido no lado consumidor, onde os dois poderiam divergir. O exemplo workload-identity-binding renderiza isso de ponta a ponta.

.labels é o que permite a um template se adaptar a o que uma vinculação é sem comparar seu nome nem analisar sua URI. O compilador não lê nenhum deles — ele transporta as strings, e o autor do template decide o que significam.

Uma Feature que não declara rótulos não carrega nenhum .labels, em vez de um mapa vazio, então verifique antes de acessar um rótulo individual — acessar por meio de uma chave que não existe interrompe o build. Leia um rótulo que a Feature pode não declarar por meio de optional, porque index interrompe o build nomeando a chave quando o mapa não a contém:

{{ if .features.db.labels }}
{{ if eq (optional .features.db.labels "feature.aggrega.ai/kind" "") "secret" }}...{{ end }}
{{ end }}

Como os rótulos chegam literalmente, o namespace próprio do autor de um catálogo chega ao template inalterado, e uma Recipe lê a mesma chave que a Feature declara.

O bloco .context

.context é o contexto de execução montado pelo compilador para um único nó — os dados de identidade, de topologia e do pipe de entrega que o renderizador passa por cada ponto de template. Seus campos:

  • .context.instance_id (string). A identidade do nó como nome — o valor que o próprio build usa para nomear e rotular o que emite, de modo que um template que compõe a partir dele um nome de recurso ou um endereço interno do cluster prevê o nome que o build realmente produz. É o nome que você escreveu para um nó que seu próprio Aggregate declara. Para um nó que um Aggregate importado contribui, é a identidade achatada com o separador de módulo escrito por extenso (data-layer.main-db se torna data-layer-zdmain-db), porque um ponto não é um caractere que um nome de recurso possa conter e, dentro de um endereço de cluster, ele separa um serviço de seu namespace. A forma com pontos é a que seus documentos e os diagnósticos do build usam para endereçar esse nó; veja Convenções de nomenclatura.
  • .context.rendered_name (string). O nome que o provedor do nó dá aos recursos que renderiza para o nó — a partir da fonte que você forneceu, como o nome da release que um chart lê, e a partir de um workload que ele sintetiza quando nomeia os recursos desse workload segundo um nome próprio, como helm faz com o mesmo nome da release. Presente apenas onde esse provedor deriva um. Nos templates de uma vinculação de Feature, é o nome do componente host, assim como .context.instance_id ali é a identidade do host; veja Nomear um recurso renderizado.
  • .context.labels (mapa com valores string). Rótulos escritos no catálogo mais quaisquer adições de label-transform feitas na construção da topologia.
  • .context.annotations (três contêineres, veja abaixo). Anotações em cascata, agrupadas por origem.
  • .context.inject (mapa de mecanismos, veja abaixo). O pipe de entrega pré-hidratado e interceptado — a superfície padrão que os templates de Recipe leem para valores entre componentes.
  • .context.uses (mapa de conexões, veja abaixo). A projeção JOIN sobre as arestas topológicas de saída.
  • .context.self_inject (mapa de mecanismos, veja abaixo). Para cada nome que o desenvolvedor escreveu no próprio bloco inject: do componente, a chave provides própria que essa entrada entrega ou o único valor próprio que seu template lê.
  • .context.used_by (lista, veja abaixo). Os componentes cujas entradas uses apontam para este. Lido por uma FeatureRecipe vinculada ao componente, nos templates que produzem os recursos próprios da vinculação; vazio em qualquer outro lugar.
  • .context.render_facts (mapa de listas, veja abaixo). O que o provedor do componente informou sobre a saída que renderizou, indexado pelo nome do fato. Lido por uma FeatureRecipe vinculada ao componente, em cada um de seus templates que é executado depois que o componente foi renderizado; ausente em qualquer outro lugar.

.context.annotations — três contêineres

As anotações se propagam em cascata para três contêineres indexados por origem:

  • .context.annotations.release — anotações da fronteira da Release (Domínio 4). Usadas para governar realidades físicas; os renderizadores as direcionam para campos infra: quando apropriado. As anotações conhecidas aggrega.ai/* ficam neste contêiner.
  • .context.annotations.catalog — anotações de metadados do Component do Domínio 2. Traços intrínsecos imutáveis escritos pelo Architect; consumidos principalmente por plugins de política Wasm.
  • .context.annotations.aggregate — anotações de subsistema do Aggregate do Domínio 1. Metadados cognitivos; os renderizadores as direcionam para payloads values: quando apropriado.

Cada contêiner é um mapa plano de string para string. Segundo as regras de separação da arquitetura, os contêineres se destinam a usos distintos; o motor não impõe a separação, então é a disciplina de autoria que mantém os contêineres alinhados com a semântica pretendida. Veja capítulo 6 §2 Fluxo 5 para o design das anotações em cascata.

.context.inject — o pipe de entrega

O pipe é o mapa de entrega pré-resolvido do compilador. Quando um template de Recipe é executado na renderização base, toda fonte de inject (literais self-inject escritos pelo desenvolvedor, referências from: self-inject resolvidas em relação aos próprios provides, referências uses[].inject entre componentes resolvidas em relação aos provides do destino, interceptações injectMapping de FeatureRecipe) já foi resolvida em um valor string final e mesclada neste mapa.

Campos:

  • .context.inject.env — mapa com valores string de nome de variável de ambiente → valor resolvido.
  • .context.inject.file — mapa com valores string de caminho de arquivo → valor resolvido.
  • .context.inject.arg — mapa com valores string de flag de argumento → valor resolvido.
  • .context.inject.all — mapa com valores string que combina os mecanismos env/file/arg/personalizados em um único dicionário plano; útil para serializar o pipe inteiro ({{ toJson .context.inject.all }}).

Um mecanismo está no pipe apenas quando algo entrega por meio dele. Um template que lê um pelo qual nada entrega — .context.inject.file sem nenhuma entrega de arquivo — o lê como vazio, como um template de valor lê qualquer chave ausente, e um range sobre ele não renderiza nada; essa leitura fornece o valor vazio para o template inteiro, de modo que um {{ toJson .context.inject }} no mesmo template mostra "file": "". hasKey .context.inject "file" indica se algo entrega por meio dele.

  • Mecanismos personalizados (por ex., ssm_param) — legíveis sob seu próprio nome de campo, .context.inject.<mechanism>.<key>, exatamente como os três principais. Os valores de um mecanismo personalizado chegam ao pipe a partir do self-inject no nível do componente, de uma aresta uses[].inject, do mapeamento inject: de uma vinculação de Feature e da saída injectMapping de uma FeatureRecipe. Para o self-inject no nível do componente, a allowlist spec.inject do Component deve nomear o mecanismo, e um mecanismo que a allowlist não nomeia interrompe o build. As entradas de um mecanismo personalizado também aparecem em .context.inject.all ao lado dos três principais. Um mecanismo personalizado pode ter qualquer nome, exceto all: esse nome é a própria visão mesclada, de modo que um mecanismo com esse nome nunca poderia ser lido isoladamente. Um bloco inject que nomeia um mecanismo all, e uma allowlist de um Component ou de uma Feature (spec.inject, o inject de um socket) que o lista, interrompem o build quando o documento é carregado, e a recusa explica que o nome pertence a essa visão mesclada. Os nomes diferenciam maiúsculas de minúsculas, então ALL é um mecanismo personalizado comum.

O pipe é o estado posterior à interceptação — os blocos injectMapping de FeatureRecipe já mesclaram em profundidade suas substituições sobre este pipe durante o mapeamento de inject, quando os templates de Recipe o leem. Um mapeamento pode substituir uma chave que o próprio bloco inject: do componente, um dos blocos inject: de suas conexões ou o bloco inject: de sua própria vinculação entregou; uma chave que duas Features vinculadas entregam, por meio de seus blocos inject: ou de seus mapeamentos, interrompe o build em vez de chegar a este pipe com um dos dois valores. Uma Feature vinculada a uma fronteira da Release chega ao componente da mesma forma, por meio do injectMapping de sua FeatureRecipe, que é executado no próprio contexto do componente, qualquer que seja o executionScope da FeatureRecipe — a reescrita, pelo bridge do compose, da variável de host de um consumidor é um desses mapeamentos, sujeito à mesma regra.

.context.self_inject — qual valor próprio cada um dos nomes do desenvolvedor entrega

Quando um Component declara spec.inject, o desenvolvedor pode escrever um bloco inject: no próprio componente e escolher os nomes sob os quais os valores e os provides próprios do componente são entregues. .context.inject contém o resultado da resolução dessas entradas e .inject_raw as contém como foram escritas; .context.self_inject informa, para cada uma, a chave provides própria do componente que ela entrega ou o único valor próprio que seu template lê. Ele tem a forma que o .context.uses.<alias>.inject de uma conexão tem — mecanismo, depois o nome do desenvolvedor, depois uma chave —, com a chave nomeando um dos provides ou dos valores próprios do componente:

  • provides.<key> — uma entrada escrita com from: <key>, que entrega um dos provides próprios do componente.
  • values.<key> — uma entrada cujo template value: lê exatamente um dos valores próprios do componente e nada mais, sendo <key> a chave de nível superior desse valor. Texto ou funções em torno da leitura não importam, nem a profundidade com que o template lê dentro do valor: '{{ .values.role }}', 'role={{ .values.role | upper }}' e '{{ with .values.role }}{{ . }}{{ end }}' correspondem todos a values.role, e '{{ .values.config.port }}', '{{ index .values.config "port" }}' e '{{ (default dict .values.config).port }}' correspondem todos a values.config.
  • uma string vazia — qualquer outra entrada: um literal, um template que lê dois valores, um template que lê qualquer coisa além dos valores (.infra, .metadata, .context), e um template cuja leitura dos valores o texto não atribui a uma única chave de nível superior — os valores passados a uma função pela raiz (index .values "role"), os valores lidos por inteiro (toJson .values, ou um campo lido dentro de {{ with .values }} ou por meio de uma variável vinculada a .values), ou o contexto inteiro repassado (toJson .).
# The developer's block on the component, in the Aggregate
inject:
env:
- { in: SERVICE_HOST, from: host }
- { in: AGENT_ROLE, value: '{{"{{"}} .values.role }}' }
- { in: MODE, value: batch }
- { in: ROLE_AND_GOAL, value: '{{"{{"}} .values.role }}-{{"{{"}} .values.goal }}' }
ssm_param:
- { in: /app/goal, value: '{{"{{"}} .values.goal }}' }
# What the Recipe reads at .context.self_inject
env:
SERVICE_HOST: provides.host
AGENT_ROLE: values.role
MODE: ""
ROLE_AND_GOAL: ""
ssm_param:
/app/goal: values.goal

No Aggregate, cada template value: começa com {{"{{"}} em vez de {{, porque todo o texto do Aggregate é lido uma vez como template, para a interpolação de parâmetros, antes de os templates do próprio bloco serem avaliados; os templates citados na lista acima são mostrados como ficam após esse escape. Veja Texto que contém suas próprias chaves duplas.

É isso que permite que uma Recipe que executa a imagem do próprio desenvolvedor trate seus próprios nomes de variável para os valores próprios do componente como padrões — a convenção do catálogo da biblioteca padrão, que um catálogo corporativo pode escolher de outra forma. Antes de entregar um valor próprio sob um nome seu, essa Recipe verifica se o bloco do desenvolvedor já entrega esse valor e, nesse caso, ignora seu padrão — assim, um desenvolvedor que renomeia um valor mantém todos os outros padrões:

workload: |
containers:
main:
variables:
{{- range $name, $value := .context.inject.env }}
{{ $name }}: {{ $value | quote }}
{{- end }}
{{- $named := dict }}
{{- with .context.self_inject.env }}{{ range $name, $key := . }}{{ $_ := set $named $key true }}{{ end }}{{ end }}
{{- if not (hasKey $named "values.role") }}
APP_ROLE: {{ .values.role | quote }}
{{- end }}

.context.self_inject está presente em toda renderização e vazio onde o desenvolvedor não escreveu nenhum bloco. Um mecanismo aparece apenas quando o bloco o nomeia, então proteja a leitura de um mecanismo que o bloco pode não nomear, como faz o with acima. Um template encontra os nomes ordenados, seja qual for a forma como os lê, como encontra qualquer mapa. O mapa é lido do texto que o desenvolvedor escreveu; nada nele é um valor resolvido, e o compilador não atribui nenhum significado aos nomes nem às chaves.

.context.uses — projeção JOIN

.context.uses é a visão enriquecida do compilador de cada aresta topológica de saída do nó atual. Cada entrada do mapa é indexada pelo alias local do socket (por ex., databases.primary se torna .context.uses.primary quando o Aggregate escreveu uses: { databases: { primary: { target: ... } } }) e carrega uma projeção JOIN do estado resolvido do destino mais o contrato de entrega do lado do chamador:

  • .target (string) — ID de instância do nó de destino.
  • .socket (string) — nome do socket do lado do chamador (a chave usesSchema).
  • .provides (mapa com valores string) — as chaves provides: resolvidas do destino (as strings de saída públicas que a Recipe de destino exportou na avaliação dos provides).
  • .inject (mapa de mecanismo → mapa de chave → valor) — diretivas de inject do lado do chamador para esta aresta (o bloco inject: na declaração uses[].inject). As chaves de mecanismo são env/file/arg/personalizadas; as entradas do mapa por mecanismo são referências chave local → chave de provides do destino.
  • .labels (mapa com valores string) — os rótulos do destino, nunca os do componente consumidor: o conjunto que o próprio .context.labels do destino carrega, seus rótulos escritos no catálogo mais quaisquer adições de label-transform feitas na construção da topologia.
  • .annotations (três contêineres) — os contêineres de anotações release/catalog/aggregate do destino.
  • .component (string) — URI do tipo de Component do destino.
  • .resolved_version (string) — versão do Component do destino após a resolução do Manifest.
  • .boundary_path (string) — caminho da fronteira da Release do destino, definido quer o destino esteja na fronteira do chamador, quer em outra.
  • .origin_feature (string) — definido quando a aresta foi sintetizada por uma vinculação de Feature (por ex., uma Feature sidecar que contribui com uma aresta uses para uma Feature de credenciais).
  • .values (mapa) — configuração do desenvolvedor por aresta, resolvida, para esta conexão, escrita na entrada uses do Aggregate. Presente apenas quando a aresta carrega valores por aresta.
  • .infra (mapa) — configuração do operador por aresta, resolvida, para esta conexão, escrita na entrada uses da Release. Presente apenas quando a aresta carrega infra por aresta.
  • .origin_release (booleano) — true quando foi a Release que cabeou esta conexão, em vez de o Aggregate declará-la; ausente para uma conexão que o Aggregate declara.
  • .features (mapa de vinculações) — as vinculações escritas nesta conexão, indexadas pelo nome do slot que o socket declara; veja abaixo. Presente apenas quando a conexão carrega uma.
  • .render_facts (mapa de listas) — o que as renderizações do destino informaram sobre a saída que emitiram, indexado pelo nome do fato, na mesma forma que o .render_facts de um chamador em .context.used_by: cada fato é uma lista, primeiro as chamadas do próprio provedor do destino e depois cada uma de suas Features na ordem em que renderizaram, e as listas que um nome recebe de cada um são unidas em uma só. Presente apenas para uma FeatureRecipe que define readsTargetRenderFacts: true — suas vinculações são renderizadas depois que todos os componentes foram renderizados, de modo que a renderização de cada destino está completa — e então em cada conexão, vazio para um destino cujos provedores não informam nada. Lido apenas em valuesMapping:, workload: e artifacts: dessa FeatureRecipe; ausente dos próprios templates de Recipe do componente, de um injectMapping:, de with: e when: de uma etapa de pipeline: e de toda FeatureRecipe que não define a chave — um template de uma delas que o lê interrompe o build antes que qualquer coisa seja renderizada.

Ambos os mapas de configuração por aresta têm escopo de consumidor: eles chegam apenas ao contexto de renderização do nó consumidor, nunca ao do destino.

Um valor fornecido é lido em .provides.<name> — os nomes fornecidos ficam aninhados sob .provides em vez de estarem diretamente na aresta, de modo que .context.uses.<alias>.<name> não endereça nenhum campo e não retorna nada.

Em uma conexão cujas duas pontas são renderizadas em saídas diferentes, .provides contém substitutos em vez dos valores. Onde o provedor cabeia essa conexão com uma referência própria depois que ambas as saídas são montadas — uma stack do CloudFormation lendo um valor de outra stack, por exemplo —, cada valor que .context.uses.<alias>.provides carrega é um marcador de posição que o provedor substitui depois, por uma referência entre stacks ou pelo próprio valor, como descreve sua própria página. Esse valor deve ser copiado, não comparado — a mesma regra seguida pelo valor que essa conexão entrega no pipe de inject, que é um marcador de posição do mesmo tipo. Escreva-o inteiro, dentro de uma string maior, ou por meio de uma função que o deixe como está, como quote. Um template que compara um valor que lê de .provides, ramifica com base nele, o mede ou o altera estaria decidindo com base no marcador de posição, então o build é interrompido em vez disso, nomeando o template e cada valor que ele leu; ramifique com base em um valor próprio do componente consumidor. A interrupção abrange todo template que lê os .provides da conexão, incluindo o injectMapping: de uma FeatureRecipe vinculada, e uma FeatureRecipe de escopo de fronteira que lê as mesmas conexões sob .boundary. Uma conexão cujas duas pontas são renderizadas em uma única saída carrega seus valores como são.

Um alias nomeia uma conexão, então o mapa contém uma entrada para cada conexão que o componente faz. O mapa é indexado apenas pelo alias, qualquer que seja o socket em que uma conexão está cabeada, e duas conexões de um mesmo componente nunca compartilham um alias — nem em um socket nem em dois, qualquer que seja o documento ou a vinculação que traçou cada uma. O build recusa um par assim, nomeando ambas as conexões e onde cada uma foi escrita, antes que qualquer coisa seja renderizada. Uma lista que nomeia o mesmo destino duas vezes é um par assim, já que o alias de uma entrada de lista é o seu destino; também o é uma conexão local em um socket models ao lado de uma conexão local em um socket databases.

Os templates de Recipe consomem esta projeção para consultar o estado do lado do destino sem percorrer o grafo IR. Os templates injectMapping de FeatureRecipe a usam para acessar as anotações do destino em decisões de roteamento entre fronteiras (o padrão do resolvedor de DNS do K8s documentado em entities/featurerecipe.md é o exemplo canônico desenvolvido).

Um template que itera sobre .context.uses vê as conexões em ordem de chave — ordenadas por alias —, não na ordem em que o Aggregate as escreveu. Todo mapa sobre o qual um template itera é percorrido dessa forma, incluindo .features e os .features de uma conexão, de modo que um template nunca recupera a ordem escrita iterando sobre um mapa; onde a ordem tem significado, a superfície de autoria a modela como uma lista. De qualquer forma, a saída renderizada é idêntica byte a byte entre builds da mesma entrada.

As vinculações de uma conexão — .context.uses.<alias>.features

Uma vinculação escrita em uma conexão — sob features: na entrada uses de um componente no Aggregate, ou na entrada da Release para essa conexão — preenche um slot que o socket declara. Ela é uma vinculação do componente consumidor para tudo o que o build faz com ela: o Manifest associa sua realização, sua FeatureRecipe é renderizada no lado do consumidor, seu contrato de provides é aplicado. Um template a lê sob a conexão em que foi escrita:

{{- range $alias, $edge := .context.uses }}
- name: {{ $alias }}
api_base: {{ $edge.provides.endpoint }}
{{- with $edge.features }}{{ with .credential }}
api_key_secret: {{ .provides.name }}
api_key_key: {{ .provides.key }}
{{- end }}{{ end }}
{{- end }}
  • Indexadas por slot. .context.uses.<alias>.features.<slot> nomeia o slot que o socket da conexão declara — credential acima —, de modo que um consumidor que alcança vários destinos lê a credencial própria de cada destino sob o alias desse destino. Uma conexão que não carrega nenhuma vinculação não tem .features, e é por isso que a leitura é protegida.
  • A forma da vinculação. Cada entrada carrega exatamente o que .features.<name> carrega para uma das vinculações próprias do componente — .type, .resolved_version, .labels, .values, .infra e os .provides resolvidos da FeatureRecipe associada a ela —; veja a forma da vinculação. Os provides lidos aqui são aqueles com base nos quais a própria FeatureRecipe da vinculação é renderizada, de modo que o nome que um consumidor referencia e o nome do recurso que essa FeatureRecipe emite são um único valor avaliado.
  • Nunca em .features. Os .features próprios do componente contêm apenas as vinculações escritas em seu próprio bloco. Uma Recipe que itera sobre .features e seleciona vinculações por tipo — {{ range $name, $f := (default dict .features) }}{{ if eq $f.type "core/referenced-secret" }}… — portanto nunca encontra a credencial de uma conexão, nem mesmo uma da mesma Feature: um template alcança a vinculação de uma conexão por meio de sua conexão, nunca por meio de .features. O mesmo vale em toda superfície que mostra as vinculações de um componente, incluindo o contexto assertions.

Os componentes que usam este — .context.used_by

.context.uses olha para fora, para as conexões que um componente faz. .context.used_by olha para dentro, para os componentes cujas entradas uses apontam para este. Uma FeatureRecipe vinculada ao componente o lê, e é ali que cabe um recurso que descreve ou restringe essas conexões — uma network policy que admite apenas os componentes declarados como chamadores deste, por exemplo:

artifacts:
callers.yaml: |
apiVersion: v1
kind: ConfigMap
metadata:
name: {{ .context.rendered_name }}-{{ .attachment_name }}
data:
callers: |
{{- range .context.used_by }}
- component: {{ .component_id }}
socket: {{ .socket }}
selector: {{ .provides.selector }}
{{- with .source_namespace }}
namespace: {{ . }}
{{- end }}
{{- end }}

Cada entrada carrega:

  • .component_id (string) — o ID de instância do componente que se conecta em sua forma achatada (frontend, data-layer.etl), o valor que um template de caminho subDirectory: lê como .component_id.
  • .socket (string) — o socket que a conexão preenche no componente que se conecta (sua chave usesSchema).
  • .provides (mapa com valores string) — o que o componente que se conecta publica, restrito às chaves que seu Component declara: os mesmos valores que um consumidor desse componente lê em .context.uses.<alias>.provides. Uma chave que a Recipe do componente publica sem que seu Component a declare não está entre eles.
  • .source_namespace (string) — o namespace em que o componente que se conecta está posicionado: a anotação aggrega.ai/namespace que se aplica a ele, propagada em cascata pelas suas fronteiras, com precedência para sua própria entrada na Release. Um componente cuja entrada na Release define o namespace, ou o limpa com null, carrega sua própria configuração em vez da de sua fronteira, de modo que o valor nomeia o namespace em que os recursos próprios do componente são renderizados. Ausente quando nenhum namespace se aplica ao componente; leia-o por meio de with ou if, como faz o exemplo, em vez de imprimi-lo diretamente.
  • .source_boundary_path (string) — o caminho da fronteira da Release que contém o componente que se conecta, com as fronteiras aninhadas unidas por / (edge, edge/inner).
  • .render_facts (mapa de listas) — o que as renderizações do componente que se conecta informaram sobre a saída que emitiram, indexado pelo nome do fato, na mesma forma que .context.render_facts. Cada fato é uma lista, então um template sempre itera sobre ele, mesmo quando contém uma única entrada. Suas entradas podem vir da própria renderização do componente que se conecta e das renderizações das Features vinculadas a ele: as listas que um nome recebe de cada um são unidas em uma só, primeiro as chamadas do próprio provedor do componente, depois cada uma de suas Features na ordem em que renderizaram. Presente apenas para uma FeatureRecipe que define readsCallerRenderFacts: true — suas vinculações são renderizadas depois que todos os componentes foram renderizados, de modo que a renderização de cada chamador está completa — e então em cada entrada, vazio para um chamador cujos provedores não informam nada. Uma FeatureRecipe que não define a chave não vê nenhum .render_facts em nenhuma entrada, e um template dela que os lê interrompe o build antes que qualquer coisa seja renderizada.

Os dois valores de posicionamento são os que uma FeatureRecipe de escopo de fronteira lê como source_namespace e source_boundary_path na entrada da mesma conexão em suas listas de arestas .boundary: ambas as visões leem da mesma forma onde um componente está posicionado, então nunca divergem sobre isso. Uma aresta nessas listas também carrega o caminho de montagem de cada ponta — source_assembly_path e target_assembly_path, o diretório sob o diretório de saída do build no qual o provedor da ponta a monta —, que uma entrada de .context.used_by não carrega.

Uma FeatureRecipe que define readsCallerRenderFacts: true lê os fatos de cada chamador da mesma forma que lê os do host. Para um provedor que documenta um fato chamado ports cujas entradas carregam cada uma um port:

artifacts:
callers.yaml: |
callers:
{{- range .context.used_by }}
- component: {{ .component_id }}
ports:
{{- range .render_facts.ports }}
- {{ .port }}
{{- end }}
{{- end }}

Um chamador cujo provedor não informa nenhum ports renderiza um ports: vazio em vez de falhar, porque um nome que ninguém informou é lido como nada.

Como a lista se comporta:

  • Na ordem escrita. As entradas seguem a ordem em que os componentes que se conectam estão escritos, depois a ordem das entradas uses próprias de cada um. Um componente que se conecta duas vezes aparece duas vezes, uma por conexão. Como é uma lista e não um mapa, um range encontra os chamadores nessa ordem — nada é ordenado.
  • Apenas onde a vinculação renderiza seus próprios recursos. valuesMapping:, workload: e artifacts: da FeatureRecipe a leem. Ela está vazia nos próprios templates de Recipe do componente, em um injectMapping: e em with: e when: de uma etapa de pipeline:, porque o que cada um deles produz pode acabar na própria saída renderizada do componente: um injectMapping: escreve o pipe de entrega do componente, e uma etapa de pipeline pode reescrever os documentos do componente. É isso que mantém a própria saída de um componente igual, quem quer que o use — cabear mais um chamador a um componente altera a saída de uma Feature vinculada a ele que lê seus chamadores, e nada do que o próprio componente renderiza.
  • Nada sobre a conexão em si. Uma entrada não carrega values nem infra por conexão nem nenhuma das vinculações da conexão; esses ficam com o componente consumidor, sob seu .context.uses.<alias>.
  • Vazia quando nada usa o componente. Um range sobre ela então não renderiza nada.
  • Repassado, nunca interpretado. A identidade, o socket, os valores publicados e o posicionamento são strings que o compilador repassa, e os fatos de renderização são o que os provedores de cada chamador informaram, indexados por nome. Ele não infere nada de um nome, não busca nada e não decide nada sobre quais chamadores um recurso deve admitir; o template decide.

O que foi informado por um provedor sobre uma renderização — .context.render_facts

O provedor de um componente pode informar fatos sobre a saída que renderizou — propriedades dos documentos que escreveu que apenas o seu próprio conhecimento do seu formato consegue ver. Quais fatos um provedor informa, sob quais nomes e com o que em cada entrada, é o contrato documentado próprio desse provedor; veja Relatar fatos sobre o que um guest emitiu para o lado do provedor. O provedor helm, por exemplo, informa os rótulos dos templates de pod que emitiu, os seletores de seus controladores e Services e as portas de seus contêineres — veja seus fatos de renderização. Uma FeatureRecipe vinculada ao componente lê o que o provedor do componente informou em .context.render_facts, indexado pelo nome do fato. Para um provedor que documenta um fato chamado ports cujas entradas carregam cada uma um name e um port:

artifacts:
ports.yaml: |
ports:
{{- range .context.render_facts.ports }}
- name: {{ .name }}
port: {{ .port }}
{{- end }}
  • Cada fato é uma lista. Um provedor informa cada fato como uma lista, mesmo quando contém uma única entrada, então um template sempre itera sobre ele — não há um valor único para ler isoladamente.
  • Uma lista por nome, unida ao longo da renderização do componente. Renderizar um componente pode exigir mais de uma chamada de seu provedor — uma renderização de chart e um posicionamento de artifacts, por exemplo — e cada chamada informa por si. As listas que um nome recebe dessas chamadas são unidas em uma só, na ordem em que as chamadas foram executadas. O que as Features vinculadas ao componente renderizaram não está entre elas aqui: uma Feature lê apenas a própria renderização do componente em .context.render_facts, seja o que for que as outras Features do componente tenham emitido.
  • Em todo template de uma FeatureRecipe vinculada. Seus valuesMapping:, workload: e artifacts: o leem, assim como with: e when: de suas etapas de pipeline: — os fatos vêm da própria renderização do componente, então lê-los não torna nada dependente de quem se conecta ao componente. Ele está ausente dos próprios templates de Recipe do componente e de um injectMapping:, que são executados antes que o componente tenha sido renderizado.
  • Vazio em vez de ausente. Onde o provedor do componente não informa nada, .context.render_facts é um mapa vazio, e um nome que ninguém informou é lido como nada, então um range sobre ele não renderiza nada em vez de falhar.
  • Ordem. Uma lista mantém suas entradas na ordem em que o provedor as informou. Uma entrada de objeto é um mapa com chaves como qualquer outro no contexto, então um template que itera sobre um encontra suas chaves em ordem de chave.
  • Repassado, nunca interpretado. O compilador verifica apenas que o valor de cada fato é uma lista. Ele não lê nada do que um nome ou uma entrada significa; o template decide o que fazer com isso.

O .uses de uma asserção — indexado por socket e depois por alias

Um template assertions: lê as mesmas conexões por meio de uma visão própria mais estreita: .uses na raiz em vez de sob .context, e sem nada do que o destino de uma conexão publicou, porque ambas as fases de asserção são avaliadas antes da renderização. Ele espelha a forma de autoria uses: <socket>: <alias>: { target: … } — indexado por socket e, sob cada socket, pelo alias de cada conexão nele, sendo que uma conexão escrita como entrada de lista toma seu destino como alias. A entrada de cada conexão carrega target, alias e, para uma conexão que uma vinculação de Feature traçou, origin_feature, além de três dos fatos que .context.uses carrega, com os mesmos nomes e os mesmos valores: .labels, os rótulos do destino; .values, os valores escritos na conexão; e .features, as vinculações escritas nela, indexadas por slot. Cada um dos três está presente em toda entrada, vazio onde a conexão não carrega nenhum. Uma vinculação sob .features carrega apenas seu type, seu resolved_version e seus values — a forma em que uma asserção lê toda vinculação, incluindo as próprias de um componente, já que a FeatureRecipe de uma vinculação ainda não resolveu seus provides quando uma asserção é executada.

Um socket que contém uma conexão e um socket que contém várias têm a mesma forma, então uma asserção lê qualquer um deles da mesma forma. Para um componente cuja entrada no Aggregate escreve uses: { models: { local: { target: llama }, fast: { target: turbo } } }:

assertions:
two-models-wired: |
{{- if lt (len (optional .uses "models" dict)) 2 -}}
{{- fail "wire two models to the models socket" -}}
{{- end -}}
local-is-llama: |
{{- if and (hasKey .uses "models") (hasKey .uses.models "local") (ne .uses.models.local.target "llama") -}}
{{- fail (printf "the local connection must point at llama; it points at %s" .uses.models.local.target) -}}
{{- end -}}

hasKey .uses "models" pergunta se o socket está cabeado, len conta suas conexões, um range sobre ele visita cada uma em ordem alfabética de seus aliases, e .uses.models.local.target lê uma conexão. .uses.models.target não endereça nenhuma conexão e interrompe o build sob o missingkey=error da superfície de asserções. Cada conexão tem uma entrada própria, pelo mesmo motivo que o mapa do contexto de renderização: duas conexões de um mesmo componente nunca compartilham um alias, porque o build recusa isso antes que qualquer asserção seja executada. O contexto completo de asserções está documentado em assertions-block.md.

O contexto de template carrega estes campos com forma de inject, cada um com sua própria semântica. Autores de Recipe e de FeatureRecipe devem saber qual superfície ler.

SuperfícieTipoPreenchido quandoUso
.context.injectmapa de mecanismos (sempre presente)Toda renderizaçãoO pipe de entrega padrão pré-hidratado — leia-o nos templates valuesMapping:/workload:/artifacts: e em qualquer ponto de template de uma FeatureRecipe.
.inject (nível superior)mapa de mecanismos (anulável)Ao renderizar a FeatureRecipe de uma vinculação, quando a vinculação escreve um bloco inject:As entradas inject: próprias da vinculação, sob cada mecanismo que seu bloco nomeia — env, file, arg ou um personalizado, como vault_ref —, com cada nome local mapeado para a chave que seu from: nomeia. Essa chave é uma que a FeatureRecipe publica em seus provides:, que o compilador também entrega no .context.inject do componente, ou uma chave que uma FeatureRecipe que lê .inject consome ela mesma: uma entrada que nomeia uma chave que a FeatureRecipe não publica interrompe o build, a menos que um template que a FeatureRecipe avalia em relação a esse contexto — seu valuesMapping:, workload:, artifacts:, omits: ou o with: ou o when: de uma etapa do pipeline — leia .inject por um caminho que o template nomeia: .inject, .inject.env, {{ with .inject }} e semelhantes, não uma passagem do contexto inteiro como toJson .. Seu injectMapping: não conta, porque é avaliado em relação ao contexto do componente, onde .inject está ausente. O bloco de uma vinculação não carrega literais: uma entrada value: ali interrompe o build, e um literal de que o componente precisa é escrito no próprio bloco inject: do componente. Um mecanismo personalizado é lido em .inject.<mechanism> exatamente como .inject.env, e suas entradas aparecem em .inject.all ao lado dos três principais. Uma leitura com pontos de um mecanismo que a vinculação não escreve é interrompida como chave desconhecida, mesmo dentro de um if ou de um with, onde .context.inject.<mechanism> é lido como vazio; leia um mecanismo que a vinculação pode não escrever por meio de {{ with .inject }}{{ if hasKey . "<mechanism>" }}{{ index . "<mechanism>" "<key>" }}{{ end }}{{ end }}, que compila quer a vinculação escreva ou não o mecanismo ou algum bloco inject:. Ausente dos templates de uma Recipe base e de uma vinculação que não escreve nenhum bloco inject:.
.inject_raw (nível superior)mapa de mecanismos (anulável)Definido quando o desenvolvedor escreveu um bloco inject: no componente paiA intenção do desenvolvedor sem modificações, antes de qualquer interceptação de inject-mapping. Cada mecanismo que o bloco nomeia — env, file, arg ou um personalizado, como ssm_param — fica sob o seu próprio nome, contendo as entradas exatamente como escritas (in com from ou value), na ordem em que foram escritas: .inject_raw.ssm_param lê um mecanismo personalizado da mesma forma que .inject_raw.env lê o mecanismo nativo. Use para verificações lógicas do tipo “o desenvolvedor solicitou originalmente esta chave de entrega?”; imune à reescrita pelo injectMapping de uma FeatureRecipe. nil se o desenvolvedor omitiu o bloco inject:.
.context.self_injectmapa de mecanismos (sempre presente)Toda renderização; vazio onde o desenvolvedor não escreveu nenhum bloco inject: no componenteCada nome no próprio bloco inject: do componente, mapeado para a chave própria que sua entrada entrega — provides.<key>, values.<key> ou vazio. Use para ignorar um nome padrão para um valor próprio que o desenvolvedor já entrega; veja acima.

Autores que precisam da entrega resolvida após a interceptação devem ler .context.inject. Autores que precisam da intenção original imutável (por ex., para detectar uma interceptação ou para emitir um comportamento alternativo quando o desenvolvedor omitiu um bloco inject) devem ler .inject_raw. Autores que precisam saber quais dos valores próprios do componente o desenvolvedor já nomeou devem ler .context.self_inject.

Superfície da FeatureRecipe de uma vinculação

Quando o renderizador avalia os templates da FeatureRecipe de uma vinculação, um campo adicional de nível superior é definido:

  • .attachment_name (string) — o nome de instância da vinculação: o slot que ela preenche no featuresSchema da entidade proprietária, ou o nome livre que o autor lhe deu. locals:, provides:, injectMapping:, valuesMapping: e artifacts: de uma FeatureRecipe o leem para derivar um identificador de recurso determinístico — {{ .context.rendered_name }}-{{ .attachment_name | replace "_" "-" }} onde o provedor do host informa um nome renderizado, como faz helm, e {{ .context.instance_id }}-{{ .attachment_name }} onde não informa nenhum — e para nomear a vinculação que está sendo processada.

Os próprios templates de uma Recipe base não estão resolvendo uma vinculação, então o campo não faz parte do contexto deles: um template provides:, locals: ou source: de uma Recipe que o referencia interrompe o build nomeando a referência em vez de renderizar um valor vazio. Uma FeatureRecipe com executionScope: boundary é renderizada uma vez para a fronteira em vez de uma vez por componente, então o campo também não está disponível para os templates executados para a fronteira; seu injectMapping: é executado para cada componente que a vinculação alcança e o lê ali.

Nos templates que produzem os recursos próprios da vinculação — seus valuesMapping:, workload: e artifacts: —, o contexto da vinculação também lista os componentes que usam seu host, em .context.used_by, e, onde sua FeatureRecipe define readsTargetRenderFacts: true, carrega o que cada componente ao qual seu host está cabeado renderizou, em .context.uses.<alias>.render_facts. Esses templates e suas etapas de pipeline: também leem o que o provedor de seu host informou sobre a renderização do host, em .context.render_facts. Uma FeatureRecipe de escopo de fronteira renderiza seus recursos para nenhum componente host e sem .context; em vez disso, ela lê cada conexão para sua fronteira sob .boundary.internal_uses_edges e .boundary.incoming_cross_boundary_uses_edges. Seu injectMapping: é o único template que ela escreve que é executado no contexto de um componente — o de cada componente que a vinculação alcança, .context.* incluído —, e uma referência a .boundary ali interrompe o build.

O campo é a única via para o nome de instância da vinculação. .context.instance_id é o componente host para o qual a vinculação está sendo resolvida — ele denota o host em toda superfície de template que o compilador avalia, incluindo os locals: próprios de uma FeatureRecipe —, então os dois nomes não são intercambiáveis, e nenhum substitui o outro.

.source é o da própria vinculação. O template source: de uma FeatureRecipe é avaliado antes do seu valuesMapping:, assim como o de uma Recipe é avaliado antes do seu, e o que ele produziu é o que .source contém nos templates que produzem os recursos da vinculação — o seu valuesMapping:, omits:, workload: e artifacts: — e nas suas etapas de pipeline:. Ele nunca é a fonte do componente host: uma FeatureRecipe que não declara nenhum source:, ou cujo template não produz nada, não lê nada ali, mesmo em um host cuja Recipe declara um. Uma FeatureRecipe com escopo de fronteira lê a sua própria fonte nos mesmos templates. A única exceção é o injectMapping:, que é executado antes de a fonte da vinculação ser avaliada e lê .source como a própria Recipe do componente host o faz.

.context.rendered_name também é o do componente host: em todo template de uma vinculação por componente, ele carrega o nome que o próprio provedor do host informa para o host — o valor que a própria Recipe do host lê —, de modo que uma vinculação nomeia um recurso segundo seu host com {{ .context.rendered_name }}-{{ .attachment_name }} e obtém um nome que a plataforma aceita mesmo onde a identidade do host contém um sublinhado ou uma letra maiúscula. Ele está presente onde quer que o provedor do host informe um nome e ausente onde não informa nenhum, e lê-lo em um host assim interrompe o build a partir de qualquer template que a FeatureRecipe escreva inline além de seu injectMapping:; veja Nomear um recurso renderizado.

Disponibilidade por ponto de template

A disponibilidade dos campos varia conforme o ponto de template. Os templates provides: de uma Recipe são executados na avaliação dos provides com um contexto autossuficiente (sem .context.inject/.context.uses); o valuesMapping: de uma Recipe é executado na renderização base com o contexto de template completo; o injectMapping: de uma FeatureRecipe é executado no mapeamento de inject com o contexto de template completo, incluindo o pipe de inject que está sendo interceptado. A tabela completa de disponibilidade ponto a ponto está em expansion-matrix.md; esta página documenta as formas dos campos para as quais a coluna “referências disponíveis” da matriz aponta.

Referências cruzadas