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

FeatureRecipe

O papel conceitual da entidade FeatureRecipe (Domínio 3 — a implementação de uma interface de Feature conduzida por plugins Wasm) está em architecture/04-entity-taxonomy.md. Esta página aborda a superfície de autoria de catálogo da FeatureRecipe.

Localização no catálogo

As FeatureRecipes são organizadas com o provider no primeiro segmento do caminho (mesmo padrão das Recipes):

aggrega-catalog/
└── feature-recipe/
└── {provider}/ # e.g., `helm`, `compose`
└── {feature-recipe-name}/
└── {version}/
└── recipe.yaml

URI OCI: hub.aggrega.ai/featurerecipe/{provider}/{name}:{version} (por exemplo, hub.aggrega.ai/featurerecipe/helm/k8s-secret-from-parameter:1.0.0).

Contrato de autoria

As FeatureRecipes se vinculam a uma interface de Feature por meio de implements e declaram um provider concreto. Sua superfície de autoria é o conjunto completo de tipos de entrada da Recipe base mais dois blocos específicos da FeatureRecipe:

  1. Os três tipos de entrada — source + valuesMapping (com origem), workload (sintetizado) e artifacts: idênticos em forma aos da Recipe base (consulte Composição de entradas da Recipe e entities/recipe.md). Uma FeatureRecipe que carrega qualquer um deles é geradora de recursos — ela renderiza recursos ao lado do componente base. O local onde esses recursos ficam carrega o componente ao qual a Feature está anexada e depois o nome sob o qual ela está anexada, na forma, entre as duas, que o layout próprio do destino admite: como um diretório {component}--{instance}/ ao lado do diretório do hospedeiro, sob o diretório em que esse destino coloca seus contribuidores, em um destino cujo provider dá a cada contribuidor uma posição própria; como um prefixo de nome de arquivo {component}--{instance}-- ao lado dos arquivos próprios do componente, em um destino que lê apenas os arquivos localizados diretamente em um diretório. Em um provider que compõe seus contribuidores em um único documento, os recursos são, em vez disso, incorporados a esse documento — qualquer que seja a família à qual a Feature pertence: um CRD ServiceMonitor ou ExternalSecret como artifacts: inline ou via $import; um chart ou módulo externo via source: + valuesMapping:; ou o próprio compute (por exemplo, um Deployment de agente sidecar) via workload:. valuesMapping: compartilha os três modos de autoria da Recipe base (block scalar inline, $import: de arquivo, $import: de biblioteca para uma entrada de uma MappingLibrary) — consulte entities/recipe.md “O campo valuesMapping — três modos de autoria”. Por convenção, uma FeatureRecipe modifica o componente base ou adiciona recursos ao lado dele, mas o schema não restringe quais tipos de entrada ela pode usar — o compilador renderiza o que quer que a FeatureRecipe declare, limitado apenas pela capacidade do provider associado, e permanece sem opiniões próprias sobre se um determinado tipo é “apropriado para modificadores” (consulte os invariantes fundamentais). A síntese (workload:) exige um provider que a suporte; caso contrário, o build é interrompido na renderização com o diagnóstico de capacidade do provider.
  2. injectMapping (interceptação pré-renderização): um bloco de template Go nativo executado antes de a Recipe base renderizar. Ele produz um dicionário JSON ou YAML que o compilador mescla nativamente em profundidade sobre o pipe de memória .context.inject do chamador, permitindo a mutação do lado do chamador, sem Wasm, de variáveis de ambiente e strings de conexão.
  3. pipeline: um array sequencial de etapas de plugins WebAssembly (Wasm) para a mutação de Workload pós-renderização (por exemplo, injetar um sidecar do Envoy via JSONPatch ou montar um volume de secret). O campo plugin de cada etapa nomeia uma entidade Plugin pelo seu URI, sempre com escopo pelo tipo de socket do próprio plugin (<pluginType>/<name>, opcionalmente versionado, como em parser/yaml ou parser/yaml:1.0.0); o build resolve a entidade para seu artefato .wasm endereçado por conteúdo, localizado a partir da identidade do plugin e do registry configurado, e um .wasm simples ou uma referência de artefato não é aceito aqui. Consulte o guia do desenvolvedor de plugins Wasm para criar e referenciar um plugin, e architecture/04-entity-taxonomy.md §“Domínio 3: base de infraestrutura” para o princípio do Plugin em duas partes (Fetcher / Injector). O compilador executa cada etapa na ordem declarada: ele despacha a exportação guest do plugin nomeado sobre a saída renderizada e aplica os JSON Patches retornados e os efeitos colaterais emitidos; consulte Status da linguagem para o estado de execução de cada superfície do pipeline. Um pipeline: é autossuficiente: uma FeatureRecipe pode declarar um e nenhum tipo de entrada, caso em que não emite recursos próprios e todo o seu efeito é o que suas etapas aplicam como patch aos documentos que o build já renderizou, ou emitem ao lado deles.

Uma FeatureRecipe também pode não carregar nenhum desses blocos: uma Feature de puro cabeamento cujo efeito é a aresta uses que ela carrega não renderiza nada, e sua FeatureRecipe existe apenas para satisfazer a resolução — toda instância de feature é resolvida para uma FeatureRecipe, da mesma forma que todo componente é resolvido para uma Recipe. Entre os blocos acima, injectMapping é o único campo sem contrapartida na Recipe base; os três tipos de entrada e pipeline são compartilhados com a Recipe base.

O que é fixado ao lado de uma FeatureRecipe é o que é fixado ao lado de uma Recipe: o digest de cada arquivo que uma entrada artifacts importa, e de cada source: remota cujas coordenadas estão escritas por completo, em um entity.lock no diretório da própria FeatureRecipe, que aggrega pin escreve e que você commita ao lado dela. Um pull sobre uma FeatureRecipe cujo lock não registra esses pins é interrompido e nomeia essa etapa, a menos que seja pedido ao pull que a execute. Um build é interrompido quando um arquivo importado não corresponde mais ao seu digest, e quando o digest de uma origem diverge daquele que o lockfile da Release registra (uma origem escrita em um ref: do git é registrada no commit para o qual foi resolvida e não é comparada); o arquivo da FeatureRecipe em si nunca é escrito. aggrega pull descreve o arquivo e como responder a cada interrupção.

Templating do campo source

O source: de uma FeatureRecipe é uma superfície de templating nos mesmos termos que o de uma Recipe: o template é avaliado na resolução da fonte, e o que ele produziu é o que o build resolve em seguida. Ambas as formas aceitam templates Go — a forma de string universal e a forma de objeto estruturado, cujos subcampos com valor de string são avaliados como template enquanto os subcampos que não são string passam inalterados. O inventário de formas, o tratamento de esquemas e a leitura da ancoragem são os descritos em entities/recipe.md “Templating do campo source”, “Inventário de esquemas do campo source” e “Como um caminho source: é ancorado”; esta seção indica apenas o que difere para uma anexação.

locals:
chart_dir: ./charts/exporter
source: "{{ .locals.chart_dir }}"

Em relação a que um resultado relativo é resolvido. O diretório que contém o documento FeatureRecipe que o declarou — o próprio arquivo da anexação, nunca o do componente — e o resultado deve permanecer dentro desse diretório, exatamente como para uma Recipe: um resultado que sai dele, ou que é um caminho absoluto, nomeia um arquivo que não viajaria com a FeatureRecipe e interrompe o build. Um que traz um esquema de transporte é buscado em vez de unido a um diretório. Uma FeatureRecipe resolvida a partir de um registro é lida dos arquivos que seu pacote publicado contém, dispostos no cache de conteúdo, de modo que um resultado relativo é resolvido dentro do que foi publicado exatamente como é resolvido ao lado da FeatureRecipe em um diretório de catálogo, sujeito ao mesmo limite.

O que o template pode ler. O conjunto de referências é aquele contra o qual as entradas locals: da própria FeatureRecipe são verificadas, que difere do de uma Recipe de duas maneiras que decorrem de se resolver uma anexação e não um componente:

  • .attachment_name está disponível, nomeando a instância sob a qual a Feature está anexada. O template de fonte de uma Recipe o recusa, porque a fonte de uma Recipe é resolvida para um nó e nenhuma anexação está em jogo.
  • .context.instance_id nomeia o componente host para o qual a anexação está sendo resolvida, não a anexação, e .context.rendered_name traz o nome que o próprio provedor do host informa para o host — presente apenas onde esse provedor informa um, e interrompendo o build onde não informa. Consulte Nomeando um recurso renderizado.

