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

Contexto de template dos parâmetros

O pilar parameters: carrega os valores de parâmetros fornecidos pela Release e validados em relação ao contrato. Dois modelos mentais paralelos governam a sua acessibilidade:

  • As superfícies de template de valor (strings values: de componente / feature / subaggregate dentro do Aggregate, além de valuesMapping da Recipe, injectMapping e provides da FeatureRecipe, corpos de Workload) consomem os valores dos parâmetros como literais já interpolados. A passagem de interpolação dentro da resolução avalia todo o texto do Aggregate como um template e substitui toda referência {{ .parameters.<slot> }} pelo valor resolvido; as superfícies de template de valor a jusante nunca veem .parameters diretamente no seu contexto de template.
  • As superfícies de template de caminho (templates directory: e subDirectory: escritos pelo operador nas fronteiras da Release) leem .parameters.<slot> diretamente na avaliação dos templates de caminho durante a renderização. O mapa de parâmetros mesclado permanece legível até o fim da renderização para que um template de caminho possa ler .parameters em relação à allowlist fechada.

A concessão assimétrica — os templates de caminho leem .parameters diretamente; os templates de valor não — faz com que cada camada seja dona do que precisa: os values: do lado do desenvolvedor levam adiante dados já resolvidos e específicos do ambiente até os templates de valor; os templates de caminho do lado do operador referenciam parâmetros de região / ambiente / id de conta sem dar a volta pelo esquema values do Aggregate.

Esta página documenta a passagem de interpolação, as formas de valor por slot, os padrões de acesso dentro das strings YAML do Aggregate, a exceção dos templates de caminho e por quanto tempo o mapa mesclado permanece legível. Para a forma mais ampla do contexto de template de Recipe / FeatureRecipe (.values, .infra, .uses etc.), veja template-context-contract.md. Para a disponibilidade por local de template ao longo do pipeline de compilação, veja expansion-matrix.md. Para a forma da declaração dos contratos de parâmetros tipados no Aggregate, veja entities/aggregate.md §“Typed parameter contracts (Contratos de parâmetros tipados)”. Para a allowlist de variáveis de template de caminho que inclui .parameters.<slot> na avaliação de directory: / subDirectory: de uma fronteira, veja path-template-variables.md.

Ciclo de vida dos parâmetros

