Release
O papel conceitual da entidade Release (Domínio 4 — o roteador de implantação que associa um Aggregate a um Manifest e mapeia componentes em limites físicos) está em architecture/04-entity-taxonomy.md. O mecanismo de sequenciamento temporal (syncWave por limite), o Dynamic Addressing Polyfill e o padrão Parameter Hoisting estão em architecture/12-day-two-lifecycles.md. Esta página trata da superfície de autoria da Release.
O papel da Release
A Release associa um aggregate a um manifest e mapeia componentes em limites físicos de implantação (por exemplo, aws-eks-production). Ela é o único ponto de entrada para a compilação: aggrega build --release release.yaml.
A Release cumpre o contrato abstrato do agregado injetando as realidades físicas estritamente no bloco parameters, e injeta o dimensionamento físico (como CPUs ou portas) por meio do namespace paralelo infra.
Toda Release declara um campo manifest: que nomeia seu Manifest (a menos que a Release use extends:, que herda o ponteiro de manifesto do pai). A CLI aggrega build lê esse campo diretamente; não existe nenhuma flag de CLI --manifest, de modo que a especificação de dependências permanece commitada no Git junto à própria Release, tornando o histórico de implantações auditável pelo próprio histórico do Git da Release.
Os campos aggregate: e manifest: são resolvidos por identidade ou por arquivo com caminho relativo, da mesma forma que o resto da linguagem resolve referências — nunca como um radical de nome de arquivo relativo à Release. Um valor ./ ou ../ é um arquivo local explícito, lido diretamente em relação à Release. Um token simples é uma identidade — o metadata.name da entidade referenciada. Uma identidade manifest: é resolvida varrendo o próprio diretório da Release (um Manifest é configuração de operador do lado da implantação, portanto não tem camada de catálogo nem de registry). Uma identidade aggregate: é resolvida por toda a cascata — o diretório da Release, depois o catálogo, depois o registry —, de modo que uma Release pode nomear um Aggregate publicado por identidade e o mesmo módulo publicado é resolvido, seja ele o spec.aggregate de nível superior de uma Release ou um subagregado dentro de outro Aggregate. Esse modelo de identidade ou caminho permite que um Aggregate compartilhado sustente muitas variantes de Release sem acoplar a referência a um nome de arquivo, e que um Aggregate publicado seja implantado diretamente pelo nome.
Um caminho permanece dentro do workspace. Um valor ./ ou ../ nomeia um arquivo que o workspace contém, e o mesmo vale para qualquer outro caminho que uma Release escreva — seu extends: e um $import: de parâmetros, abaixo. Um caminho que sai do workspace da forma como está escrito, ou que um link simbólico no trajeto leva para fora dele, é recusado antes que qualquer coisa seja lida do arquivo que ele nomeia. Para implantar um Aggregate mantido fora do workspace, nomeie-o por identidade e liste o diretório que o contém como diretório de catálogo na configuração do workspace; um Manifest, uma Release que um extends: nomeia e um arquivo de parâmetros são lidos ao lado da Release e nunca procurados por nome, então são mantidos dentro do workspace. Uma Release que você nomeia na linha de comando, ou que a configuração do workspace nomeia, fora do workspace é uma raiz própria: todo caminho que ela escreve — e todo caminho que escreve uma Release a que sua cadeia extends: leva — deve levar a um arquivo dentro do diretório que contém essa Release, e um caminho que sai desse diretório, ou que um link leva para fora dele, é recusado da mesma forma. Mantenha o que uma Release dessas nomeia ao lado dela, ou faça o build dela no workspace que contém as duas. Consulte errors/fatal-halts.md §“A reference to another file leads out of the directory it must stay inside (Uma referência a outro arquivo sai do diretório dentro do qual deve permanecer)”.
A Release define o destino dos artefatos compilados; o despacho para os provedores cabe ao Manifest para o qual a Release aponta (consulte Manifest vs. Release: separação de responsabilidades para a divisão de papéis).
Metadados de ambiente
Todo bloco de metadados de uma Release aceita um campo environment: — uma string livre que identifica o ambiente no qual a Release é implantada (valores típicos: production, staging, dev). O campo é informativo: não carrega nenhuma enumeração, nenhum padrão no nível do schema e nenhuma validação entre entidades além de type: string. O compilador emite seu valor como o label aggrega.ai/environment em todo manifesto Kubernetes que o provedor helm renderiza, junto com o restante do conjunto de labels de procedência da Aggrega — como está escrito quando é um valor de label Kubernetes válido e, caso contrário, reescrito em um valor válido, com o valor exato levado na anotação aggrega.ai/environment (assim, eu/prod recebe o label eu-prod); o provedor helm-chart adiciona os mesmos labels a cada artefato carregado via $import: que coloca em um sub-chart, enquanto os templates próprios do sub-chart carregam o que seu autor escreveu. O provedor compose carrega o mesmo valor como o label aggrega.ai/environment em cada serviço que emite.
Cinco padrões práticos orientam a escrita de environment::
-
Atribuição de custos OTel/FinOps. Painéis de custos de nuvem (AWS Cost Explorer, Datadog Cloud Cost Management, CloudHealth) filtram pods do Kubernetes por ambiente usando tags. O label
aggrega.ai/environment: productionflui para os labels dos pods por meio da injeção de labels do provedor Helm; relatórios de custos agrupam os gastos poraggrega.ai/environmentsem tagging manual por recurso. -
Filtragem de traces e logs OTel. Painéis de observabilidade (Datadog, New Relic, Honeycomb, Grafana Tempo) filtram a telemetria pelo label de ambiente.
aggrega.ai/environment: stagingpermite que os operadores limitem consultas de logs e buscas de traces ao staging sem filtrar por convenções de namespace ou nomes de charts — um único label canônico em toda a superfície renderizada. -
Direcionamento de operadores Kubernetes. Controladores GitOps (ArgoCD, Flux) e operadores de políticas (Kyverno, OPA Gatekeeper) às vezes filtram recursos pelo label de ambiente para políticas específicas de ambiente (por exemplo, “recursos exclusivos de produção exigem um label approved-image-source”). O label
aggrega.ai/environmentfornece um seletor estável, distinto de convenções de namespace ou padrões de nomenclatura. -
Diferenciação de produção multirregião. Uma equipe que executa uma Release
production-us-eastao lado de uma Releaseproduction-eu-west— ambas commetadata.environment: production— obtém o mesmo labelaggrega.ai/environment: productionem todas as regiões. Combinado com um label de região separado, isso permite a consolidação de custos entre regiões (“gasto total de produção”) e o detalhamento por região. -
Delimitação de conformidade. A coleta de evidências SOC 2, PCI e HIPAA é delimitada por ambiente (auditoria apenas de produção etc.). O label
aggrega.ai/environmenté consumido por ferramentas de coleta de evidências de conformidade (Vanta, Drata) para filtrar recursos por escopo de auditoria.
O schema exige environment: em toda Release; o valor é informativo, e o compilador o lê apenas para escrever o label aggrega.ai/environment.
Restrições em nível de esquema
Duas garantias estruturais protegem o Aggregate como fonte única da verdade:
values:é proibido. Para proteger o Aggregate como fonte única da verdade, o esquema da Release proíbe mecanicamente um blocovalues:— o operador não pode declararvaluesem nenhum Component ou Feature a partir de uma Release. A proibição se estende às arestasuses: uma entradausespor aresta de uma Release carregainfrae as vinculações que ela escreve na conexão, e essas também carregaminfra— nuncavalues(os valores por aresta voltados ao desenvolvedor, e os valores de uma vinculação em uma conexão, permanecem no Aggregate). A variação por ambiente dos valores voltados ao desenvolvedor passa pelo Parameter Hoisting: o desenvolvedor expõe um campo tipadoparameters.*no Aggregate, o templatevaluesdo Component o referencia e a Release preenche o parâmetro para o seu ambiente. Veja architecture/06-data-taxonomy-and-composition.md §8 Restrição 4 para a proibição em nível de esquema declarada explicitamente. A superfície de arestasusesda Release — o que ela pode configurar e ligar — está documentada em Configuração de conexão por aresta abaixo.extends+aggregate:é rejeitado. Para impedir Releases não rastreáveis que “alteram o aggregate”, quando uma Release usaextends, a declaração de um ponteiroaggregateé rejeitada pelo esquema da Release. A release filha deve corresponder exatamente à mesma intenção do desenvolvedor que sua release pai. Omanifest, porém, torna-se opcional, liberando a “vinculação tardia” — permitindo que o operador herde toda a topologia física, mas troque cirurgicamente o Manifest.
O bloco parameters:
Uma Release cumpre o contrato tipado de parâmetros que o Aggregate declara. spec.parameters: é a superfície de autoria — um mapa YAML cujas chaves correspondem às declarações parameters.* do Aggregate e cujos valores fornecem o preenchimento por ambiente.
# Aggregate declares the typed contractapiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: my-app version: 1.0.0spec: parameters: db_size: { type: string, required: true } timeout_seconds: { type: integer, default: 30 } region: { type: string, enum: [us-east-1, eu-west-1], required: true }# Release fulfills the contract for this environmentapiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: prod-release version: 1.0.0 environment: productionspec: aggregate: my-app manifest: prod-manifest parameters: db_size: "100Gi" timeout_seconds: 60 region: "us-east-1"Cada valor passa pela verificação do esquema declarado pelo Aggregate na camada do contrato de parâmetros, e a compilação é interrompida quando uma Release omite um parâmetro obrigatório (E0165, parameter-missing) ou fornece um valor que o contrato do seu slot recusa (E0164, parameter-contract-violation). Os parâmetros declarados com um default: recebem o valor padrão quando a Release omite o slot; o contrato tipado é o único vocabulário de autoria.
Dois modos de autoria — seleção pela forma do conteúdo. parameters: aceita um mapa YAML inline (modo 1, mostrado acima) ou uma única chave $import: apontando para um arquivo local (modo 2):
spec: aggregate: my-app manifest: prod-manifest parameters: $import: ./prod-parameters.yamlUm caminho $import: relativo é resolvido a partir do diretório que contém a Release que o escreve, de onde quer que um comando seja executado, de modo que a linha de comando e o editor leem o mesmo arquivo; um caminho absoluto nomeia o seu próprio local, e qualquer um deles deve levar a um arquivo dentro do workspace — ou, para uma Release indicada fora do workspace, dentro do diretório que a contém. Os dois modos são mutuamente exclusivos nesse ponto, e só é possível importar um único arquivo. O empilhamento de parâmetros em vários arquivos cabe às cadeias extends: de Release: a Release pai fornece um conjunto base de parâmetros e a filha estende e sobrescreve por ambiente. Veja Release composta / herança extends: mais abaixo para o padrão.
Separação entre parâmetros e infra. Os parâmetros carregam a intenção cognitiva do desenvolvedor expressa como slots tipados que o Aggregate declara; a Release os preenche. infra: na Release carrega o dimensionamento físico do operador (contagens de réplicas, limites de CPU/memória, classes de armazenamento) associado a componentes específicos ou a vinculações de Feature. Os parâmetros fluem para os templates values: do Aggregate por meio de .parameters.X; infra: flui para o template valuesMapping: da Recipe por meio de .infra.X. Veja architecture/06-data-taxonomy-and-composition.md §3 para a taxonomia dos pilares de dados e templates/parameters-context.md para o ciclo de vida dos parâmetros ao longo do pipeline.
Fronteiras e o escopo padrão
Uma Release agrupa componentes em fronteiras — unidades físicas de implantação, cada uma com seu próprio diretório de saída e sua própria cascata de anotações. O caso de fronteira única é o comum, por isso não exige cerimônia.
Escopo único (o padrão). Escreva os componentes diretamente sob spec.components: e omita o bloco boundaries:. O compilador os incorpora a uma fronteira default sintetizada cuja saída é plana — os artefatos ficam diretamente sob dist/ (por provedor, por meio do padrão seguro de subDirectory descrito abaixo: dist/compose/, dist/helm/, …), sem nenhum segmento com o nome da fronteira no caminho. Essa é a implantação mais simples: aggrega build sobre um destino Compose plano ou de cluster único sem nomear fronteiras.
spec: aggregate: aggregate manifest: manifest components: db: infra: engine_version: "11.4" web: infra: port: 8080Vários escopos. Quando uma Release abrange mais de um agrupamento físico — clusters, regiões ou sync waves separados — declare fronteiras nomeadas sob boundaries:. Cada fronteira carrega seu próprio directory:, sua própria cascata de anotações e seu próprio syncWave:, e os componentes são endereçados dentro da sua fronteira.
Exclusão mútua. spec.components: e spec.boundaries: são mutuamente exclusivos na raiz da Release — uma Release escreve um ou outro, nunca ambos. Um documento que declara ambos é interrompido no carregamento com um erro de envelope. A superfície components de nível superior carrega a mesma forma por componente, do lado do operador, que os components de uma fronteira carregam (infra:, annotations:, uses:).
Uma fronteira declarada com o nome default. A saída plana é uma propriedade da fronteira padrão sintetizada, não do nome. Uma fronteira chamada default que uma Release declara explicitamente sob boundaries: é uma fronteira nomeada comum: sua saída segue o seu directory: (por padrão dist/boundaries/default/), exatamente como qualquer outra fronteira declarada.
Veja architecture/06-data-taxonomy-and-composition.md §7 para o modelo do escopo padrão.
Segregação espacial e caminhos de saída
Cada fronteira declara um directory físico de saída para seus artefatos compilados; os componentes dentro de uma fronteira podem substituí-lo por meio de um subDirectory por componente. O compilador calcula o caminho final do artefato juntando-os, em forma separada por barras em todas as plataformas: Final_Path = Clean(Join(Evaluated(directory), Evaluated(subDirectory))).
- Um diretório, uma grafia. O caminho avaliado é limpo uma única vez, de modo que
out/a,out//a,./out/aeout/a/são um mesmo diretório. Fronteiras cujos caminhos, depois de limpos, resultam no mesmo diretório e que renderizam pelo mesmo provedor são montadas juntas, exatamente como fronteiras escritas com caminhos idênticos. - O caminho permanece sob a raiz de saída. Um caminho que sobe para fora da raiz de saída (
..,../escape,a/../..), um absoluto, ou um que não nomeia nenhum diretório — vazio, ou que, depois de limpo, resulta na própria raiz de saída — interrompe a compilação antes que qualquer coisa seja escrita. A mensagem nomeia a Release, a fronteira, o campo com problema (directory:ousubDirectory:) e o valor para o qual ele foi avaliado, já que esse valor muitas vezes é o resultado de um template. - Padrão seguro. Se
subDirectoryfor omitido ou estiver vazio, o compilador aplica automaticamentesubDirectory: "{{ .capability }}"— os artefatos de cada capacidade de renderização (Helm, Helm-chart, Compose, Terraform, CloudFormation) ficam em sua própria subpasta, evitando colisões de artefatos misturados nas ferramentas de CI/CD posteriores. UmsubDirectory: ""escrito explicitamente é lido exatamente como um omitido, então também recebe esse padrão. - Substituição plana. Para desativar completamente os subdiretórios (todos os artefatos diretamente sob
directory), definasubDirectory: ".". Um templatesubDirectoryque é avaliado como uma string vazia —"{{ .parameters.sub }}"comsubdefinido como"", por exemplo — também os desativa. - Variáveis de template.
directoryé avaliado com{{ .capability }},{{ .boundary_name }},{{ .parameters.X }},{{ .manifest.recipe_name }}e{{ .parent_boundary.* }}para dados em cascata de uma fronteira envolvente.subDirectoryé avaliado com o mesmo conjunto mais{{ .component_id }}(somente em substituições por componente). O compilador avalia os templates de caminho commissingkey=error— referenciar uma variável não declarada interrompe a compilação com um diagnóstico preciso. Veja variáveis de templates de caminho para a matriz por contexto e as regras de cascata da fronteira pai.
As anotações de fronteira descem em cascata para cada componente contido; infra permanece estritamente localizado no componente que o recebe. O mapa recursivo boundaries permite aninhamento arbitrário (fronteira dentro de fronteira dentro de fronteira), enquanto as invariantes da cascata de anotações e do infra local valem em todos os níveis.
Exemplo prático:
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: spatial-release version: 1.0.0 environment: productionspec: aggregate: spatial-app manifest: prod-manifest boundaries: eu-prod: directory: "deploy/eu-prod" # Scenario A: Safe Default. Compiler automatically applies `subDirectory: "{{ .capability }}"`. annotations: "aggrega.ai/namespace": "finance-frontend" # Merges downwards as annotations components: api-server: infra: { replicas: 5 } # Strictly local aws-rds: # Scenario B: Bespoke Enterprise Naming. subDirectory: provisioning postgres-db: # Scenario C: The Flat Directory Override. subDirectory: "." # not "", which takes the defaultAs anotações propagadas em cascata por esse mecanismo aparecem nos templates de Recipe posteriores por meio de .context.annotations.release; veja Autoria de uma Recipe e a matriz de expansão de templates para saber como os renderizadores as consomem.
Valores de anotação estruturados. Quando um binding do Manifest declara vários caminhos de roteamento do pilar infra para uma mesma chave de anotação, o valor da anotação do lado da Release pode ser um objeto estruturado que carrega valores para vários campos do esquema de uma Feature em uma única declaração:
boundaries: prod: annotations: feature.myco/db-pool: pool_size: 20 max_connections: 100 components: api: annotations: feature.myco/db-pool: max_connections: 200 # closer-level override # pool_size not listed → inherits 20 from boundaryOs valores estruturados descem em cascata com uma mesclagem profunda por subchave; as subchaves do nível mais próximo substituem as do pai. Um null por subchave exclui uma subchave enquanto as subchaves irmãs permanecem. O lado da Release aplica apenas as subchaves cujo pilar no mapa de binding é infra; as subchaves roteadas para values pertencem às anotações do lado do Aggregate. Para a explicação completa dos valores estruturados — composição entre os lados, validação de tipo por subchave, a disciplina dos padrões flexibilizados — veja providers/well-known-annotations.md §“Valores de anotação estruturados”.
Anotações conhecidas. Além das chaves ad hoc, a biblioteca padrão do Aggrega define um conjunto de anotações conhecidas sob os namespaces aggrega.ai/ e feature.aggrega.ai/, agrupadas nas categorias de posicionamento, rede, segurança e observabilidade. Quem adiciona anotações a uma fronteira de Release deve consultar providers/well-known-annotations.md para a matriz completa e as regras de consumo por provedor — a página documenta quais provedores aplicam cada chave conhecida e que comportamento emitem quando a chave está presente.
Configuração de conexão por aresta
Um componente de fronteira pode carregar um bloco uses: que configura ou liga as arestas da topologia dentro dos sockets que o usesSchema de catálogo do Component declara. Essa é a superfície por conexão do operador, delimitada para que o desenvolvedor mantenha a posse da arquitetura que escreveu:
- Configurar uma aresta existente. Defina
infrapor aresta em uma aresta que o desenvolvedor já declarou. A entrada nomeia o alias do desenvolvedor e forneceinfra; ela nomeia o mesmo destino que o desenvolvedor ligou ou omite o destino. Oinfraé validado em relação aoinfraSchemado socket. - Ligar um socket não associado. Crie uma aresta para um socket que o
usesSchemado Component declara, mas que o desenvolvedor deixou sem ligação, apontando para um componente existente. A aresta criada também pode carregarinfrapor aresta. - Vincular em uma conexão. Coloque vinculações sob
features:da entrada, indexadas por um slot que o socket declara em seufeaturesSchema— os mesmos slots que a entrada de conexão do desenvolvedor preenche. Cada uma carregatype, umadescriptionopcional einfra, e nuncavalues. Sob um slot que o desenvolvedor já preencheu na mesma conexão, a entrada dimensiona essa vinculação: escreva apenasinfra, pois o tipo e os valores vêm do Aggregate (umtypeescrito aqui deve concordar com o do Aggregate, ou a compilação é interrompida nesta entrada, nomeando ambos). Sob um slot que o desenvolvedor deixou vazio, a vinculação é da própria Release etypeé obrigatório. Em ambos os casos, o preenchimento está sujeito aoselectordo slot e conta para um slotrequired, exatamente como o do desenvolvedor.
A superfície é criar-sem-redirecionar: uma Release pode adicionar uma aresta a um socket não associado, mas não pode redirecionar uma aresta que o desenvolvedor já declarou. Uma entrada por aresta que nomeia um destino diferente do da aresta do desenvolvedor interrompe a compilação; uma entrada que nomeia o mesmo destino (ou o omite) configura essa aresta. A Release também não pode declarar values em uma aresta ou em uma vinculação que escreve ali (os valores voltados ao desenvolvedor permanecem no Aggregate), associar um socket que o usesSchema não declara, nem apontar uma aresta para um componente que não existe — cada um desses casos é uma interrupção fatal. O mesmo vale para uma entrada que define infra ou features em uma conexão que não existe depois que todas as arestas são traçadas, a menos que o componente consumidor esteja desativado com active: false. Veja errors/fatal-halts.md §“Ao construir a topologia”.
Mais três interrupções mantêm as vinculações de uma conexão na sua conexão:
- Um nome para o qual o socket não declara nenhum slot interrompe a compilação, exatamente como na entrada de conexão do Aggregate, nesta entrada da Release, nomeando os slots que o socket declara e aqueles dos quais o nome está a uma edição de distância.
- Uma vinculação que apenas a Release faz, escrita sem
type, interrompe a compilação na entrada de conexão, nomeando o slot. Uma vinculação que a Release faz não carregavalues, então serve para uma Feature cujosvaluesnão exigem nada; uma cujo esquema exige um valor é interrompida pelo valor ausente na mesma entrada. As Features de credenciais da biblioteca padrão que carregam o localizador de quem chama não exigem nenhum emvalues: cada uma o aceita também eminfra(veja abaixo). - O nome composto escrito em qualquer lugar que não seja a conexão interrompe a compilação. Uma vinculação de conexão torna-se uma vinculação do componente consumidor chamada
<alias>.<slot>(veja a entrada de conexão do Aggregate), e tanto as chavesfeatures:próprias de uma entrada de componente quanto as de uma fronteira admitem um ponto. Uma entrada de componente que escreve esse nome, ou uma fronteira que o escreve de forma que ele alcance um componente cuja conexão o carrega — um componente colocado nessa fronteira ou em uma aninhada dentro dela, incluídos os de um submódulo roteado — interrompe a compilação nomeando ambas as grafias, uma vez para cada componente que alcança. O slot de um socket é preenchido em cada conexão e nunca por uma vinculação que desce em cascata de um escopo mais amplo.
spec: components: router: uses: models: # Size the attachment the Aggregate declared on the "gpt" connection: infra only. gpt: features: credential: infra: { rotation: hourly } # Attach on a connection the developer left without one: the type is required. plain: features: credential: type: core/generated-secretUma credencial em uma conexão que a Release liga nomeia seu segredo em infra. Uma conexão que a Release liga não tem entrada no Aggregate, então nada ali escreve os values da credencial, e a Release não escreve values em lugar nenhum. Cada Feature de credenciais da biblioteca padrão que carrega o localizador de quem chama — core/referenced-secret, core/referenced-secret-set, core/secret-value e core/secret-provided — portanto o aceita em infra além de em values: origin, ou entries para core/referenced-secret-set, com a mesma forma e a mesma declaração sensitive: true em ambos os pilares. Cada realização lê o pilar que o carregar.
spec: components: router: uses: models: gpt: target: gpt # wire the socket the developer left unbound features: credential: type: core/referenced-secret infra: origin: openai-team-a # the secret the operator namesO localizador é escrito em exatamente um pilar por vinculação. Uma vinculação que o carrega em ambos — os values do Aggregate e o infra da Release para o mesmo slot — ou em nenhum é interrompida na asserção da própria Feature (E0033), nomeando a Feature, a vinculação e o componente, e dizendo qual dos dois casos ocorreu. A regra pertence às entidades de catálogo dessas Features, não ao compilador, que avalia a asserção delas como avalia a de qualquer Feature. Os campos que não são o localizador mantêm o seu pilar: key continua sendo uma folha de values, então uma vinculação que apenas a Release faz lê a chave de dados padrão da Feature, value. A proibição de values: não muda — o localizador do operador é infra.
core/secret-provided é a que não serve para uma conexão: ela publica seu valor para que o bloco inject: da própria vinculação o entregue, e a vinculação de uma conexão não carrega bloco inject: em nenhum dos dois documentos, então em uma conexão nenhum bloco inject: o entrega. Use core/referenced-secret ou core/secret-value ali.
spec: aggregate: spatial-app manifest: prod-manifest boundaries: eu-prod: components: api-server: uses: databases: # Configure the developer-declared edge "primary": add per-edge infra. # The target matches what the Aggregate wired (or is omitted) — a configure, not a retarget. primary: infra: { storage_class: fast-ssd } caches: # Wire an edge into the declared-but-unbound "caches" socket to an existing component. main: target: redis-prod infra: { storage_class: standard }O infra por aresta resolvido flui para o contexto de renderização do componente consumidor em .context.uses.<alias>.infra.<key>; ele nunca aparece no contexto do componente de destino, de modo que a saída renderizada de um destino é invariante em relação aos consumidores que configuram arestas para ele. Uma vinculação em uma conexão também chega ao componente consumidor, como uma de suas vinculações: seu infra é mesclado com os values do Aggregate para o mesmo slot, e sua FeatureRecipe renderiza com base em ambos. A Recipe do componente consumidor a lê sob sua conexão, em .context.uses.<alias>.features.<slot>, e seu Workload a entrega nomeando a conexão ao lado do slot — veja Entregar uma credencial que uma conexão carrega.
O campo aggregates: — roteando submódulos aninhados para fronteiras
Quando o Aggregate declara submódulos aninhados via spec.aggregates:, a Release decide em qual fronteira os componentes de cada submódulo vão parar declarando aggregates: ao lado de components: dentro da fronteira de destino:
# Aggregate declares two sub-aggregatesapiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: platform version: 1.0.0spec: aggregates: finance: type: finance-module:1.2.0 analytics: type: analytics-module:2.0.0 components: gateway: type: core/ingress---# Release routes each sub-aggregate into a specific boundaryapiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: prod-release version: 1.0.0 environment: productionspec: aggregate: platform manifest: prod-manifest boundaries: eu-prod: directory: "deploy/eu-prod" aggregates: finance: {} components: gateway: {} us-prod: directory: "deploy/us-prod" aggregates: analytics: {}Coloque cada subagregado listado em Aggregate.spec.aggregates: em exatamente uma fronteira.
O roteamento posiciona componentes. Cada componente de um submódulo roteado vai para a fronteira que o roteia e recebe dela directory, subDirectory, syncWave e a cascata de anotações — o mesmo contexto que um componente nomeado diretamente em components: recebe, incluindo a procedência aggrega.ai/boundary-path carimbada nos artefatos emitidos. Rotear um submódulo e endereçar cada um de seus componentes pelo caminho pontuado qualificado com um corpo vazio produzem, portanto, artefatos idênticos; o roteamento é a forma mais curta de dizer isso, e a única forma de dizê-lo sem conhecer o conteúdo do submódulo.
Um componente pertence a exatamente uma fronteira, e o build é interrompido quando um documento posiciona um componente duas vezes — o mesmo submódulo roteado para duas fronteiras, um submódulo roteado para uma fronteira enquanto um de seus componentes é nomeado em outra, ou um componente nomeado tanto diretamente quanto por meio de uma entrada de roteamento. O diagnóstico nomeia os dois locais, porque qual manter é decisão do autor. Rotear um submódulo para uma fronteira e nomear um de seus componentes sob essa mesma fronteira não é um conflito: o roteamento posiciona o componente e a entrada nomeada o configura.
Um subagregado que a Release não posiciona em lugar nenhum interrompe o build. O posicionamento é lido nas duas grafias, então o build só é interrompido quando nenhuma delas alcança o submódulo: nenhuma fronteira o roteia em aggregates:, e nenhuma fronteira nomeia qualquer um de seus componentes em components: pelo caminho pontuado qualificado. Qualquer uma das grafias sozinha o posiciona, e um submódulo cujos componentes são todos nomeados individualmente não precisa de entrada de roteamento. A correção cabe ao bloco aggregates: do Aggregate que importou o submódulo — o Aggregate que a Release implanta, para um que ele importa diretamente, e o próprio documento do submódulo importador, para um aninhado. O diagnóstico nomeia essa entrada pela chave com que o documento importador a escreve, de modo que, para um submódulo aninhado, ela aparece como o nome local, e não como o caminho pontuado.
Dois casos deliberadamente não interrompem o build. Um submódulo que não contribui com nenhum componente não tem nada a posicionar. Um submódulo cujo interruptor active: é resolvido como false nunca foi composto, então nenhum de seus componentes existe para ser posicionado.
O posicionamento parcial não aciona esta regra: um submódulo está posicionado assim que qualquer um de seus componentes alcança uma fronteira, então nomear um deles satisfaz o submódulo. Disso não decorre que os demais possam ser omitidos. Nada posiciona então cada componente que a fronteira não nomeou, e a regra de componentes abaixo o relata em sua própria chave — então um submódulo posicionado em parte interrompe o build uma vez para cada componente que deixou para trás, e não no submódulo. As duas grafias que posicionam um submódulo inteiro em uma linha são a entrada de roteamento e nomear cada componente; qualquer coisa entre as duas posiciona o que nomeia e nada mais.
Um componente que a Release não posiciona em lugar nenhum também interrompe o build, um nível abaixo. A regra acima pergunta se um submódulo alcançou uma fronteira; esta pergunta o mesmo sobre cada componente que a composição contém. Um componente alcança uma fronteira sendo nomeado em components: dessa fronteira, ou estando dentro de um submódulo que uma fronteira roteia para si. Um que não alcança nenhum dos dois é renderizado fora de toda fronteira que a Release declara, recebendo seu directory, subDirectory, syncWave, cascata de anotações e infra: por componente de lugar nenhum — então o build para e nomeia o componente em vez de emitir artefatos que a configuração das fronteiras nunca alcançou.
As duas regras dividem o terreno perguntando sobre o submódulo do componente, não apenas se ele tem um. Um componente de um submódulo que a Release não posicionou em lugar nenhum fica a cargo da regra de submódulos, que relata aquele único erro de autoria uma vez na entrada aggregates: em vez de uma vez por componente que o módulo contém. Um componente de um submódulo que a Release posicionou em parte pertence a esta regra, porque a regra de submódulos lê esse módulo como posicionado e não diz nada sobre ele — então cada componente que a fronteira não nomeou é relatado aqui, em sua própria chave dentro do documento que o declara. Posicionar um submódulo em parte, portanto, nomeia exatamente o que você pretendia nomear, e informa você sobre cada componente que você não nomeou.
E uma entrada de fronteira que nomeia um componente que o Aggregate implantado não contém interrompe o build. As duas regras acima leem o posicionamento do lado do componente — algo o posicionou? Esta o lê do lado da Release: o nome é resolvido? Uma entrada que não é resolvida para nada não posiciona nada, de modo que seu subDirectory, suas anotações, seu infra: por componente e seus uses: configuram um componente que não existe, e o build para em vez de emitir uma implantação que a entrada nunca alcançou. As duas grafias são verificadas: um nome em components: de uma fronteira é lido como o id que o componente tem quando a composição está concluída, e um nome em components: de uma entrada de roteamento é lido como o nome local que ele tem dentro daquele submódulo. O diagnóstico relata o id que a entrada endereçou, que na grafia roteada não é o nome no arquivo — o arquivo escreve a metade local e o submódulo fornece seu prefixo.
Um nome é recusado por não ser resolvido para nada, e nunca por sua forma: um nome pontuado é comum, porque um componente um módulo abaixo carrega o prefixo desse módulo. Um componente cujo interruptor active: é resolvido como false continua nomeável — desativar um componente não exige editar a Release que o configura.
Um subsistema não contribui com nada para o caminho qualificado, então uma fronteira endereça um componente pelo seu nome simples, seja qual for a forma como o Aggregate o agrupa. Somente a composição de submódulos qualifica um id. Um componente do Aggregate implantado é store, quer o autor o tenha escrito no nível superior, quer dentro de um subsistema chamado data; um componente um módulo abaixo é data.store, e ali data é o prefixo do módulo, e não de algum subsistema. Assim, uma entrada de fronteira escrita data.store para um componente que está em um subsistema chamado data não endereça nada: a própria entrada interrompe o build pela regra acima, e o componente a que ela se destinava também não alcança nenhuma fronteira. Corrigir a entrada para store resolve as duas coisas.
Posicionar um submódulo exige, portanto, boundaries:. A forma de escopo único não tem superfície de roteamento — aggregates: é uma chave de uma fronteira, não de spec: — e o mapa components: de nível superior aceita apenas nomes não qualificados, então uma Release que implanta um Aggregate que importa submódulos declara boundaries:.
Roteamento recursivo. aggregates: é recursivo — cada entrada sob o aggregates: de uma fronteira pode ela própria declarar um mapa aggregates: aninhado para uma composição de módulos profundamente aninhada.
Bloco de roteamento por agregado. Uma entrada de roteamento aceita exatamente duas chaves e nada mais: components:, para configurar componentes individuais daquele submódulo, e um aggregates: aninhado para módulos aninhados mais profundamente. annotations: pertence à fronteira, e o infra: por componente pertence a uma entrada sob o próprio components: da entrada de roteamento.
Dentro de uma entrada de roteamento, um componente é identificado pelo nome que tem dentro do seu submódulo — consumer, não data.consumer — porque esse é o único nome que ele tem ali. O caminho pontuado qualificado é a forma como o mapa components: de uma fronteira endereça o mesmo componente; as duas grafias não são intercambiáveis, e uma entrada de roteamento rejeita uma chave pontuada.
boundaries: eu-prod: directory: "deploy/eu-prod" annotations: aggrega.ai/namespace: "finance-zone" aggregates: finance: components: ledger: # the component's name inside the finance module infra: replicas: 3 aggregates: reporting: {} # a module nested inside financeOs componentes e as Features próprios do subagregado não são declarados novamente na Release — a Release os roteia em vez de repeti-los, e só nomeia um deles para configurá-lo.
Sequenciamento temporal — syncWave por fronteira
Cada fronteira na Release declara opcionalmente um campo inteiro syncWave:, que dá ao operador controle explícito sobre a ordem de implantação sem mexer no Aggregate do desenvolvedor. O número da onda é uma propriedade da própria fronteira; cada componente contido na subárvore da fronteira herda o valor de onda da sua fronteira quando os artefatos são emitidos.
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: prod-release version: 1.0.0 environment: productionspec: aggregate: my-app manifest: prod-manifest boundaries: infra: directory: "deploy/infra" syncWave: 0 components: core-vpc: {} postgres-db: {} migrations: directory: "deploy/migrations" syncWave: 1 components: db-migration-task: {} apps: directory: "deploy/apps" syncWave: 2 components: web-server: {} ai-agent: {}Semântica do valor de onda. syncWave: é um inteiro com sinal (positivo, zero ou negativo). O padrão quando o campo é omitido é 0. Os valores de onda não são herdados de uma fronteira pai — cada fronteira que quer uma onda diferente do padrão declara uma explicitamente. Components não podem substituir a onda da sua fronteira (a onda é uma propriedade da unidade espacial, não de componentes individuais).
Emissão por provedor. O compilador emite o valor de onda da fronteira na saída renderizada, na forma nativa do provedor. Três das formas são detalhadas abaixo; o que a onda faz em cada provedor da biblioteca padrão, incluindo terraform, está tabelado em providers/reference-matrix.md “O que a syncWave de uma fronteira faz em cada provedor”.
- Kubernetes (provedor helm / helm-chart). Onde a onda não é
0, cada recurso Kubernetes que o provedor helm renderiza para a fronteira carrega a anotação padrão do GitOpsargocd.argoproj.io/sync-wave: "<N>"; os hooks do Helm carregam adicionalmente a anotaçãohelm.sh/hook-weight: "<N>", para que o mesmo valor de onda conduza a própria ordenação pre/post-install do Helm. O ArgoCD lê a anotação sync-wave e o Helm lê o peso de um hook, e cada um ordena a aplicação dos recursos de acordo. O provedor helm-chart copia os templates de um chart de origem como o autor os escreveu, então os recursos próprios de um subchart carregam a onda apenas onde esses templates a escrevem; um artefato carregado por$import:que ele adiciona carregaargocd.argoproj.io/sync-wavee nenhumhelm.sh/hook-weight(vejaproviders/helm-chart.md). - Compose. Cada serviço no arquivo compose em que uma fronteira é renderizada espera, por meio de
depends_on, pelos serviços da onda imediatamente anterior que contribuíram para o mesmo arquivo — condicionado à saúde do destino onde o destino declara umhealthcheck, e ao seu início onde não declara. Assim, a onda ordena os serviços de um arquivo e nada fora dele: fronteiras que são renderizadas em arquivosdocker-compose.yamlseparados são projetos compose separados, e sequenciá-los é responsabilidade do operador. As arestasuses:continuam a expressar a ordenação por aresta junto com a onda. Vejaproviders/compose.md. - CloudFormation. Cada recurso no template de stack montado depende, por meio de
DependsOn, dos recursos da onda imediatamente anterior que contribuíram para o mesmo stack — então a onda fixa a ordem em que os recursos são criados e, inversamente, a ordem em que são excluídos. Não é uma ordenação por prontidão: um template de stack não tem noção de um recurso estar apto a atender. ODependsOnpróprio de um fragmento é estendido em vez de substituído. Os Components que são montados em um stack diferente ficam fora de alcance, e sequenciar dois stacks é responsabilidade do operador. Vejaproviders/cloudformation.md.
Unidade de autoria de ondas vs. unidade implantável. A fronteira é a unidade em que as ondas são escritas. A unidade implantável é o caminho de montagem para o qual os componentes são emitidos — por padrão 1:1 com a fronteira, mas duas fronteiras irmãs que compartilham um directory: se fundem em uma única saída montada (um Chart.yaml, um docker-compose.yaml). Quando isso acontece, a saída montada pode conter recursos de várias ondas; uma Application do ArgoCD que a lê ordena, dentro da Application, cada recurso pela anotação sync-wave que esse recurso carrega — no helm, cada recurso renderizado para uma onda diferente de zero, e no helm-chart, apenas um artefato carregado por $import:, enquanto os templates próprios de um subchart carregam o que o autor deles escreveu. O sequenciamento entre Applications através de caminhos é responsabilidade da CI do operador.
Casos de uso. A ordenação por ondas importa sempre que a inicialização de uma fronteira depende da conclusão prévia de outra. Padrão canônico: uma fronteira infra na onda 0 (VPC + banco de dados), uma fronteira migrations na onda 1 (job de migração de schema) e uma fronteira apps na onda 2 (a aplicação que consome o schema migrado). Sem ondas explícitas, as três são implantadas simultaneamente e a aplicação entra em crash-loop enquanto espera a migração terminar.
Para o enquadramento arquitetural completo — o modelo de execução em DAG, a justificativa para colocar o sequenciamento temporal na Release em vez de no Aggregate, e a distinção entre unidade de autoria de ondas e unidade implantável — veja architecture/12-day-two-lifecycles.md §1.
Vinculação de Feature
A Release pode vincular Features tanto no escopo da fronteira (política ampla) quanto no escopo específico de um componente (direcionamento preciso), com a execução seguindo o modelo de cebola de 5 camadas definido em architecture/10-compilation-pipeline.md. As Features declaradas na Release contribuem com type, infra e uses; elas não podem declarar values (veja Restrições no nível do schema acima).
Uma Feature vinculada a uma fronteira é identificada por um nome de instância que você escolhe, e esse nome não pode ser . nem ... Em um provedor que dá a cada contribuidor um diretório próprio — terraform, em modules/, e helm-chart, em charts/ —, os arquivos de uma Feature no nível da fronteira são escritos em um diretório com o nome apenas da instância, e nenhum desses dois nomes é um diretório próprio: o build para, nomeando a Release, a fronteira e a instância. Um nome que apenas contém pontos, como audit.v2, é um nome comum.
features: é a única superfície de vinculação da Release, nos dois escopos — como é a do Aggregate. Uma credencial é uma Feature que carrega o rótulo feature.aggrega.ai/kind: secret, então uma credencial vinculada pelo operador é vinculada em features: como qualquer outra Feature, e nomeia seu segredo em infra exatamente como faz uma em uma conexão (veja Configuração de conexão por aresta) — em um componente que o Aggregate deixou sem nenhuma, ou como o dimensionamento de uma vinculação que o Aggregate declarou sem nomear um segredo. Não existe uma segunda palavra-chave de vinculação em nenhum escopo; um documento que declara uma é rejeitado no carregamento com um erro de envelope que nomeia a propriedade inesperada.
Uma funcionalidade vinculada a toda a fronteira pode carregar um bloco uses:, e esse bloco se projeta para cada componente roteado para a fronteira: cada componente ganha uma aresta de dependência para os destinos que a funcionalidade nomeia e recebe por injeção os provides desses destinos. Isso expressa uma dependência compartilhada uma única vez na fronteira — “todo componente desta fronteira se comunica com o cache / coletor / barramento de mensagens compartilhado” — em vez de repetir a mesma aresta uses: em cada componente. Uma vinculação de Feature no nível do subsistema no Aggregate projeta seu uses: da mesma forma nos componentes do subsistema. uses é uma declaração de ligação da topologia, não um valor, então é permitida na Release. A projeção é independente do escopo de execução da Feature vinculada: uma Feature cuja FeatureRecipe é renderizada uma vez por fronteira ainda projeta seu uses: por componente, enquanto o próprio recurso compartilhado é renderizado uma vez.
Uma funcionalidade vinculada a um único componente carrega o mesmo bloco uses: e liga a mesma aresta a partir desse único componente: o componente ganha uma aresta de dependência para cada destino nomeado, recebe por injeção os provides desses destinos, e a aresta registra a vinculação como sua origem exatamente como faz a forma para toda a fronteira. As duas são uma única declaração em duas amplitudes — vincule na fronteira para ligar cada componente dela, vincule em um componente para ligar esse componente — e a escolha entre elas é uma questão de alcance, nunca do que a ligação faz. Nenhuma das duas cria computação: o destino precisa já nomear um componente que o Aggregate declarou, e um que não o faça interrompe o build. Uma conexão traçada por uma Feature não carrega vinculações próprias: sua entrada aceita target e inject, e uma chave features: ali é recusada quando a Release é carregada.
boundaries: cluster: directory: ./dist/cluster components: api: features: shared_backend: type: core/shared-backend uses: backend: primary: target: db # a component of the assembled graph inject: env: - in: DB_HOST from: host # db's `host` provides reaches api as DB_HOST db: {}Como um destino é escrito. Um destino de aresta nomeia um componente do grafo montado, então é escrito com o caminho pontuado qualificado — data.store, não store — sempre que o destino pertence a um submódulo roteado. Isso vale mesmo onde a própria vinculação fica sob uma entrada de roteamento, cujas chaves components: são locais ao módulo: a chave diz em qual componente a vinculação está e o destino diz qual componente a aresta alcança, e apenas o segundo é um nome válido em todo o grafo. Um destino escrito com um nome local ao módulo não corresponde a nenhum componente e interrompe o build com o mesmo diagnóstico que qualquer aresta pendente produz.
Release composta e herança com extends:
Uma Release pode declarar spec.extends: apontando para uma Release base cuja superfície de autoria ela herda.
A referência é um caminho para um arquivo ao lado da Release que a declara — ./base-release.yaml, ou ../shared/base-release.yaml. Uma Release pertence ao lado da implantação e não é indexada no catálogo, então uma referência extends: nunca é resolvida pelo catálogo. O caminho relativo é a única forma que ela aceita: uma referência escrita como coordenada de registro é recusada, assim como um nome simples, cada uma com a forma de caminho relativo indicada no diagnóstico. O extends: de um Manifest é o vizinho próximo que se lê de outra forma — ele aceita um caminho relativo ou o metadata.name simples de um Manifest ao lado da Release —, então as duas formas não são intercambiáveis, e um nome simples que seria resolvido em um Manifest não é resolvido aqui. Cada elo de uma cadeia é lido da mesma forma: uma Release pai mantida em outro diretório nomeia a sua própria Release pai por um caminho ao lado de si mesma, onde quer que esteja a Release que você nomeou, exatamente como o $import: dos seus parâmetros é resolvido ao lado dela. O caminho deve levar a uma Release dentro do workspace, como todo caminho que uma Release escreve deve levar — ou, para uma Release nomeada fora do workspace, dentro do diretório que contém essa Release, ao qual cada elo da sua cadeia está sujeito: um caminho que sai subindo, ou que um elo leva para fora, é recusado antes que o arquivo que ele nomeia seja lido.
O compilador segue a cadeia quando a Release é carregada — recusando uma cadeia que retorna a um arquivo já presente nela, uma que ultrapassa o limite de profundidade e uma referência que não nomeia nada — e então reduz a cadeia a uma única Release resolvida.
O que você herda, você pode substituir chave por chave. O seu valor prevalece, até o fim, até chegar a um valor que é uma única coisa indivisível — um escalar, uma lista, um template — que você aceita ou substitui por inteiro. Você remove algo herdado escrevendo-o como null. Essa é a mesma regra que seguem um Component, uma Feature e um Manifest que estendem, então um autor que conheceu um conheceu todos.
Aplicado a uma Release: boundaries são compostos por nome de fronteira e uma fronteira por chave, components por nome de componente, infra em profundidade, features por nome de instância e depois por pilar; os uses de um componente por socket e depois por conexão, em que um target escrito pelo filho substitui o herdado, o infra da conexão é composto chave por chave, e as suas features são compostas por slot e depois por pilar pela mesma regra que seguem as features do próprio componente; directory, subDirectory, syncWave e os ponteiros para o Aggregate e o Manifest são escalares que substituem.
Duas coisas não são transmitidas:
- Identidade e proveniência. Nenhum campo
metadataé herdado.metadata.environmenté o que se deve conhecer: ele é obrigatório em toda Release e é próprio de cada Release por natureza, então um filho renderiza com o seu próprio ambiente nos seus rótulos de proveniência, e não com o do seu pai. - O ponteiro para o Aggregate é herdado, e não sobrescrevível. O filho não pode declarar
aggregate:— o esquema recusaextends:eaggregate:em um mesmo documento —, então um filho implanta a mesma intenção do desenvolvedor que a sua base.
O filho pode omitir manifest:, herdando o da sua base, ou sobrescrevê-lo para o Late Binding.
Uma única forma de roteamento ao longo da cadeia. boundaries: e components: são mutuamente exclusivos dentro de uma única Release, e isso também vale ao longo de uma cadeia: uma base que declara fronteiras nomeadas junto com um filho que declara componentes de nível superior é recusada, e o diagnóstico nomeia os dois arquivos e as duas chaves. Escolha uma forma de roteamento e use-a até o fim.
O padrão de ponte para desenvolvimento local. O caso de uso canônico é um desenvolvedor executando localmente o Aggregate de produção da sua equipe sem fazer fork do Aggregate nem duplicar a topologia de fronteiras. A equipe publica uma Release de produção; uma Release local a estende com extends: e sobrescreve apenas o ponteiro para o Manifest, trocando Recipes voltadas para a nuvem por equivalentes locais:
# production Release (committed; the source of truth for prod deployments)apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: prod-release environment: production version: "1.0.0"spec: aggregate: my-app manifest: prod-manifest parameters: region: us-east-1 db_size: 100Gi out_dir: prod boundaries: prod: # A directory is a TEMPLATE, not a fixed path. Writing it against a # parameter is what lets a child render somewhere else without # restating the boundary topology. directory: deploy/{{ .parameters.out_dir }} components: api: { infra: { replicas: 5 } } db: {}
---# Local Release (developer-side; inherits everything, swaps the Manifest)apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: local-release environment: local version: "1.0.0"spec: extends: ./prod-release.yaml manifest: local-manifest # surgically overrides for local parameters: region: dev-local db_size: 1Gi out_dir: local # the inherited directory resolves here insteadlocal-release herda da sua base a topologia de fronteiras, as vinculações de Feature e as sobrescritas de componentes; o desenvolvedor mantém um único local-release.yaml e executa aggrega build --release local-release.yaml sem nenhuma configuração de produção duplicada.
Escreva directory: em função de um parâmetro. Como um diretório é herdado como qualquer outro escalar, um filho que herda um diretório sem nenhuma variável de template renderiza no mesmo caminho em que a sua base renderiza, e nenhuma opção de linha de comando o redireciona. Isso é legítimo quando é o que você pretendia — trocar apenas as Recipes para comparar a saída delas, por exemplo —, então o build informa isso e continua em vez de recusar. Escrever o diretório em função de um parâmetro, como acima, mantém a topologia em um só lugar e ainda envia a saída de cada Release para um lugar próprio.
Camadas de parâmetros em vários arquivos. A herança de Release é o lugar das camadas de parâmetros em vários arquivos. Uma Release base fornece o conjunto comum de parâmetros; os filhos por ambiente estendem a base com extends: e sobrescrevem os slots que diferem:
# base-release.yaml — common parametersspec: aggregate: my-app parameters: timeout_seconds: 30 feature_flags: { dark_mode: true }
---# prod-release.yamlspec: extends: ./base-release.yaml manifest: prod-manifest parameters: feature_flags: { dark_mode: false } # override one nested key
---# staging-release.yamlspec: extends: ./base-release.yaml manifest: staging-manifestCada filho vê os parâmetros herdados da sua base mesclados com os seus. Parâmetros com valor de mapa são mesclados em profundidade, com a chave do filho prevalecendo; parâmetros com valor escalar são substituídos pelo filho; uma chave que um filho escreve como null é removida em vez de ser definida como nada.
Uma base pode importar os seus parâmetros e um filho ainda pode sobrescrever chaves individuais. Os dois modos de autoria descritos acima em parameters: — inline, ou um único $import: — são uma regra sobre um documento, não sobre uma cadeia: cada Release ao longo da cadeia declara um modo ou o outro, e a importação de cada uma é resolvida em relação ao diretório que contém essa Release antes que a cadeia seja reduzida. Assim, uma base que importa um arquivo compartilhado e um filho que escreve algumas chaves inline são compostos por chave, exatamente como dois blocos inline seriam:
# base-release.yaml — parameters arrive from a shared file beside itspec: aggregate: my-app parameters: $import: ./shared-params.yaml # tier: prod, region: eu
---# local-release.yaml — overrides one key, inherits the restspec: extends: ./base-release.yaml manifest: local-manifest parameters: tier: local # region stays eu, from the imported fileModos de erro. Cadeias extends: cíclicas, ponteiros para pais ausentes e declarações aggregate: do lado do filho interrompem o carregamento do workspace com diagnósticos explícitos que nomeiam a Release infratora e a violação no nível do esquema. Consulte errors/fatal-halts.md para o formato das mensagens de cada erro.