.locals traz o conjunto que os outros templates desta FeatureRecipe leem: seu próprio bloco resolvido, com o da Recipe host abaixo dele, de modo que uma chave que a anexação declara prevalece sobre uma chave do host com o mesmo nome. Uma referência a uma chave que esse conjunto não contém interrompe o build e a nomeia, em vez de fazer a chave desaparecer na renderização. .provides, .context.inject e .context.uses são recusados pelos mesmos motivos de autocontenção pelos quais a superfície de fonte de uma Recipe os recusa.

Uma FeatureRecipe com escopo de fronteira lê a fronteira em vez disso. Uma Feature cuja FeatureRecipe declara executionScope: boundary é renderizada uma vez para a fronteira em vez de uma vez por componente, então seu template de fonte não tem componente host para ler. Ele lê .boundary.* — os mesmos pilares que seus locals: e provides: leem — e os pilares por componente (.context, .workload, .attachment_name, .inject) não estão disponíveis para ele.

Um resultado vazio. Um template que não produz nada deixa a anexação sem fonte, que é o modo sem fonte — a mesma leitura que a fonte de uma Recipe adota, e distinta de você mesmo escrever source: "".

O que .source lê depois. O source é avaliado antes do valuesMapping:, assim como o de uma Recipe é avaliado antes do seu, e o que ele produziu é .source em cada template executado depois dele: o valuesMapping:, o omits:, os corpos de workload: e artifacts: e as etapas de pipeline:. Assim, um valuesMapping: que lê .source lê o source desta própria FeatureRecipe, nunca o source do componente ao qual ela está associada, e não lê nada quando esta FeatureRecipe não declara nenhum source ou seu template não produz nada. Uma FeatureRecipe com escopo de fronteira lê seu próprio source da mesma forma. O injectMapping: é executado antes de o source da associação ser avaliado, então .source ali é o do componente hospedeiro.

Exclusividade de injectMapping

O campo injectMapping é exclusivo das FeatureRecipes — está intencionalmente ausente do esquema base de Recipe. Essa exclusividade isola a interceptação de variáveis de valuesMapping: o valuesMapping da Recipe base consome, sem saber, as strings .context.inject reescritas geradas pelos blocos injectMapping da FeatureRecipe, de modo que os dois permanecem desacoplados. Consulte a seção sobre a interceptação de inject mapping abaixo para saber como o mecanismo funciona, e architecture/10-compilation-pipeline.md sobre o inject mapping para a semântica completa da interceptação pré-renderização.

Interceptação de inject mapping: como injectMapping funciona

Quando um chamador precisa que a string de conexão para seu destino tenha uma forma diferente do .provides.host não modificado do destino — acrescentando um namespace para o DNS do Kubernetes entre fronteiras, prefixando um código de região para um gateway multirregião ou adicionando um sufixo de modo SSL a um DSN —, injectMapping trata a modificação no chamador, antes que o valuesMapping da Recipe base sequer veja o canal de inject.

O campo injectMapping é um text/template Go que o renderizador avalia no inject mapping, antes que a renderização da Recipe base seja executada. O template produz um dicionário JSON ou YAML com chaves de mecanismo opcionais (env, file, arg, ou um mecanismo personalizado que a Recipe do componente lê em .context.inject.<name>) — ou um mapa plano que assume env por padrão — e o renderizador mescla em profundidade essa sobreposição sobre o canal .context.inject do nó chamador. O roteamento do lado do chamador via injectMapping é executado no inject mapping sem invocar um sandbox Wasm para manipulação simples de strings; os plugins Wasm continuam reservados para alterações estruturais da AST via o array pipeline.

Escreva cada valor por meio de toJson. O renderizador lê a saída do template como YAML, então um valor interpolado entre aspas como está quebra essa saída ou é lido de volta alterado assim que contém uma aspa dupla ou uma barra invertida — uma senha é o caso comum. toJson escreve o valor como uma string JSON, que o YAML lê de volta exatamente, de modo que o valor é entregue com todos os caracteres que contém:

injectMapping: |
env:
{{ .values.key }}: {{ .values.origin | toJson }}

Um valor montado a partir de várias partes é montado primeiro e escrito uma única vez por meio de toJson, como fazem os exemplos abaixo.

Uma saída que não pode ser lida interrompe o build. Quando a saída do template não é lida como nenhuma das duas formas — a causa habitual é um escalar entre aspas quebrado pelo valor dentro dele —, nenhuma de suas chaves poderia ser entregue, então o build é interrompido nomeando o anexo e a FeatureRecipe em vez de renderizar o componente como se nada tivesse sido entregue; consulte fatal-halts.md “An attached Feature’s injectMapping output cannot be read (A saída de injectMapping de uma Feature anexada não pode ser lida)”. O motivo informado é omitido quando depende de um valor declarado sensível. Uma saída vazia, ou que é interpretada como um dicionário que não entrega nada, não entrega nada e não é uma falha.

Uma chave de nível superior é um mecanismo, e all não é um. Cada chave de nível superior de uma saída em forma de dicionário nomeia o mecanismo pelo qual suas entradas são entregues: env, file e arg, ou qualquer outro nome, que é entregue como um mecanismo próprio com esse nome. .context.inject.all é construído a partir desses mecanismos após a mesclagem e nunca é mesclado a partir de uma saída, então entradas escritas sob all: não chegariam a lugar nenhum; em vez disso, o build é interrompido, nomeando o anexo, a chave e a FeatureRecipe, e informando quais chaves uma saída pode conter — consulte fatal-halts.md “An attached Feature’s injectMapping output writes deliveries under a key nothing delivers (A saída de injectMapping de uma Feature anexada grava entregas sob uma chave que nada entrega)”. Escreva essas entradas sob o mecanismo a partir do qual o componente as lê.

A modificação é estritamente local ao chamador. A FeatureRecipe modifica apenas o canal de inject do nó ao qual está anexada, nunca a saída .provides do destino. O .provides.host de um destino é consumido potencialmente por muitos chamadores em todo o cluster; o injectMapping do lado do chamador mescla apenas no canal do chamador específico, de modo que as modificações de roteamento permanecem restritas à aresta que as solicitou.

O que um mapeamento pode reescrever. Todo bloco inject: já entregou quando os mapeamentos são renderizados, então a saída de um mapeamento é sempre mesclada sobre chaves que outra coisa já escreveu — e quem escreveu uma chave decide o que acontece. Uma chave que o próprio bloco inject: do chamador ou o bloco inject: de uma de suas conexões entregou pode ser reescrita pelo mapeamento: isso é interceptação, e o valor do mapeamento substitui aquela única entrada. Uma chave que a própria anexação do mapeamento entregou por meio de seu bloco inject: também pode ser reescrita por ele. Uma chave que uma Feature anexada diferente já entregou — por meio de seu próprio bloco inject: ou do injectMapping de sua própria FeatureRecipe — não pode: o build é interrompido nomeando ambas as anexações, em vez de deixar que o mapeamento executado por último decida qual valor o chamador lê. Assim, duas Features de roteamento podem cada uma qualificar uma chave própria, mas duas Features não podem ambas entregar uma mesma chave — incluindo duas Features de roteamento que reescrevem a chave da mesma conexão, já que a primeira é interceptação e a segunda encontra a entrega da primeira; consulte fatal-halts.md “Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping” (Duas Features anexadas entregam uma mesma chave, a segunda pelo injectMapping de sua FeatureRecipe).

Inferência de destino sem acoplamento

Como o compilador incorpora as anotações em cascata de cada destino no canal .context.uses do chamador, o template injectMapping pode extrair coordenadas de roteamento sem que Ops codifique de forma fixa a identidade do destino no infra da Feature:

  1. O template pesquisa .context.uses para encontrar a aresta topológica exata que injetou a variável solicitada pelo desenvolvedor.
  2. Ele extrai as release_annotations em cascata do destino (por exemplo, aggrega.ai/namespace).
  3. Ele formata o nome de domínio totalmente qualificado (FQDN) ou a string de conexão.
  4. Ele emite o dicionário de substituição.

O compilador permanece agnóstico em relação à semântica de rede — namespaces do Kubernetes, regiões de nuvem, topologias bridge-proxy — e simplesmente executa a mesclagem em profundidade com o que quer que o template tenha produzido. Quando o valuesMapping da Recipe base é executado em seguida, ele consome as strings interceptadas e reescritas de .context.inject.env como se fossem as originais do desenvolvedor.

Exemplo completo: resolvedor de DNS do K8s

