Matriz de expansão de templates
Referência da expansão de templates — a matriz completa
A DSL do Aggrega suporta a expansão text/template do Go (com a biblioteca Sprig pré-registrada) em vários locais das entidades YAML. Cada local tem um conjunto específico de referências disponíveis, determinado pelo momento em que os dados se tornam concretos à medida que a compilação avança. Esta página é a referência do que pode ser referenciado e onde.
1. A árvore temporal do pipeline (quando os dados se tornam concretos)
Entender quais referências estão disponíveis exige entender quando cada dado é resolvido. As fases abaixo estão listadas na ordem em que são executadas, e cada uma recebe o nome do que faz — esse nome é como o restante desta página se refere a ela:
Resolution — resolver and syntax validator ├── .parameters → Interpolated into the Aggregate's text; the merged map │ then stays readable to path templates only ├── .values → schema-validated against the Component's pillar schema, concrete ├── .infra → Release-merged into target components/features, concrete └── Catalog entities → Resolved (extends merged, pillar schemas composed, usesSchema extracted)
Topology construction ├── .context.instance_id → Node identity, written as a name (e.g., "data-layer-zdmain-db") └── .context.labels → From Catalog + label-transform mutations
Graph finalization ├── .context.annotations.release → Cascaded from boundary hierarchy ├── .context.annotations.catalog → From Component metadata.annotations ├── .context.annotations.aggregate → Cascaded from subsystem hierarchy └── feature_values_mapping → 5-Tier Onion Model normalized
Rendering begins. Provides evaluation — locals preamble, then provides ├── .context.rendered_name → Asked of each node's provider before the preamble; present only where │ that provider derives a name for the node's output ├── .locals (per node) → Block resolved in author order; an entry reads earlier siblings └── .provides (all nodes) → Self-contained templates evaluated (any order), reading .locals
Inject hydration — self-inject resolution └── component.inject → value: literals expanded, from: own provides resolved
Inject hydration — uses-inject resolution └── uses[].inject → from: target provides resolved
Inject mapping — injectMapping interception └── .context.inject → Fully populated pipe, intercepted by FeatureRecipe injectMappings
Base rendering └── Full template context → Everything available
The plugin pipeline — post-render mutation └── Full template context + .steps → Inter-step pipeline outputs available2. A matriz de expansão de templates
Todo local da DSL em que expressões de template Go são avaliadas, e exatamente quais referências estão disponíveis:
| # | Location | Entidade | Avaliado em | Referências disponíveis |
|---|---|---|---|---|
| 1 | {{ .parameters.X }} em strings YAML do Aggregate | Aggregate | Resolução (interpolação) | Apenas .parameters. Todos os outros dados ainda não estão resolvidos. |
| 2 | {{ .parameters.X }} em strings YAML da Release | Release | Não avaliado | Nenhuma. As strings de uma Release são lidas como estão escritas: um {{ .parameters.X }} sob infra:, em uma anotação ou como valor de parameters: chega ao seu destino como esse texto literal. A Release fornece os valores dos parâmetros (o mapa parameters: inline e os valores carregados por $import: combinados no mapa de parâmetros mesclado); as strings do Aggregate os leem (#1), e os templates de caminho também (#3). |
| 3 | Templates directory / subDirectory | Fronteira da Release | Renderização (avaliação de caminhos) | .capability, .boundary_name, .parameters.X, .manifest.recipe_name, .parent_boundary.* e .component_id (apenas subDirectory: — um template directory: o recusa). |
| 4 | Strings value: de inject do Component | Componente do Aggregate | Resolução de self-inject | .values, .infra, .context.instance_id, .context.labels, .context.annotations.* (os 3 contêineres), .metadata.* (release_name, release_version, environment, aggregate_name). PROIBIDO: .context.inject (circular — o pipe está sendo construído), .context.uses (use em vez disso uses[].inject para a fiação entre componentes). O template fica no texto do Aggregate, que a interpolação de parâmetros de #1 lê primeiro, então escreva-o com escape — value: '{{"{{"}} .metadata.release_name }}' — para que ele chegue a esta fase; escrito sem escape, a interpolação o avalia e é interrompida, já que o texto de um Aggregate não define nenhuma raiz além de .parameters. |
| 5 | Strings do campo source (string de nível superior OU subcampos com valor string de um mapa source: estruturado) | Recipe / FeatureRecipe | Resolução da fonte | Duas superfícies, decididas pelo que a fonte nomeia. Uma coordenada remota — os version, chart, ref e module_subdir de um bloco estruturado que nomeia um registry, um repositório de charts ou um repositório git — é avaliada quando aggrega pull resolve o artefato para fixá-lo: apenas .values, .infra, .locals e strings estáticas, com os helpers próprios do Aggrega (optional, capitalizedWords, index) e nenhuma das funções do Sprig, e sem raiz .context. As entradas de .locals avaliadas ali são as que esses campos leem, diretamente ou através de outra entrada — todas as entradas quando um campo lê .locals de uma forma que não nomeia nenhuma entrada específica —, de modo que uma entrada que nenhum campo lê fica para a renderização. Uma fonte que nomeia um caminho no espaço de trabalho é avaliada enquanto a entidade é renderizada: .context.instance_id, .values, .infra, .locals (todo o bloco resolvido da entidade declarante), strings estáticas. Ali a fonte de uma FeatureRecipe lê além disso .attachment_name — o que está sendo resolvido é uma vinculação — e o seu .context.instance_id nomeia o componente host, ao lado de .context.rendered_name, o nome reportado do componente host (veja #9); uma FeatureRecipe com escopo de fronteira lê .boundary.* e nenhum dos pilares por componente. PROIBIDO em ambas: .context.inject, .context.uses, .provides (invariante de autocontenção — a superfície de fonte do espaço de trabalho compartilha o seu contexto com os locals próprios da entidade declarante, de modo que as duas admitem e recusam as mesmas referências, e uma coordenada remota lê um subconjunto desse contexto; a resolução da fonte precisa ser concluída antes que o pipe da topologia seja hidratado e antes que qualquer chart, módulo ou corpo de artefato seja carregado). |
| 6 | Templates provides da Recipe | Recipe | Avaliação de provides | .context.instance_id, .context.rendered_name (o nome que o provedor do nó dá à saída que renderiza para o nó — a partir de uma origem fornecida pelo autor, ou de um workload que ele sintetiza; lê-lo em um nó cujo provedor não reporta nenhum nome desse tipo provoca uma interrupção — veja Nomear um recurso renderizado), .values, .infra, .locals (todo o bloco resolvido do nó — os locals são resolvidos no preâmbulo desta fase, antes dos provides), strings estáticas. PROIBIDO: qualquer outra raiz — .context.inject, .context.uses (entre nós), .context.annotations.*, .context.labels, .context.metadata, .metadata.* (acoplado a posicionamento/implantação) e .attachment_name (nenhuma vinculação está sendo resolvida durante a avaliação de provides de uma Recipe base). A verificação é uma allowlist positiva: referenciar qualquer raiz que o contexto de provides não expõe provoca uma interrupção (invariante de autocontenção — permite a avaliação paralela sem nenhuma ordenação topológica). Um .locals.<key> que nomeia uma chave que o bloco de locals não declara também provoca uma interrupção, já que o pilar é um mapa aberto com chaves que a verificação de raiz sozinha não consegue policiar. |
| 7 | valuesMapping da Recipe (inline, $import: de arquivo ou $import: de biblioteca) | Recipe | Renderização base | Contexto de template completo: .values, .infra, .context.* (instance_id, rendered_name, labels, annotations, inject, uses), .locals, .provides, .features, .metadata. Uma referência .context.rendered_name escrita inline provoca uma interrupção em um nó cujo provedor não reporta nenhum nome desse tipo, como em #6; uma dentro de um corpo carregado por $import: não é verificada, e é renderizada vazia em um nó assim. |
| 8 | injectMapping da FeatureRecipe | FeatureRecipe | Mapeamento de inject | Contexto de template completo: .values, .infra, .context.* (incluindo .context.inject — o pipe que está sendo interceptado — e .context.uses). .context.used_by está vazio aqui: a saída do mapeamento chega ao pipe de entrega próprio do host. .context.render_facts está ausente: o mapeamento é executado antes que o host seja renderizado. .context.rendered_name é o nome reportado do componente host, como em #9; um mapeamento que o lê não é verificado, e o renderiza vazio em um host cujo provedor não reporta nenhum. O mesmo contexto qualquer que seja o executionScope da FeatureRecipe: o mapeamento de uma FeatureRecipe com escopo de fronteira é executado uma vez para cada componente que a vinculação alcança, lê o .context.* desse componente, e lê .features.<attachment>.provides e .locals como a única avaliação da fronteira. PROIBIDO: .boundary, que o contexto de nenhum componente carrega — uma referência interrompe o build. |
| 9 | valuesMapping da FeatureRecipe (e os seus workload: e artifacts:) | FeatureRecipe | Renderização base | Contexto de template completo + .attachment_name, .inject (as entradas inject: próprias da vinculação, quando a vinculação escreve um bloco inject:), .context.render_facts — o que o provedor do host reportou sobre a renderização do host — e .context.used_by — os componentes que usam o host, cada um carregando os seus próprios fatos de renderização quando a FeatureRecipe define readsCallerRenderFacts: true. Cada conexão em .context.uses carrega os fatos de renderização do seu destino, em .render_facts, quando a FeatureRecipe define readsTargetRenderFacts: true. .context.instance_id e .context.rendered_name são a identidade do componente host e o nome que o próprio provedor do host reporta para ele — o mesmo valor que a Recipe do host lê, também nos locals: e provides: da FeatureRecipe — e uma referência a .context.rendered_name escrita inline provoca uma interrupção em um host cujo provedor não reporta nenhum nome desse tipo. .source é o source: avaliado da própria FeatureRecipe, nunca o do componente host, e não contém nada quando a FeatureRecipe não declara nenhum. |
| 10 | Blocos with: do pipeline | Recipe / FeatureRecipe | O pipeline de plugins | Contexto de template completo + .steps (saídas entre etapas vindas das etapas anteriores do pipeline). .context.used_by está vazio aqui, e nenhuma conexão em .context.uses carrega os fatos de renderização do seu destino: uma etapa pode reescrever os próprios documentos do host. A etapa de uma FeatureRecipe vinculada lê .context.render_facts, os próprios fatos de renderização do host, como faz #9. |
| 11 | Corpo workload: da Recipe (todo campo com template dentro dele, seja inline ou carregado por $import:) | Recipe | Renderização base | Contexto de template completo. Todo campo dentro do corpo do Workload — replicas, containers.<name>.image, containers.<name>.variables.<KEY>, containers.<name>.ports.<port>, services.<name>.ports.<port>, volumes.<name>.*, health.* — faz parte da mesma avaliação de template que consome toda a string do Workload. O conteúdo do Workload é um único template Go avaliado uma vez em relação ao contexto de template completo; os templates em nível de campo dentro dele são resolvidos na mesma avaliação, e não em uma separada. |
Nota de autocontenção. As strings source (#5) compartilham a invariante de autocontenção de provides (#6): ambas as superfícies rejeitam referências a .context.inject e .context.uses. A resolução da fonte é executada antes da hidratação de inject que preenche .context.inject, e antes que qualquer coisa a jusante consuma a fonte resolvida — então a regra e a sua justificativa valem para ambas as superfícies. Onde as duas diferem é no pilar provides: uma source do espaço de trabalho compartilha o seu contexto com os locals da entidade declarante, e uma coordenada remota lê um subconjunto dele, então ambas recusam .provides, enquanto provides é ele próprio a superfície que está sendo resolvida. Ambas leem .locals. A regra alcança a source de uma FeatureRecipe nos mesmos termos em que alcança a de uma Recipe, cada uma verificada em relação à superfície locals própria dessa entidade.
Nota sobre templates no corpo do Workload (#11). O corpo do Workload é uma única string com templates que o renderizador avalia como um todo, para depois analisar o resultado como um documento Workload. Os templates em nível de campo dentro dele (um replicas: {{ .infra.replicas | default 1 }} aqui, um LOG_LEVEL: "{{ .values.log_level }}" dentro de containers.app.variables ali) não são pontos de avaliação de template separados — todos participam da única avaliação da renderização base que produz o Workload. Os autores não precisam de uma regra de disponibilidade separada para os campos internos do Workload; a regra para o Workload como um todo (#11) cobre todo template em nível de campo dentro dele.
Fallback ciente do discriminador dentro do corpo do Workload. O exemplo replicas: {{ .infra.replicas | default 1 }} acima confunde “o autor não definiu replicas” com “o autor definiu replicas como 0” — default é acionado nos dois casos. Quando uma Release escreve legitimamente infra.replicas: 0 para expressar scale-to-zero (um padrão comum de Knative / KEDA), a forma | default 1 substitui silenciosamente a intenção. A forma ciente do discriminador é replicas: {{ optional .infra "replicas" 1 }} — optional verifica a presença da chave e retorna o valor escrito (incluindo um zero escrito) quando a chave está definida, recorrendo a 1 apenas quando a chave está ausente. Veja sprig-functions.md para a semântica completa e as orientações sobre quando preferi-la.
3. Referências proibidas & justificativa
| Location | Referência proibida | Justificativa |
|---|---|---|
value: de inject do Component (#4) | .context.inject | O pipe de inject está sendo construído nesse ponto — um template value: de self-inject não pode ler do pipe para o qual contribui. |
value: de inject do Component (#4) | .context.uses | A fiação entre componentes fica em uses[].inject. Os templates value: de self-inject de um componente permanecem fechados sobre os dados próprios do componente. |
provides da Recipe (#6) | .context.inject | Os templates de provides são avaliados em qualquer ordem e se fecham apenas sobre os dados próprios do nó (.values, .infra, .locals, .context.instance_id, .context.rendered_name). O pipe de inject não é preenchido até a hidratação de inject, que é executada depois que os provides de todos os nós são avaliados. |
provides da Recipe (#6) | .attachment_name | A passagem de provides de uma Recipe base não resolve nenhuma vinculação, então o nome seria renderizado vazio. A raiz é recusada em vez de ser entregue em branco. |
source (#5) | .provides | Nenhuma das duas superfícies de fonte carrega um pilar provides: a superfície de fonte do espaço de trabalho compartilha o seu contexto com os locals próprios da entidade declarante, que não tem nenhum, e uma coordenada remota lê um subconjunto desse contexto. Os locals são resolvidos antes dos provides para que provides: possa ler .locals; o template da fonte lê os mesmos locals em vez de voltar atrás para buscar os provides. |
locals da Recipe (preâmbulo de #6) | .provides | Os locals são resolvidos antes dos provides, então os provides próprios do nó ainda não existem quando um local é avaliado. Um local que precisa de um valor que os provides também publicam o calcula diretamente a partir de .values / .infra — e a entrada provides então lê o local. |
locals da Recipe (preâmbulo de #6) | .context.rendered_name | Os locals de uma Recipe compartilham o seu contexto com o seu template source (#5), e essa superfície não oferece o nome: se o nó fornece uma origem, o que o template source decide, é uma das coisas de que o nome depende. A referência é interrompida com o diagnóstico de raiz desconhecida, que lista .context.instance_id como o que .context define ali. Em vez disso, leia a chave em uma entrada provides, ou em um template da fase de renderização base. |
provides da Recipe (#6) | .context.uses | .context.uses se refere aos provides de outros nós, e a avaliação de provides os executa em ordem arbitrária. Os templates de provides permanecem autocontidos para que a avaliação continue independente da ordem. |
locals, provides, source (#5) de uma FeatureRecipe e templates de renderização inline (#9, #10), em um host cujo provedor não reporta nenhum nome | .context.rendered_name | Em uma vinculação de Feature a chave carrega o nome reportado do componente host, e um host que coloca sozinho um conjunto de artefatos, ou que renderiza por meio de um provedor que não deriva nenhum nome desse tipo, não tem nenhum para carregar. A referência é interrompida com o diagnóstico de raiz desconhecida, que lista .context.instance_id entre o que .context define ali; em vez disso, leia a identidade, que é o que dá nome aos recursos próprios do host em um host assim. |
source (#5) | .context.inject | A resolução da fonte é executada antes da hidratação de inject que preenche .context.inject. O pipe ainda não está preenchido quando o URI da fonte é avaliado. |
source (#5) | .context.uses | A resolução da fonte precisa ser concluída antes que qualquer coisa a jusante carregue o chart, o módulo ou o corpo de artefato da entidade declarante. Permitir referências entre nós acoplaria a resolução da fonte à ordem de iteração da topologia, o que ela evita deliberadamente. |
| Parâmetros (em todos os lugares, exceto nos templates de caminho) | Qualquer superfície de template de valor após a interpolação | A interpolação consome toda referência {{ .parameters.X }} no YAML escrito e escreve o valor resolvido em seu lugar, de modo que uma superfície de template de valor recebe o literal resolvido em vez do pilar de parâmetros. Os templates de caminho escritos pelo operador são a única exceção e leem .parameters.X diretamente. |
4. O caminho de resolução de self-inject
A resolução de self-inject é a primeira metade da hidratação de inject, e é executada depois que os provides de todos os nós foram avaliados. Quando um componente declara um bloco inject: no nível do componente, o compilador o avalia ali:
- Strings
value:literais: se o valor contém expressões de template Go, o compilador as avalia com o contexto da linha #4 da matriz (.values,.infra,.context.instance_id,.metadata.*etc.), escritas com escape como a linha #4 mostra. Strings simples passam sem alteração. - Referências
from:: o compilador procura a chave no dicionárioprovidespróprio do nó, já resolvido nesse momento. Se a chave não existe, o compilador interrompe o build com um erro de chave de inject inválida. - Verificação de colisões: antes de mesclar no pipe
.context.inject, o compilador verifica que nenhuma chave colide com as chaves de uses-inject que a segunda metade da hidratação de inject resolve. Colisões interrompem o build com um erro de chave de entrega duplicada.
As strings resultantes são mescladas em .context.inject.env, .context.inject.file, .context.inject.arg (e quaisquer mecanismos personalizados), ao lado dessas resoluções de uses-inject. Quando o mapeamento de inject (injectMapping) é executado, o pipe contém todos os valores de inject escritos pelo desenvolvedor vindos de ambas as origens.