O compilador resolve os parâmetros em quatro fases ordenadas:

  1. Leitura do contrato — o bloco spec.parameters: do Aggregate é verificado nos seus próprios termos antes que qualquer valor da Release seja examinado, de modo que um slot que não poderia restringir nada interrompe o build mesmo quando nenhuma Release o fornece. Um minLength ou maxLength negativo na própria declaração de um parâmetro é recusado quando o Aggregate é carregado, nomeando o parâmetro e a chave. Todo pattern — no próprio slot e dentro de qualquer contrato aninhado sob items, properties ou valuesType — é compilado como expressão regular, e um que não compila é recusado nomeando o parâmetro, o padrão e o motivo. Um limite de comprimento dentro de um contrato aninhado não está sujeito a esse piso; veja entities/aggregate.md.
  2. Preenchimento de valores padrão — os slots com default: definido e sem valor fornecido pela Release recebem o seu valor padrão. O mapa .parameters está no escopo neste ponto.
  3. Validação do contrato de parâmetros — cada valor no mapa mesclado, seja fornecido pela Release ou preenchido por um default:, é validado em relação às restrições type / enum / min / max / pattern / de estrutura aninhada declaradas em spec.parameters.<slot> do Aggregate; um pattern é comparado com a expressão compilada quando o contrato foi lido. O mapa .parameters existe no contexto em memória do validador como o payload estruturado que está sendo verificado.
  4. Interpolação — o compilador avalia todo o texto do Aggregate como um template, antes de lê-lo como YAML, e substitui toda referência {{ .parameters.<slot> }} pelo valor resolvido; qualquer outro {{ no texto também é lido como sintaxe de template, de modo que um valor que carrega chaves duplas próprias escreve cada {{ como {{"{{"}} (veja Texto que contém suas próprias chaves duplas). A interpolação é o caminho de substituição para as superfícies de template de valor — após essa passagem, os contextos de template de valor não carregam mais .parameters; eles consomem os valores resolvidos escritos nas strings values: ao redor. O mapa mesclado permanece legível após a interpolação, durante toda a renderização, especificamente para dar suporte à avaliação dos templates de caminho. Seu tempo de vida legível é limitado pelo do build: o compilador entrega a visão resolvida à compilação que a consome em vez de devolvê-la a um chamador, de modo que nada fora desse build pode alcançar o mapa. A superfície de template de caminho (directory: / subDirectory: da Release) lê .parameters.<slot> durante a renderização em relação à allowlist fechada documentada em path-template-variables.md.

Os templates dentro das strings YAML do Aggregate (values: de componente, values: de feature, expressões de repasse parameters: de subaggregate) leem o mapa .parameters por meio da sintaxe padrão de templates Go durante a passagem de interpolação. Os templates dentro dos arquivos de Recipe e FeatureRecipe NÃO recebem .parameters no seu contexto de template (veja “Boundary with downstream template contexts (Fronteira com os contextos de template a jusante)” mais abaixo para o contrato por superfície).

Texto que contém suas próprias chaves duplas

Como todo o texto é um template, as chaves duplas que pertencem a um valor e não a um template também são lidas como ações de template. A definição de uma plataforma de fluxos carregada nos values: de um componente é o caso comum: o n8n envolve em chaves duplas cada expressão nos parâmetros de um nó, como em ={{ $json.body.message }}, um prompt do Flowise nomeia uma variável como {{question}} e um chatflow do Flowise escreve {{chatOpenAI_0.data.instance}} para cada conexão entre dois nós, e uma exportação do Langflow carrega o código-fonte dos seus componentes, onde as chaves também podem aparecer. Escritas como estão em um Aggregate, elas interrompem o build no Aggregate com E0158, descrito em “A {{ .parameters.* }} reference cannot be interpolated (Uma referência a parâmetros não pode ser interpolada)” em Interrupções fatais; o seu motivo nomeia a linha e o primeiro token que o mecanismo de templates não conseguiu ler — undefined variable "$json" para uma expressão do n8n. Um comentário YAML também é texto de template, de modo que um {{ escrito em um comentário é interrompido da mesma forma.

Escreva cada {{ em um valor desse tipo como {{"{{"}}. Essa é uma ação de template cujo resultado é a string {{, de modo que a interpolação recoloca as duas chaves. Um }} de fechamento não precisa de nada, porque fora de uma ação é texto simples. A interpolação é executada uma vez, sobre o texto do Aggregate, e um template de Recipe escreve o que lê de .values como dados, de modo que as chaves restauradas chegam à saída renderizada tal como foram exportadas.

# Aggregate fragment — an n8n workflow definition carried as exported
spec:
components:
automation:
type: core/ai-agent/n8n
values:
workflow_id: support-reply
flow_definition: |
{
"name": "Support reply",
"nodes": [
{
"name": "Set reply",
"type": "n8n-nodes-base.set",
"parameters": {
"value": "={{"{{"}} $json.body.message }} for {{"{{"}} $env.SUPPORT_TEAM }}"
}
}
],
"connections": {}
}

A plataforma recebe "value": "={{ $json.body.message }} for {{ $env.SUPPORT_TEAM }}".

Mantenha uma definição desse tipo em um escalar de bloco (|), como acima, onde as aspas do escape são caracteres comuns. O texto do Aggregate também é lido como YAML antes de ser interpolado, e dentro de uma string YAML entre aspas duplas o " do escape fecha a string, de modo que o arquivo deixa de ser analisado e o build é interrompido com o erro de YAML.

O padrão de acesso .parameters.<slot>

Cada slot de parâmetro declarado é acessível como um campo no mapa .parameters. O acesso correto quanto ao tipo corresponde ao type declarado:

# Aggregate fragment — parameter declarations
spec:
parameters:
region: { type: string, enum: [us-east-1, us-west-2] }
cache_ttl_seconds: { type: integer, min: 1, max: 86400, default: 60 }
enable_debug: { type: boolean, default: false }
components:
web:
type: core/web-server:1.0.0
values:
region: "{{ .parameters.region }}" # string
cache_ttl_seconds: {{ .parameters.cache_ttl_seconds }} # integer
debug: {{ .parameters.enable_debug }} # boolean

A passagem de interpolação produz uma avaliação de template Go sobre o mapa .parameters; o resultado substitui no lugar a expressão de template no documento. O esquema values: do Component / da Feature valida em seguida o valor resultante na fase de validação de esquema pós-interpolação da resolução.

As aspas decidem o tipo elevado

Coloque entre aspas uma referência destinada a uma folha do tipo string; deixe-a sem aspas para qualquer outro tipo declarado. A regra é a do próprio YAML, não uma que o Aggrega acrescenta por cima: a interpolação substitui o valor fornecido nos bytes do documento e não faz mais nada, de modo que a análise que segue lê o resultado exatamente como lê qualquer outro escalar. Um {{ .parameters.cache_ttl_seconds }} sem aspas carrega o tipo próprio do valor fornecido, que é o que permite que um parâmetro inteiro chegue a uma folha inteira e que um parâmetro booleano chegue a uma folha booleana. Um "{{ .parameters.cache_ttl_seconds }}" entre aspas carrega uma string, e uma folha declarada integer ou boolean a recusa: o valor escrito falha no esquema values: do seu Component ou da sua Feature quanto ao tipo, e o diagnóstico nomeia a incompatibilidade de tipo em vez de qualquer restrição do espaço de valores que a string também teria deixado de cumprir.

Uma referência que compartilha o seu escalar com outro texto é uma string de qualquer forma que seja escrita, porque o documento substituído tem um único escalar para ler — image: app:{{ .parameters.tag }} produz app:1.4.0. Essa é a forma a usar quando um parâmetro que não é string precisa chegar a uma folha do tipo string.

Acesso a slots do tipo objeto e do tipo array

Os slots de parâmetro do tipo objeto expõem as suas propriedades declaradas como campos aninhados no mapa .parameters.<slot>. Os slots do tipo array expõem a semântica de slices dos templates Go (range, index, len).

# Aggregate fragment — object-typed parameter
spec:
parameters:
database_config:
type: object
properties:
host: { type: string, required: true }
port: { type: integer, min: 1, max: 65535, default: 5432 }
ssl_mode: { type: string, enum: [disable, require, verify-full] }
components:
api:
type: core/compute/api:1.0.0
values:
db_host: "{{ .parameters.database_config.host }}"
db_port: {{ .parameters.database_config.port }}
db_ssl: "{{ .parameters.database_config.ssl_mode }}"

Os slots de parâmetro do tipo array suportam a iteração por meio de range:

# Aggregate fragment — array-typed parameter
spec:
parameters:
allowed_hosts:
type: array
items: { type: string, format: hostname }
min: 1
components:
ingress:
type: core/ingress:1.0.0
values:
# Compose a comma-separated list from the parameter array
hosts: "{{ range $i, $h := .parameters.allowed_hosts }}{{ if $i }},{{ end }}{{ $h }}{{ end }}"

Cada elemento que a Release fornece é verificado em relação ao contrato items antes da interpolação, de modo que um valor que não é um nome de host — *, por exemplo — interrompe o build nomeando o parâmetro, o elemento e o formato. Os nomes que format aceita, e o que cada um verifica, estão listados em vocabulary/compact-form-authoring.md.

A biblioteca de templates Sprig está disponível durante a interpolação, fornecendo helpers como join para conversões compactas de array em string:

hosts: "{{ join `,` .parameters.allowed_hosts }}"

Semântica do preenchimento de valores padrão

Um slot de parâmetro com uma declaração default: recebe o seu valor padrão quando a Release omite o slot. O valor padrão é aplicado antes de a passagem de validação do contrato ser executada, de modo que a validação vê o valor resolvido (fornecido pela Release ou padrão):

# Aggregate
spec:
parameters:
timeout_seconds:
type: integer
min: 1
max: 300
default: 30
components:
api:
type: core/compute/api:1.0.0
values:
timeout: {{ .parameters.timeout_seconds }}
# Release omits timeout_seconds — interpolation uses default: 30
# Release supplies timeout_seconds: 60 — interpolation uses 60
# Release supplies timeout_seconds: 0 — validation rejects (below min: 1)
# Release supplies timeout_seconds: 500 — validation rejects (above max: 300)
# Release supplies timeout_seconds: "thirty" — validation rejects (type mismatch)

Um slot marcado com required: true sem default: gera um erro em tempo de build quando a Release o omite (E0165). O erro nomeia o slot e a sua localização no contrato para que o autor o corrija. Um slot sem required: true nem default: é opcional: se omitido, cada referência a ele é interpolada como vazia, e o esquema values: do Component julga então o resultado.

Parâmetros de objetos aninhados

Quando um parâmetro declara type: object com properties: cujos filhos carregam eles próprios valores default:, três casos de escrita produzem resultados distintos. Entender a distinção importa quando a declaração do parâmetro é um objeto estruturado — uma configuração de banco de dados, um conjunto de feature flags, uma política de timeout e retry — em vez de um único escalar.

Caso 1 — a Release omite o slot pai. Os valores padrão dos filhos do contrato são preenchidos. O autor do Aggregate que declarou os valores padrão aninhados obtém o comportamento pretendido: quando ops não fornece o slot, a configuração usa os valores padrão documentados.

# Aggregate
spec:
parameters:
database:
type: object
properties:
host: { type: string, default: "localhost" }
port: { type: integer, default: 5432 }
# Release (parent omitted)
spec:
parameters: {}
# Resolved at template-interpolation time
parameters:
database:
host: "localhost"
port: 5432

Caso 2 — a Release escreve o pai como um mapa vazio explícito. O vazio explícito é respeitado como um opt-out deliberado. Os valores padrão dos filhos NÃO são preenchidos; o slot permanece vazio. Use essa forma quando ops quiser suprimir os valores padrão aninhados do contrato sem fornecer substituições — por exemplo, quando um consumidor a jusante espera o slot presente, mas vazio.

# Release (parent explicit empty)
spec:
parameters:
database: {}
# Resolved at template-interpolation time
parameters:
database: {}

A distinção em relação ao Caso 1 é deliberada: ops pode expressar tanto “use os valores padrão” (omitindo o slot) quanto “suprima os valores padrão” (escrevendo o slot como {}). Isso espelha como o Aggrega trata o null explícito nas anotações — uma anotação escrita como aggrega.ai/<key>: null é um opt-out deliberado distinto de omitir a anotação por completo.

Caso 3 — a Release escreve parcialmente o pai. Os filhos que a Release forneceu assumem os seus valores escritos; os filhos que a Release não forneceu são preenchidos com os valores padrão.

# Release (partial)
spec:
parameters:
database:
host: "db.prod.example.com"
# Resolved at template-interpolation time
parameters:
database:
host: "db.prod.example.com" # Release-supplied
port: 5432 # filled from default

Esse é o caso comum para autores de Release que querem substituir campos selecionados deixando o resto nos valores padrão do contrato.

Quando usar cada forma

  • Omita o slot quando quiser que os valores padrão do contrato se apliquem.
  • Escreva {} quando quiser deliberadamente o slot presente, mas vazio — quando os valores padrão do contrato estão errados para o seu ambiente e você não tem substituições.
  • Escreva parcialmente quando quiser algumas substituições e quiser que o resto use os valores padrão do contrato.

Um autor de Release que digita database: {} esperando “me dê os valores padrão” vai se surpreender — o valor resolvido é vazio, não os valores padrão preenchidos. Para obter os valores padrão, omita o slot por completo.

O tratamento dos três casos é por irmão em cada profundidade de aninhamento. Um pai escrito como { connection: {}, other_field: "x" } produz uma árvore resolvida em que connection está vazio (Caso 2 na profundidade 1) e other_field é o valor fornecido pela Release (Caso 3 na profundidade 0) — os casos são tratados de forma independente para cada irmão, não como uma única decisão para a subárvore inteira.

Fronteira com os contextos de template a jusante

A concessão assimétrica — os templates de caminho leem .parameters diretamente; os templates de valor não — é a distinção fundamental nessa fronteira. A semântica da fronteira por superfície:

  • Um template values: de componente do Aggregate que escreve {{ .parameters.X }} é resolvido corretamente na interpolação. O literal resolvido é escrito no lugar na string YAML.
  • Um template valuesMapping: da Recipe que escreve {{ .parameters.X }} é uma superfície de template de valor; o contexto de template não carrega .parameters. Os autores que precisam de variação por ambiente em valuesMapping: a expressam por meio do caminho de consumo do .values.<key> resolvido — o Aggregate expõe um parâmetro, faz referência a ele a partir dos values: de um Component, a Release o satisfaz, e o valor pós-interpolação flui até a Recipe.
  • Um template injectMapping:, provides: ou pipeline.with: da FeatureRecipe é uma superfície de template de valor; o mesmo que valuesMapping: da Recipe. .parameters não está no contexto de template.
  • Um template de corpo de Workload (conteúdo workload: dentro de uma Recipe) é uma superfície de template de valor; idem.
  • Um template de caminho (directory: / subDirectory: da fronteira da Release) é a exceção. O contexto de template de caminho inclui .parameters.<slot> em relação à allowlist fechada; as referências são resolvidas quando a renderização posiciona a saída de cada fronteira. Veja path-template-variables.md para a matriz completa de variáveis de template de caminho.

A fronteira de propriedade entre os quatro domínios é preservada por qual superfície recebe os parâmetros, não por o mapa de parâmetros existir ou não em memória em uma dada fase do pipeline. Os templates de caminho são escritos pelo operador e pertencem ao operador; conceder a eles acesso direto aos parâmetros mantém as preocupações do operador (o layout de artefatos por ambiente) dentro da superfície do operador. Os templates de valor são escritos no catálogo; negar a eles acesso direto aos parâmetros mantém a escrita do lado do catálogo fracamente acoplada ao contrato do Aggregate como fonte única da verdade.

O mapa de parâmetros mesclado permanece legível até que todas as fases de renderização tenham sido concluídas, e não além: ele só é alcançável a partir da compilação para a qual foi resolvido, de modo que o seu tempo de vida é limitado pelo do build.

Ponte entre pilares

Os parâmetros são interpolados nas strings de valores ao redor durante a resolução. Os valores interpolados podem chegar a qualquer pilar que o Aggregate escreve no seu escopo: strings values: de componente, strings values: de feature, declarações de repasse parameters: de subaggregate (em que o valor do parâmetro do Aggregate pai é resolvido e depois propagado para o slot de parâmetro do Aggregate filho), e strings name: / labels: dos metadados.

A ponte é unidirecional: um valor de parâmetro flui do .parameters.<slot> fornecido pela Release (ou padrão) para a string YAML no local da referência. Os parâmetros não fluem na outra direção — um parâmetro não pode ler um campo values:, um campo provides: ou o conteúdo de qualquer outro pilar. A direcionalidade faz parte da garantia do contrato de parâmetros de valer apenas em tempo de compilação.

Referências cruzadas

  • Para a forma da declaração dos contratos de parâmetros tipados no Aggregate: entities/aggregate.md §“Typed parameter contracts (Contratos de parâmetros tipados)”.
  • Para o contexto de template mais amplo que as Recipes consomem na renderização base (.values, .infra, .uses, .context.* etc.): template-context-contract.md.
  • Para a disponibilidade por local de template ao longo do pipeline de compilação (quais campos estão presentes em qual ponto de avaliação): expansion-matrix.md.
  • Para a checklist da elevação de parâmetros (os quatro pontos de contato sequenciais de escrita — declaração no Aggregate, referência em values, atendimento na Release, consumo na Recipe): vocabulary/data-pillars.md §“The parameter-hoisting checklist (A checklist da elevação de parâmetros)”.
  • Para o conjunto mais amplo de pilares de dados (values:, infra:, provides:, uses:, features:, locals:, parameters:): vocabulary/data-pillars.md.