O catálogo padrão fornece isso como core/k8s-dns-resolver com uma FeatureRecipe helm. Como os nomes de variáveis de ambiente devem ser únicos dentro de um contêiner, a target_var (por exemplo, API_HOST) atua como um identificador globalmente único para um contrato de injeção específico dentro do chamador. Percorrendo as arestas explícitas em .context.uses e verificando qual aresta reivindicou a target_var, o template localiza o nó de destino correto e lê seu namespace. O único parâmetro é a variável a reescrever; o destino e seu namespace são descobertos, nunca codificados de forma fixa.

O esquema da Feature de roteamento (core/k8s-dns-resolver):

infra: {
target_var: string # Ops dictates WHICH injected var to rewrite
}

A implementação da FeatureRecipe:

injectMapping: |
# 1. Grab the atomic base host directly from the flattened pipe, or an
# empty value when nothing was injected under target_var
{{ $base_host := optional .context.inject.env .infra.target_var "" }}
# 2. Dynamically locate the specific edge that injected this variable
{{ $target_edge := dict }}
{{ range $alias, $edge := .context.uses }}
{{ if hasKey $edge.inject.env $.infra.target_var }}
{{ $target_edge = $edge }}
{{ end }}
{{ end }}
# 3. Read the target's namespace from its cascaded release annotation,
# coalescing an absent namespace to "default"
{{ $ns := "default" }}
{{ if $target_edge.annotations }}{{ if $target_edge.annotations.release }}
{{ $raw := optional $target_edge.annotations.release "aggrega.ai/namespace" "" }}
{{ if $raw }}{{ $ns = $raw }}{{ end }}
{{ end }}{{ end }}
# 4. Qualify the host with the namespace — but only when a target connection
# and a base host were actually found, so a target_var that matches no
# connection injects nothing instead of a spurious variable. An unset
# namespace resolves to "default", where the helm provider deploys an
# unannotated workload, so the qualified host always matches the service's
# actual location and is never malformed.
{{ if and $target_edge $base_host }}
{{ $resolved_host := printf "%s.%s" $base_host $ns }}
# 5. Emit the precise override dictionary for the compiler to deep-merge
env:
{{ .infra.target_var | toJson }}: {{ $resolved_host | toJson }}
{{ end }}

Casos de uso além do roteamento

injectMapping é mais comumente usado para resolução de endereços entre fronteiras (como o resolvedor de DNS do K8s acima), mas essa modificação do lado do chamador se aplica a qualquer cenário que exija interceptar e formatar a intenção do desenvolvedor antes da renderização da infraestrutura. Dois outros padrões ilustram a abrangência.

Formatação dinâmica de segurança (o anexador de SSL). Se uma empresa exige que todas as conexões com bancos de dados externos usem verificação TLS estrita, uma Feature pode interceptar o DB_URL solicitado pelo desenvolvedor e acrescentar o modo SSL necessário, para que a aplicação inicie com os parâmetros de segurança corretos.

# Inside force-ssl-feature
injectMapping: |
{{ $base_url := index .context.inject.env .infra.target_var }}
env:
{{ .infra.target_var | toJson }}: {{ printf "%s?sslmode=verify-full" $base_url | toJson }}

Prefixação de gateway multirregião. Se um componente de API genérico é implantado globalmente, uma Feature de roteamento regional pode consultar de forma autônoma as anotações de sua própria fronteira de ambiente para prefixar as strings de conexão injetadas para seus chamadores.

# Inside regional-router
injectMapping: |
{{ $base_host := index .context.inject.env .infra.target_var }}
{{ $region_code := index .context.annotations.release "cloud.aggrega.ai/region" }}
env:
{{ .infra.target_var | toJson }}: {{ printf "%s.%s" $region_code $base_host | toJson }}

O limite de injectMapping. O mecanismo se limita a modificar o canal de memória .context.inject (o contrato de entrega). Ele não pode acrescentar novos contêineres, montar volumes nem alterar a saída do valuesMapping da Recipe base. Qualquer modificação que exija mudanças estruturais na AST renderizada (como arrays JSON ou YAML) pertence ao array pipeline da FeatureRecipe, executado via plugins WebAssembly.

O limite dos alvos de patch de pipeline. Uma etapa de pipeline aplica patch apenas à saída que o provedor renderiza em uma árvore estruturada. A saída em forma de YAML e JSON é estruturada — incluindo módulos Terraform .tf.json escritos em JSON —, de modo que o JSONPatch de uma etapa edita no lugar os valores endereçados, deixando intocado todo outro byte (comentários, ordenação, formatação). A saída que o provedor emite como corpo opaco, como configuração Terraform em HCL nativo, não é um alvo de patch: um patch contra um corpo opaco interrompe o build com um diagnóstico em vez de modificar texto que não consegue endereçar estruturalmente. Escrever uma etapa de pipeline contra uma saída opaca é, portanto, um erro de projeto que aparece como uma interrupção explícita, não como um no-op silencioso.

As entradas de um módulo Terraform vendorizado não são um alvo de patch, e vale a pena declarar essa ausência. Elas são os argumentos do bloco module desse componente, que o provedor terraform escreve na configuração raiz da fronteira: HCL nativo, portanto opaco pela regra acima, e um artefato de toda a fronteira e não do nó cuja saída a etapa modifica. Portanto, não há posição a partir da qual uma etapa de pipeline possa endereçá-las, nem nada que ela possa fazer para mudar o que um módulo Terraform obtido via source recebe. Esses valores são moldados onde são escritos — no valuesMapping: da Recipe base.

Etapas condicionais — when:

Uma etapa de pipeline pode ter um campo when: opcional: um template Go inline que o compilador avalia durante o percurso do pipeline, com o mesmo contexto de template e o mesmo avaliador que o corpo with: da etapa usa. O resultado renderizado decide se a etapa é executada.

  • Um resultado falsy pula a etapa como uma passagem direta: o conjunto de documentos segue inalterado para a próxima etapa, e a etapa pulada não contribui com nada — nenhum patch, nenhum efeito colateral, nenhum registro de ter sido executada.
  • Um when: vazio ou ausente sempre executa a etapa.

when: e optional: são independentes. when: decide se uma etapa é executada ou não; optional: atenua a falha de uma etapa em execução. Uma etapa pode declarar ambos — when: controla a entrada e, se a etapa for executada, optional: rege como uma falha dentro dela é tratada. Um template when: que falha ao renderizar é um defeito de autoria e interrompe o build independentemente de optional:.

O texto when: renderizado é avaliado pela regra compartilhada de templates booleanos: as strings true, True e TRUE, qualquer número diferente de zero e qualquer outra string não vazia são verdadeiros; as strings false, False e FALSE, a string vazia e um número zero são falsos.

Padrão de FeatureRecipe de credenciais

Quando uma FeatureRecipe implementa uma Feature de credenciais (uma rotulada feature.aggrega.ai/kind: secret), ela pode seguir o princípio do Plugin em duas partes: uma pipeline que encadeia um plugin Fetcher (que gera a CRD específica do cofre) e um plugin Injector (que monta o secret no contêiner de destino), a forma que examples/04-secrets descreve. As FeatureRecipes de credenciais da biblioteca padrão não declaram nenhuma pipeline: e renderizam elas mesmas o recurso do secret; consulte examples/05-credential-features.

Uma FeatureRecipe de credenciais é renderizada pela mesma passagem de geração de recursos que a de qualquer outra anexação, e sua pipeline: é executada nos mesmos termos: o compilador percorre cada anexação que tem trabalho nessa passagem como uma única sequência ordenada e executa o pipeline declarado de cada uma, com a mesma semântica de conjuntos de documentos /own e /host. Uma anexação entra nessa sequência por um de dois motivos — sua FeatureRecipe declara um tipo de entrada, então gera recursos próprios, ou declara uma pipeline:, então reescreve documentos já emitidos. Uma anexação de credenciais pode, portanto, atuar sobre os documentos renderizados do componente host — montando um volume de secret, adicionando uma referência env — exatamente como uma anexação operacional pode, e a única diferença entre as duas é onde seus próprios arquivos gerados vão parar.

Em um componente, uma declaração de sensibilidade na Feature segue o valuesMapping: da FeatureRecipe exatamente como a de um Component segue o de sua Recipe. Onde uma FeatureRecipe renderiza a partir de um source: sem valuesMapping:, os valores que seu destino recebe têm como chaves os caminhos de folha que a Feature declara, de modo que uma folha declarada sensitive: true marca sua chave renderizada. Onde a FeatureRecipe declara um valuesMapping:, as chaves são invenção própria desse template, nenhuma declaração as nomeia, e o build imprime um aviso por folha desse tipo, nomeando a anexação, a folha e a FeatureRecipe. Uma Feature anexada a uma fronteira não gera nenhum: seu .values está sempre vazio, de modo que nenhuma folha declarada tem um valor a marcar — consulte A declared-sensitive value reaches the target through a values mapping (Um valor declarado sensível chega ao destino por meio de um values mapping).

