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

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 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 cada 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 fundido permanece legível até ao 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 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:

  1. 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. Um minLength ou maxLength negativo na própria declaração de um parâmetro é recusado quando o Aggregate é carregado, indicando o parâmetro e a chave. Cada 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 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; ver entities/aggregate.md.
  2. Preenchimento dos valores predefinidos — os slots com default: definido e sem valor fornecido pela Release recebem o seu valor predefinido. O mapa .parameters está no âmbito neste ponto.
  3. 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çõ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á a ser verificado.
  4. 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 cadeias values: 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 em path-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 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 }}".

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 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 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 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 através 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, 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):

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

# 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 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 time
parameters:
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 time
parameters:
database:
host: "db.prod.example.com" # Release-supplied
port: 5432 # filled from default

Este é 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 em valuesMapping: exprimem-na através do caminho de consumo do .values.<key> resolvido — o Aggregate expõe um parâmetro, referencia-o a partir dos values: de um Component, a Release satisfá-lo, e o valor pós-interpolação flui até à 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 coloca a saída de cada fronteira. Ver 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, 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.