Contexto de template dos parâmetros
O pilar parameters: contém os valores de parâmetros fornecidos pela Release e validados em relação ao contrato. Dois modelos mentais paralelos regem a sua acessibilidade:
- As superfícies de template de valor (cadeias
values:de componente / feature / subaggregate dentro do Aggregate, além devaluesMappingda Recipe,injectMappingeprovidesda 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 cada referência{{ .parameters.<slot> }}pelo valor resolvido; as superfícies de template de valor a jusante nunca veem.parametersdiretamente no seu contexto de template. - As superfícies de template de caminho (templates
directory:esubDirectory: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 fundido permanece legível até ao fim da renderização para que um template de caminho possa ler.parametersem 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 daquilo de que precisa: os values: do lado do programador levam dados já resolvidos e específicos do ambiente até aos 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 cadeias YAML do Aggregate, a exceção dos templates de caminho e durante quanto tempo o mapa fundido permanece legível. Para a forma mais ampla do contexto de template de Recipe / FeatureRecipe (.values, .infra, .uses, etc.), ver template-context-contract.md. Para a disponibilidade por local de template ao longo do pipeline de compilação, ver expansion-matrix.md. Para a forma da declaração dos contratos de parâmetros tipados no Aggregate, ver 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, ver path-template-variables.md.
Ciclo de vida dos parâmetros
O compilador resolve os parâmetros em quatro fases ordenadas:
- Leitura do contrato — o bloco
spec.parameters:do Aggregate é verificado nos seus próprios termos antes de qualquer valor da Release ser examinado, pelo que um slot que não poderia restringir nada interrompe a compilação mesmo quando nenhuma Release o fornece. UmminLengthoumaxLengthnegativo na própria declaração de um parâmetro é recusado quando o Aggregate é carregado, indicando o parâmetro e a chave. Cadapattern— no próprio slot e dentro de qualquer contrato aninhado sobitems,propertiesouvaluesType— é compilado como expressão regular, e um que não compile é recusado indicando o parâmetro, o padrão e o motivo. Um limite de comprimento dentro de um contrato aninhado não está sujeito a esse mínimo; verentities/aggregate.md. - Preenchimento dos valores predefinidos — os slots com
default:definido e sem valor fornecido pela Release recebem o seu valor predefinido. O mapa.parametersestá no âmbito neste ponto. - Validação do contrato de parâmetros — cada valor no mapa fundido, quer tenha sido fornecido pela Release, quer tenha sido preenchido por um
default:, é validado em relação às restriçõestype/enum/min/max/pattern/ de estrutura aninhada declaradas emspec.parameters.<slot>do Aggregate; umpatterné comparado com a expressão compilada quando o contrato foi lido. O mapa.parametersexiste no contexto em memória do validador como o payload estruturado que está a ser verificado. - Interpolação — o compilador avalia todo o texto do Aggregate como um template, antes de o ler como YAML, e substitui cada referência
{{ .parameters.<slot> }}pelo valor resolvido; qualquer outro{{no texto é também lido como sintaxe de template, pelo que um valor que contenha chavetas duplas próprias escreve cada{{como{{"{{"}}(ver Texto que contém as suas próprias chavetas duplas). A interpolação é o caminho de substituição para as superfícies de template de valor — após esta passagem, os contextos de template de valor deixam de conter.parameters; consomem os valores resolvidos escritos nas cadeiasvalues:envolventes. O mapa fundido permanece legível após a interpolação, durante toda a renderização, especificamente para suportar a avaliação dos templates de caminho. O seu tempo de vida legível é limitado pelo da compilação: o compilador entrega a vista resolvida à compilação que a consome em vez de a devolver a um chamador, pelo que nada fora dessa compilação 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 empath-template-variables.md.
Os templates dentro das cadeias YAML do Aggregate (values: de componente, values: de feature, expressões de passagem parameters: de subaggregate) leem o mapa .parameters através da sintaxe normal de templates Go durante a passagem de interpolação. Os templates dentro dos ficheiros de Recipe e FeatureRecipe NÃO recebem .parameters no seu contexto de template (ver «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 as suas próprias chavetas duplas
Como todo o texto é um template, as chavetas 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 contida nos values: de um componente é o caso comum: o n8n envolve em chavetas 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 ligação entre dois nós, e uma exportação do Langflow contém o código-fonte dos seus componentes, onde as chavetas também podem aparecer. Escritas tal como estão num Aggregate, interrompem a compilação 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 indica a linha e o primeiro token que o motor de templates não conseguiu ler — undefined variable "$json" para uma expressão do n8n. Um comentário YAML também é texto de template, pelo que um {{ escrito num comentário interrompe a compilação da mesma forma.
Escreve-se cada {{ num valor deste tipo como {{"{{"}}. Trata-se de uma ação de template cujo resultado é a cadeia {{, pelo que a interpolação repõe as duas chavetas. Um }} de fecho 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, pelo que as chavetas repostas chegam à saída renderizada tal como foram exportadas.
# Aggregate fragment — an n8n workflow definition carried as exportedspec: 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 }}".
Uma definição deste tipo deve ser mantida num 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 cadeia YAML entre aspas duplas o " do escape fecha a cadeia, pelo que o ficheiro deixa de ser analisado e a compilação é interrompida 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 declarationsspec: 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 }} # booleanA passagem de interpolação produz uma avaliação de template Go sobre o mapa .parameters; o resultado substitui no próprio local a expressão de template no documento. O esquema values: do Component / da Feature valida depois o valor resultante na fase de validação de esquema pós-interpolação da resolução.
As aspas decidem o tipo elevado
Uma referência destinada a uma folha do tipo cadeia leva aspas; para qualquer outro tipo declarado, fica sem aspas. A regra é a do próprio YAML, não uma que o Aggrega acrescente por cima: a interpolação substitui o valor fornecido nos bytes do documento e não faz mais nada, pelo que a análise que se segue lê o resultado exatamente como lê qualquer outro escalar. Um {{ .parameters.cache_ttl_seconds }} sem aspas contém o tipo próprio do valor fornecido, e é isso 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 contém uma cadeia, e uma folha declarada integer ou boolean recusa-a: o valor escrito falha o esquema values: do seu Component ou da sua Feature quanto ao tipo, e o diagnóstico indica a incompatibilidade de tipo em vez de qualquer restrição do espaço de valores que a cadeia também não teria cumprido.
Uma referência que partilha o seu escalar com outro texto é uma cadeia seja qual for a forma como é 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 é uma cadeia tem de chegar a uma folha do tipo cadeia.
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 parameterspec: 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 através de range:
# Aggregate fragment — array-typed parameterspec: 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, pelo que um valor que não seja um nome de anfitrião — *, por exemplo — interrompe a compilação indicando o parâmetro, o elemento e o formato. Os nomes que format aceita, e o que cada um verifica, estão enumerados 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 cadeia:
hosts: "{{ join `,` .parameters.allowed_hosts }}"Semântica do preenchimento dos valores predefinidos
Um slot de parâmetro com uma declaração default: recebe o seu valor predefinido quando a Release omite o slot. O valor predefinido aplica-se antes de a passagem de validação do contrato ser executada, pelo que a validação vê o valor resolvido (fornecido pela Release ou predefinido):
# Aggregatespec: 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: provoca um erro em tempo de compilação quando a Release o omite (E0165). O erro indica o slot e a sua localização no contrato para que o autor o corrija. Um slot sem required: true nem default: é opcional: se for omitido, cada referência a ele é interpolada como vazia, e o esquema values: do Component julga depois o resultado.
Parâmetros de objetos aninhados
Quando um parâmetro declara type: object com properties: cujos filhos contêm eles próprios valores default:, três casos de escrita produzem resultados distintos. Compreender a distinção é importante quando a declaração do parâmetro é um objeto estruturado — uma configuração de base 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 predefinidos dos filhos do contrato são preenchidos. O autor do Aggregate que declarou os valores predefinidos aninhados obtém o comportamento pretendido: quando ops não fornece o slot, a configuração usa os valores predefinidos documentados.
# Aggregatespec: parameters: database: type: object properties: host: { type: string, default: "localhost" } port: { type: integer, default: 5432 }
# Release (parent omitted)spec: parameters: {}
# Resolved at template-interpolation timeparameters: database: host: "localhost" port: 5432Caso 2 — a Release escreve o pai como um mapa vazio explícito. O vazio explícito é respeitado como um opt-out deliberado. Os valores predefinidos dos filhos NÃO são preenchidos; o slot permanece vazio. Esta forma usa-se quando ops quer suprimir os valores predefinidos 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 timeparameters: database: {}A distinção em relação ao Caso 1 é deliberada: ops pode exprimir tanto «usar os valores predefinidos» (omitindo o slot) como «suprimir os valores predefinidos» (escrevendo o slot como {}). Isto espelha a forma 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 completamente a anotação.
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 a partir dos valores predefinidos.
# Release (partial)spec: parameters: database: host: "db.prod.example.com"
# Resolved at template-interpolation timeparameters: database: host: "db.prod.example.com" # Release-supplied port: 5432 # filled from defaultEste é o caso comum para os autores de Release que querem substituir campos selecionados deixando o resto nos valores predefinidos do contrato.
Quando usar cada forma
- Omitir o slot quando se pretende que os valores predefinidos do contrato se apliquem.
- Escrever
{}quando se pretende deliberadamente o slot presente, mas vazio — quando os valores predefinidos do contrato estão errados para o ambiente em causa e não há substituições. - Escrever parcialmente quando se pretende algumas substituições e que o resto use os valores predefinidos do contrato.
Um autor de Release que escreva database: {} à espera de «dá-me os valores predefinidos» terá uma surpresa — o valor resolvido é vazio, não os valores predefinidos preenchidos. Para obter os valores predefinidos, omite-se completamente o slot.
O tratamento dos três casos é feito por irmão a 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, e 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 nesta 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 próprio local na cadeia YAML. - Um template
valuesMapping:da Recipe que escreve{{ .parameters.X }}é uma superfície de template de valor; o contexto de template não contém.parameters. Os autores que precisam de variação por ambiente emvaluesMapping:exprimem-na através do caminho de consumo do.values.<key>resolvido — o Aggregate expõe um parâmetro, referencia-o a partir dosvalues:de um Component, a Release satisfá-lo, e o valor pós-interpolação flui até à Recipe. - Um template
injectMapping:,provides:oupipeline.with:da FeatureRecipe é uma superfície de template de valor; o mesmo quevaluesMapping:da Recipe..parametersnã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 coloca a saída de cada fronteira. Verpath-template-variables.mdpara 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, e não por o mapa de parâmetros existir ou não em memória numa dada fase do pipeline. Os templates de caminho são escritos pelo operador e pertencem ao operador; conceder-lhes acesso direto aos parâmetros mantém as preocupações do operador (a disposição dos artefactos por ambiente) dentro da superfície do operador. Os templates de valor são escritos no catálogo; negar-lhes acesso direto aos parâmetros mantém a escrita do lado do catálogo fracamente acoplada ao contrato do Aggregate como fonte única de verdade.
O mapa de parâmetros fundido permanece legível até todas as fases de renderização terem terminado, e não para além disso: só é alcançável a partir da compilação para a qual foi resolvido, pelo que o seu tempo de vida é limitado pelo da compilação.
Ponte entre pilares
Os parâmetros são interpolados nas cadeias de valores envolventes durante a resolução. Os valores interpolados podem chegar a qualquer pilar que o Aggregate escreva no seu âmbito: cadeias values: de componente, cadeias values: de feature, declarações de passagem 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 cadeias name: / labels: dos metadados.
A ponte é unidirecional: um valor de parâmetro flui do .parameters.<slot> fornecido pela Release (ou predefinido) para a cadeia YAML no local da referência. Os parâmetros não fluem no outro sentido — um parâmetro não pode ler um campo values:, um campo provides: nem 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 (que campos estão presentes em que ponto de avaliação): expansion-matrix.md.
- Para a lista de verificação da elevação de parâmetros (os quatro pontos de contacto sequenciais da escrita — declaração no Aggregate, referência em values, satisfação na Release, consumo na Recipe):
vocabulary/data-pillars.md§«The parameter-hoisting checklist (A lista de verificação 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.