O bloco provides: — publicação para o consumidor

O bloco provides: de uma FeatureRecipe é sua saída publicada: um mapa com valores string de templates Go avaliados no escopo próprio da anexação (.values, .infra, os .locals totalmente resolvidos da FeatureRecipe, e .context.instance_id e .context.rendered_name do nó host). Os locals são resolvidos primeiro, então uma entrada de provides: os lê e recebe valores resolvidos; nomear uma chave que o bloco locals: não declara interrompe o build. É assim que uma anexação informa ao seu consumidor o que produziu — o nome de um recurso emitido, uma chave de dados gerada, uma identidade de nuvem — sem que o consumidor derive novamente essa identidade a partir das mesmas entradas.

O consumidor o lê em .features.<instance-name>.provides.<key> (ou .features.<slot>.provides.<key> para uma anexação de credenciais), espelhando .context.uses.<alias>.provides para uma aresta uses. Onde a anexação é escrita em uma das conexões do consumidor, o consumidor lê o mesmo mapa sob essa conexão, em .context.uses.<alias>.features.<slot>.provides.<key>, e a anexação não está entre suas .features (consulte As anexações de uma conexão). O próprio bloco inject: da anexação resolve suas referências from: contra o mesmo mapa, então um autor pode escolher qualquer um dos canais: provides para uma leitura de template, inject para entrega em uma variável de ambiente, arquivo ou argumento.

# FeatureRecipe: emits a ServiceAccount and publishes its name.
provides:
name: "{{ .infra.service_account_name }}"
# Consuming Recipe: binds the pod to what the attachment published.
workload: |
serviceAccount: "{{ .features.identity.provides.name }}"

Quando a Feature que esta FeatureRecipe implements declara um contrato schema.provides, o contrato é aplicado à FeatureRecipe: toda chave que a Feature declara deve aparecer no provides: da FeatureRecipe, ou o build é interrompido nomeando a chave ausente. Chaves publicadas extras são permitidas — o contrato é um piso, não um teto. Os valores nunca são inspecionados; são ponteiros determinísticos opacos que o runtime resolve.

A resolução acontece uma vez por anexação, antes que o consumidor seja renderizado, e o mesmo mapa resolvido alimenta a leitura do consumidor, a verificação do contrato e a própria geração de recursos da anexação — de modo que o que o consumidor lê e o que a anexação emite não podem divergir.

Provider & implements

spec.capability é obrigatório e nomeia o provedor cujo plugin de renderização Wasm renderiza a saída da FeatureRecipe (helm, helm-chart, compose, etc.), nos mesmos termos do spec.capability de uma Recipe (consulte entities/recipe.md): um pin de versão seleciona qual versão desse plugin a renderiza, e não faz parte do nome da FeatureRecipe — um Manifest mapeia uma FeatureRecipe que declara capability: "compose:1.2.3" como compose/<name>:<version>, e um valor de mapeamento que escreve o pin no nome é recusado como referência de receita malformada (E0095) antes de qualquer consulta. O campo implements vincula a FeatureRecipe à sua interface de Feature e suporta correspondência exata, por intervalo compatível com a versão major ou sem versão — consulte vocabulary/inheritance-and-interface para a semântica de correspondência de versões de implements.

Escopo de execução — spec.executionScope

O enum opcional spec.executionScope seleciona o modelo de despacho da geração de recursos. Dois valores são aceitos; quando o campo é omitido, o padrão é component.

  • component (padrão). A geração de recursos da FeatureRecipe é executada uma vez por instância de componente anexada. Cada invocação recebe um contexto de template por componente com raiz em .context.*: .context.instance_id, .context.inject, .context.uses, .context.annotations etc. Seus valuesMapping:, workload: e artifacts: também leem .context.used_by, os componentes cujas entradas uses apontam para o host — cada um com sua identidade, seu socket, o que publica e o namespace e a fronteira em que está posicionado —, que nenhum template renderizado pelo próprio host consegue ver.
  • boundary. A geração de recursos é executada uma vez por fronteira anexada, independentemente de quantos componentes dentro da subárvore da fronteira consumam a funcionalidade. Cada invocação recebe um contexto de template com escopo de fronteira com raiz em .boundary.* em vez de .context.*.

A interceptação injectMapping descrita acima é sempre por consumidor, independentemente de executionScope. Cada componente que usa a funcionalidade continua recebendo sua própria reescrita do lado do chamador de .context.inject. Somente a etapa de geração de recursos (source/valuesMapping e o array pipeline) é deduplicada no escopo de fronteira.

Os templates de uma FeatureRecipe com escopo de fronteira são, portanto, executados em dois escopos. Seu injectMapping é executado uma vez para cada componente que a anexação alcança, contra o contexto desse componente — o mesmo que o injectMapping de uma FeatureRecipe com escopo de componente lê: .context.*, .attachment_name, .features e os .values, .infra e .locals próprios da anexação. Seu .infra é o bloco infra: da anexação à fronteira, e seu .locals é o bloco avaliado uma única vez para a fronteira. Todo outro template que ela escreve — entre eles seus locals:, provides:, source:, valuesMapping: e artifacts: e os with: e when: das etapas do seu pipeline — é executado uma vez para a fronteira, contra o contexto com escopo de fronteira descrito abaixo. Cada template é verificado contra o escopo em que é executado: um valuesMapping: que lê .context.instance_id interrompe a build, e um injectMapping que o lê renderiza a identidade desse componente. .boundary não é definido no contexto de nenhum componente, então um injectMapping que o lê interrompe a build nomeando a referência, qualquer que seja o executionScope da FeatureRecipe.

Contexto de template com escopo de fronteira

Quando executionScope: boundary, os templates da FeatureRecipe, exceto seu injectMapping, são avaliados contra uma visão .boundary.* da fronteira à qual a funcionalidade está anexada. A visão expõe:

  • .boundary.path — o caminho da fronteira da Release à qual a funcionalidade está anexada: os nomes das fronteiras da mais externa para dentro, unidos com / (bridge, bridge/frontend). Ele nomeia a fronteira, não o diretório em que sua saída é gravada, que é definido por directory: (substitui .context.instance_id).
  • .boundary.assembly_path — o diretório, relativo ao diretório de saída da build, no qual a saída própria da anexação é montada: os directory: e subDirectory: avaliados da fronteira, ou seja, o diretório para o qual a build encaminha essa saída (bridge/compose). Ele é igual ao source_assembly_path ou ao target_assembly_path de uma extremidade de conexão exatamente quando essa extremidade é renderizada no mesmo arquivo montado, de modo que uma FeatureRecipe os compara para distinguir uma conexão dentro do seu próprio arquivo de uma em outro arquivo.
  • .boundary.boundary_name — o nome da fronteira tal como escrito na Release.
  • .boundary.components — um mapa indexado por ID de instância contendo cada componente da subárvore da fronteira (instance_id, component, resolved_version, boundary_path).
  • .boundary.internal_uses_edges — arestas uses: em que ambas as extremidades estão dentro da subárvore desta fronteira (o padrão compose-bridge as enumera, mantendo as arestas cujas duas extremidades são montadas no seu próprio arquivo compose e posicionadas em redes diferentes dele, para derivar sua configuração de proxy por aresta). Cada aresta carrega os provides resolvidos de suas extremidades, as variáveis de ambiente injetadas e o posicionamento de cada extremidade: source_namespace e target_namespace, a anotação aggrega.ai/namespace que se aplica a essa extremidade — a configuração da sua própria entrada da Release, quando ela tem uma, ou caso contrário a da sua fronteira; source_boundary_path e target_boundary_path, o caminho da fronteira da Release que a contém; e source_assembly_path e target_assembly_path, o diretório sob o diretório de saída da build no qual seu provider a monta, composto a partir dos directory: e subDirectory: avaliados da sua fronteira (bridge/compose). Duas extremidades com o mesmo caminho de montagem são renderizadas em um único arquivo montado, e o provider compose lê o caminho de montagem como a rede da extremidade quando nenhum namespace se aplica.
  • .boundary.outgoing_cross_boundary_uses_edges — arestas com a origem dentro da subárvore e o destino fora.
  • .boundary.incoming_cross_boundary_uses_edges — arestas com o destino dentro da subárvore e a origem fora (usadas por agregadores no estilo ingress).
  • .boundary.cross_boundary_uses_edges — a união das arestas entre fronteiras de entrada e de saída, quando a FeatureRecipe quer a visão completa entre fronteiras.
  • .boundary.labels — a união dos labels da subárvore, preservando a ordem de escrita.
  • .boundary.annotations — as anotações próprias da fronteira mais a cascata.
  • .boundary.feature_attachments — cada funcionalidade anexada a esta fronteira (para que uma FR com escopo de fronteira possa inspecionar suas irmãs, se necessário).

