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

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 available

2. 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:

#LocationEntidadeAvaliado emReferências disponíveis
1{{ .parameters.X }} em strings YAML do AggregateAggregateResolução (interpolação)Apenas .parameters. Todos os outros dados ainda não estão resolvidos.
2{{ .parameters.X }} em strings YAML da ReleaseReleaseNão avaliadoNenhuma. 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).
3Templates directory / subDirectoryFronteira da ReleaseRenderizaçã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).
4Strings value: de inject do ComponentComponente do AggregateResoluçã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.
5Strings do campo source (string de nível superior OU subcampos com valor string de um mapa source: estruturado)Recipe / FeatureRecipeResolução da fonteDuas 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).
6Templates provides da RecipeRecipeAvaliaçã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.
7valuesMapping da Recipe (inline, $import: de arquivo ou $import: de biblioteca)RecipeRenderização baseContexto 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.
8injectMapping da FeatureRecipeFeatureRecipeMapeamento de injectContexto 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.
9valuesMapping da FeatureRecipe (e os seus workload: e artifacts:)FeatureRecipeRenderização baseContexto 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.
10Blocos with: do pipelineRecipe / FeatureRecipeO pipeline de pluginsContexto 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.
11Corpo workload: da Recipe (todo campo com template dentro dele, seja inline ou carregado por $import:)RecipeRenderização baseContexto 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

LocationReferência proibidaJustificativa
value: de inject do Component (#4).context.injectO 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.usesA 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.injectOs 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_nameA 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).providesNenhuma 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).providesOs 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_nameOs 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_nameEm 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.injectA 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.usesA 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çãoA 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:

  1. 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.
  2. Referências from:: o compilador procura a chave no dicionário provides pró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.
  3. 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.