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

Variáveis dos templates de caminho

Os campos directory: e subDirectory: de uma fronteira de Release são templates Go avaliados no momento da compilação. Controlam onde os artefactos renderizados ficam no disco e, por extensão, que artefactos são montados em conjunto — duas fronteiras que avaliam para o mesmo tuplo (path, provider) partilham um montador e produzem uma única saída fundida (um Chart.yaml, um docker-compose.yaml). Esta página é a referência de autoria para as variáveis que esses templates podem referenciar, a semântica de avaliação estrita e as regras de cascata que permitem às fronteiras herdar das suas fronteiras-mãe.

Para o tratamento conceptual da separação espacial e do despacho por (path, provider), consulte architecture/16-recipe-input-composition.md. Para a superfície de autoria da Release ao nível da entidade, consulte entities/release.md. As consequências do lado do fornecedor encontram-se em providers/architecture.md e nas páginas de cada fornecedor.

Avaliação estrita: missingkey=error

Os templates de caminho são avaliados com o modo missingkey=error do Go. Uma referência a um campo não declarado, a uma chave parameters.X não definida ou uma gralha como {{ .parmaeters.region }} produz um erro explícito em vez de renderizar silenciosamente uma string vazia num caminho.

Esta rigidez é assimétrica em relação ao resto do compilador — valuesMapping, injectMapping e outras superfícies de renderização de valores usam missingkey=zero segundo a convenção do Helm/Sprig. A emissão de caminhos é estruturalmente diferente: um template de renderização de valores que produz uma string vazia vai parar a um campo de manifesto, onde a consequência é limitada; um template de caminho que produz uma string vazia vai parar a uma estrutura de diretórios, onde a consequência é ilimitada (colisões, montagem partida, caminhos fantasma). O regime estrito dos templates de caminho existe para expor essas falhas no momento da compilação e não no momento da implementação.

Validação por lista de permissões no momento da análise

Para além da rigidez em tempo de execução, os templates de caminho são validados no momento da análise contra uma lista de permissões fechada de nomes de variáveis. Uma referência a um nome de variável que não esteja na lista de permissões interrompe a compilação antes de começar qualquer trabalho de renderização, com um diagnóstico que nomeia o campo infrator e a fronteira em que aparece.

A lista de permissões é fechada por conceção: superfícies como .context.inject, .values e .locals não são deliberadamente expostas aos templates de caminho. A emissão de caminhos é uma questão estrutural, não de renderização de valores; ligar os caminhos de montagem a valores por componente tornaria o grafo de caminhos dependente dos dados e corroeria o invariante da saída determinística.

A matriz de variáveis

Variáveldirectory:subDirectory:Descrição
{{ .capability }}simsimA capacidade de renderização (helm, helm-chart, compose, terraform, cloudformation) que a Recipe do componente contribuinte declara, para os artefactos emitidos neste caminho.
{{ .boundary_name }}simsimO nome escrito da fronteira na Release (por exemplo, production, eu-prod).
{{ .parameters.X }}simsimQualquer parâmetro tipado declarado no Aggregate e satisfeito pela Release. Acesso estrito — referenciar .parameters.unknown interrompe a compilação.
{{ .manifest.recipe_name }}simsimO nome da Recipe resolvido através do Manifest para o componente contribuinte. Útil para encaminhar os artefactos de cada Recipe para subpastas por Recipe.
{{ .parent_boundary.* }}simsimAcesso em cascata aos valores avaliados da fronteira envolvente. Consulte Cascata da fronteira-mãe mais abaixo.
{{ .component_id }}—simO ID de instância do componente contribuinte. Para uma Feature anexada a uma fronteira cuja FeatureRecipe é executada uma vez para a fronteira (executionScope: boundary), é a identidade composta que os recursos desse anexo têm na sua etiqueta aggrega.ai/component-id — bfr--app--shared para um anexo shared na fronteira app, encurtada onde o fornecedor do anexo limita os nomes — de modo que a saída do anexo fica num diretório com o nome dessa etiqueta. Disponível em subDirectory: apenas porque directory: é uma propriedade por fronteira — a cadeia do diretório é calculada uma vez por fronteira, antes de ocorrer qualquer encaminhamento por componente.

O campo directory: tem como predefinição boundaries/ seguido do caminho da fronteira (um identificador estável no momento da compilação, derivado da árvore de fronteiras); uma Release que lista os seus componentes sem declarar fronteiras escreve-os sem qualquer segmento de diretório. O campo subDirectory: tem como predefinição {{ .capability }}, de modo que os artefactos de cada capacidade ficam na sua própria subpasta sob o diretório da fronteira — quer seja omitido, quer seja escrito como subDirectory: "", que se lê exatamente como um omitido. Definir subDirectory: ".", ou escrever um template que avalie para uma string vazia, achata esse agrupamento.

O que estes templates não decidem: o posicionamento de artifacts:

