FeatureRecipe
O papel conceptual da entidade FeatureRecipe (Domínio 3 — a implementação, orientada por plugins Wasm, de uma interface de Feature) está descrito em architecture/04-entity-taxonomy.md. Esta página abrange a superfície de criação da FeatureRecipe no catálogo.
Localização no catálogo
As FeatureRecipes organizam-se com o fornecedor no primeiro segmento do caminho (o mesmo padrão que as Recipes):
aggrega-catalog/└── feature-recipe/ └── {provider}/ # e.g., `helm`, `compose` └── {feature-recipe-name}/ └── {version}/ └── recipe.yamlURI OCI: hub.aggrega.ai/featurerecipe/{provider}/{name}:{version} (p. ex., hub.aggrega.ai/featurerecipe/helm/k8s-secret-from-parameter:1.0.0).
Contrato de criação
As FeatureRecipes associam-se a uma interface de Feature através de implements e declaram um fornecedor concreto. A sua superfície de criação é o conjunto completo de tipos de entrada da Recipe base, mais dois blocos específicos da FeatureRecipe:
- Os três tipos de entrada —
source+valuesMapping(com origem),workload(sintetizado) eartifacts: com forma idêntica à da Recipe base (consulte Composição de entradas da Recipe eentities/recipe.md). Uma FeatureRecipe que contenha qualquer um destes é geradora de recursos — renderiza recursos ao lado do componente base. O local onde esses recursos ficam contém o componente a que a Feature está anexada e depois o nome sob o qual está anexada, em qualquer das duas formas que a própria estrutura do destino admite: como um diretório{component}--{instance}/ao lado do do seu anfitrião, sob o que quer que esse destino chame ao diretório onde residem os seus contribuidores, num destino cujo fornecedor dá a cada contribuidor uma posição própria; como um prefixo de nome de ficheiro{component}--{instance}--ao lado dos próprios ficheiros do componente, num destino que lê apenas os ficheiros que se encontram diretamente num diretório. Num fornecedor que compõe os seus contribuidores num único documento, os recursos são, em vez disso, integrados nesse documento — qualquer que seja a família a que a Feature pertence: um CRDServiceMonitorouExternalSecretcomoartifacts:inline ou$import; um chart ou módulo externo através desource:+valuesMapping:; ou a sua própria computação (por exemplo, um Deployment de agente sidecar) através deworkload:.valuesMapping:partilha os três modos de criação da Recipe base (escalar de bloco inline,$import:de ficheiro,$import:de biblioteca para uma entrada de MappingLibrary) — consulteentities/recipe.md«O campovaluesMapping— três modos de criação». Por convenção, uma FeatureRecipe modifica o componente base ou acrescenta recursos ao lado dele, mas o esquema não restringe que tipos de entrada pode usar — o compilador renderiza o que quer que a FeatureRecipe declare, condicionado apenas pela capacidade do fornecedor associado, e mantém-se sem opiniões próprias sobre se um dado tipo é «adequado a um modificador» (consulte as invariantes fundadoras). A síntese (workload:) requer um fornecedor que a suporte; caso contrário, o build é interrompido na renderização com o diagnóstico de capacidade do fornecedor. injectMapping(interceção pré-renderização): um bloco de template Go nativo executado antes de a Recipe base ser renderizada. Produz um dicionário JSON ou YAML que o compilador funde nativamente em profundidade sobre o pipe de memória.context.injectdo chamador, permitindo a mutação do lado do chamador, sem Wasm, de variáveis de ambiente e cadeias de ligação.pipeline: um array sequencial de passos de plugins WebAssembly (Wasm) para a mutação de Workload pós-renderização (por exemplo, injetar um sidecar Envoy através de JSONPatch ou montar um volume secreto). O campopluginde cada passo indica uma entidadePluginpelo seu URI, sempre com o âmbito do tipo de socket do próprio plugin (<pluginType>/<name>, opcionalmente com versão, como emparser/yamlouparser/yaml:1.0.0); o build resolve a entidade no seu artefacto.wasmendereçado por conteúdo, localizado a partir da identidade do plugin e do registo configurado, e um.wasmsimples ou uma referência de artefacto não são aceites aqui. Consulte o guia do programador 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 passo pela ordem declarada: despacha a exportação guest do plugin indicado contra a saída renderizada e aplica os JSON Patches devolvidos e os efeitos secundários emitidos; consulte Estado da linguagem para o estado de execução de cada superfície do pipeline. Umpipeline:é autónomo: uma FeatureRecipe pode declarar um e nenhum tipo de entrada, caso em que não emite recursos próprios e todo o seu efeito é aquilo que os seus passos aplicam como patch aos documentos que o build já renderizou, ou emitem ao lado deles.
Uma FeatureRecipe pode também não conter nenhum destes blocos: uma Feature de pura ligação cujo efeito é a aresta uses que transporta não renderiza nada, e a sua FeatureRecipe existe apenas para satisfazer a resolução — cada instância de funcionalidade resolve-se para uma FeatureRecipe, da mesma forma que cada componente se resolve para uma Recipe. Entre os blocos acima, injectMapping é o único campo sem equivalente na Recipe base; os três tipos de entrada e pipeline são partilhados com a Recipe base.
O que é fixado ao lado de uma FeatureRecipe é o que é fixado ao lado de uma Recipe: o digest de cada ficheiro que uma entrada artifacts importa, e de cada source: remota cujas coordenadas estejam escritas por extenso, num entity.lock no próprio diretório da FeatureRecipe, que o aggrega pin escreve e de que se faz commit ao lado dela. Um pull sobre uma FeatureRecipe cujo lock não regista essas fixações é interrompido e indica esse passo, a menos que seja pedido ao pull que o execute. Um build é interrompido quando um ficheiro importado deixa de corresponder ao seu digest, e quando o digest de uma origem diverge do registado no lockfile da Release (uma origem escrita num ref: de git é registada no commit para o qual foi resolvida e não é comparada); o próprio ficheiro da FeatureRecipe nunca é escrito. O aggrega pull descreve o ficheiro e como responder a cada interrupção.
Templates no campo de origem
O source: de uma FeatureRecipe é uma superfície de templates nos mesmos termos que o de uma Recipe: o template é avaliado na resolução da origem, e o que 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 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 de URI e a leitura de ancoragem são os descritos em entities/recipe.md «Templates no campo de origem», «Inventário de esquemas do campo de origem» e «Como é ancorado um caminho source:»; esta secção indica apenas o que difere para uma anexação.
locals: chart_dir: ./charts/exportersource: "{{ .locals.chart_dir }}"Contra o que é resolvido um resultado relativo. O diretório que contém o documento da FeatureRecipe que o declarou — o próprio ficheiro da anexação, nunca o do componente — e o resultado tem de permanecer dentro desse diretório, exatamente como para uma Recipe: um resultado que saia dele, ou que seja um caminho absoluto, indica um ficheiro que não viajaria com a FeatureRecipe e interrompe o build. Um que contenha um esquema de transporte é obtido em vez de ser juntado a um diretório. Uma FeatureRecipe resolvida a partir de um registo é lida a partir dos ficheiros que o seu arquivo publicado contém, dispostos na cache de conteúdos, pelo que um resultado relativo é resolvido dentro do que foi publicado exatamente como é resolvido ao lado da FeatureRecipe num 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 próprias entradas locals: da FeatureRecipe são verificadas, que difere do de uma Recipe de duas formas que decorrem de ser uma anexação, e não um componente, a ser resolvida:
.attachment_nameestá disponível, indicando a instância sob a qual a Feature está anexada. O template de origem de uma Recipe recusa-o, porque a origem de uma Recipe é resolvida para um nó e não há nenhuma anexação em jogo..context.instance_idindica o componente anfitrião para o qual a anexação está a ser resolvida, não a anexação, e.context.rendered_namecontém o nome que o próprio fornecedor do anfitrião indica para o anfitrião — presente apenas quando esse fornecedor indica um, e interrompendo o build quando não indica. Consulte Dar nome a um recurso renderizado.
.locals contém o conjunto que os outros templates desta FeatureRecipe leem: o seu próprio bloco resolvido, com o da Recipe anfitriã por baixo, pelo que uma chave que a anexação declara prevalece sobre uma chave do anfitrião com o mesmo nome. Uma referência a uma chave que esse conjunto não contém interrompe o build e indica-a, em vez de renderizar a chave como vazia. .provides, .context.inject e .context.uses são recusados pelos mesmos motivos de autossuficiência pelos quais a superfície de origem de uma Recipe os recusa.
Uma FeatureRecipe com âmbito de fronteira lê, em vez disso, a fronteira. Uma Feature cuja FeatureRecipe declara executionScope: boundary renderiza uma vez para a fronteira e não uma vez por componente, pelo que o seu template de origem não tem nenhum componente anfitrião para ler. Lê .boundary.* — os mesmos pilares que os 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 origem, que é o modo sem origem — a mesma leitura que a origem de uma Recipe tem, e distinta de escrever source: "" explicitamente.
O que .source lê depois. O source é avaliado antes do valuesMapping:, tal como o de uma Recipe é avaliado antes do seu, e o que produziu é .source em todos os templates executados depois dele: o valuesMapping:, o omits:, os corpos de workload: e artifacts: e os passos de pipeline:. Assim, um valuesMapping: que lê .source lê o source desta própria FeatureRecipe, nunca o source do componente a que está anexada, e não lê nada quando esta FeatureRecipe não declara nenhum source ou o seu template não produz nada. Uma FeatureRecipe com âmbito de fronteira lê o seu próprio source da mesma forma. O injectMapping: é executado antes de o source da anexação ser avaliado, pelo que .source aí é o do componente anfitrião.
Exclusividade de injectMapping
O campo injectMapping é exclusivo das FeatureRecipes — está intencionalmente ausente do esquema base de Recipe. Esta exclusividade isola a interceção de variáveis de valuesMapping: o valuesMapping da Recipe base consome, sem o saber, as strings .context.inject reescritas geradas pelos blocos injectMapping da FeatureRecipe, pelo que os dois permanecem desacoplados. Consulte a secção sobre a interceçã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 interceção pré-renderização.
Interceção de inject-mapping: como funciona o injectMapping
Quando um chamador precisa que a cadeia de ligação ao seu destino tenha uma forma diferente do .provides.host não modificado do destino — acrescentar um namespace para o DNS do Kubernetes entre fronteiras, prefixar um código de região para um gateway multirregião ou acrescentar um sufixo de modo SSL a um DSN — o injectMapping trata a mutação no chamador, antes de o valuesMapping da Recipe base alguma vez ver o canal de inject.
O campo injectMapping é um text/template Go que o renderizador avalia no inject mapping, antes da execução da renderização da Recipe base. 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 predefinição — e o renderizador funde em profundidade esta sobreposição sobre o canal .context.inject do nó chamador. O encaminhamento do lado do chamador através de injectMapping é executado no inject mapping sem invocar uma sandbox Wasm para manipulações simples de strings; os plugins Wasm ficam reservados para alterações estruturais da AST através do array pipeline.
Escreva cada valor através de toJson. O renderizador lê a saída do template como YAML, pelo que um valor interpolado entre aspas tal como está ou quebra essa saída ou é lido de volta alterado assim que contém uma aspa dupla ou uma barra invertida — uma palavra-passe é o caso habitual. toJson escreve o valor como uma string JSON, que o YAML lê de volta exatamente, pelo 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 é primeiro montado e depois escrito uma única vez através de toJson, como fazem os exemplos abaixo.
Uma saída que não pode ser lida para o build. Quando a saída do template não se lê como nenhuma das duas formas — a causa habitual é um escalar entre aspas quebrado pelo valor que contém —, nenhuma das suas chaves poderia ser entregue, pelo que o build para, indicando a associação 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 injectMapping de uma Feature associada não pode ser lida)». O motivo indicado é 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 deles. Cada chave de nível superior de uma saída em forma de dicionário indica o mecanismo através do qual as 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 depois da fusão e nunca é fundido a partir de uma saída, pelo que entradas escritas sob all: não chegariam a nada; em vez disso, o build para, indicando a associação, a chave e a FeatureRecipe, e dizendo que 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 injectMapping de uma Feature associada escreve entregas sob uma chave que nada entrega)». Escreva essas entradas sob o mecanismo a partir do qual o componente as lê.
A mutação é estritamente local ao chamador. A FeatureRecipe modifica apenas o canal de inject do nó a que está anexada, nunca a saída .provides do destino. O .provides.host de um destino é potencialmente consumido por muitos chamadores em todo o cluster; o injectMapping do lado do chamador funde-se apenas no canal desse chamador específico, pelo que as mutações de encaminhamento ficam restringidas à aresta que as pediu.
O que um mapeamento pode reescrever. Todos os blocos inject: já fizeram a sua entrega quando os mapeamentos renderizam, pelo que a saída de um mapeamento é sempre fundida 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 um dos blocos inject: das suas ligações entregou pode ser reescrita pelo mapeamento: isso é interceção, e o valor do mapeamento substitui essa entrada. Uma chave que a própria anexação do mapeamento entregou através do seu bloco inject: também pode ser reescrita por ele. Uma chave que uma Feature anexada diferente já entregou — através do seu próprio bloco inject: ou do injectMapping da sua própria FeatureRecipe — não pode: o build é interrompido indicando ambas as anexações, em vez de deixar que o último mapeamento a ser executado decida que valor o chamador lê. Assim, duas Features de encaminhamento podem cada uma qualificar uma chave própria, mas duas Features não podem ambas entregar uma mesma chave — incluindo duas Features de encaminhamento que reescrevam a chave da mesma ligação, uma vez que a primeira é interceçã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 última através do injectMapping da sua FeatureRecipe)».
Inferência do 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 encaminhamento sem que a equipa de Ops codifique a identidade do destino no infra da Feature:
- O template pesquisa
.context.usespara encontrar a aresta topológica exata que injetou a variável pedida pelo programador. - Extrai as
release_annotationsem cascata do destino (p. ex.,aggrega.ai/namespace). - Formata o nome de domínio totalmente qualificado (FQDN) ou a cadeia de ligação.
- Emite o dicionário de substituição.
O compilador mantém-se agnóstico em relação à semântica de rede — namespaces do Kubernetes, regiões de cloud, topologias de proxy de ponte — e limita-se a executar a fusão em profundidade com o que quer que o template tenha produzido. Quando o valuesMapping da Recipe base é executado a seguir, consome as strings intercetadas e reescritas de .context.inject.env como se fossem as originais do programador.
Exemplo prático: resolvedor de DNS do K8s
O catálogo padrão disponibiliza isto como core/k8s-dns-resolver com uma FeatureRecipe helm. Como os nomes das variáveis de ambiente têm de ser únicos dentro de um contentor, a target_var (p. ex., API_HOST) funciona como um identificador globalmente único de um contrato de injeção específico dentro do chamador. Percorrendo as arestas explícitas em .context.uses e verificando que aresta reclamou a target_var, o template localiza o nó de destino correto e lê o seu namespace. O único parâmetro é a variável a reescrever; o destino e o seu namespace são descobertos, nunca codificados.
O esquema da Feature de encaminhamento (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 utilização além do encaminhamento
O injectMapping é usado sobretudo para a resolução de endereços entre fronteiras (como o resolvedor de DNS do K8s acima), mas essa mutação do lado do chamador aplica-se a qualquer cenário que exija intercetar e formatar a intenção do programador antes da renderização da infraestrutura. Mais dois padrões ilustram a amplitude.
Formatação dinâmica de segurança (o acrescentador de SSL). Se uma empresa exigir que todas as ligações a bases de dados externas usem verificação TLS estrita, uma Feature pode intercetar o DB_URL pedido pelo programador e acrescentar o modo SSL exigido, para que a aplicação arranque com os parâmetros de segurança corretos.
# Inside force-ssl-featureinjectMapping: | {{ $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 gateways multirregião. Se um componente de API genérico for implementado globalmente, uma Feature de encaminhamento regional pode consultar autonomamente as anotações da sua própria fronteira de ambiente para prefixar as cadeias de ligação injetadas para os seus chamadores.
# Inside regional-routerinjectMapping: | {{ $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 do injectMapping. O mecanismo limita-se a alterar o canal de memória .context.inject (o contrato de entrega). Não pode acrescentar novos contentores, montar volumes nem alterar a saída do valuesMapping da Recipe base. Qualquer mutação que exija alterações estruturais à AST renderizada (como arrays JSON ou YAML) pertence ao array pipeline da FeatureRecipe, executado através de plugins WebAssembly.
O limite de destinos de patch do pipeline. Um passo de pipeline aplica patches apenas à saída que o fornecedor renderiza numa árvore estruturada. A saída com forma YAML e JSON é estruturada — incluindo módulos Terraform .tf.json criados em JSON — pelo que o JSONPatch de um passo edita os valores endereçados no local, deixando todos os outros bytes (comentários, ordenação, formatação) intactos. A saída que o fornecedor emite como corpo opaco, como a configuração Terraform em HCL nativo, não é um destino de patch: um patch contra um corpo opaco interrompe o build com um diagnóstico, em vez de alterar texto que não consegue endereçar estruturalmente. Criar um passo de pipeline contra saída opaca é, portanto, um erro de conceção que surge como uma interrupção ruidosa, não como uma operação nula silenciosa.
As entradas de um módulo Terraform incorporado não são um destino de patch, e vale a pena indicar essa ausência. São os argumentos do bloco module desse componente, que o fornecedor terraform escreve na configuração raiz da fronteira: HCL nativo, portanto opaco segundo a regra acima, e um artefacto de toda a fronteira e não do nó cuja saída o passo modifica. Assim, não existe nenhuma posição a partir da qual um passo de pipeline os possa endereçar, nem nada que possa fazer para alterar o que um módulo Terraform com origem recebe. Esses valores são moldados onde são criados — no valuesMapping: da Recipe base.
Passos condicionais — when:
Um passo de pipeline pode conter um campo when: opcional: um template Go inline que o compilador avalia no momento do percurso do pipeline, contra o mesmo contexto de template e o mesmo avaliador que o corpo with: do passo usa. O resultado renderizado decide se o passo é executado.
- Um resultado falso ignora o passo como pass-through: o conjunto de documentos passa para o passo seguinte sem alterações, e o passo ignorado não contribui com nada — nenhum patch, nenhum efeito secundário, nenhum registo de ter sido executado.
- Um
when:vazio ou ausente executa sempre o passo.
when: e optional: são independentes. when: decide se um passo é sequer executado; optional: atenua a falha de um passo em execução. Um passo pode declarar ambos — when: controla a entrada e, se o passo for executado, optional: determina como é tratada uma falha dentro dele. Um template when: que não consiga ser renderizado é um defeito de criação e interrompe o build independentemente de optional:.
O texto when: renderizado é avaliado pela regra partilhada 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 com a etiqueta feature.aggrega.ai/kind: secret), pode seguir o princípio do Plugin em duas partes: um pipeline que encadeia um plugin Fetcher (que gera o CRD específico do cofre) e um plugin Injector (que monta o segredo no contentor de destino), a forma que examples/04-secrets descreve. As FeatureRecipes de credenciais da biblioteca padrão não declaram nenhum pipeline: e renderizam elas próprias o recurso do segredo; consulte examples/05-credential-features.
Uma FeatureRecipe de credenciais renderiza através da mesma passagem de geração de recursos que a de qualquer outra anexação, e o seu pipeline: é executado nos mesmos termos: o compilador percorre todas as anexações com 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 junta-se a essa sequência por uma de duas razões — a sua FeatureRecipe declara um tipo de entrada, pelo que gera recursos próprios, ou declara um pipeline:, pelo que reescreve documentos já emitidos. Uma anexação de credencial pode, portanto, alcançar os documentos renderizados do componente anfitrião — montando um volume secreto, acrescentando uma referência de ambiente — exatamente como uma anexação operacional, e a única diferença entre as duas é onde ficam os seus próprios ficheiros gerados.
Num componente, uma declaração de sensibilidade na Feature segue o valuesMapping: da FeatureRecipe exatamente como a de um Component segue o da sua Recipe. Quando uma FeatureRecipe renderiza a partir de um source: sem valuesMapping:, os valores que o seu destino recebe são indexados pelos caminhos das folhas que a Feature declara, pelo que uma folha declarada sensitive: true marca a sua chave renderizada. Quando a FeatureRecipe declara um valuesMapping:, as chaves são invenção desse template, nenhuma declaração as indica, e o build imprime um aviso por cada folha desse tipo, indicando a anexação, a folha e a FeatureRecipe. Uma Feature anexada a uma fronteira não gera nenhum: o seu .values está sempre vazio, pelo que nenhuma folha declarada tem um valor a marcar — consulte A declared-sensitive value reaches the target through a values mapping (Um valor declarado como sensível chega ao destino através de um mapeamento de valores).
O bloco provides: — publicar para o consumidor
O bloco provides: de uma FeatureRecipe é a sua saída publicada: um mapa com valores string de templates Go avaliados contra o próprio âmbito da anexação (.values, .infra, os .locals totalmente resolvidos da FeatureRecipe e os .context.instance_id e .context.rendered_name do nó anfitrião). Os locals são resolvidos primeiro, pelo que uma entrada de provides: os lê e recebe valores resolvidos; indicar uma chave que o bloco locals: não declara interrompe o build. É assim que uma anexação diz ao seu consumidor o que produziu — o nome de um recurso emitido, uma chave de dados gerada, uma identidade de cloud — sem que o consumidor volte a derivar essa identidade a partir das mesmas entradas.
O consumidor lê-a em .features.<instance-name>.provides.<key> (ou .features.<slot>.provides.<key> para uma anexação de credencial), espelhando .context.uses.<alias>.provides para uma aresta uses. Quando a anexação está escrita numa das ligações do consumidor, o consumidor lê o mesmo mapa sob essa ligação, em .context.uses.<alias>.features.<slot>.provides.<key>, e a anexação não está entre as suas .features (consulte As anexações de uma ligação). O próprio bloco inject: da anexação resolve as suas referências from: contra o mesmo mapa, pelo que um autor pode escolher qualquer um dos canais: provides para uma leitura em template, inject para entrega numa variável de ambiente, ficheiro 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 é imposto à FeatureRecipe: todas as chaves que a Feature declara têm de aparecer no provides: da FeatureRecipe, caso contrário o build é interrompido indicando a chave em falta. São permitidas chaves publicadas adicionais — o contrato é um mínimo, não um máximo. 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 de o consumidor renderizar, 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 — pelo que o que o consumidor lê e o que a anexação emite não podem divergir.
Provider & implements
spec.capability é obrigatório e indica o fornecedor 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): uma fixação de versão seleciona que 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 escreva a fixação no nome é recusado como referência de receita malformada (E0095) antes de qualquer pesquisa. O campo implements associa 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.
Âmbito de execução — spec.executionScope
O enum opcional spec.executionScope seleciona o modelo de despacho da geração de recursos. São aceites dois valores; a predefinição quando o campo é omitido é component.
component(predefiniçã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. Os seusvaluesMapping:,workload:eartifacts:também leem.context.used_by, os componentes cujas entradasusesapontam para o anfitrião — cada um com a sua identidade, o seu socket, o que publica e o namespace e a fronteira em que está colocado — que nenhum template que o próprio anfitrião renderiza 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 âmbito de fronteira com raiz em.boundary.*em vez de.context.*.
A interceção injectMapping descrita acima é sempre por consumidor, independentemente de executionScope. Cada componente que usa a funcionalidade continua a receber a sua própria reescrita de .context.inject do lado do chamador. Apenas o passo de geração de recursos (source/valuesMapping e o array pipeline) é desduplicado no âmbito de fronteira.
Os templates de uma FeatureRecipe com âmbito de fronteira são, por isso, executados em dois âmbitos. O 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 âmbito de componente lê: .context.*, .attachment_name, .features e os .values, .infra e .locals próprios da anexação. O seu .infra é o bloco infra: da anexação à fronteira, e o seu .locals é o bloco avaliado uma única vez para a fronteira. Qualquer outro template que escreva — entre eles os seus locals:, provides:, source:, valuesMapping: e artifacts: e os with: e when: dos passos do seu pipeline — é executado uma vez para a fronteira, contra o contexto com âmbito de fronteira descrito abaixo. Cada template é verificado contra o âmbito em que é executado: um valuesMapping: que leia .context.instance_id interrompe a compilação, e um injectMapping que o leia renderiza a identidade desse componente. .boundary não está definido no contexto de nenhum componente, pelo que um injectMapping que o leia interrompe a compilação indicando a referência, qualquer que seja o executionScope da FeatureRecipe.
Contexto de template com âmbito de fronteira
Quando executionScope: boundary, os templates da FeatureRecipe, à exceção do seu injectMapping, são avaliados contra uma vista .boundary.* da fronteira a que a funcionalidade está anexada. A vista expõe:
.boundary.path— o caminho da fronteira da Release a que a funcionalidade está anexada: os nomes das fronteiras da mais exterior para o interior, unidos com/(bridge,bridge/frontend). Indica a fronteira, não o diretório em que a sua saída é escrita, que é definido pordirectory:(substitui.context.instance_id)..boundary.assembly_path— o diretório, relativo ao diretório de saída da compilação, em que a saída própria da anexação é montada: osdirectory:esubDirectory:avaliados da fronteira, ou seja, o diretório para onde a compilação encaminha essa saída (bridge/compose). É igual aosource_assembly_pathou aotarget_assembly_pathde uma extremidade de ligação exatamente quando essa extremidade é renderizada no mesmo ficheiro montado, pelo que uma FeatureRecipe os compara para distinguir uma ligação dentro do seu próprio ficheiro de uma ligação noutro ficheiro..boundary.boundary_name— o nome criado da fronteira na Release..boundary.components— um mapa indexado por ID de instância que contém todos os componentes da subárvore da fronteira (instance_id,component,resolved_version,boundary_path)..boundary.internal_uses_edges— arestasuses:em que ambas as extremidades estão dentro da subárvore desta fronteira (o padrão compose-bridge enumera-as, mantendo as arestas cujas duas extremidades são montadas no seu próprio ficheiro compose e colocadas em redes diferentes desse ficheiro, para derivar a sua configuração de proxy por aresta). Cada aresta transporta os provides resolvidos das suas extremidades, as variáveis de ambiente injetadas e a colocação de cada extremidade:source_namespaceetarget_namespace, a anotaçãoaggrega.ai/namespaceque se aplica a essa extremidade — a definição da sua própria entrada da Release, quando a tem, ou caso contrário a da sua fronteira;source_boundary_pathetarget_boundary_path, o caminho da fronteira da Release que a contém; esource_assembly_pathetarget_assembly_path, o diretório sob o diretório de saída da compilação em que o seu fornecedor a monta, composto a partir dosdirectory:esubDirectory:avaliados da sua fronteira (bridge/compose). Duas extremidades com o mesmo caminho de montagem são renderizadas num único ficheiro montado, e o fornecedor compose lê o caminho de montagem como a rede da extremidade quando não se aplica nenhum namespace..boundary.outgoing_cross_boundary_uses_edges— arestas com a origem dentro da subárvore e o destino fora dela..boundary.incoming_cross_boundary_uses_edges— arestas com o destino dentro da subárvore e a origem fora dela (usadas por agregadores do 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 vista completa entre fronteiras..boundary.labels— a união das etiquetas da subárvore, preservando a ordem de criação..boundary.annotations— as próprias anotações da fronteira mais a cascata..boundary.feature_attachments— todas as funcionalidades anexadas nesta fronteira (para que uma FR com âmbito de fronteira possa inspecionar as irmãs, se necessário).
O pilar .infra numa FR com âmbito de fronteira resolve-se para o bloco infra: da funcionalidade anexada à fronteira (o dimensionamento físico criado do lado da Release para essa anexação de fronteira). .values está sempre vazio nas FRs com âmbito de fronteira: a regra de separação de pilares do esquema da Release proíbe values: nas anexações de Feature ao nível da Release, pelo que uma funcionalidade anexada a uma fronteira não transporta valores para projetar. As FRs com âmbito de fronteira que precisem de dados com forma de parâmetros devem consumi-los através de .infra (a superfície de criação do operador para a configuração de funcionalidades de fronteira) ou através de .boundary.annotations (valores string resolúveis por cascata, criados na fronteira ou em qualquer antecessor); .parameters não faz parte da vista, e um template que o leia é interrompido indicando as raízes que a vista define. .locals continua a ser o próprio bloco locals da FR. .steps e .metadata mantêm-se inalterados.
Lista de permissões de campos de template com âmbito de fronteira
As FRs com âmbito de fronteira só podem referenciar campos disponíveis na vista com âmbito de fronteira, em todos os templates exceto o injectMapping. Criar um template desse tipo que referencie um campo exclusivo do âmbito de componente (p. ex., .context.instance_id, .context.inject, .context.uses) quando executionScope: boundary faz com que a FeatureRecipe falhe a validação no momento da análise sintática, com um erro que indica a FR, o campo infrator e os campos que a vista com âmbito de fronteira define. A regra espelho aplica-se no sentido inverso: uma FR com âmbito de componente que referencie campos .boundary.* falha no mesmo validador. O injectMapping é verificado contra o contexto do componente em que é executado, em qualquer dos âmbitos, pelo que pode ler .context.*, e uma referência a .boundary nele é interrompida indicando a referência e as raízes que esse contexto define.
O validador executa o mesmo percurso da AST de templates que a lista de permissões de variáveis de templates de caminhos usa, com um conjunto de referências diferente por âmbito.
Desduplicação e saída da geração de recursos
Para executionScope: boundary, o compilador desduplica a geração de recursos pelo tuplo (boundary_path, FR-instance). Dois componentes na mesma subárvore de fronteira que consumam ambos a mesma funcionalidade anexada à fronteira acionam uma única invocação da FR, não duas. As anexações da mesma funcionalidade em fronteiras diferentes são executadas de forma independente por fronteira.
Uma FR com âmbito de fronteira emite um conjunto de ficheiros não intermédios por tuplo (boundary_path, FR-instance), e o local onde ficam decorre da forma como o fornecedor combina a saída da sua fronteira. Aqui, o nome da instância por si só é a coordenada, enquanto uma anexação com âmbito de componente transporta também o seu componente: uma funcionalidade com âmbito de fronteira está anexada à fronteira e não a um componente, pelo que o diretório da fronteira envolvente já diz tudo o que um segmento de componente diria, e não há nenhum componente a indicar.
Um fornecedor que escreve cada documento diretamente no diretório da fronteira declara que o seu destino lê apenas os ficheiros que se encontram diretamente num diretório. Não existe, portanto, nenhum diretório envolvente onde uma anexação possa ficar, e o nome da instância passa a ser, em vez disso, um prefixo de nome de ficheiro: <boundary_directory>/<fr-provider>/<feature-instance>--<file>, ao lado dos próprios ficheiros da fronteira. O nome da instância é codificado, porque um nome de ficheiro não tem um separador a que recorrer, e encontra o próprio nome do ficheiro numa fronteira de dois caracteres que nenhuma coordenada codificada pode conter — pelo que duas anexações que emitam o mesmo nome de ficheiro continuam a chegar a dois ficheiros.
Um fornecedor que compõe a saída da sua fronteira numa estrutura envolvente — um chart que contém um chart por contribuidor, uma configuração raiz que contém um módulo por contribuidor — coloca cada contribuidor num subdiretório próprio, e uma anexação de fronteira é um contribuidor como qualquer outro. A sua saída fica então em <boundary_directory>/<fr-provider>/<contributors-directory>/<feature-instance>/, em que <contributors-directory> é o que quer que esse destino chame ao local onde residem as suas unidades filhas. O subdiretório tem o nome de instância da anexação, que é o nome sob o qual a escreveu no bloco features: da fronteira, pelo que o diretório que um build produz é um que se consegue encontrar naquilo que se criou.
A saída intermédia flui para o montador por (caminho, fornecedor) da fronteira, no caminho avaliado da FR, sob a própria spec.capability da FR — é este o mecanismo que a Feature core/compose-bridge usa para fundir um serviço de ponte a par dos contribuidores compose por componente no mesmo caminho de montagem. Essa saída só é escrita como parte do ficheiro aí montado a partir dos componentes da fronteira, pelo que, quando nenhum deles chega a esse caminho — por exemplo, por cada componente ser enviado para outro lado pelo seu subDirectory: —, a compilação é interrompida indicando a fronteira, a Feature, o caminho para onde a sua saída foi encaminhada e o fornecedor, em vez de escrever a saída em lado nenhum (consulte «A boundary-level Feature’s output reaches no assembled file (A saída de uma Feature ao nível da fronteira não chega a nenhum ficheiro montado)» em fatal-halts.md).
Resolução de provides: sensível à cascata
As FRs com âmbito de fronteira produzem um conjunto de provides: por tuplo (boundary_path, FR-instance), avaliado uma única vez. O template provides: da FR é avaliado com o contexto de template com âmbito de fronteira (pelo que 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 — todos os consumidores na subárvore da fronteira veem os mesmos valores fornecidos.
A resolução, do lado do consumidor, dos provides de uma FR com âmbito de fronteira lê essa única avaliação em todo o lado. Cada componente que a anexação alcança lê-a em .features.<instance-name>.provides.<key> — nos templates da sua própria Recipe e no próprio injectMapping da FeatureRecipe, que é executado no contexto desse componente. Um Component consumidor que leia através de uma aresta uses transportada pela anexação, em .context.uses.<feature-alias>.provides.<provided-name>, obtém os mesmos valores: o compilador resolve-o para o provides: da FeatureRecipe com âmbito de fronteira para a fronteira em que o consumidor se encontra, percorrendo desde a aresta uses do consumidor — que transporta a identidade da instância de funcionalidade por anexação — até ao provides: da FR com âmbito de fronteira. Uma pré-passagem avalia esses provides antes da montagem do consumidor, pelo que os valores estão presentes quando o canal do consumidor é construído.
Um efeito por consumidor é uma tabela em provides: lida pelo injectMapping. Uma FeatureRecipe com âmbito de fronteira que tenha de alterar algo para cada consumidor calcula uma única vez, no seu provides:, uma tabela indexada por consumidor a partir das ligações da fronteira, e o seu injectMapping lê as linhas do componente atual — (index .features .attachment_name).provides, indexadas por .context.instance_id — e entrega-as através do próprio canal do consumidor, segundo a regra que todos os mappings seguem (consulte 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 âmbito 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, pelo que um catálogo pode concretizar 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: partilhado, cada um com a sua própria anotação aggrega.ai/namespace (aggrega.ai/namespace: services-net, aggrega.ai/namespace: data-net) para que cada um fique numa rede própria; sem as anotações, ambos partilham a única rede nomeada a partir do caminho do seu ficheiro compose e alcançam-se mutuamente sem bridge. O seu executionScope: boundary executa a FR uma vez por anexo ao boundary pai.
O seu provides: calcula a tabela do bridge, uma única vez. De .boundary.internal_uses_edges mantém as arestas cujos dois extremos são montados no seu próprio ficheiro compose — source_assembly_path e target_assembly_path ambos iguais a .boundary.assembly_path — e estão em redes diferentes desse ficheiro, sendo a rede de um extremo o seu aggrega.ai/namespace, ou, na falta deste, o seu caminho de montagem. Uma aresta entre dois ficheiros 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 (predefinição 10000) — e um upstream, o host publicado do destino (o campo provides que o providesField do anexo nomeia, predefinição host) e a sua port; o upstream é derivado da aresta, nunca escrito à mão. A partir da mesma tabela, 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.
O seu injectMapping entrega as linhas de cada consumidor. Executado no contexto de cada consumidor, lê as linhas desse consumidor na tabela em .features.<attachment>.provides e entrega-as por cima dos valores que a própria ligação do consumidor entregou (por exemplo, DB_HOST), o que constitui uma interceção; um consumidor sem linha não recebe nada. Onde outra Feature anexada ao consumidor entregou essa chave — através do seu bloco inject: ou do seu injectMapping — o build é interrompido nomeando ambas as Features em vez de substituir essa entrega (ver «Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping (Duas Features anexadas entregam a mesma chave, a posterior através 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, pelo que coincidem por aresta por construção, incluindo as colisões reatribuídas através de portBase.
O seu valuesMapping escreve o gateway. O fragmento compose próprio da FeatureRecipe declara o serviço aggrega-gw. Onde algo é ligado por bridge, o seu valuesMapping acrescenta 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 ligação em vez de uma única vez no arranque; o $ nessas variáveis escreve-se $$ 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. Nomeia também cada extremo ligado por bridge sob o x-aggrega-networks-of do gateway, que o provider compose resolve nas redes em que esses extremos estão colocados, de modo que o gateway se junta a todas as redes que as 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 continua a ser renderizado, inativo: nenhuma configuração, nenhuma rede adicional e nenhuma reescrita.
O montador compose por (caminho, provider) junta o gateway aos contribuidores por componente no mesmo caminho avaliado: um único docker-compose.yaml que contém todos os componentes mais o gateway do bridge. Onde nenhum dos componentes do boundary é montado no ficheiro do gateway, o build é interrompido em vez de escrever o gateway em lado 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 resolve-o (nenhuma resolução de tempo de execução em tempo de compilação).
Renderizar depois dos chamadores — spec.readsCallerRenderFacts
O spec.readsCallerRenderFacts opcional (booleano, predefinição false) declara que os templates desta FeatureRecipe leem o que renderizaram os componentes que se ligam ao seu anfitrião: os factos de renderização que o fornecedor de cada um desses chamadores indica sobre a saída que emitiu. O que um fornecedor indica, e sob que nomes, é o contrato próprio desse fornecedor; Indicar factos sobre o que um guest emitiu descreve os factos que um fornecedor pode indicar.
Quando é que uma anexação deste tipo renderiza. O build renderiza os seus componentes um de cada vez, por uma ordem fixa, e uma anexação renderiza normalmente logo a seguir ao componente a que está anexada. Um componente que se liga ao anfitrião e vem mais tarde nessa ordem ainda não renderizou nesse ponto, pelo que nada do que emitiu existe para ser lido. Uma anexação cuja FeatureRecipe define readsCallerRenderFacts: true renderiza, em vez disso, depois de todos os componentes do build terem renderizado, juntamente com todas as anexações que não definem nem esta chave nem readsTargetRenderFacts — pelo que a renderização de cada chamador está completa antes de a anexação ser avaliada. A sua saída fica onde teria ficado e sob os mesmos nomes; a chave altera quando a anexação renderiza, não o que renderiza. Uma ordenação decorre da renderização posterior: quando a FeatureRecipe transporta um pipeline que reescreve os documentos do seu componente anfitrião e o fornecedor do anfitrião escreve documentos discretos, esses passos são executados depois dos pipelines das outras anexações do anfitrião e não pela sua ordem de anexação.
O que lê. Com a chave definida, cada entrada de .context.used_by transporta .render_facts: os factos de renderização do chamador, indexados pelo nome do facto. Cada facto de renderização é uma lista, pelo que um template percorre-a sempre — mesmo quando contém uma única entrada. As suas entradas podem vir da própria renderização do chamador e das renderizações das Features anexadas ao chamador: as listas que um nome obtém de cada uma são juntadas numa só, primeiro as chamadas do próprio fornecedor do chamador, depois cada uma das suas Features pela ordem em que renderizaram. Uma Feature do chamador que ela própria defina a chave também renderiza depois de todos os componentes, pelo que o que indicou não está entre elas. Um chamador cujos fornecedores não indicam nada transporta um .render_facts vazio, pelo que um nome que ninguém indicou se lê como nada:
artifacts: callers.yaml: | callers: {{- range .context.used_by }} - component: {{ .component_id }} ports: {{- range .render_facts.ports }} - {{ .port }} {{- end }} {{- end }}Que nomes de factos existem, e o que cada entrada contém, é o contrato documentado do fornecedor do chamador — os do fornecedor helm, por exemplo, são os seus factos de renderização, que indicam as etiquetas dos pods que renderizou. Os factos dos chamadores estão nas ligações que os valuesMapping:, workload: e artifacts: da FeatureRecipe leem; os with: e when: de um passo de pipeline: não veem de todo os componentes que se ligam ao anfitrião, pelo que um passo lê apenas os factos do próprio anfitrião. Cada FeatureRecipe anexada a um componente — defina ou não a chave — lê os factos do próprio componente em .context.render_facts, com a mesma forma; o contexto de template descreve ambos.
Declare-a sempre que um template ler os factos. Um template escrito inline numa FeatureRecipe que não define a chave — o seu valuesMapping:, o seu workload: ou uma entrada de artifacts: — que leia render_facts sob .context.used_by interrompe o build antes de qualquer renderização, indicando a referência e o campo em que foi escrita (consulte «A template reads its callers’ render facts without declaring it (Um template lê os factos de renderização dos seus chamadores sem o declarar)» em fatal-halts.md). A verificação lê o template tal como está escrito, pelo que não vê uma referência construída enquanto o template é executado, nem uma escrita em conteúdo importado de um ficheiro ou de uma biblioteca — e um template que leia um campo chamado render_facts de alguma outra lista ao lado de .context.used_by, ou que leia os factos do próprio anfitrião como .render_facts dentro de {{ with .context }} ao lado dela, é tratado como lendo os factos dos chamadores; escreva os do próprio anfitrião como .context.render_facts por extenso. É a chave, e não a verificação, que decide quando a anexação renderiza, por isso defina-a em cada FeatureRecipe cujos templates leiam os factos de renderização dos seus chamadores, seja como for que lá cheguem; defini-la não custa nada além da renderização posterior.
Um passo de pipeline lê apenas os factos do seu próprio anfitrião. Um passo pode reescrever os próprios documentos do componente anfitrião, e a própria saída de um componente é a mesma independentemente de quem se liga a ele, pelo que os with: e when: de um passo nunca veem os componentes que se ligam ao anfitrião — quer a FeatureRecipe defina ou não a chave, que decide quando a anexação renderiza e nada sobre o que um passo vê. Um with: ou when: de um passo escrito inline que leia render_facts sob .context.used_by interrompe portanto o build antes de qualquer renderização, com o código curto E0326, indicando a referência e o campo do passo — em vez de renderizar um valor vazio. Leia os factos do próprio anfitrião num passo em .context.render_facts, escrito por extenso, e leia os factos dos chamadores nos valuesMapping:, workload: ou artifacts: da FeatureRecipe. Esta verificação lê o template tal como está escrito, com os mesmos limites que a anterior.
Âmbito. A chave aplica-se a uma FeatureRecipe que renderiza uma vez por componente — executionScope: component, a predefinição. Uma FeatureRecipe que declara executionScope: boundary renderiza onde sempre renderiza, defina ou não a chave, e os templates que produzem os seus recursos leem .boundary em vez de .context.
Renderizar depois dos destinos — spec.readsTargetRenderFacts
O spec.readsTargetRenderFacts opcional (booleano, predefinição false) declara que os templates desta FeatureRecipe leem o que renderizaram os componentes a que o seu anfitrião está ligado: os factos de renderização que o fornecedor de cada um desses destinos indica sobre a saída que emitiu. Lê a outra extremidade de uma ligação em relação a readsCallerRenderFacts — os componentes para os quais apontam as entradas uses do anfitrião, e não os componentes cujas entradas uses apontam para o anfitrião — e tudo o que diz respeito aos próprios factos lê-se da mesma forma.
Qualquer uma das chaves faz com que a anexação renderize depois de todos os componentes. Uma anexação cuja FeatureRecipe define readsCallerRenderFacts: true, readsTargetRenderFacts: true ou ambas renderiza depois de todos os componentes do build terem renderizado, como descreve a secção acima — existe uma única renderização posterior deste tipo, e o que ela faz ao local onde fica a saída da anexação e à ordem dos seus passos de pipeline é o mesmo, qualquer que seja a chave que levou a anexação até lá. As duas chaves diferem apenas nas ligações que transportam factos no contexto da anexação: um destino que vem depois do anfitrião na ordem do build já renderizou nessa altura, pelo que o que emitiu está lá para ser lido.
O que lê. Com a chave definida, cada entrada de .context.uses transporta .render_facts: os factos de renderização do destino, indexados pelo nome do facto, com a forma que a entrada de um chamador transporta. Cada facto de renderização é uma lista, pelo que um template percorre-a sempre. As suas entradas podem vir da própria renderização do destino e das renderizações das Features anexadas ao destino, primeiro as chamadas do próprio fornecedor do destino, depois cada uma das suas Features pela ordem em que renderizaram; uma Feature do destino que ela própria renderize depois de todos os componentes não está entre elas. Um destino cujos fornecedores não indicam nada transporta um .render_facts vazio. Um template lê os factos de uma ligação sob o seu alias, .context.uses.<alias>.render_facts.<name>, ou os de cada ligação à 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 ligação, seja o que for que defina. Que nomes de factos existem é o contrato documentado do fornecedor de cada destino — os do fornecedor helm são os seus factos de renderização, que indicam as etiquetas, os seletores de controlador e as portas de contentor dos pods que renderizou, e portanto aquilo de que uma política de egress precisa para selecionar exatamente os pods que o seu anfitrião pode alcançar.
Declare-a sempre que um template ler os factos. Um template escrito inline numa FeatureRecipe que não define a chave — o seu valuesMapping:, o seu workload: ou uma entrada de artifacts: — que leia render_facts sob .context.uses interrompe o build antes de qualquer renderização, com o código curto E0347, indicando a referência e o campo em que foi escrita (consulte «A template reads its targets’ render facts without declaring it (Um template lê os factos de renderização dos seus destinos sem o declarar)» em fatal-halts.md). Definir readsCallerRenderFacts não evita essa interrupção. A verificação lê o template tal como está escrito, com os limites que a verificação dos chamadores tem: não vê uma referência construída enquanto o template é executado, nem uma escrita em conteúdo importado de um ficheiro ou de uma biblioteca — e um template que leia .context.uses de todo e também leia um campo chamado render_facts de algum outro valor, incluindo a entrada de um chamador dentro de {{ range .context.used_by }}, é tratado como lendo os factos dos seus destinos. Um template que leia os factos de ambas as extremidades define ambas as chaves.
Um passo de pipeline lê apenas os factos do seu próprio anfitrião. Os with: e when: de um passo leem as ligações que o anfitrião faz, tal como a própria Recipe do anfitrião as lê, e nunca os factos de renderização dos seus destinos — quer a FeatureRecipe defina ou não a chave. Um passo pode reescrever os próprios documentos do componente anfitrião, e a própria renderização do anfitrião lê o que os seus destinos publicam, nunca o que emitiram. Um with: ou when: de um passo escrito inline que leia render_facts sob .context.uses interrompe portanto o build antes de qualquer renderização, com o código curto E0348, indicando a referência e o campo do passo — em vez de renderizar um valor vazio. Leia os factos dos destinos nos valuesMapping:, workload: ou artifacts: da FeatureRecipe.
Âmbito. Tal como para a chave dos chamadores: aplica-se a uma FeatureRecipe que renderiza uma vez por componente. Uma FeatureRecipe que declara executionScope: boundary renderiza onde sempre renderiza, defina ou não a chave, e as ligações que lê sob .boundary não transportam factos de renderização.
O bloco locals:
FeatureRecipe.spec.locals: é um mapa opcional de strings de template Go com nome cuja saída renderizada expõe um mapa .locals.* a todos os outros templates dentro da mesma FeatureRecipe. É o equivalente privado da FeatureRecipe dos locals: da Recipe — um local para calcular strings derivadas uma única vez e referenciá-las a partir de injectMapping, valuesMapping, pipeline[].with e provides sem as recalcular. As assertions: da FeatureRecipe não as leem: os .locals de uma asserção são os da Recipe do componente anfitrião, como indica assertions-block.md. A saída renderizada de cada entrada é guardada 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 esquema.
apiVersion: aggrega.ai/v1beta1kind: FeatureRecipemetadata: name: regional-routerspec: 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 da FR resolve o seu próprio bloco locals:, e o resultado só é visível para os templates a jusante dessa invocação. O bloco é resolvido antes de os outros templates da superfície de criação da FR serem avaliados, pelo que todos eles veem valores resolvidos.
Cada entrada é avaliada contra um contexto autónomo: .context.instance_id, .context.rendered_name, .attachment_name, .values, .infra e as entradas deste mesmo bloco já resolvidas. Isto é deliberadamente mais restrito do que o contexto que os outros templates da FR leem — uma entrada de locals: não consegue 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. Os valores derivados que precisem 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: lê-os exatamente como os outros templates da FeatureRecipe:
.context.instance_idé o componente anfitrião para o qual a anexação está a ser resolvida. Significa o componente anfitrião em todas as superfícies de template que o compilador avalia, pelo que a mesma referência se lê da mesma forma, qualquer que seja o bloco de entidade que se esteja a escrever..context.rendered_nameé o nome do componente anfitrião tal como o seu próprio fornecedor o indica — comhelm, o nome de release, que é a identidade do anfitrião escrita no alfabeto que um nome do Kubernetes admite. Só está presente quando o fornecedor do anfitrião indica um nome, e lê-lo num anfitrião cujo fornecedor não indica nenhum interrompe o build..attachment_nameé a instância de anexação a ser resolvida — o slot que preenche nofeaturesSchemada entidade proprietária, ou o nome livre que lhe deu.
Assim, uma entrada de locals: que deriva um nome para um recurso emitido compõe o anfitrião e a anexação, exatamente como faria um template de artifacts::
spec: locals: scrape_name: "{{ .context.instance_id }}-{{ .attachment_name }}" # api-scrape_targetQuando o nome tem de ser um que a plataforma aceite e o fornecedor do anfitrião indica um, componha-o antes a partir de .context.rendered_name: para um anfitrião chamado my_api com helm e uma anexação scrape, {{ .context.rendered_name }}-{{ .attachment_name }} dá my-zuapi-scrape, enquanto a identidade daria my_api-scrape, que um nome do Kubernetes recusa. Consulte Dar nome a um recurso renderizado.
.values e .infra numa entrada de locals: são os pilares da própria anexação, criados na declaração da anexação — não os do componente anfitrião.
A ordem de criação é determinante
As entradas são resolvidas pela ordem em que estão escritas, e uma entrada pode ler uma irmã definida acima dela, recebendo o valor resolvido dessa irmã:
spec: locals: region_prefix: "{{ .infra.region | lower }}" # defined first bucket: "{{ .locals.region_prefix }}-artifacts" # reads the entry aboveO encadeamento funciona apenas para baixo. Quando uma entrada lê outra, a ordem das entradas decide se o build é bem-sucedido: mova region_prefix para baixo de bucket e o build é interrompido. O compilador nunca reordena o bloco para fazer uma referência resolver-se, pelo que reordenar um bloco locals: é uma alteração de comportamento, não uma alteração cosmética.
Uma referência a uma entrada que o bloco define mais abaixo interrompe o build indicando a falha de ordenação (mova a definição para cima de quem a lê); uma referência a uma chave que o bloco não declara de todo interrompe o build indicando a chave (corrija a grafia). A verificação segue um alias do bloco: uma chave alcançada através do ponto que um corpo with .locals volta a associar, ou através de uma variável associada a .locals, interrompe o build exatamente nos mesmos termos que a grafia direta, tal como uma chave lida do bloco entre parênteses — {{ (.locals).nope }} ou {{ ($.locals).nope }}. Só uma grafia lhe escapa: uma chave alcançada através de 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 destas não interrompe o build e renderiza o texto literal <no value>; a leitura com index interrompe o build indicando a chave, porque index interrompe o build em todas as superfícies 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 dos seus provides; um template provides: que indique 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 de âmbito. Para executionScope: component (predefinição), locals: é avaliado por instância de componente anexada contra o contexto autónomo acima. Para executionScope: boundary, locals: é avaliado por anexação de fronteira contra a vista com âmbito 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 com âmbito de fronteira aplica-se a locals: da mesma forma que se aplica aos outros templates da superfície de criação da FR. O injectMapping, que é executado para cada componente que a anexação alcança, lê essa única avaliação de fronteira como o seu .locals. O contrato de avaliação — ordem de criação, leituras de irmãs apenas para baixo, as duas interrupções — é idêntico em ambos os âmbitos; só a forma do contexto envolvente difere.
Distinção em relação às sobreposições de injectMapping e aos mapeamentos de pipeline[].with. locals: produz um mapa visível no contexto para os templates a jusante; não contribui com saída. injectMapping escreve no canal .context.inject do consumidor (mutação do lado do chamador). pipeline[].with fornece a carga args do plugin Wasm. As três superfícies são ortogonais — uma FeatureRecipe usa habitualmente as três em conjunto, com locals: a transportar as strings derivadas partilhadas que as outras duas referenciam.
O bloco assertions:
FeatureRecipe.spec.assertions: é um mapa opcional de regras com nome que exprimem invariantes de implementação da FeatureRecipe — regras entre campos que se verificam dado o pipeline de plugins Wasm, o chart ou o mecanismo específico em que a FeatureRecipe assenta. Cada chave é um identificador de regra que aparece na mensagem de falha; cada valor é um corpo de template Go. Tal como as asserções de Recipe, as asserções de FeatureRecipe são propriedades da implementação específica; as regras de contrato ao nível da Feature aplicam-se de forma independente numa 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; não se aplica se se associar uma FeatureRecipe core/referenced-secret diferente. As regras de contrato ao nível da Feature da definição da Feature continuam a aplicar-se em paralelo.
As asserções de FeatureRecipe são avaliadas depois da associação da FeatureRecipe e antes da geração de recursos. O contexto de template das FRs com âmbito de componente espelha o contexto das asserções de Recipe (campos da instância da entidade mais .provides, .locals, .recipe.metadata, .recipe.source); nas FRs com âmbito de fronteira (executionScope: boundary), as asserções são avaliadas contra a vista com âmbito de fronteira (campos .boundary.* disponíveis; campos por componente não). Para a gramática de criação completa e exemplos práticos, consulte templates/assertions-block.md.
O campo omits: — deixar documentos renderizados de fora de uma origem
A maioria das FeatureRecipes nunca precisa disto. Destina-se a uma FeatureRecipe cujo source: é um chart usado tal como é — na maioria das vezes, um obtido a partir de um registo — 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 anfitrião ou o operador já fornece. omits: deixa esse documento de fora do que a FeatureRecipe gera — ou, para um ficheiro compose que a FeatureRecipe usa como origem, um serviço, um volume ou uma config que a anexação não deve contribuir, e para um template CloudFormation que usa como origem, 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-dashboardsA chave é criada de forma idêntica numa Recipe, e Recipe → O campo omits: é a sua referência completa: o que cada campo de entrada seleciona, que when: é avaliado primeiro e que um falso elimina a entrada, que cada entrada que se aplica tem de deixar algo de fora ou o build é interrompido indicando-a, que a origem continua a ser renderizada na íntegra e apenas a sua saída é filtrada, e que fornecedores respeitam a chave. O que difere numa FeatureRecipe é apenas 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 âmbito que o seuexecutionScopeseleciona. As entradas de uma FeatureRecipe com âmbito de componente são avaliadas uma vez por anexação, contra os.valuese o.infradessa anexação; as de uma com âmbito de fronteira, uma vez por fronteira, contra a vista com âmbito de fronteira e o.infrada anexação de fronteira. As regras sobre o que os templates de uma anexação podem ler aplicam-se às entradas tal como se aplicam ao seuvaluesMapping:. - Só é filtrado o que o próprio
source:desta FeatureRecipe renderiza. Os seusworkload:eartifacts:não o são, nem a saída do componente anfitrião: as entradas de uma anexação alcançam o seu próprio chart, o seu próprio ficheiro compose ou o seu próprio template CloudFormation, e nada mais — um serviço compose que o anfitrião declara sob a mesma chave nodocker-compose.yamlem que ambos se montam fica intacto, tal como um recurso que o anfitrião declara sob o mesmo ID lógico na stack em que ambos se montam. Para alterar um documento que o anfitrião renderiza, a Recipe do anfitrião declara a entrada, ou um passo depipeline:aplica-lhe um patch.
Uma interrupção numa entrada indica o nó, o fornecedor, esta FeatureRecipe e a posição da entrada na sua lista omits:; para uma FeatureRecipe com âmbito de fronteira, a linha acima da mensagem indica a anexação e a sua fronteira.
Para um exemplo prático da chave, criada numa 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.