O pilar .infra em uma FR com escopo de fronteira é resolvido para o bloco infra: da funcionalidade anexada à fronteira (o dimensionamento físico escrito do lado da Release para essa anexação à fronteira). .values está sempre vazio para FRs com escopo de fronteira: a regra de separação de pilares do schema da Release proíbe values: em anexações de Feature no nível da Release, então uma funcionalidade anexada a uma fronteira não carrega valores a projetar. FRs com escopo de fronteira que precisam de dados em forma de parâmetros devem consumi-los via .infra (a superfície de autoria do operador para a configuração de funcionalidades de fronteira) ou via .boundary.annotations (valores string resolvíveis por cascata, escritos na fronteira ou em qualquer ancestral); .parameters não faz parte da visão, e um template que o lê é interrompido nomeando as raízes que a visão define. .locals continua sendo o próprio bloco locals da FR. .steps e .metadata permanecem inalterados.

Lista de campos permitidos em templates com escopo de fronteira

FRs com escopo de fronteira só podem referenciar campos disponíveis na visão com escopo de fronteira, em todos os templates exceto o injectMapping. Escrever um template desse tipo que referencie um campo exclusivo do escopo de componente (por exemplo, .context.instance_id, .context.inject, .context.uses) quando executionScope: boundary faz a FeatureRecipe falhar na validação no momento do parsing, com um erro que nomeia a FR, o campo problemático e os campos que a visão com escopo de fronteira define. A regra espelhada se aplica na direção oposta: uma FR com escopo de componente que referencia campos .boundary.* falha no mesmo validador. O injectMapping é verificado contra o contexto do componente em que é executado, em qualquer um dos escopos, então ele pode ler .context.*, e uma referência a .boundary nele é interrompida nomeando a referência e as raízes que esse contexto define.

O validador executa o mesmo percurso pela AST dos templates que a lista de variáveis permitidas dos templates de caminho usa, com um conjunto de referências diferente para cada escopo.

Deduplicação e saída da geração de recursos

Para executionScope: boundary, o compilador deduplica a geração de recursos pela tupla (boundary_path, FR-instance). Dois componentes na mesma subárvore de fronteira que consomem a mesma funcionalidade anexada à fronteira disparam uma única invocação da FR, não duas. Anexações da mesma funcionalidade em fronteiras diferentes são executadas de forma independente para cada fronteira.

Uma FR com escopo de fronteira emite um conjunto de arquivos não intermediários por tupla (boundary_path, FR-instance), e onde eles ficam decorre de como o provider combina a saída da sua fronteira. Aqui a coordenada é apenas o nome da instância, enquanto uma anexação com escopo de componente carrega também o seu componente: uma funcionalidade com escopo de fronteira é anexada à fronteira, e não a um componente, de modo que o diretório da fronteira que a contém já diz tudo o que um segmento de componente diria, e não há componente a nomear.

Um provider que grava cada documento diretamente no diretório da fronteira declara que seu destino lê apenas os arquivos localizados diretamente em um diretório. Portanto, não há um diretório envolvente em que uma anexação possa ficar, e o nome da instância se torna, em vez disso, um prefixo do nome do arquivo: <boundary_directory>/<fr-provider>/<feature-instance>--<file>, ao lado dos arquivos próprios da fronteira. O nome da instância é codificado, porque um nome de arquivo não tem um separador em que se apoiar, e ele encontra o nome próprio do arquivo em um limite de dois caracteres que nenhuma coordenada codificada pode conter — de modo que duas anexações que emitem o mesmo nome de arquivo ainda chegam a dois arquivos.

Um provider que compõe a saída da sua fronteira em uma estrutura envolvente — um chart contendo um chart por contribuidor, uma configuração raiz contendo um módulo por contribuidor — posiciona cada contribuidor em um subdiretório próprio, e uma anexação à fronteira é um contribuidor como qualquer outro. Sua saída fica então em <boundary_directory>/<fr-provider>/<contributors-directory>/<feature-instance>/, onde <contributors-directory> é o nome que esse destino dá ao lugar onde ficam suas unidades filhas. O subdiretório carrega o nome de instância da anexação, que é o nome com que você a escreveu no bloco features: da fronteira, de modo que o diretório que uma build produz é um que você consegue encontrar no que escreveu.

A saída intermediária flui para o montador por (caminho, provider) da fronteira, no caminho avaliado da FR e sob a spec.capability própria da FR — esse é o mecanismo que a Feature core/compose-bridge usa para mesclar um serviço de ponte junto aos contribuidores compose por componente no mesmo caminho de montagem. Essa saída é gravada apenas como parte do arquivo montado ali a partir dos componentes da fronteira, então, quando nenhum deles chega a esse caminho — cada componente enviado para outro lugar pelo seu subDirectory:, por exemplo —, a build é interrompida nomeando a fronteira, a Feature, o caminho para o qual sua saída foi encaminhada e o provider, em vez de gravar a saída em lugar nenhum (veja “A boundary-level Feature’s output reaches no assembled file (A saída de uma Feature no nível de fronteira não chega a nenhum arquivo montado)” em fatal-halts.md).

Resolução de provides: ciente da cascata

FRs com escopo de fronteira produzem um conjunto de provides: por tupla (boundary_path, FR-instance), avaliado uma única vez. O template provides: da FR é avaliado com o contexto de template com escopo de fronteira (então ele pode referenciar .boundary.components, .boundary.path, .infra, mas não campos por consumidor nem .values). Os valores de provides são constantes em relação aos consumidores — todo consumidor na subárvore da fronteira vê os mesmos valores fornecidos.

A resolução, do lado do consumidor, dos provides de uma FR com escopo de fronteira lê essa única avaliação em todos os lugares. Cada componente que a anexação alcança a lê em .features.<instance-name>.provides.<key> — nos templates da sua própria Recipe e no injectMapping próprio da FeatureRecipe, que é executado no contexto desse componente. Um Component consumidor que lê através de uma aresta uses carregada pela anexação, em .context.uses.<feature-alias>.provides.<provided-name>, obtém os mesmos valores: o compilador o resolve para o provides: da FeatureRecipe com escopo de fronteira para a fronteira em que o consumidor está, percorrendo desde a aresta uses do consumidor — que carrega a identidade da instância de funcionalidade por anexação — até o provides: da FR com escopo de fronteira. Uma pré-passagem avalia esses provides antes da montagem dos consumidores, de modo que os valores estão presentes quando o pipe do consumidor é construído.

Um efeito por consumidor é uma tabela em provides: lida por injectMapping. Uma FeatureRecipe com escopo de fronteira que precisa alterar algo para cada consumidor calcula uma única vez, no seu provides:, uma tabela indexada por consumidor a partir das conexões da fronteira, e seu injectMapping lê as linhas do componente atual — (index .features .attachment_name).provides, indexadas por .context.instance_id — e as entrega pelo próprio pipe do consumidor, segundo a regra que todo mapping segue (veja O que um mapping pode reescrever). O compilador encaminha a tabela que a FeatureRecipe escreveu e não lê nada nela.

O padrão compose-bridge

A FeatureRecipe compose-bridge é o padrão canônico de FR com escopo boundary, e é conteúdo de catálogo escrito com os mecanismos acima: nem o compilador nem o provider compose contêm qualquer lógica do bridge, então um catálogo pode realizar a Feature core/compose-bridge de outra forma. Uma feature core/compose-bridge é anexada a um boundary pai que contém dois sub-boundaries (por exemplo, services-net e data-net) com directory: compartilhado, cada um com sua própria anotação aggrega.ai/namespace (aggrega.ai/namespace: services-net, aggrega.ai/namespace: data-net) para que cada um fique em uma rede própria; sem as anotações, ambos compartilham a única rede nomeada a partir do caminho do seu arquivo compose e se alcançam mutuamente sem bridge. Seu executionScope: boundary executa a FR uma vez por anexo ao boundary pai.

