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é-registada) 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 daquilo que pode ser referenciado e onde.
1. A árvore temporal do pipeline (quando os dados se tornam concretos)
Compreender que referências estão disponíveis exige compreender quando cada dado é resolvido. As fases abaixo estão listadas pela ordem em que são executadas, e cada uma tem o nome daquilo que faz — é por esse nome que o resto desta página se lhe refere:
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
Cada local da DSL em que são avaliadas expressões de template Go, e exatamente que referências estão disponíveis:
| # | Location | Entidade | Avaliado em | Referências disponíveis |
|---|---|---|---|---|
| 1 | {{ .parameters.X }} em cadeias YAML do Aggregate | Aggregate | Resolução (interpolação) | Apenas .parameters. Todos os outros dados ainda não estão resolvidos. |
| 2 | {{ .parameters.X }} em cadeias YAML da Release | Release | Não avaliado | Nenhuma. As cadeias de uma Release são lidas tal como estão escritas: um {{ .parameters.X }} sob infra:, numa 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 fundido); as cadeias do Aggregate leem-nos (#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: recusa-o). |
| 4 | Cadeias value: de inject do Component | Componente do Aggregate | Resolução de self-inject | .values, .infra, .context.instance_id, .context.labels, .context.annotations.* (os 3 contentores), .metadata.* (release_name, release_version, environment, aggregate_name). PROIBIDO: .context.inject (circular — o pipe está a ser construído), .context.uses (deve usar-se antes uses[].inject para a cablagem entre componentes). O template está no texto do Aggregate, que a interpolação de parâmetros de #1 lê primeiro, pelo que deve ser escrito com escape — value: '{{"{{"}} .metadata.release_name }}' — para chegar a esta fase; escrito sem escape, a interpolação avalia-o e para, uma vez que o texto de um Aggregate não define nenhuma raiz além de .parameters. |
| 5 | Cadeias do campo source (cadeia de nível superior OU subcampos com valor de cadeia de um mapa source: estruturado) | Recipe / FeatureRecipe | Resolução da fonte | Duas superfícies, decididas por aquilo 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 artefacto para o fixar: apenas .values, .infra, .locals e cadeias 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 aí avaliadas 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 concreta —, pelo que uma entrada que nenhum campo lê fica para a renderização. Uma fonte que nomeia um caminho no espaço de trabalho é avaliada durante a renderização da entidade: .context.instance_id, .values, .infra, .locals (todo o bloco resolvido da entidade declarante), cadeias estáticas. Aí, a fonte de uma FeatureRecipe lê adicionalmente .attachment_name — o que está a ser resolvido é um anexo — e o seu .context.instance_id nomeia o componente host, ao lado de .context.rendered_name, o nome reportado do componente host (ver #9); uma FeatureRecipe com âmbito de fronteira lê .boundary.* e nenhum dos pilares por componente. PROIBIDO em ambas: .context.inject, .context.uses, .provides (invariante de autossuficiência — a superfície de fonte do espaço de trabalho partilha o seu contexto com os locals próprios da entidade declarante, pelo que as duas admitem e recusam as mesmas referências, e uma coordenada remota lê um subconjunto desse contexto; a resolução da fonte tem de estar concluída antes de o pipe da topologia ser hidratado e antes de qualquer chart, módulo ou corpo de artefacto ser carregado). |
| 6 | Templates provides da Recipe | Recipe | Avaliação de provides | .context.instance_id, .context.rendered_name (o nome que o fornecedor do nó dá à saída que renderiza para o nó — a partir de uma origem fornecida pelo autor, ou de um workload que sintetiza; lê-lo num nó cujo fornecedor não reporta nenhum nome desse tipo provoca uma paragem — ver Atribuir um nome a 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), cadeias estáticas. PROIBIDO: qualquer outra raiz — .context.inject, .context.uses (entre nós), .context.annotations.*, .context.labels, .context.metadata, .metadata.* (ligado a posicionamento/implementação) e .attachment_name (nenhum anexo está a ser resolvido 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 paragem (invariante de autossuficiência — permite a avaliação paralela sem qualquer ordenação topológica). Um .locals.<key> que nomeia uma chave que o bloco de locals não declara também provoca uma paragem, uma vez que o pilar é um mapa aberto com chaves que a verificação de raiz, por si só, não consegue controlar. |
| 7 | valuesMapping da Recipe (inline, $import: de ficheiro 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 paragem num nó cujo fornecedor não reporta nenhum nome desse tipo, como em #6; uma dentro de um corpo carregado por $import: não é verificada, e é renderizada vazia num nó assim. |
| 8 | injectMapping da FeatureRecipe | FeatureRecipe | Mapeamento de inject | Contexto de template completo: .values, .infra, .context.* (incluindo .context.inject — o pipe que está a ser intercetado — 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 de o host ser renderizado. .context.rendered_name é o nome reportado do componente host, como em #9; um mapeamento que o lê não é verificado, e renderiza-o vazio num host cujo fornecedor não reporta nenhum. O mesmo contexto qualquer que seja o executionScope da FeatureRecipe: o mapeamento de uma FeatureRecipe com âmbito de fronteira é executado uma vez para cada componente que o anexo 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 contém — uma referência interrompe a compilação. |
| 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 do anexo, quando o anexo escreve um bloco inject:), .context.render_facts — aquilo que o fornecedor do host reportou sobre a renderização do host — e .context.used_by — os componentes que usam o host, cada um com os seus próprios factos de renderização quando a FeatureRecipe define readsCallerRenderFacts: true. Cada ligação em .context.uses contém os factos 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 fornecedor 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 paragem num host cujo fornecedor 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 passos provenientes dos passos anteriores do pipeline). .context.used_by está vazio aqui, e nenhuma ligação em .context.uses contém os factos de renderização do seu destino: um passo pode reescrever os documentos próprios do host. O passo de uma FeatureRecipe anexada lê .context.render_facts, os factos de renderização próprios do host, tal como faz #9. |
| 11 | Corpo workload: da Recipe (cada campo com template no seu interior, seja inline ou carregado por $import:) | Recipe | Renderização base | Contexto de template completo. Cada 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 cadeia do Workload. O conteúdo do Workload é um único template Go avaliado uma vez em relação ao contexto de template completo; os templates ao nível do campo no seu interior são resolvidos na mesma avaliação, e não numa avaliação separada. |
Nota de autossuficiência. As cadeias source (#5) partilham a invariante de autossuficiência 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 de qualquer elemento a jusante consumir a fonte resolvida — pelo que a regra e a sua fundamentação valem para ambas as superfícies. Aquilo em que as duas diferem é o pilar provides: uma source do espaço de trabalho partilha o seu contexto com os locals da entidade declarante, e uma coordenada remota lê um subconjunto dele, pelo que ambas recusam .provides, enquanto provides é ele próprio a superfície que está a ser 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 cadeia com templates que o renderizador avalia como um todo, analisando depois o resultado como um documento Workload. Os templates ao nível do campo no seu interior (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 — participam todos na ú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) abrange cada template ao nível do campo no seu interior.
Alternativa sensível ao 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 em ambos os casos. Quando uma Release escreve legitimamente infra.replicas: 0 para exprimir scale-to-zero (um padrão comum de Knative / KEDA), a forma | default 1 substitui silenciosamente a intenção. A forma sensível ao discriminador é replicas: {{ optional .infra "replicas" 1 }} — optional verifica a presença da chave e devolve o valor escrito (incluindo um zero escrito) quando a chave está definida, recorrendo a 1 apenas quando a chave está ausente. Ver sprig-functions.md para a semântica completa e as orientações sobre quando a preferir.
3. Referências proibidas & fundamentação
| Location | Referência proibida | Fundamentação |
|---|---|---|
value: de inject do Component (#4) | .context.inject | O pipe de inject está a ser 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 cablagem 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 por qualquer ordem e fecham-se apenas sobre os dados próprios do nó (.values, .infra, .locals, .context.instance_id, .context.rendered_name). O pipe de inject só é preenchido na hidratação de inject, que é executada depois de os provides de todos os nós terem sido avaliados. |
provides da Recipe (#6) | .attachment_name | A passagem de provides de uma Recipe base não resolve nenhum anexo, pelo que 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 contém um pilar provides: a superfície de fonte do espaço de trabalho partilha 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 recuar para ir buscar os provides. |
locals da Recipe (preâmbulo de #6) | .provides | Os locals são resolvidos antes dos provides, pelo que 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 calcula-o diretamente a partir de .values / .infra — e a entrada provides lê depois o local. |
locals da Recipe (preâmbulo de #6) | .context.rendered_name | Os locals de uma Recipe partilham 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 provoca uma paragem com o diagnóstico de raiz desconhecida, que lista .context.instance_id como aquilo que .context define aí. Deve antes ler-se a chave numa entrada provides, ou num template da fase de renderização base. |
provides da Recipe (#6) | .context.uses | .context.uses refere-se aos provides de outros nós, e a avaliação de provides executa-os por ordem arbitrária. Os templates de provides permanecem autossuficientes para que a avaliação continue independente da ordem. |
locals, provides, source (#5) de uma FeatureRecipe e templates de renderização inline (#9, #10), num host cujo fornecedor não reporta nenhum nome | .context.rendered_name | Num anexo de Feature, a chave contém o nome reportado do componente host, e um host que coloca sozinho um conjunto de artefactos, ou que renderiza através de um fornecedor que não deriva nenhum nome desse tipo, não tem nenhum para conter. A referência provoca uma paragem com o diagnóstico de raiz desconhecida, que lista .context.instance_id entre aquilo que .context define aí; deve antes ler-se a identidade, que é aquilo de que os recursos próprios do host recebem o nome num 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 tem de estar concluída antes de qualquer elemento a jusante carregar o chart, o módulo ou o corpo de artefacto 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 todo o lado, exceto nos templates de caminho) | Qualquer superfície de template de valor após a interpolação | A interpolação consome cada referência {{ .parameters.X }} no YAML escrito e escreve o valor resolvido no seu lugar, pelo 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 de os provides de todos os nós terem sido avaliados. Quando um componente declara um bloco inject: ao nível do componente, o compilador avalia-o aí:
- Cadeias
value:literais: se o valor contiver expressões de template Go, o compilador avalia-as com o contexto da linha #4 da matriz (.values,.infra,.context.instance_id,.metadata.*, etc.), escritas com escape como a linha #4 mostra. As cadeias simples passam sem alterações. - Referências
from:: o compilador procura a chave no dicionárioprovidespróprio do nó, já resolvido nessa altura. Se a chave não existir, o compilador interrompe a compilação com um erro de chave de inject inválida. - Verificação de colisões: antes de fundir 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. As colisões interrompem a compilação com um erro de chave de entrega duplicada.
As cadeias resultantes são fundidas 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 programador provenientes de ambas as origens.