Variáveis dos templates de caminho
Os campos directory: e subDirectory: de uma fronteira de Release são templates Go avaliados em tempo de build. Eles controlam onde os artefatos renderizados ficam no disco e, por extensão, quais artefatos são montados juntos — duas fronteiras que avaliam para a mesma tupla (path, provider) compartilham um montador e produzem uma única saída mesclada (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 pai.
Para o tratamento conceitual da separação espacial e do despacho por (path, provider), veja architecture/16-recipe-input-composition.md. Para a superfície de autoria da Release no nível da entidade, veja entities/release.md. As consequências do lado do provedor estão em providers/architecture.md e nas páginas de cada provedor.
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 um erro de digitação como {{ .parmaeters.region }} produz um erro explícito em vez de renderizar silenciosamente uma string vazia em um caminho.
Essa 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 em um campo de manifesto, onde a consequência é limitada; um template de caminho que produz uma string vazia vai parar em um layout de diretórios, onde a consequência é ilimitada (colisões, montagem quebrada, caminhos fantasmas). O regime estrito dos templates de caminho existe para expor essas falhas em tempo de build, e não em tempo de implantação.
Validação por lista de permissões em tempo de análise
Além da rigidez em tempo de execução, os templates de caminho são validados em tempo de 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 está na lista de permissões interrompe o build antes que qualquer trabalho de renderização comece, com um diagnóstico que nomeia o campo infrator e a fronteira em que ele aparece.
A lista de permissões é fechada por design: superfícies como .context.inject, .values e .locals deliberadamente não são expostas aos templates de caminho. A emissão de caminhos é uma questão estrutural, não de renderização de valores; vincular os caminhos de montagem a valores por componente tornaria o grafo de caminhos dependente de dados e corroeria o invariante da saída determinística.
A matriz de variáveis
| Variável | directory: | subDirectory: | Descrição |
|---|---|---|---|
{{ .capability }} | sim | sim | A capacidade de renderização (helm, helm-chart, compose, terraform, cloudformation) que a Recipe do componente contribuinte declara, para os artefatos emitidos neste caminho. |
{{ .boundary_name }} | sim | sim | O nome escrito da fronteira na Release (por exemplo, production, eu-prod). |
{{ .parameters.X }} | sim | sim | Qualquer parâmetro tipado declarado no Aggregate e satisfeito pela Release. Acesso estrito — referenciar .parameters.unknown interrompe o build. |
{{ .manifest.recipe_name }} | sim | sim | O nome da Recipe resolvido por meio do Manifest para o componente contribuinte. Útil para rotear os artefatos de cada Recipe para subpastas por Recipe. |
{{ .parent_boundary.* }} | sim | sim | Acesso em cascata aos valores avaliados da fronteira envolvente. Veja Cascata da fronteira pai abaixo. |
{{ .component_id }} | — | sim | O 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 carregam no rótulo aggrega.ai/component-id — bfr--app--shared para um anexo shared na fronteira app, encurtada onde o provedor do anexo limita os nomes — de modo que a saída do anexo vai para um diretório com o nome desse rótulo. Disponível em subDirectory: apenas porque directory: é uma propriedade por fronteira — a string do diretório é calculada uma vez por fronteira, antes que qualquer roteamento por componente aconteça. |
O campo directory: tem como padrão boundaries/ seguido do caminho da fronteira (um identificador estável em tempo de build, derivado da árvore de fronteiras); uma Release que lista os seus componentes sem declarar fronteiras os grava sem nenhum segmento de diretório. O campo subDirectory: tem como padrão {{ .capability }}, de modo que os artefatos de cada capacidade ficam na sua própria subpasta sob o diretório da fronteira — seja ele omitido ou escrito como subDirectory: "", que é lido exatamente como um omitido. Definir subDirectory: ".", ou escrever um template que avalia para uma string vazia, achata esse agrupamento.
O que estes templates não decidem: o posicionamento de artifacts:
Um segmento do caminho de saída não cabe a um template de caminho definir. Um arquivo que o bloco artifacts: de uma Recipe nomeia é gravado sob um diretório com o nome do componente que o declarou, dentro daquilo para o qual subDirectory: avalia. Esse segmento é fixo e sempre presente, para um destino que grava os arquivos dos seus contribuintes lado a lado em vez de aninhar cada contribuinte em um chart ou módulo próprio.
O motivo é o que dá nome ao arquivo. Um manifesto que um destino renderiza ou sintetiza é nomeado pelo destino a partir do componente ao qual pertence, então ele já identifica o seu componente. Um artefato é nomeado pela chave que o seu autor escreveu — app-config.yaml, netpol.yaml — e essa chave não diz nada sobre o componente, porque a Recipe que o declara não sabe quais componentes serão associados a ela. Dois componentes em uma fronteira associados a uma mesma Recipe gravariam um único caminho, e nem o autor da Recipe nem o autor da Release têm uma superfície na qual separá-los.
Apenas o diretório é adicionado; o nome do arquivo continua sendo a chave escrita, então o arquivo que um autor relê na saída carrega o nome que ele escreveu.
O que subDirectory: ainda oferece, e como os dois se combinam. subDirectory: move cada arquivo que um contribuinte emite — manifestos renderizados, manifestos sintetizados e artefatos juntos —, então é a ferramenta para dar a um componente um diretório próprio para ferramentas posteriores que operam sobre o conjunto inteiro de manifestos de um único componente, ou para rotear vários componentes para uma pasta compartilhada. O segmento de artifacts: se aplica abaixo daquilo para o qual ele avalia. Escrever subDirectory: "{{ .capability }}/{{ .component_id }}" em um componente cuja Recipe declara artifacts: produz, portanto, o nome do componente duas vezes — o artefato fica em <capability>/<component>/<component>/<key> enquanto os manifestos renderizados desse componente ficam em <capability>/<component>/<key>. Recorra à sobrescrita quando quiser reunir a saída inteira do componente, e deixe-a de lado quando separar os artefatos for tudo de que você precisa, o que o padrão já faz.
.capability é resolvido por componente, e o directory: de uma fronteira é avaliado para dois propósitos distintos. A avaliação por fronteira que publica .parent_boundary.directory para as fronteiras filhas é executada antes que qualquer componente seja associado, então .capability fica vazio ali. A avaliação por componente que fixa onde os artefatos de um contribuinte de fato ficam carrega a capacidade desse componente. Uma fronteira pai que escreve directory: "d-{{ .capability }}" publica, portanto, d- cascata abaixo, enquanto os seus próprios artefatos ficam sob d-compose.
Cascata da fronteira pai
Fronteiras aninhadas recebem uma visão .parent_boundary que expõe o caminho avaliado da fronteira pai imediata e os seus próprios dados resolvidos em cascata. A cascata tem um nível — o .parent_boundary de uma fronteira é a sua pai direta, não a avó. Para alcançar níveis acima, a própria fronteira pai usa .parent_boundary nos seus próprios templates, propagando valores árvore abaixo de forma explícita.
Campos disponíveis sob .parent_boundary:
| Campo | Descrição |
|---|---|
.parent_boundary.directory | O valor avaliado de directory: da fronteira pai (após o template). |
.parent_boundary.boundary_name | O nome escrito da fronteira pai. |
.parent_boundary.parameters | O mesmo mapa .parameters.* que a fronteira pai viu (os valores dos parâmetros são globais da Release, mas o alias é fornecido por simetria). |
.parent_boundary.annotations | As anotações resolvidas em cascata da fronteira pai. |
O padrão canônico: uma fronteira pai que escreve um directory: uma vez, mais fronteiras filhas que roteiam os seus artefatos sob a pai declarando directory: "{{ .parent_boundary.directory }}". Isso faz as filhas convergirem no caminho de montagem da pai, produzindo uma única saída mesclada que contém contribuintes de cada filha. A Feature core/compose-bridge depende exatamente disso: uma fronteira pai que contém a funcionalidade bridge, duas fronteiras filhas (por exemplo services-net e data-net) que compartilham o directory: da pai, e um único docker-compose.yaml mesclado 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 padrão 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, então cada uma obtém a sua própria montagem:
deploy/api-prod/<capability>/...deploy/data-prod/<capability>/...O padrão subDirectory: "{{ .capability }}" separa os artefatos por capacidade dentro do diretório de cada fronteira. Duas fronteiras, duas saídas de montagem por capacidade, nenhuma mesclagem.
Layout 2 — montagem unificada por meio de um diretório pai compartilhado
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 pai), então todos os contribuintes se mesclam em um único caminho de montagem. Com o padrão subDirectory: "{{ .capability }}", os contribuintes compose de ambas as filhas ficam em deploy/cluster/compose/ e produzem um único docker-compose.yaml mesclado. A Feature compose-bridge vinculada à pai é executada uma única vez (despacho com escopo de fronteira) e contribui com o serviço bridge para o mesmo arquivo mesclado.
A anotação aggrega.ai/chart-name: "cluster-umbrella" da pai se propaga em cascata para ambas as filhas; se as fronteiras também contivessem contribuintes helm-chart, os subcharts helm-chart de ambas as filhas se comporiam sob um único umbrella chamado cluster-umbrella. Valores de chart-name divergentes entre contribuintes em um mesmo caminho interrompem o build.
Layout 3 — roteamento por componente por meio 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). Sobrescritas de subDirectory: por componente roteiam cada contribuinte para uma subpasta por componente, com o componente ingress sobrescrevendo para uma subpasta plana shared para artefatos transversais:
deploy/eu-west-1/<capability>/api/...deploy/eu-west-1/<capability>/db/...deploy/eu-west-1/shared/...Esse padrão se adequa a empresas que querem diretórios de artefatos por componente para ferramentas posteriores 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 acima antes de escolher essa forma: esses arquivos já carregam um segmento de componente, então essa sobrescrita adiciona um segundo.
Diagnósticos
A superfície dos templates de caminho interrompe o build em cada uma das situações a seguir, e errors/fatal-halts.md as documenta com estes nomes. Essa página cita a mensagem que cada interrupção emite; compare a saída do build 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) — em tempo de 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) — em tempo de montagem: dois contribuintes de fronteira avaliam para o mesmo caminho, mas divergem em uma propriedade que deve ser uniforme entre os contribuintes desse caminho.
- Instance-ID collision (Colisão de ID de instância) — em tempo de montagem: duas fronteiras que avaliam para a mesma tupla
(path, provider)contribuem com componentes com IDs de instância idênticos. - Chart-name mismatch (Nome de chart divergente) — em tempo de montagem: uma montagem helm-chart mesclada recebe contribuintes com anotações
aggrega.ai/chart-nameresolvidas em cascata que entram em conflito. - Missing template key (Chave de template ausente) — 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 omiteregion, ou uma chave de.parent_boundaryem uma fronteira de nível superior que não tem fronteira pai);missingkey=errorproduz uma mensagem explícita que nomeia a fronteira, o campo do template (directory:ousubDirectory:) e a chave ausente..parameterse.parent_boundarysão abertas — as suas chaves são dados escritos pelo autor —, enquanto.manifestdeclara as suas chaves, então uma chave digitada errada sob.manifesté, em vez disso, recusada em tempo de análise como uma referência desconhecida, com o diagnóstico listando as chaves que.manifestdefine.
Referências cruzadas
entities/release.md— autoria da Release, incluindo a separação espacial e os camposdirectory:/subDirectory:.providers/architecture.md— despacho para os provedores 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 mesclado.providers/helm-chart.md— composição umbrella de helm-chart e a regra de cascata do chart-name para caminhos mesclados.entities/featurerecipe.md— FeatureRecipes com escopo de fronteira (a Featurecore/compose-bridgedepende do modelo de montagem de caminho mesclado documentado aqui).errors/fatal-halts.md— catálogo completo de diagnósticos, incluindo as interrupções do despacho de caminhos enumeradas acima.