Seu provides: calcula a tabela do bridge, uma única vez. De .boundary.internal_uses_edges ele mantém as arestas cujos dois extremos são montados no seu próprio arquivo compose — source_assembly_path e target_assembly_path ambos iguais a .boundary.assembly_path — e estão em redes diferentes desse arquivo, sendo a rede de um extremo o seu aggrega.ai/namespace, ou então o seu caminho de montagem. Uma aresta entre dois arquivos compose não é ligada por bridge, e o seu consumidor mantém o nome próprio do destino. Cada aresta ligada por bridge recebe uma porta de escuta — a porta própria do destino ou, onde uma aresta anterior já escuta nela, a primeira porta livre igual ou superior ao portBase do anexo (padrão 10000) — e um upstream, o host publicado do destino (o campo provides que o providesField do anexo nomeia, padrão host) e sua port; o upstream é derivado da aresta, nunca escrito à mão. A partir da mesma tabela, ele calcula a reescrita de cada consumidor: uma variável que a aresta entrega a partir do campo host passa a ser aggrega-gw:<listen port>, ou aggrega-gw onde a mesma aresta também entrega uma variável a partir de port, que passa então a ser a porta de escuta.

Seu injectMapping entrega as linhas de cada consumidor. Executado no contexto de cada consumidor, ele lê as linhas desse consumidor na tabela em .features.<attachment>.provides e as entrega por cima dos valores que a própria conexão do consumidor entregou (por exemplo, DB_HOST), o que é uma interceptação; um consumidor sem linha não recebe nada. Onde outra Feature anexada ao consumidor entregou essa chave — por meio do seu bloco inject: ou do seu injectMapping — o build é interrompido nomeando ambas as Features em vez de substituir essa entrega (veja “Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping (Duas Features anexadas entregam uma mesma chave, a posterior por meio do injectMapping da sua FeatureRecipe)” em fatal-halts.md). O listen do gateway e a reescrita do consumidor são lidos de uma única tabela, então concordam por aresta por construção, incluindo as colisões reatribuídas via portBase.

Seu valuesMapping escreve o gateway. O fragmento compose próprio da FeatureRecipe declara o serviço aggrega-gw. Onde algo é ligado por bridge, seu valuesMapping adiciona um bloco nginx stream server por aresta ligada por bridge (listen <port>; set $uN <target-host>:<target-port>; proxy_pass $uN;, sob uma diretiva resolver para que cada upstream seja resolvido no momento da conexão em vez de uma única vez na inicialização; o $ nessas variáveis é escrito $$ para que a interpolação $ do Docker Compose deixe um $ literal para o nginx), entregue como uma configuração compose montada — uma entrada configs: de nível superior com content: inline, referenciada a partir de aggrega-gw e montada em /etc/nginx/nginx.conf (para que o nginx a carregue sem um command: escrito pelo autor). configs.content inline requer Docker Compose ≥ 2.23.1. Ele também nomeia cada extremo ligado por bridge sob o x-aggrega-networks-of do gateway, que o provider compose resolve nas redes em que esses extremos são colocados, de modo que o gateway entra em todas as redes que suas arestas ligadas por bridge abrangem (a rede do consumidor e a do destino) — em tempo de execução, o consumidor pode alcançar aggrega-gw:<port> e o gateway pode fazer proxy_pass para o destino. Onde nada é ligado por bridge, o gateway que o fragmento declara ainda é renderizado, ocioso: nenhuma configuração, nenhuma rede extra e nenhuma reescrita.

O montador compose por (caminho, provider) mescla o gateway junto aos contribuintes por componente no mesmo caminho avaliado: um único docker-compose.yaml contendo todos os componentes mais o gateway do bridge. Onde nenhum dos componentes do boundary é montado no arquivo do gateway, o build é interrompido em vez de escrever o gateway em lugar nenhum. O upstream é um ponteiro determinístico, fixado em tempo de compilação, para um serviço compose; o DNS de tempo de execução do compose o resolve (nenhuma resolução de tempo de execução em tempo de compilação).

Renderização depois dos chamadores — spec.readsCallerRenderFacts

O campo opcional spec.readsCallerRenderFacts (booleano, padrão false) declara que os templates desta FeatureRecipe leem o que os componentes que se conectam ao seu host renderizaram: os fatos de renderização que o provider de cada um desses chamadores relata sobre a saída que emitiu. O que um provider relata, e sob quais nomes, é o contrato próprio desse provider; Relatar fatos sobre o que um guest emitiu descreve os fatos que um provider pode relatar.

Quando um anexo desse tipo é renderizado. O build renderiza seus componentes um de cada vez, em uma ordem fixa, e um anexo normalmente é renderizado logo depois do componente ao qual está anexado. Um componente que se conecta ao host e vem depois nessa ordem ainda não foi renderizado nesse ponto, então nada do que ele emitiu existe para ser lido. Um anexo cuja FeatureRecipe define readsCallerRenderFacts: true é renderizado, em vez disso, depois que todos os componentes do build foram renderizados, junto com todos os anexos que não definem nem esta chave nem readsTargetRenderFacts — assim a renderização de cada chamador está completa antes de o anexo ser avaliado. Sua saída vai para onde teria ido e com os mesmos nomes; a chave muda quando o anexo é renderizado, não o que ele renderiza. Uma ordenação decorre da renderização posterior: onde a FeatureRecipe traz uma pipeline que reescreve os documentos do seu componente host e o provider do host escreve documentos discretos, essas etapas são executadas depois das pipelines dos outros anexos do host em vez de na ordem de anexação deles.

O que ele lê. Com a chave definida, cada entrada de .context.used_by traz .render_facts: os fatos de renderização do chamador, indexados por nome de fato. Todo fato de renderização é uma lista, então um template sempre a percorre com range — mesmo quando ela contém uma única entrada. Suas entradas podem vir da renderização própria do chamador e das renderizações das Features anexadas ao chamador: as listas que um nome recebe de cada um são unidas em uma só, primeiro as chamadas do provider próprio do chamador, depois cada uma das suas Features na ordem em que foram renderizadas. Uma Feature do chamador que também define a chave é renderizada depois de todos os componentes, então o que ela relatou não está entre elas. Um chamador cujos providers não relatam nada traz um .render_facts vazio, então um nome que ninguém relatou é lido como nada:

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

Quais nomes de fato existem, e o que cada entrada contém, é o contrato documentado do provider do chamador — os do provider helm, por exemplo, são seus fatos de renderização, que nomeiam os labels dos pods que ele renderizou. Os fatos dos chamadores estão nas conexões que valuesMapping:, workload: e artifacts: da FeatureRecipe leem; with: e when: de uma etapa pipeline: não veem de forma alguma os componentes que se conectam ao host, então uma etapa lê apenas os fatos próprios do host. Toda FeatureRecipe anexada a um componente — defina ela ou não a chave — lê os fatos próprios do componente em .context.render_facts, no mesmo formato; o contexto de templates descreve ambos.

Declare-a sempre que um template ler os fatos. Um template escrito inline em uma FeatureRecipe que não define a chave — seu valuesMapping:, seu workload: ou uma entrada de artifacts: — que lê render_facts sob .context.used_by interrompe o build antes que qualquer coisa seja renderizada, nomeando a referência e o campo em que foi escrita (veja “A template reads its callers’ render facts without declaring it (Um template lê os fatos de renderização dos seus chamadores sem declarar isso)” em fatal-halts.md). A verificação lê o template como está escrito, então não vê uma referência construída enquanto o template é executado, nem uma escrita em conteúdo importado de um arquivo ou de uma biblioteca — e um template que lê um campo chamado render_facts de alguma outra lista ao lado de .context.used_by, ou que lê os fatos próprios do host como .render_facts dentro de {{ with .context }} ao lado dela, é tratado como se lesse os fatos dos chamadores; escreva os do próprio host por extenso como .context.render_facts. É a chave, não a verificação, que decide quando o anexo é renderizado, então defina-a em toda FeatureRecipe cujos templates leiam os fatos de renderização dos seus chamadores, seja como for que os alcancem; defini-la não custa nada além da renderização posterior.

Uma etapa de pipeline lê apenas os fatos próprios do seu host. Uma etapa pode reescrever os documentos próprios do componente host, e a saída própria de um componente permanece a mesma independentemente de quem se conecte a ele, então with: e when: de uma etapa nunca veem os componentes que se conectam ao host — defina ou não a FeatureRecipe a chave, que decide quando o anexo é renderizado e nada sobre o que uma etapa vê. Um with: ou when: de uma etapa escrito inline que lê render_facts sob .context.used_by portanto interrompe o build antes que qualquer coisa seja renderizada, com o código curto E0326, nomeando a referência e o campo da etapa — em vez de renderizar um valor vazio. Leia os fatos próprios do host em uma etapa em .context.render_facts, escrito por extenso, e leia os fatos dos chamadores em valuesMapping:, workload: ou artifacts: da FeatureRecipe. Essa verificação lê o template como está escrito, com os mesmos limites da anterior.