Há um segmento do caminho de saída que não cabe a um template de caminho definir. Um ficheiro que o bloco artifacts: de uma Recipe nomeia é escrito sob um diretório com o nome do componente que o declarou, dentro daquilo para que subDirectory: avalia. Esse segmento é fixo e está sempre presente, para um destino que escreve os ficheiros dos seus contribuintes lado a lado em vez de aninhar cada contribuinte num chart ou módulo próprio.

A razão é o que dá nome ao ficheiro. Um manifesto que um destino renderiza ou sintetiza recebe do destino o nome do componente a que pertence, pelo que já identifica o seu componente. Um artefacto recebe o nome da chave que o seu autor escreveu — app-config.yaml, netpol.yaml — e essa chave nada diz sobre o componente, porque a Recipe que o declara não sabe que componentes lhe serão associados. Dois componentes numa fronteira associados a uma mesma Recipe escreveriam um único caminho, e nem o autor da Recipe nem o autor da Release têm uma superfície na qual os separar.

Apenas o diretório é acrescentado; o nome do ficheiro continua a ser a chave escrita, pelo que o ficheiro que um autor relê na saída tem o nome que escreveu.

O que subDirectory: ainda oferece, e como os dois se combinam. subDirectory: move cada ficheiro que um contribuinte emite — manifestos renderizados, manifestos sintetizados e artefactos em conjunto —, pelo que é a ferramenta para dar a um componente um diretório próprio para ferramentas a jusante que operam sobre o conjunto completo de manifestos de um único componente, ou para encaminhar vários componentes para uma pasta partilhada. O segmento de artifacts: aplica-se abaixo daquilo para que ele avalia. Escrever subDirectory: "{{ .capability }}/{{ .component_id }}" num componente cuja Recipe declara artifacts: produz, portanto, o nome do componente duas vezes — o artefacto fica em <capability>/<component>/<component>/<key> enquanto os manifestos renderizados desse componente ficam em <capability>/<component>/<key>. Recorra à substituição quando quiser reunir a saída completa do componente, e prescinda dela quando separar os artefactos for tudo o que precisa, o que a predefinição já faz.

.capability é resolvido por componente, e o directory: de uma fronteira é avaliado para dois fins distintos. A avaliação por fronteira que publica .parent_boundary.directory para as fronteiras-filhas é executada antes de qualquer componente ser associado, pelo que .capability está vazio aí. A avaliação por componente que fixa onde os artefactos de um contribuinte ficam efetivamente transporta a capacidade desse componente. Uma fronteira-mãe que escreve directory: "d-{{ .capability }}" publica, portanto, d- ao longo da cascata, enquanto os seus próprios artefactos ficam sob d-compose.

Cascata da fronteira-mãe

As fronteiras aninhadas recebem uma vista .parent_boundary que expõe o caminho avaliado da fronteira-mãe imediata e os seus próprios dados resolvidos em cascata. A cascata tem um único nível — o .parent_boundary de uma fronteira é a sua mãe direta, não a avó. Para chegar mais acima, a própria fronteira-mãe usa .parent_boundary nos seus próprios templates, propagando valores ao longo da árvore de forma explícita.

Campos disponíveis sob .parent_boundary:

CampoDescrição
.parent_boundary.directoryO valor avaliado de directory: da fronteira-mãe (após o template).
.parent_boundary.boundary_nameO nome escrito da fronteira-mãe.
.parent_boundary.parametersO mesmo mapa .parameters.* que a fronteira-mãe viu (os valores dos parâmetros são globais da Release, mas o alias é fornecido por simetria).
.parent_boundary.annotationsAs anotações resolvidas em cascata da fronteira-mãe.

O padrão canónico: uma fronteira-mãe que escreve um directory: uma vez, mais fronteiras-filhas que encaminham os seus artefactos para baixo da mãe declarando directory: "{{ .parent_boundary.directory }}". Isto faz as filhas convergirem no caminho de montagem da mãe, produzindo uma única saída fundida que contém contribuintes de cada filha. A Feature core/compose-bridge depende exatamente disto: uma fronteira-mãe que contém a funcionalidade bridge, duas fronteiras-filhas (por exemplo services-net e data-net) que partilham o directory: da mãe, e um único docker-compose.yaml fundido que contém cada componente mais o serviço bridge.

O caso inverso: omita .parent_boundary.directory nas filhas (ou faça-as avaliar para um caminho distinto) e cada filha obtém a sua própria montagem. Ambas as formas são igualmente suportadas.

Exemplos de layouts

Layout 1 — separação predefinida por fronteira

spec:
boundaries:
api-prod:
directory: "deploy/api-prod"
components:
api: {}
cache: {}
data-prod:
directory: "deploy/data-prod"
components:
db: {}

Cada fronteira avalia para um directory: distinto, pelo que cada uma obtém a sua própria montagem:

deploy/api-prod/<capability>/...
deploy/data-prod/<capability>/...

A predefinição subDirectory: "{{ .capability }}" separa os artefactos por capacidade dentro do diretório de cada fronteira. Duas fronteiras, duas saídas de montagem por capacidade, nenhuma fusão.

Layout 2 — montagem unificada através de um diretório pai partilhado

