Release
O papel conceptual da entidade Release (Domínio 4 — o encaminhador de implementação que associa um Aggregate a um Manifest e mapeia componentes para fronteiras físicas) encontra-se em architecture/04-entity-taxonomy.md. O mecanismo de sequenciação temporal (syncWave por fronteira), o Dynamic Addressing Polyfill e o padrão Parameter Hoisting encontram-se em architecture/12-day-two-lifecycles.md. Esta página cobre a superfície de autoria da Release.
O papel da Release
A Release associa um aggregate a um manifest e mapeia componentes para fronteiras de implementação físicas (por exemplo, aws-eks-production). É o ponto de entrada único da compilação: aggrega build --release release.yaml.
A Release cumpre o contrato abstrato do aggregate injetando realidades físicas estritamente no bloco parameters, e injeta o dimensionamento físico (como CPUs ou portas) através do espaço de nomes paralelo infra.
Todas as Releases declaram um campo manifest: que indica o seu Manifest (a menos que a Release use extends:, que herda o ponteiro de manifest da mãe). A CLI aggrega build lê este campo diretamente; não existe nenhuma flag de CLI --manifest, pelo que a especificação de dependências permanece no Git, com commit ao lado da própria Release, tornando o histórico de implementações auditável através do próprio histórico Git da Release.
Os campos aggregate: e manifest: são resolvidos por identidade ou por ficheiro com caminho relativo, da mesma forma que o resto da linguagem resolve referências — nunca como um radical de nome de ficheiro relativo à release. Um valor ./ ou ../ é um ficheiro local explícito, lido diretamente em relação à Release. Um token simples é uma identidade — o metadata.name da entidade referenciada. Uma identidade manifest: é resolvida percorrendo o próprio diretório da Release (um Manifest é configuração de operador do lado da implementação, pelo que não tem nível de catálogo nem de registo). Uma identidade aggregate: é resolvida através da cascata completa — o diretório da Release, depois o catálogo, depois o registo — pelo que uma Release pode indicar um Aggregate publicado por identidade e o mesmo módulo publicado é resolvido quer seja o spec.aggregate de nível superior de uma Release, quer seja um subaggregate dentro de outro Aggregate. Este modelo de identidade ou caminho permite que um Aggregate partilhado sirva de base a muitas variantes de Release sem acoplar a referência a um nome de ficheiro, e que um Aggregate publicado seja implementado diretamente pelo nome.
Um caminho permanece dentro do workspace. Um valor ./ ou ../ indica um ficheiro que o workspace contém, tal como todos os outros caminhos que uma Release escreve — o seu extends: e um $import: de parameters, abaixo. Um que, tal como está escrito, saia do workspace, ou que uma ligação simbólica no caminho leve para fora dele, é recusado antes de se ler qualquer coisa do ficheiro que indica. Para implementar um Aggregate mantido fora do workspace, indique-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 indicada por um extends: e um ficheiro de parameters são lidos ao lado da Release e nunca procurados pelo nome, pelo que são mantidos dentro do workspace. Uma Release indicada na linha de comandos, ou pela configuração do workspace, fora do workspace é uma raiz própria: todos os caminhos que escreve — e todos os caminhos escritos por uma Release a que a sua cadeia extends: conduz — têm de levar a um ficheiro dentro do diretório que contém essa Release, e um que saia desse diretório, ou que uma ligação leve para fora dele, é recusado da mesma forma. Mantenha o que essa Release indica ao lado dela, ou compile-a no workspace que contém ambos. Consulte errors/fatal-halts.md §«A reference to another file leads out of the directory it must stay inside (Uma referência a outro ficheiro sai do diretório onde tem de permanecer)».
A Release determina o destino dos artefactos compilados; o despacho para providers pertence ao Manifest para que a Release aponta (consulte Manifest vs. Release: separação de responsabilidades para a divisão de papéis).
Metadados do ambiente
Todos os blocos de metadados de uma Release aceitam um campo environment: — uma string livre que identifica o ambiente em que a Release é implementada (valores típicos: production, staging, dev). O campo é informativo: não tem enumeração, nem padrão ao nível do esquema, nem validação entre entidades para além de type: string. O compilador emite o seu valor como a etiqueta aggrega.ai/environment em todos os manifestos Kubernetes que o fornecedor helm renderiza, a par do resto do conjunto de etiquetas de proveniência da Aggrega — tal como está escrito quando é um valor de etiqueta Kubernetes válido e, caso contrário, reescrito num valor válido, com o valor exato transportado na anotação aggrega.ai/environment (assim, eu/prod recebe a etiqueta eu-prod); o fornecedor helm-chart acrescenta as mesmas etiquetas a cada artefacto carregado através de $import: que coloca num sub-chart, enquanto os templates próprios do sub-chart contêm o que o seu autor escreveu. O fornecedor compose aplica o mesmo valor como a etiqueta aggrega.ai/environment a cada serviço que emite.
Cinco padrões práticos orientam a escrita de environment::
-
Imputação de custos OTel/FinOps. Os painéis de custos de cloud (AWS Cost Explorer, Datadog Cloud Cost Management, CloudHealth) filtram pods Kubernetes por etiqueta de ambiente. A etiqueta
aggrega.ai/environment: productionpassa para as etiquetas dos pods através da injeção de etiquetas do provider Helm; os relatórios de custos agrupam a despesa poraggrega.ai/environmentsem etiquetagem manual por recurso. -
Filtragem de traces e logs OTel. Os painéis de observabilidade (Datadog, New Relic, Honeycomb, Grafana Tempo) filtram a telemetria por etiqueta de ambiente.
aggrega.ai/environment: stagingpermite aos operadores limitar consultas de logs e pesquisas de traces a staging sem filtrar por convenções de namespace ou nomes de charts — uma única etiqueta canónica em toda a superfície renderizada. -
Segmentação por operadores Kubernetes. Os controladores GitOps (ArgoCD, Flux) e os operadores de políticas (Kyverno, OPA Gatekeeper) filtram por vezes recursos por etiqueta de ambiente para políticas específicas do ambiente (por exemplo, «os recursos só de produção exigem uma etiqueta de origem de imagem aprovada»). A etiqueta
aggrega.ai/environmentfornece um seletor estável, distinto das convenções de namespace ou dos padrões de nomenclatura. -
Diferenciação de produção multirregião. Uma equipa que execute uma Release
production-us-easta par de uma Releaseproduction-eu-west— ambas commetadata.environment: production— obtém a mesma etiquetaaggrega.ai/environment: productionem todas as regiões. Combinada com uma etiqueta de região separada, isto permite agregar custos entre regiões («despesa total de produção») e detalhar por região. -
Âmbito de conformidade. A recolha de evidências SOC 2, PCI e HIPAA tem âmbito por ambiente (auditoria só de produção, etc.). A etiqueta
aggrega.ai/environmenté consumida por ferramentas de recolha de evidências de conformidade (Vanta, Drata) para filtrar recursos por âmbito de auditoria.
O esquema exige environment: em cada Release; o valor é informativo, e o compilador só o lê para escrever a etiqueta aggrega.ai/environment.
Restrições ao nível do esquema
Duas garantias estruturais protegem o Aggregate como fonte única de verdade:
values:é proibido. Para proteger o Aggregate como fonte única de 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 estende-se às arestasuses: uma entradausespor aresta de uma Release contéminfrae os anexos que escreve na ligação, e esses contêm tambéminfra— nuncavalues(os values por aresta destinados ao programador, e os values de um anexo numa ligação, permanecem no Aggregate). A variação por ambiente dos values destinados ao programador flui através do Parameter Hoisting: o programador expõe um campo tipadoparameters.*no Aggregate, o templatevaluesdo Component referencia-o, e a Release cumpre o parâmetro para o seu ambiente. Consulte architecture/06-data-taxonomy-and-composition.md §8 Restrição 4 para a proibição ao nível do esquema declarada explicitamente. A superfície de arestasusesda Release — o que pode configurar e ligar — está documentada em Configuração de ligações por aresta abaixo.extends+aggregate:é rejeitado. Para evitar Releases «que alteram o aggregate» impossíveis de rastrear, quando uma Release usaextends, declarar um ponteiroaggregateé rejeitado pelo esquema da Release. A release filha tem de mapear exatamente para a mesma intenção do programador que a sua mãe. Omanifest, no entanto, torna-se opcional, desbloqueando o «Late Binding» — permitindo ao operador herdar toda a topologia física, mas substituir cirurgicamente o Manifest.
O bloco parameters:
Uma Release cumpre o contrato de parâmetros tipado 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 cumprimento 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 espaço recusa (E0164, parameter-contract-violation). Os parâmetros declarados com um default: recebem o valor predefinido quando a Release omite o espaço; o contrato tipado é o único vocabulário de autoria.
Dois modos de autoria — despacho pela forma do conteúdo. parameters: aceita um mapa YAML inline (Modo 1, mostrado acima) ou uma única chave $import: que aponta para um ficheiro 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, seja qual for o local a partir do qual um comando é executado, pelo que a linha de comandos e o editor leem o mesmo ficheiro; um caminho absoluto indica o seu próprio local, e qualquer um deles tem de levar a um ficheiro 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 neste local, e só pode ser importado um único ficheiro. A sobreposição de parâmetros de vários ficheiros é da competência das cadeias extends: de Releases: a Release mãe fornece um conjunto base de parâmetros e a filha estende-o e substitui-o por ambiente. Consulte Release composta / herança extends: mais abaixo para o padrão.
Fronteira entre parameters e infra. Os parâmetros transportam a intenção cognitiva do programador, expressa como espaços tipados que o Aggregate declara; a Release cumpre-os. infra: na Release transporta o dimensionamento físico do operador (número de réplicas, limites de CPU/memória, classes de armazenamento) associado a componentes específicos ou a anexos de Feature. Os parâmetros fluem para os templates values: do Aggregate através de .parameters.X; infra: flui para o template valuesMapping: da Recipe através de .infra.X. Consulte 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 âmbito predefinido
Uma Release agrupa componentes em fronteiras — unidades de implementação físicas, cada uma com o seu próprio diretório de saída e cascata de anotações. O caso de fronteira única é o mais comum, pelo que não exige cerimónia.
Âmbito único (o predefinido). Escreva os componentes diretamente em spec.components: e omita o bloco boundaries:. O compilador agrupa-os numa fronteira default sintetizada cuja saída é plana — os artefactos ficam diretamente em dist/ (por provider, através do valor predefinido seguro de subDirectory abaixo: dist/compose/, dist/helm/, …), sem nenhum segmento de nome de fronteira no caminho. Esta é a implementação mais simples: aggrega build sobre um destino Compose plano ou de cluster único sem indicar fronteiras.
spec: aggregate: aggregate manifest: manifest components: db: infra: engine_version: "11.4" web: infra: port: 8080Vários âmbitos. Quando uma Release abrange mais do que um agrupamento físico — clusters, regiões ou sync waves separados — declare fronteiras com nome em boundaries:. Cada fronteira tem o seu próprio directory:, cascata de anotações e syncWave:, e os componentes são endereçados dentro da sua fronteira.
Exclusividade 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 declare ambos é interrompido no carregamento com um erro de envelope. A superfície components de nível superior tem a mesma forma de operador por componente que os components de uma fronteira (infra:, annotations:, uses:).
Uma fronteira declarada com o nome default. A saída plana é uma propriedade do predefinido sintetizado, não do nome. Uma Release que declare explicitamente uma fronteira chamada default em boundaries: tem uma fronteira com nome normal: a sua saída segue o seu directory: (por predefinição dist/boundaries/default/), exatamente como qualquer outra fronteira declarada.
Consulte architecture/06-data-taxonomy-and-composition.md §7 para o padrão de âmbito predefinido.
Segregação espacial e caminhos de saída
Cada fronteira declara um directory de saída físico para os seus artefactos compilados; os componentes dentro de uma fronteira podem substituí-lo através de um subDirectory por componente. O compilador calcula o caminho final do artefacto juntando-os, na forma separada por barras em todas as plataformas: Final_Path = Clean(Join(Evaluated(directory), Evaluated(subDirectory))).
- Um diretório, uma grafia. O caminho avaliado é normalizado uma vez, pelo que
out/a,out//a,./out/aeout/a/são um único diretório. As fronteiras cujos caminhos normalizados correspondem ao mesmo diretório e que são renderizadas pelo mesmo provider são montadas em conjunto, exatamente como as fronteiras escritas com caminhos idênticos. - O caminho permanece abaixo da raiz de saída. Um caminho que sai da raiz de saída (
..,../escape,a/../..), um caminho absoluto, ou um que não indique nenhum diretório — vazio, ou que, normalizado, corresponda à própria raiz de saída — para a compilação antes de qualquer escrita. A mensagem indica a Release, a fronteira, o campo com o problema (directory:ousubDirectory:) e o valor para o qual foi avaliado, uma vez que esse valor é muitas vezes o resultado de um template. - Valor predefinido seguro. Se
subDirectoryfor omitido ou estiver vazio, o compilador aplica automaticamentesubDirectory: "{{ .capability }}"— os artefactos de cada capacidade de renderização (Helm, Helm-chart, Compose, Terraform, CloudFormation) ficam na sua própria subpasta, evitando colisões de artefactos mistos nas ferramentas de CI/CD a jusante. UmsubDirectory: ""escrito explicitamente é lido exatamente como um omitido, pelo que também recebe este valor predefinido. - Substituição plana. Para desativar totalmente os subdiretórios (todos os artefactos diretamente em
directory), definasubDirectory: ".". Um templatesubDirectoryque seja 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 }}(apenas 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. Consulte variáveis de template de caminho para a matriz por contexto e as regras de cascata da fronteira mãe.
As anotações de fronteira propagam-se em cascata para baixo, para todos os componentes contidos; infra permanece estritamente localizado no componente a que se destina. O mapa recursivo boundaries permite aninhamento arbitrário (fronteira dentro de fronteira dentro de fronteira), mantendo-se os invariantes de cascata de anotações e de infra local em todos os níveis.
Exemplo completo:
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 por este mecanismo surgem nos templates de Recipe a jusante através de .context.annotations.release; consulte Autoria de Recipes e a matriz de expansão de templates para saber como os renderizadores as consomem.
Valores de anotação estruturados. Quando uma associação do Manifest declara vários caminhos de encaminhamento do pilar infra para uma chave de anotação, o valor da anotação do lado da Release pode ser um objeto estruturado que contém valores para vários campos do esquema da Feature numa só 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 propagam-se em cascata com deep merge por subchave; as subchaves de nível mais próximo substituem as subchaves do nível pai. Um null por subchave exclui uma subchave enquanto as subchaves irmãs se mantêm. O lado da Release ativa apenas as subchaves cujo pilar no mapa da associação é infra; as subchaves encaminhadas para values pertencem às anotações do lado do Aggregate. Para a explicação completa dos valores estruturados — composição entre lados, validação de tipo por subchave, a disciplina de predefinições flexíveis — consulte providers/well-known-annotations.md §«Valores de anotação estruturados».
Anotações bem conhecidas. Para além das chaves ad hoc, a biblioteca standard da Aggrega define um conjunto de anotações bem conhecidas nos espaços de nomes aggrega.ai/ e feature.aggrega.ai/, agrupadas nas categorias de colocação, rede, segurança e observabilidade. Os autores que adicionem anotações a uma fronteira de Release devem consultar providers/well-known-annotations.md para a matriz completa e as regras de consumo por provider — a página documenta que providers aplicam cada chave bem conhecida e que comportamento produzem quando a chave está presente.
Configuração de ligações por aresta
Um componente de fronteira pode conter um bloco uses: que configura ou liga as arestas da topologia dentro dos sockets que o usesSchema do catálogo do Component declara. Esta é a superfície por ligação do operador, limitada para que o programador mantenha a titularidade da arquitetura que escreveu:
- Configurar uma aresta existente. Defina
infrapor aresta numa aresta que o programador já declarou. A entrada indica o alias do programador e forneceinfra; indica o mesmo destino que o programador ligou ou omite o destino. Oinfraé validado contra oinfraSchemado socket. - Ligar um socket não associado. Crie uma aresta para um socket que o
usesSchemado Component declara, mas que o programador deixou por ligar, apontando para um componente existente. A aresta criada também pode conterinfrapor aresta. - Anexar numa ligação. Coloque anexos sob o
features:da entrada, indexados por um slot que o socket declara no seufeaturesSchema— os mesmos slots que a entrada de ligação do programador preenche. Cada um contémtype, umadescriptionopcional einfra, e nuncavalues. Sob um slot que o programador já preencheu na mesma ligação, a entrada dimensiona esse anexo: escreva apenasinfra, uma vez que o tipo e os values vêm do Aggregate (umtypeescrito aqui tem de coincidir com o do Aggregate, caso contrário a compilação é interrompida nesta entrada, indicando ambos). Sob um slot que o programador deixou vazio, o anexo pertence à própria Release etypeé obrigatório. Em qualquer dos casos, o preenchimento está sujeito aoselectordo slot e conta para um slotrequired, exatamente como o do programador.
A superfície é de criação, não de redirecionamento: uma Release pode adicionar uma aresta a um socket não associado, mas não pode redirecionar uma aresta que o programador já declarou. Uma entrada por aresta que indique um destino diferente do da aresta do programador interrompe a compilação; uma entrada que indique o mesmo destino (ou o omita) configura essa aresta. A Release também não pode declarar values numa aresta nem num anexo que escreva aí (os values destinados ao programador 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 destes casos é uma interrupção fatal. O mesmo acontece com uma entrada que define infra ou features numa ligação que não existe depois de todas as arestas estarem traçadas, a menos que o componente consumidor esteja desativado com active: false. Consulte errors/fatal-halts.md §«Ao construir a topologia».
Mais três interrupções mantêm os anexos de uma ligação na sua ligação:
- Um nome para o qual o socket não declara nenhum slot interrompe a compilação, exatamente como acontece na entrada de ligação do Aggregate, nesta entrada da Release, indicando os slots que o socket declara e qualquer um deles de que o nome esteja a uma edição de distância.
- Um anexo que só a Release cria, escrito sem
type, interrompe a compilação na entrada de ligação, indicando o slot. Um anexo criado pela Release não contémvalues, pelo que se adequa a uma Feature cujosvaluesnão exigem nada; uma cujo esquema exija um valor é interrompida na mesma entrada pelo valor em falta. As Features de credenciais da biblioteca standard que contêm um localizador do chamador não exigem nenhum emvalues: cada uma aceita-o também eminfra(ver abaixo). - O nome composto escrito em qualquer lado que não a ligação interrompe a compilação. Um anexo de ligação torna-se um anexo do componente consumidor com o nome
<alias>.<slot>(consulte a entrada de ligação do Aggregate), e tanto as chavesfeatures:próprias de uma entrada de componente como as de uma fronteira admitem um ponto. Uma entrada de componente que escreva esse nome, ou uma fronteira que o escreva de forma a chegar a um componente cuja ligação o contém — um componente colocado nessa fronteira ou numa aninhada nela, incluindo os de um submódulo encaminhado — interrompe a compilação indicando ambas as grafias, uma vez por cada componente a que chega. O slot de um socket é preenchido em cada ligação e nunca por um anexo propagado em cascata a partir de um âmbito 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 numa ligação que a Release liga indica o seu segredo em infra. Uma ligação que a Release liga não tem entrada no Aggregate, pelo que nada aí escreve os values da credencial, e a Release não escreve values em lado nenhum. Cada Feature de credenciais da biblioteca standard que contém um localizador do chamador — core/referenced-secret, core/referenced-secret-set, core/secret-value e core/secret-provided — aceita-o, portanto, em infra e também 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. Todas as realizações leem o pilar que o contém.
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 anexo. Um anexo que o contenha em ambos — nos values do Aggregate e no infra da Release para o mesmo slot — ou em nenhum é interrompido na asserção da própria Feature (E0033), indicando a Feature, o anexo e o componente, e dizendo qual dos dois casos se verificou. A regra pertence às entidades de catálogo dessas Features, não ao compilador, que avalia a sua asserção como avalia a de qualquer Feature. Os campos que não o localizador mantêm o seu pilar: key continua a ser uma folha de values, pelo que um anexo que só a Release cria lê a chave de dados predefinida da Feature, value. A proibição de values: mantém-se — o localizador do operador é infra.
core/secret-provided é a que não se adequa a uma ligação: publica o seu valor para que o bloco inject: do próprio anexo o entregue, e o anexo de uma ligação não contém nenhum bloco inject: em nenhum dos documentos, pelo que, numa ligação, nenhum bloco inject: o entrega. Use core/referenced-secret ou core/secret-value nesse caso.
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>; nunca aparece no contexto do componente de destino, pelo que a saída renderizada de um destino é invariante em relação aos consumidores que configuram arestas para ele. Um anexo numa ligação também fica no componente consumidor, como um dos seus anexos: o seu infra é fundido com os values do Aggregate para o mesmo slot, e a sua FeatureRecipe é renderizada contra ambos. A Recipe do componente consumidor lê-o sob a sua ligação, em .context.uses.<alias>.features.<slot>, e o seu Workload entrega-o indicando a ligação ao lado do slot — consulte Entregar uma credencial que uma ligação contém.
O campo aggregates: — encaminhar submódulos aninhados para fronteiras
Quando o Aggregate declara submódulos aninhados através de spec.aggregates:, a Release decide em que fronteira ficam os componentes de cada submódulo declarando aggregates: a par 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 subaggregate listado em Aggregate.spec.aggregates: em exatamente uma fronteira.
O encaminhamento coloca componentes. Todos os componentes de um submódulo encaminhado ficam na fronteira que o encaminha e recebem o directory, o subDirectory, o syncWave e a cascata de anotações dessa fronteira — o mesmo contexto que recebe um componente indicado diretamente em components:, incluindo a proveniência aggrega.ai/boundary-path marcada nos artefactos emitidos. Encaminhar um submódulo e endereçar cada um dos seus componentes pelo caminho qualificado com pontos com um corpo vazio produz, portanto, artefactos idênticos; o encaminhamento é a forma mais curta de o dizer, e a única forma de o dizer sem conhecer o conteúdo do submódulo.
Um componente pertence a exatamente uma fronteira, e a compilação é interrompida quando um documento coloca um duas vezes — o mesmo submódulo encaminhado para duas fronteiras, um submódulo encaminhado para uma fronteira enquanto um dos seus componentes é indicado noutra, ou um componente indicado tanto diretamente como através de uma entrada de encaminhamento. O diagnóstico indica ambos os locais, porque a escolha de qual manter cabe ao autor. Encaminhar um submódulo para uma fronteira e indicar um dos seus componentes nessa mesma fronteira não é um conflito: o encaminhamento coloca o componente e a entrada com nome configura-o.
Um subaggregate que a Release não coloca em lado nenhum interrompe a compilação. A colocação é lida em ambas as grafias, pelo que a compilação só é interrompida quando nenhuma chega ao submódulo: nenhuma fronteira o encaminha em aggregates:, e nenhuma fronteira indica qualquer dos seus componentes em components: pelo caminho qualificado com pontos. Qualquer das grafias, por si só, coloca-o, e um submódulo cujos componentes são todos indicados individualmente não precisa de nenhuma entrada de encaminhamento. A correção pertence ao bloco aggregates: do Aggregate que importou o submódulo — o Aggregate que a Release implementa, para um que importa diretamente, e o próprio documento do submódulo importador, para um aninhado. O diagnóstico indica essa entrada pela chave com que o documento importador a escreve, pelo que, para um submódulo aninhado, aparece como o nome local e não como o caminho com pontos.
Há dois casos que deliberadamente não interrompem a compilação. Um submódulo que não contribui com nenhum componente não tem nada a colocar. Um submódulo cujo interruptor active: é resolvido como false nunca foi composto, pelo que nenhum dos seus componentes existe para ser colocado.
A colocação parcial não interrompe a compilação segundo esta regra: um submódulo é colocado assim que qualquer um dos seus componentes chega a uma fronteira, pelo que indicar um deles satisfaz o submódulo. Daí não decorre que os restantes possam ficar de fora. Cada componente que a fronteira não indicou não é então colocado por nada, e a regra de componentes abaixo reporta-o na sua própria chave — pelo que um submódulo parcialmente colocado interrompe a compilação uma vez por cada componente que deixou para trás, e não no submódulo. As duas grafias que colocam um submódulo inteiro numa linha são a entrada de encaminhamento e a indicação de todos os componentes; qualquer coisa entre as duas coloca o que indica e nada mais.
Um componente que a Release não coloca em lado nenhum também interrompe a compilação, um nível abaixo. A regra acima pergunta se um submódulo chegou a uma fronteira; esta pergunta o mesmo sobre cada componente que a composição contém. Um componente chega a uma fronteira por ser indicado em components: dessa fronteira, ou por estar dentro de um submódulo que uma fronteira encaminha. Um que não chegue por nenhuma das vias é renderizado fora de todas as fronteiras que a Release declara, recebendo o seu directory, subDirectory, syncWave, cascata de anotações e infra: por componente de lado nenhum — pelo que a compilação para e indica o componente, em vez de emitir artefactos aos quais a configuração da fronteira nunca chegou.
As duas regras dividem o terreno perguntando pelo submódulo do componente, e não apenas se ele tem um. Um componente de um submódulo que a Release não colocou em lado nenhum fica a cargo da regra de submódulos, que reporta essa falha de autoria uma vez na entrada aggregates:, em vez de uma vez por cada componente que o módulo contém. Um componente de um submódulo que a Release colocou em parte pertence a esta regra, porque a regra de submódulos considera esse módulo colocado e não diz nada sobre ele — pelo que cada componente que a fronteira não indicou é reportado aqui, na sua própria chave dentro do documento que o declara. Colocar um submódulo em parte indica, portanto, exatamente o que se pretendia indicar, e informa sobre cada componente que não foi indicado.
E uma entrada de fronteira que indique um componente que o Aggregate implementado não contém interrompe a compilação. As duas regras acima leem a colocação do lado do componente — se algo o colocou. Esta lê-a do lado da Release: se o nome é resolvido. Uma entrada que não seja resolvida para nada não coloca nada, pelo que o seu subDirectory, as anotações, o infra: por componente e o uses: configuram um componente que não existe, e a compilação para em vez de emitir uma implementação à qual a entrada nunca chegou. Ambas as grafias são verificadas: um nome em components: de uma fronteira é lido como o id que o componente tem depois de a composição estar concluída, e um nome em components: de uma entrada de encaminhamento é lido como o nome local que tem dentro desse submódulo. O diagnóstico reporta o id que a entrada endereçou, que, na grafia encaminhada, não é o nome no ficheiro — o ficheiro escreve a metade local e o submódulo fornece o seu prefixo.
Um nome é recusado por não ser resolvido para nada e nunca pela sua forma: um nome com pontos é normal, porque um componente um módulo abaixo tem o prefixo desse módulo. Um componente cujo interruptor active: é resolvido como false continua a poder ser indicado — desativar um componente não exige editar a Release que o configura.
Um subsistema não contribui com nada para o caminho qualificado, pelo que uma fronteira endereça um componente pelo seu nome simples, seja qual for a forma como o Aggregate o agrupa. Apenas a composição de submódulos qualifica um id. Um componente do Aggregate implementado é 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 o data aí é o prefixo do módulo e não o de qualquer subsistema. Assim, uma entrada de fronteira escrita data.store para um componente que está num subsistema chamado data não endereça nada: a própria entrada interrompe a compilação segundo a regra acima, e o componente a que se destinava também não chega a nenhuma fronteira. Corrigir a entrada para store resolve ambos.
Colocar um submódulo exige, portanto, boundaries:. A forma de âmbito único não tem superfície de encaminhamento — aggregates: é uma chave de uma fronteira, não de spec: — e o mapa components: de nível superior aceita apenas nomes não qualificados, pelo que uma Release que implemente um Aggregate que importa submódulos declara boundaries:.
Encaminhamento recursivo. aggregates: é recursivo — cada entrada sob o aggregates: de uma fronteira pode ela própria declarar um mapa aggregates: aninhado para composição de módulos profundamente aninhados.
Bloco de encaminhamento por aggregate. Uma entrada de encaminhamento aceita exatamente duas chaves e nada mais: components:, para configurar componentes individuais desse submódulo, e um aggregates: aninhado para módulos aninhados mais abaixo. annotations: pertence à fronteira, e o infra: por componente pertence a uma entrada sob o próprio components: da entrada de encaminhamento.
Dentro de uma entrada de encaminhamento, um componente é indexado pelo nome que tem dentro do seu submódulo — consumer, não data.consumer — porque é o único nome que tem aí. O caminho qualificado com pontos é a forma como o próprio mapa components: de uma fronteira endereça o mesmo componente; as duas grafias não são intermutáveis, e uma entrada de encaminhamento rejeita uma chave com pontos.
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 subaggregate não são declarados de novo na Release — a Release encaminha-os em vez de os repetir, e só indica um para o configurar.
Sequenciação temporal — syncWave por fronteira
Cada fronteira da Release declara opcionalmente um campo inteiro syncWave:, dando ao operador controlo explícito sobre a ordem de implementação sem tocar no Aggregate do programador. O número da wave é uma propriedade da própria fronteira; todos os componentes contidos na subárvore da fronteira herdam o valor de wave da sua fronteira quando os artefactos 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 wave. syncWave: é um inteiro com sinal (positivo, zero ou negativo). O valor predefinido quando o campo é omitido é 0. Os valores de wave não são herdados de uma fronteira pai — cada fronteira que pretenda uma wave diferente da predefinida declara-a explicitamente. Os Components não podem substituir a wave da sua fronteira (a wave é uma propriedade da unidade espacial, não dos componentes individuais).
Emissão por provider. O compilador emite o valor de wave da fronteira na saída renderizada na forma nativa do provider. Três das formas são explicadas abaixo; o que a wave faz em todos os providers da biblioteca standard, incluindo terraform, está tabelado em providers/reference-matrix.md «O que o syncWave de uma fronteira faz em cada provider».
- Kubernetes (fornecedor helm / helm-chart). Quando a wave não é
0, todos os recursos Kubernetes que o fornecedor helm renderiza para a fronteira contêm a anotação habitual em GitOpsargocd.argoproj.io/sync-wave: "<N>"; os hooks Helm contêm adicionalmente a anotaçãohelm.sh/hook-weight: "<N>", para que o mesmo valor de wave oriente 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 em conformidade. O fornecedor helm-chart copia os templates de um chart de origem tal como o seu autor os escreveu, pelo que os recursos próprios de um sub-chart só contêm a wave onde esses templates a escrevem; um artefacto carregado por$import:que o fornecedor acrescenta contémargocd.argoproj.io/sync-wavee nenhumhelm.sh/hook-weight(verproviders/helm-chart.md). - Compose. Cada serviço do ficheiro compose para o qual uma fronteira é renderizada espera, através de
depends_on, pelos serviços da wave imediatamente anterior que contribuíram para o mesmo ficheiro — condicionado ao estado de saúde do destino quando o destino declara umhealthcheck, e ao seu arranque quando não declara. Assim, a wave ordena os serviços de um ficheiro e nada fora dele: as fronteiras renderizadas em ficheirosdocker-compose.yamlseparados são projetos compose separados, e a sua sequenciação cabe ao operador. As arestasuses:continuam a exprimir a ordenação por aresta a par da wave. Consulteproviders/compose.md. - CloudFormation. Cada recurso no template de stack montado depende, através de
DependsOn, dos recursos da wave imediatamente anterior que contribuíram para o mesmo stack — pelo que a wave fixa a ordem pela qual os recursos são criados e, inversamente, a ordem pela qual são eliminados. Não se trata de uma ordenação por prontidão: um template de stack não tem noção de um recurso estar apto a prestar serviço. ODependsOnpróprio de um fragmento é estendido em vez de substituído. Os Components que são montados num stack diferente estão fora de alcance, e a sequenciação de dois stacks é uma preocupação do operador. Verproviders/cloudformation.md.
Unidade de autoria de waves vs. unidade implementável. A fronteira é a unidade de autoria de waves. A unidade implementável é o caminho de montagem para o qual os componentes são emitidos — por predefinição 1:1 com a fronteira, mas duas fronteiras irmãs que partilham um directory: colapsam numa única saída montada (um Chart.yaml, um docker-compose.yaml). Quando isso acontece, a saída montada pode conter recursos de várias waves; uma Application do ArgoCD que a lê ordena, dentro da Application, cada recurso pela anotação sync-wave que esse recurso contém — no helm, todos os recursos renderizados para uma wave diferente de zero, e no helm-chart, apenas um artefacto carregado por $import:, contendo os templates próprios de um sub-chart o que o seu autor escreveu. A sequenciação entre Applications através de caminhos diferentes é uma preocupação da CI do operador.
Casos de utilização. A ordenação por waves é relevante sempre que o arranque de uma fronteira depende da conclusão prévia de outra. Padrão canónico: uma fronteira infra na wave 0 (VPC + base de dados), uma fronteira migrations na wave 1 (job de migração do esquema) e uma fronteira apps na wave 2 (a aplicação que consome o esquema migrado). Sem waves explícitas, as três são implementadas em simultâneo e a aplicação entra em ciclo de falhas enquanto espera que a migração termine.
Para o enquadramento arquitetural completo — o modelo de execução em DAG, a fundamentação para colocar a sequenciação temporal na Release e não no Aggregate, e a distinção entre unidade de autoria de waves e unidade implementável — consulte architecture/12-day-two-lifecycles.md §1.
Anexação de Feature
A Release pode anexar Features tanto ao nível da fronteira (política ampla) como ao nível de um componente específico (segmentação precisa), com a execução a seguir o modelo em cebola de 5 níveis definido em architecture/10-compilation-pipeline.md. As Features declaradas na Release contribuem com type, infra e uses; não podem declarar values (consulte «Restrições ao nível do esquema» acima).
Uma Feature anexada a uma fronteira é indexada por um nome de instância escolhido pelo autor, e esse nome não pode ser . nem ... Num provider que dá a cada contribuidor um diretório próprio — terraform, em modules/, e helm-chart, em charts/ — os ficheiros de uma Feature ao nível da fronteira são escritos num diretório com o nome apenas da instância, e nenhum desses nomes é um diretório próprio: a compilação para, indicando a Release, a fronteira e a instância. Um nome que apenas contenha pontos, como audit.v2, é um nome normal.
features: é a única superfície de anexação da Release, em ambos os âmbitos — tal como é a do Aggregate. Uma credencial é uma Feature com a etiqueta feature.aggrega.ai/kind: secret, pelo que uma credencial anexada pelo operador é anexada em features: como qualquer outra Feature, e indica o seu segredo em infra exatamente como uma numa ligação (consulte Configuração de ligações por aresta) — num componente que o Aggregate deixou sem nenhuma, ou como dimensionamento de um anexo que o Aggregate declarou sem indicar um segredo. Não existe uma segunda palavra-chave de anexação em nenhum âmbito; um documento que declare uma é rejeitado no carregamento com um erro de envelope que indica a propriedade inesperada.
Uma feature anexada a toda a fronteira pode conter um bloco uses:, e esse bloco projeta-se em todos os componentes encaminhados para a fronteira: cada componente ganha uma aresta de dependência para os destinos indicados pela feature e recebe a injeção dos provides desses destinos. Isto exprime uma dependência partilhada uma única vez na fronteira — «todos os componentes desta fronteira comunicam com a cache / o coletor / o barramento de mensagens partilhado» — em vez de repetir a mesma aresta uses: em cada componente. Um anexo de Feature ao nível do subsistema no Aggregate projeta o seu uses: da mesma forma pelos componentes do subsistema. uses é uma declaração de ligação da topologia, não um valor, pelo que é permitido na Release. A projeção é independente do âmbito de execução da Feature anexada: uma Feature cuja FeatureRecipe é renderizada uma vez por fronteira continua a projetar o seu uses: por componente, enquanto o próprio recurso partilhado é renderizado uma vez.
Uma feature anexada a um único componente contém 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 indicado, recebe a injeção dos provides desses destinos, e a aresta regista o anexo como a sua origem exatamente como a forma para toda a fronteira. As duas são uma declaração com duas amplitudes — anexar na fronteira para ligar todos os componentes que contém, anexar num componente para ligar esse — e a escolha entre elas é uma questão de alcance, nunca do que a ligação faz. Nenhuma cria computação: o destino tem de indicar um componente que o Aggregate já declarou, e um que não o faça interrompe a compilação. Uma ligação que uma Feature traça não contém anexos próprios: a sua entrada aceita target e inject, e uma chave features: aí é 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 se escreve um destino. O destino de uma aresta indica um componente do grafo montado, pelo que é escrito com o caminho qualificado com pontos — data.store, não store — sempre que o destino pertence a um submódulo encaminhado. Isto aplica-se mesmo quando o próprio anexo está sob uma entrada de encaminhamento, cujas chaves components: são locais ao módulo: a chave diz em que componente está o anexo e o destino diz a que componente chega a aresta, 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 é interrompido com o mesmo diagnóstico que qualquer aresta pendente produz.
Release composta e herança extends:
Uma Release pode declarar spec.extends: a apontar para uma Release base cuja superfície de autoria herda.
A referência é um caminho para um ficheiro ao lado da Release que a declara — ./base-release.yaml, ou ../shared/base-release.yaml. Uma Release pertence ao lado da implementação e não é indexada no catálogo, pelo que uma referência extends: nunca é resolvida através do catálogo. O caminho relativo é a única forma que aceita: uma referência escrita como coordenada de registo é recusada, tal 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 forma diferente — aceita um caminho relativo ou o metadata.name simples de um Manifest ao lado da Release — pelo que as duas formas não são intermutáveis, e um nome simples que seria resolvido num Manifest não é resolvido aqui. Cada elo de uma cadeia é lido da mesma forma: uma Release mãe mantida noutro diretório indica a sua própria mãe por um caminho ao lado de si mesma, onde quer que esteja a Release indicada, exatamente como o seu $import: de parameters é resolvido ao lado dela. O caminho tem de levar a uma Release dentro do workspace, como todos os caminhos que uma Release escreve — ou, para uma Release indicada fora do workspace, dentro do diretório que contém essa Release, ao qual todos os elos da sua cadeia estão sujeitos: um que saia, ou que uma ligação leve para fora, é recusado antes de o ficheiro que indica ser lido.
O compilador segue a cadeia quando a Release é carregada — recusando uma cadeia que volte a um ficheiro que já faz parte dela, uma que ultrapasse o limite de profundidade e uma referência que não indique nada — e depois funde a cadeia numa única Release resolvida.
O que se herda pode ser substituído chave a chave. O valor próprio prevalece, até ao fim, até se chegar a um valor que seja uma coisa indivisível — um escalar, uma lista, um template — que se aceita ou substitui por inteiro. Remove-se algo herdado escrevendo-o como null. Esta é a mesma regra que seguem um Component, uma Feature e um Manifest que estendem outro, pelo que um autor que conheça um conhece todos.
Aplicado a uma Release: boundaries compõem-se 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; o uses de um componente por socket e depois por ligação, em que um target que a filha escreva substitui o herdado, o infra da ligação compõe-se chave a chave, e as suas features compõem-se por slot e depois por pilar pela mesma regra que as features próprias de um componente seguem; directory, subDirectory, syncWave e os ponteiros para o Aggregate e o Manifest são escalares que substituem.
Há duas coisas que não são herdadas:
- Identidade e proveniência. Nenhum campo
metadataé herdado.metadata.environmenté o que importa conhecer: é obrigatório em todas as Releases e é, por natureza, próprio de cada Release, pelo que uma filha é renderizada com o seu próprio ambiente nas etiquetas de proveniência, e não com o da mãe. - O ponteiro para o Aggregate é herdado, e não pode ser substituído. A filha não pode declarar
aggregate:— o esquema recusaextends:eaggregate:no mesmo documento — pelo que uma filha implementa a mesma intenção do programador que a sua base.
A filha pode omitir manifest:, herdando o da sua base, ou substituí-lo para Late Binding.
Uma única forma de encaminhamento em toda a cadeia. boundaries: e components: são mutuamente exclusivos numa única Release, e isso aplica-se também a uma cadeia: uma base que declare fronteiras com nome e uma filha que declare componentes de nível superior é recusada, e o diagnóstico indica ambos os ficheiros e ambas as chaves. Escolha uma forma de encaminhamento e use-a em toda a cadeia.
O padrão de ponte para desenvolvimento local. O caso de utilização canónico é um programador que executa localmente o Aggregate de produção da sua equipa sem fazer fork do Aggregate nem duplicar a topologia de fronteiras. A equipa publica uma Release de produção; uma Release local faz extends: dela e substitui apenas o ponteiro para o Manifest, trocando as Recipes orientadas para a cloud 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 a topologia de fronteiras, os anexos de Feature e as substituições de componentes da sua base; o programador mantém um único local-release.yaml e executa aggrega build --release local-release.yaml sem duplicar nenhuma configuração de produção.
Escreva directory: em função de um parâmetro. Como um diretório é herdado como qualquer outro escalar, uma filha que herde um diretório sem nenhuma variável de template é renderizada no mesmo caminho em que a sua base é renderizada, e nenhuma opção da linha de comandos a redireciona. Isso é legítimo quando é o que se pretende — trocar apenas as Recipes para comparar a sua saída, por exemplo — pelo que a compilação o reporta e continua em vez de recusar. Escrever o diretório em função de um parâmetro, como acima, mantém a topologia num só lugar e continua a enviar a saída de cada Release para um local próprio.
Sobreposição de parâmetros em vários ficheiros. A herança de Releases é o lugar para a sobreposição de parâmetros em vários ficheiros. Uma Release base fornece o conjunto comum de parâmetros; as filhas por ambiente fazem extends: da base e substituem os espaços 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 filha vê os parâmetros herdados da sua base fundidos com os seus próprios. Os parâmetros com valor de mapa são fundidos em profundidade, prevalecendo a chave da filha; os parâmetros com valor escalar são substituídos pela filha; uma chave que uma filha escreva como null é removida em vez de ser definida como vazia.
Uma base pode importar os seus parâmetros e uma filha pode ainda assim substituir chaves individuais. Os dois modos de autoria descritos em parameters: acima — 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 contra o diretório que contém essa Release antes de a cadeia ser fundida. Assim, uma base que importe um ficheiro partilhado e uma filha que escreva algumas chaves inline compõem-se por chave, exatamente como dois blocos inline:
# 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 a mãe em falta e declarações aggregate: do lado da filha interrompem todos o carregamento do workspace com diagnósticos explícitos que indicam a Release em causa e a violação ao nível do esquema. Consulte errors/fatal-halts.md para as formas das mensagens de cada erro.