Escopo. A chave se aplica a uma FeatureRecipe que é renderizada uma vez por componente — executionScope: component, o padrão. Uma FeatureRecipe que declara executionScope: boundary é renderizada onde sempre é, defina ou não a chave, e os templates que produzem seus recursos leem .boundary em vez de .context.

Renderização depois dos destinos — spec.readsTargetRenderFacts

O campo opcional spec.readsTargetRenderFacts (booleano, padrão false) declara que os templates desta FeatureRecipe leem o que os componentes aos quais seu host está conectado renderizaram: os fatos de renderização que o provider de cada um desses destinos relata sobre a saída que emitiu. Ele lê a outra ponta de uma conexão em relação a readsCallerRenderFacts — os componentes para os quais apontam as entradas uses do host, em vez dos componentes cujas entradas uses apontam para o host — e tudo o que diz respeito aos próprios fatos é lido da mesma forma.

Qualquer uma das chaves faz o anexo ser renderizado depois de todos os componentes. Um anexo cuja FeatureRecipe define readsCallerRenderFacts: true, readsTargetRenderFacts: true ou ambas é renderizado depois que todos os componentes do build foram renderizados, como descreve a seção acima — existe uma única renderização posterior desse tipo, e o que ela implica para onde a saída do anexo vai e para a ordem das suas etapas de pipeline é o mesmo, qualquer que seja a chave que levou o anexo para lá. As duas chaves diferem apenas em quais conexões trazem fatos no contexto do anexo: um destino que vem depois do host na ordem do build já foi renderizado até lá, então o que ele emitiu está disponível para leitura.

O que ele lê. Com a chave definida, cada entrada de .context.uses traz .render_facts: os fatos de renderização do destino, indexados por nome de fato, no formato que a entrada de um chamador traz. Todo fato de renderização é uma lista, então um template sempre a percorre com range. Suas entradas podem vir da renderização própria do destino e das renderizações das Features anexadas ao destino, primeiro as chamadas do provider próprio do destino, depois cada uma das suas Features na ordem em que foram renderizadas; uma Feature do destino que é ela própria renderizada depois de todos os componentes não está entre elas. Um destino cujos providers não relatam nada traz um .render_facts vazio. Um template lê os fatos de uma conexão sob o seu alias, .context.uses.<alias>.render_facts.<name>, ou os de cada conexão por vez:

artifacts:
targets.yaml: |
targets:
{{- range .context.uses }}
- component: {{ .target }}
ports:
{{- range .render_facts.ports }}
- {{ .port }}
{{- end }}
{{- end }}

Uma FeatureRecipe que não define a chave não vê nenhum .render_facts em nenhuma conexão, independentemente do que mais defina. Quais nomes de fato existem é o contrato documentado do provider de cada destino — os do provider helm são seus fatos de renderização, que nomeiam os labels, os seletores de controlador e as portas de contêiner dos pods que ele renderizou, e portanto o que uma política de egress precisa para selecionar exatamente os pods que seu host pode alcançar.

Declare-a sempre que um template ler os fatos. Um template escrito inline em uma FeatureRecipe que não define a chave — seu valuesMapping:, seu workload: ou uma entrada de artifacts: — que lê render_facts sob .context.uses interrompe o build antes que qualquer coisa seja renderizada, com o código curto E0347, nomeando a referência e o campo em que foi escrita (veja “A template reads its targets’ render facts without declaring it (Um template lê os fatos de renderização dos seus destinos sem declarar isso)” em fatal-halts.md). Definir readsCallerRenderFacts não o evita. A verificação lê o template como está escrito, com os limites da verificação dos chamadores: não vê uma referência construída enquanto o template é executado, nem uma escrita em conteúdo importado de um arquivo ou de uma biblioteca — e um template que lê .context.uses de alguma forma e também lê um campo chamado render_facts de algum outro valor, incluindo a entrada de um chamador dentro de {{ range .context.used_by }}, é tratado como se lesse os fatos dos seus destinos. Um template que lê os fatos das duas pontas define ambas as chaves.

Uma etapa de pipeline lê apenas os fatos próprios do seu host. with: e when: de uma etapa leem as conexões que o host faz, como a Recipe própria do host as lê, e nunca os fatos de renderização dos seus destinos — defina ou não a FeatureRecipe a chave. Uma etapa pode reescrever os documentos próprios do componente host, e a renderização própria do host lê o que seus destinos publicam, nunca o que eles emitiram. Um with: ou when: de uma etapa escrito inline que lê render_facts sob .context.uses portanto interrompe o build antes que qualquer coisa seja renderizada, com o código curto E0348, nomeando a referência e o campo da etapa — em vez de renderizar um valor vazio. Leia os fatos dos destinos em valuesMapping:, workload: ou artifacts: da FeatureRecipe.

Escopo. Como para a chave dos chamadores: ela se aplica a uma FeatureRecipe que é renderizada uma vez por componente. Uma FeatureRecipe que declara executionScope: boundary é renderizada onde sempre é, defina ou não a chave, e as conexões que ela lê sob .boundary não trazem fatos de renderização.

O bloco locals:

FeatureRecipe.spec.locals: é um mapa opcional de strings de template Go nomeadas cuja saída renderizada expõe um mapa .locals.* a todos os outros templates dentro da mesma FeatureRecipe. É o equivalente, privado da FeatureRecipe, do locals: da Recipe — um lugar para calcular strings derivadas uma única vez e referenciá-las a partir de injectMapping, valuesMapping, pipeline[].with e provides sem recalculá-las. As assertions: da FeatureRecipe não as leem: os .locals de uma asserção são os da Recipe do componente host, como afirma assertions-block.md. A saída renderizada de cada entrada é armazenada sem os espaços em branco iniciais e finais. O bloco é um mapa, não um único corpo de template; um escalar nesta posição é rejeitado pelo schema.

apiVersion: aggrega.ai/v1beta1
kind: FeatureRecipe
metadata:
name: regional-router
spec:
implements: core/regional-router:^1.0.0
capability: helm
locals:
region_prefix: "{{ .infra.region | lower }}"
fqdn_suffix: "{{ printf \"%s.svc.cluster.local\" .infra.namespace }}"
injectMapping: |
env:
"{{ .infra.target_var }}": "{{ .locals.region_prefix }}.{{ .infra.target_var | lower }}.{{ .locals.fqdn_suffix }}"

.locals.* é por invocação: cada invocação de uma FR resolve seu próprio bloco locals:, e o resultado só é visível para os templates a jusante dessa invocação. O bloco é resolvido antes que os outros templates da superfície de autoria da FR sejam avaliados, de modo que todos eles veem valores resolvidos.

Cada entrada é avaliada contra um contexto autocontido: .context.instance_id, .context.rendered_name, .attachment_name, .values, .infra e as entradas deste mesmo bloco já resolvidas. Isso é deliberadamente mais restrito que o contexto que os outros templates da FR leem — uma entrada de locals: não pode alcançar .context.annotations, .context.inject, .context.uses nem .provides, e uma referência a qualquer um deles interrompe o build indicando a referência. Valores derivados que precisam desses pilares pertencem ao template que os lê, não a locals:.

Os nomes nesse contexto respondem a perguntas diferentes, e uma entrada de locals: os lê exatamente como os outros templates da FeatureRecipe:

  • .context.instance_id é o componente host para o qual a anexação está sendo resolvida. Ele designa o componente host em toda superfície de template que o compilador avalia, então a mesma referência é lida da mesma forma qualquer que seja a entidade cujo bloco você está escrevendo.
  • .context.rendered_name é o nome do componente host conforme informado pelo seu próprio provider — com helm, o nome da release, que é a identidade do host escrita no alfabeto que um nome Kubernetes admite. Ele só está presente onde o provider do host informa um nome, e lê-lo em um host cujo provider não informa nenhum interrompe o build.
  • .attachment_name é a instância de anexação que está sendo resolvida — o slot que ela ocupa no featuresSchema da entidade proprietária, ou o nome livre que você lhe deu.

Assim, uma entrada de locals: que deriva um nome para um recurso emitido compõe o host e a anexação, exatamente como faria um template de artifacts::

spec:
locals:
scrape_name: "{{ .context.instance_id }}-{{ .attachment_name }}" # api-scrape_target

Onde o nome precisa ser um que a plataforma aceite e o provider do host informa um, componha-o a partir de .context.rendered_name: para um host chamado my_api com helm e uma anexação scrape, {{ .context.rendered_name }}-{{ .attachment_name }} gera my-zuapi-scrape, enquanto a identidade geraria my_api-scrape, que um nome Kubernetes recusa. Consulte Nomear um recurso renderizado.

.values e .infra em uma entrada de locals: são os pilares próprios da anexação, escritos na declaração da anexação — não os do componente host.