spec:
boundaries:
cluster:
directory: "deploy/cluster"
annotations:
aggrega.ai/chart-name: "cluster-umbrella"
features:
bridge:
type: core/compose-bridge:1.0.0
boundaries:
services-net:
directory: "{{ .parent_boundary.directory }}"
annotations: { aggrega.ai/namespace: services }
components:
api: {}
data-net:
directory: "{{ .parent_boundary.directory }}"
annotations: { aggrega.ai/namespace: data }
components:
db: {}

Ambas as fronteiras-filhas avaliam directory: para deploy/cluster (o diretório da fronteira-mãe), pelo que todos os contribuintes se fundem num único caminho de montagem. Com a predefinição subDirectory: "{{ .capability }}", os contribuintes compose de ambas as filhas ficam em deploy/cluster/compose/ e produzem um único docker-compose.yaml fundido. A Feature compose-bridge anexada à mãe é executada uma única vez (despacho com âmbito de fronteira) e contribui com o serviço bridge para o mesmo ficheiro fundido.

A anotação aggrega.ai/chart-name: "cluster-umbrella" da mãe propaga-se em cascata para ambas as filhas; se as fronteiras também contivessem contribuintes helm-chart, os subcharts helm-chart de ambas as filhas compor-se-iam sob um único umbrella chamado cluster-umbrella. Valores de chart-name divergentes entre contribuintes num mesmo caminho interrompem a compilação.

Layout 3 — encaminhamento por componente através de subDirectory: mais parâmetros

spec:
parameters:
region: "eu-west-1"
boundaries:
eu-prod:
directory: "deploy/{{ .parameters.region }}"
components:
api:
subDirectory: "{{ .capability }}/{{ .component_id }}"
db:
subDirectory: "{{ .capability }}/{{ .component_id }}"
ingress:
subDirectory: "shared"

O directory: da fronteira avalia para deploy/eu-west-1 (substituição de parâmetros). Substituições de subDirectory: por componente encaminham cada contribuinte para uma subpasta por componente, com o componente ingress a substituir para uma subpasta plana shared destinada a artefactos transversais:

deploy/eu-west-1/<capability>/api/...
deploy/eu-west-1/<capability>/db/...
deploy/eu-west-1/shared/...

Este padrão adequa-se a empresas que querem diretórios de artefactos por componente para ferramentas a jusante que operam sobre os manifestos de um único componente. Quando a Recipe de um componente também declara artifacts:, leia O que estes templates não decidem mais acima antes de escolher esta forma: esses ficheiros já têm um segmento de componente, pelo que esta substituição acrescenta um segundo.

Diagnósticos

A superfície dos templates de caminho interrompe a compilação em cada uma das situações seguintes, e errors/fatal-halts.md documenta-as com estes nomes. Essa página cita a mensagem que cada interrupção emite; compare a saída da compilação com esse texto.

  • Path-template references a variable outside the allowlist (O template de caminho referencia uma variável fora da lista de permissões) — no momento da análise: um template de caminho referencia uma variável que não está na lista de permissões.
  • Path collision (Colisão de caminhos) — no momento da montagem: dois contribuintes de fronteira avaliam para o mesmo caminho, mas divergem numa propriedade que tem de ser uniforme entre os contribuintes desse caminho.
  • Instance-ID collision (Colisão de ID de instância) — no momento da montagem: duas fronteiras que avaliam para o mesmo tuplo (path, provider) contribuem com componentes com IDs de instância idênticos.
  • Chart-name mismatch (Nome de chart divergente) — no momento da montagem: uma montagem helm-chart fundida recebe contribuintes com anotações aggrega.ai/chart-name resolvidas em cascata que entram em conflito.
  • Missing template key (Chave de template em falta) — um template de caminho referencia um campo sob uma variável aberta que não se resolve em nenhum valor (por exemplo, {{ .parameters.region }} quando a Release omite region, ou uma chave de .parent_boundary numa fronteira de nível superior que não tem fronteira-mãe); missingkey=error produz uma mensagem explícita que nomeia a fronteira, o campo do template (directory: ou subDirectory:) e a chave em falta. .parameters e .parent_boundary são abertas — as suas chaves são dados escritos pelo autor —, enquanto .manifest declara as suas chaves, pelo que uma chave mal escrita sob .manifest é, em vez disso, recusada no momento da análise como uma referência desconhecida, com o diagnóstico a listar as chaves que .manifest define.

Referências cruzadas

  • entities/release.md — autoria da Release, incluindo a separação espacial e os campos directory: / subDirectory:.
  • providers/architecture.md — despacho para os fornecedores e o modelo de montagem por (path, provider).
  • providers/compose.md — saída do lado do compose por (path, provider), incluindo o cenário de caminho fundido.
  • providers/helm-chart.md — composição umbrella de helm-chart e a regra de cascata do chart-name para caminhos fundidos.
  • entities/featurerecipe.md — FeatureRecipes com âmbito de fronteira (a Feature core/compose-bridge depende do modelo de montagem de caminho fundido documentado aqui).
  • errors/fatal-halts.md — catálogo completo de diagnósticos, incluindo as interrupções do despacho de caminhos enumeradas acima.