Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Portugal)
Esta página foi traduzida automaticamente. Ler 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é-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 available

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

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

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

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