A ordem de escrita é determinante

As entradas são resolvidas na ordem em que são escritas, e uma entrada pode ler uma entrada irmã definida acima dela, recebendo o valor resolvido dessa entrada irmã:

spec:
locals:
region_prefix: "{{ .infra.region | lower }}" # defined first
bucket: "{{ .locals.region_prefix }}-artifacts" # reads the entry above

O encadeamento ocorre apenas para baixo. Onde uma entrada lê outra, a ordem das entradas decide se o build tem sucesso: mova region_prefix para baixo de bucket e o build é interrompido. O compilador nunca reordena o bloco para fazer uma referência ser resolvida, então reordenar um bloco locals: é uma mudança de comportamento, não cosmética.

Uma referência a uma entrada que o bloco define mais adiante interrompe o build indicando a falha de ordenação (mova a definição para acima de quem a lê); uma referência a uma chave que o bloco não declara de forma alguma o interrompe indicando a chave (corrija a grafia). A verificação segue um alias do bloco: uma chave alcançada pelo ponto que um corpo with .locals revincula, ou por uma variável vinculada a .locals, interrompe o build exatamente nos mesmos termos que a grafia direta, assim como uma chave lida do bloco entre parênteses — {{ (.locals).nope }} ou {{ ($.locals).nope }}. Uma única grafia escapa dela: uma chave alcançada por uma chamada cujo resultado o texto do template não consegue nomear — {{ index .locals "nope" }}, ou {{ (default dict .locals).nope }}. Um campo lido do resultado de uma chamada assim não interrompe o build e renderiza o texto literal <no value>; a leitura com index o interrompe indicando a chave, porque index interrompe o build em toda superfície de template quando o mapa que lê não contém a chave — consulte errors/fatal-halts.md “A template indexes a map with a key the map does not hold (Um template indexa um mapa com uma chave que o mapa não contém)”. provides: lê o bloco totalmente resolvido, porque os locals desta FeatureRecipe são resolvidos antes de seus provides; um template de provides: que nomeia uma chave não declarada interrompe o build. São as mesmas regras que o bloco locals: de uma Recipe segue — consulte entities/recipe.md “O bloco locals:”.

Comportamento por escopo. Para executionScope: component (padrão), locals: é avaliado por instância de componente anexada, contra o contexto autocontido acima. Para executionScope: boundary, locals: é avaliado por anexação de fronteira, contra a visão de escopo de fronteira com raiz em .boundary.*; os campos por componente (.context.instance_id, .context.inject, .context.uses) e .attachment_name não estão disponíveis, porque a FeatureRecipe é executada uma vez para a fronteira, e não uma vez por componente. A lista de permissões de campos de template do escopo de fronteira se aplica a locals: da mesma forma que se aplica aos outros templates da superfície de autoria da FR. O injectMapping, que é executado para cada componente que a anexação alcança, lê essa única avaliação de fronteira como seu .locals. O contrato de avaliação — ordem de escrita, leituras de entradas irmãs apenas para baixo, as duas interrupções — é idêntico nos dois escopos; só a forma do contexto ao redor muda.

Diferença em relação aos overlays de injectMapping e aos mapeamentos de pipeline[].with. locals: produz um mapa visível no contexto para os templates a jusante; ele não contribui com saída. injectMapping escreve no pipe .context.inject do consumidor (mutação do lado do chamador). pipeline[].with fornece o payload args do plugin Wasm. As três superfícies são ortogonais — uma FeatureRecipe usa rotineiramente as três juntas, com locals: carregando as strings derivadas compartilhadas que as outras duas referenciam.

O bloco assertions:

FeatureRecipe.spec.assertions: é um mapa opcional de regras nomeadas que expressam invariantes de implementação da FeatureRecipe — regras entre campos que valem dado o pipeline específico de plugins Wasm, o chart ou o mecanismo sobre o qual a FeatureRecipe é construída. Cada chave é um identificador de regra que aparece na mensagem de falha; cada valor é um corpo de template Go. Assim como as asserções da Recipe, as asserções da FeatureRecipe são propriedades da implementação específica; as regras de contrato no nível da Feature se aplicam de forma independente, em uma fase anterior do pipeline.

spec:
implements: core/referenced-secret:^1.0.0
pipeline:
- id: fetch_secret
plugin: pipeline-step/aws-secrets-manager:1.2.0
function: step
assertions:
# aws-secrets-manager plugin 1.x requires an explicit region when none is
# implied through the Aggregate's infra block.
region-supplied-for-secrets-manager: |
{{- if not .values.region -}}
{{- if not .infra.aws.region -}}
{{- fail "aws-secrets-manager plugin 1.x requires either values.region or infra.aws.region to be set" -}}
{{- end -}}
{{- end -}}

A regra acima é específica do plugin aws-secrets-manager 1.x; ela não se aplica se uma FeatureRecipe core/referenced-secret diferente for vinculada. As regras de contrato no nível da Feature, da definição da Feature, continuam se aplicando em paralelo.

As asserções da FeatureRecipe são avaliadas após a vinculação da FeatureRecipe e antes da geração de recursos. O contexto de template das FR de escopo de componente espelha o contexto das asserções da Recipe (campos da instância da entidade mais .provides, .locals, .recipe.metadata, .recipe.source); para as FR de escopo de fronteira (executionScope: boundary), as asserções são avaliadas contra a visão de escopo de fronteira (campos .boundary.* disponíveis; campos por componente não). Para a gramática de autoria completa e exemplos práticos, consulte templates/assertions-block.md.

O campo omits: — deixar documentos renderizados fora de uma fonte

A maioria das FeatureRecipes nunca precisa disso. Ele serve para uma FeatureRecipe cujo source: é um chart que você usa como está — na maioria das vezes, um obtido de um registry — e que renderiza um documento que a anexação não deve emitir: um Secret que o chart gera de novo a cada renderização, ou um objeto que o componente host ou o operador já fornece. omits: deixa esse documento fora do que a FeatureRecipe gera — ou, para um arquivo compose que a FeatureRecipe usa como fonte, um serviço, um volume ou uma config que a anexação não deve contribuir, e para um template CloudFormation que ela usa como fonte, um recurso.

spec:
capability: helm
implements: core/observability/collector:1.0.0
source:
kind: helm-oci-chart
url: oci://registry.example.com/charts/collector
version: "0.9.1"
omits:
# The collector chart ships its own ServiceAccount; the host supplies one.
- kind: ServiceAccount
name: collector
- when: "{{ .infra.without_dashboards }}"
kind: ConfigMap
name: collector-dashboards

A chave é escrita de forma idêntica em uma Recipe, e Recipe → O campo omits: é sua referência completa: o que cada campo de entrada seleciona, que when: é avaliado primeiro e um falso descarta a entrada, que toda entrada que se aplica deve deixar algo de fora ou o build é interrompido indicando-a, que a fonte continua sendo renderizada por inteiro e apenas sua saída é filtrada, e quais providers respeitam a chave. Em uma FeatureRecipe, a única diferença é onde os templates são avaliados:

  • Os templates de cada entrada são avaliados contra o contexto contra o qual o valuesMapping: desta FeatureRecipe é avaliado, no escopo que seu executionScope seleciona. As entradas de uma FeatureRecipe de escopo de componente são avaliadas uma vez por anexação, contra os .values e o .infra dessa anexação; as de uma de escopo de fronteira, uma vez por fronteira, contra a visão de escopo de fronteira e o .infra da anexação de fronteira. As regras sobre o que os templates de uma anexação podem ler se aplicam às entradas como se aplicam ao seu valuesMapping:.
  • Só é filtrado o que o próprio source: desta FeatureRecipe renderiza. Seu workload: e seus artifacts: não, e tampouco a saída do componente host: as entradas de uma anexação alcançam o próprio chart, o próprio arquivo compose ou o próprio template CloudFormation, e nada mais — um serviço compose que o host declara sob a mesma chave no docker-compose.yaml em que ambos são montados fica intacto, assim como um recurso que o host declara sob o mesmo ID lógico na stack em que ambos são montados. Para alterar um documento que o host renderiza, a Recipe do host declara a entrada, ou uma etapa de pipeline: aplica um patch nele.

Uma interrupção em uma entrada indica o nó, o provider, esta FeatureRecipe e a posição da entrada em sua lista omits:; para uma FeatureRecipe de escopo de fronteira, a linha acima da mensagem indica a anexação e sua fronteira.

Para um exemplo prático da chave, escrita em uma Recipe — o Secret gerado de um chart obtido deixado de fora, e as interrupções sem a entrada e com uma entrada que não corresponde a nada —, consulte ai-gateway-own-webhook-certificate.