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

Composição das entradas da Recipe — três tipos de entrada, Workload, artefatos

Uma Recipe produz arquivos de manifesto para seu provedor de destino. Este capítulo aborda como as Recipes compõem sua saída a partir de três tipos de entrada ortogonais — sourced, synthesized e artifacts —, como cada tipo de entrada é estruturado e qual provedor produz qual saída. O papel conceitual da entidade Recipe (o template de tradução escrito por Ops que mapeia a intenção do desenvolvedor para um único provedor físico) está em 04-entity-taxonomy.md; a superfície de autoria da Recipe no nível de palavra-chave está em ../language-reference/entities/recipe.md.

Justificativa

A ferramenta de renderização nativa de cada provedor — Helm, Docker Compose — já sabe como renderizar manifestos nativos do provedor. A função de uma Recipe é declarar O QUE esses manifestos devem dizer: quais imagens de contêiner, quais portas, quais variáveis de ambiente, quais volumes, quais serviços, quais limites de recursos.

Uma Recipe precisa expressar mais do que um conjunto fixo de chaves (por exemplo, image, environment, ports, replicas) mapeado sobre um Deployment e um Service consegue comportar, entre outras coisas:

  • resources (requests/limits de CPU/memória)
  • Probes de liveness, readiness ou startup
  • volumeMounts / volumes
  • nodeSelector / affinity / tolerations
  • serviceAccount / securityContext
  • Pods com vários contêineres, sidecars
  • Recursos ConfigMap / Secret / PVC / CRD
  • Services que não são ClusterIP (LoadBalancer, NodePort, Headless)

A camada de abstração precisa descrever a forma completa de uma carga de trabalho, não um conjunto fixo de chaves. Os três tipos de entrada descritos a seguir são essa abstração: uma Recipe compõe sua saída de forma aditiva a partir de um chart ou módulo carregado externamente (source:), de uma especificação abstrata de Workload que o provedor sintetiza em manifestos nativos do provedor (workload:) e de manifestos nativos do provedor baseados em templates que a Recipe emite diretamente (artifacts:).

Os três tipos de entrada

Composição por adição

Há três maneiras de produzir arquivos de manifesto nativos do provedor a partir de uma Recipe, e elas se compõem por adição, em vez de se excluírem mutuamente:

  1. source: — um artefato carregado externamente (chart do Helm, arquivo compose) que o provedor renderiza nativamente, com valuesMapping: fornecendo os valores de sobreposição.
  2. workload: — uma especificação abstrata de Workload (tipo pertencente à plataforma) que o provedor sintetiza em manifestos nativos do provedor. O campo aceita um block scalar YAML inline ou um $import: para um único arquivo local ou entrada de biblioteca; o despacho é guiado pela forma do conteúdo.
  3. artifacts: — um mapa de manifestos nativos do provedor, inline ou carregados com $import:, processados como templates Go com base no contexto completo dos pilares. Cada entrada pode ser escrita inline (o valor da entrada é um block scalar) ou via $import: para um único arquivo ou conteúdo de biblioteca.

Os três produzem arquivos que o compilador emite no diretório de saída do boundary. Os três podem coexistir em uma única Recipe, sujeitos às regras de validação abaixo. A semântica de mesclagem é apenas de nível superior: cada tipo de entrada produz arquivos completos; os arquivos são emitidos lado a lado; uma colisão no nome do arquivo de saída é um erro fatal.

Nomes descritivos dos modos

Os três “modos” são vocabulário descritivo para documentação e diagnósticos. Os autores de Recipe não declaram um modo; eles escrevem as palavras-chave de que precisam. Uma Recipe é caracterizada pela sua entrada dominante:

Palavra(s)-chave dominante(s)Nome descritivo do modo
source: + valuesMapping: (sem workload:, sem artefatos)sourced
workload: (sem source:, sem artefatos)synthesized
artifacts: (sem source:, sem workload:)artifacts-only (informalmente: “inline”)
Qualquer combinação de dois ou maisdescrito explicitamente (por exemplo, “sourced com artifacts”, “synthesized com artifacts”)

Não existe uma palavra-chave chamada mode: nem um enum. O modo é uma propriedade emergente de quais entradas estão presentes.

A forma de uma Recipe em resumo

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: ...
version: 1.0.0
spec:
capability: helm | compose | helm-chart | ...
implements: core/...:1.0.0
locals: { ... }
provides: { ... }
# ─── Sourced input (optional, paired) ───
source: ...
valuesMapping: |
# Go template → YAML/JSON overlay values
# OR:
valuesMapping:
$import: ./mappings/api-server.tmpl # local file path
# OR:
valuesMapping:
$import: <Lib>#/mappings/<entry> # MappingLibrary entry
# ─── Synthesized input (optional) ───
workload: |
# Go template → YAML → parsed Workload
# OR (single-source $import for whole-content load from a file or library):
workload:
$import: ./workload.yaml
# ─── Artifacts input (optional, multiple entries permitted) ───
artifacts:
"filename.yaml": |
# Inline Go template → manifest YAML
"other.yaml":
$import: ./artifacts/other.yaml # per-entry $import: for file or library content

Todos os campos acima são aceitos pelo schema da Recipe, e o compilador consome os três tipos de entrada — a renderização sourced, a síntese de Workload e a emissão de artifacts. O que difere é o suporte por provedor — qual provedor renderiza qual tipo de entrada —, registrado na matriz de capacidades por Provider no fim deste capítulo.

Regras de validação no carregamento

O schema da Recipe e a validação no carregamento impõem estas regras de composição:

  1. valuesMapping: exige source:. Sem um source: sobre o qual sobrepor, não há nada para receber os valores mapeados. Uma Recipe com valuesMapping: e sem source: é um erro no carregamento. (Um source: sem valuesMapping: é permitido — o chart ou módulo é renderizado com seus próprios padrões.)
  2. workload: aceita uma única fonte — inline ou $import:, não ambas. Uma Recipe especifica o Workload como um block scalar inline ou como um $import: para um único arquivo. A forma $import: é de fonte única, segundo o vocabulário unificado de importação de arquivos; a mesclagem de várias fontes não é suportada em workload:. Um despacho malformado é um erro no carregamento.
  3. workload: exige um provedor capaz de síntese. O suporte à síntese é uma propriedade do próprio provedor, não de algum campo declarado. Uma Recipe workload: vinculada a um provedor que não consegue sintetizar é rejeitada quando o nó é renderizado — pela verificação de capacidades do provedor (veja a matriz de capacidades por Provider) — com um diagnóstico claro. O catálogo da biblioteca padrão declara workloadSchema nos provedores capazes de síntese por convenção, como o contrato de tradução documentado, mas a verificação se baseia na capacidade informada pelo próprio provedor, e não na presença desse campo.
  4. Pelo menos um tipo de entrada deve estar presente. Uma Recipe sem nenhum de source:+valuesMapping:, workload: ou artifacts: não produz saída e é um erro no carregamento.
  5. Entradas de artefato inline e $import: podem coexistir. Uma Recipe pode declarar algumas entradas de artifacts: inline e outras por meio de diretivas $import: por entrada. A chave de cada entrada nomeia sua própria saída, de modo que entradas das duas formas nunca colidem entre si (veja O que dá nome a cada arquivo de saída).
  6. Colisões de nomes de arquivo entre tipos de entrada são erros no momento da renderização. Se dois dos tipos de entrada de uma Recipe — saída renderizada a partir da fonte, saída sintetizada a partir da carga de trabalho ou saída emitida a partir dos artefatos — produzirem um arquivo com o mesmo nome, o compilador emite um erro fatal identificando cada contribuinte. Essa verificação é executada após a tradução do Workload, por isso ocorre na renderização e não no carregamento.

O tipo Workload

Propriedade e localização

Workload é um tipo pertencente à plataforma em apiVersion: aggrega.ai/v1beta1. Sua declaração em JSON Schema 2020-12 é embutida no binário do compilador no momento do build; os autores de catálogo não editam o schema do Workload nem escrevem arquivos YAML Workload independentes como entidades de catálogo. A gramática do Workload é consumida dentro do campo workload: de uma Recipe ou de uma FeatureRecipe (inline, ou via $import: para um único arquivo ou uma entrada de WorkloadLibrary) e em nenhum outro lugar.

Workload é um tipo da plataforma e um conceito do compilador, não uma entidade separada na taxonomia de entidades. A Recipe é a entidade de autoria; o Workload é a forma que a entrada sintetizada da Recipe assume.

Um Workload por Recipe

Uma Recipe declara no máximo um workload:. O Workload representa a única unidade de computação associada ao Component que esta Recipe implementa. Da mesma forma, uma FeatureRecipe declara no máximo um workload: próprio — uma unidade de computação pertencente à Feature, sintetizada pelo mesmo tipo Workload —; veja FeatureRecipe. Casos de uso que exigem cargas de trabalho secundárias adicionais são expressos por meio de:

  • artifacts: — manifestos adicionais ao lado da carga de trabalho, na mesma Recipe (inline ou via $import: por entrada).
  • Features com geração de recursos — cargas de trabalho secundárias transversais (por exemplo, um sidecar de backup vinculado a bancos de dados) declaradas como entidades de catálogo separadas, em que a FeatureRecipe sintetiza seu próprio workload: (ou renderiza via source: / artifacts:). Veja 14-extensibility.md sobre a geração de recursos da FeatureRecipe.

Isso preserva o modelo de uma unidade de computação por autor: uma Recipe sintetiza a carga de trabalho do Component; uma FeatureRecipe sintetiza a sua própria.

A superfície completa

O conjunto de campos do Workload é grande e cresce. Em vez de repeti-lo aqui, onde uma cópia ficaria defasada em relação ao contrato sem que nada informasse isso, este capítulo aponta para as duas superfícies que o contêm por inteiro:

  • A referência gerada do schema do Workload — cada campo, seu tipo, seu padrão e suas restrições, gerada a partir do JSON Schema publicado e comparada com ele a cada build, de modo que não pode descrever uma forma que o compilador não aceita.
  • A página de autoria do Workload — orientação de autoria no nível de campo: o que cada campo significa, em que cada provedor o renderiza e quais combinações o build recusa.

A declaração em JSON Schema 2020-12 do Workload é a fonte de autoridade e é distribuída embutida no binário do compilador. Os providers helm e compose sintetizam o workload: de uma Recipe, inline ou carregado via $import:; veja a matriz de capacidades por Provider para o suporte por provedor.

Integração de secrets com featuresSchema

O bloco containers.<name>.attachments do Workload referencia slots declarados pelo featuresSchema do Component; ele não declara novos slots. Veja ../language-reference/entities/component.md para a superfície de autoria de featuresSchema.

O contrato de validação:

  • Todo valor attachments.<KEY>.from deve corresponder a um nome de slot declarado no featuresSchema do Component — ou, para uma entrada que nomeia uma conexão com connection: <alias>, a um slot que o socket dessa conexão declara em usesSchema.<socket>.featuresSchema. Essa entrada é reescrita para o nome que o vínculo da conexão assume no componente (<alias>.<slot>) antes que qualquer uma destas regras seja aplicada, de modo que cada regra abaixo a lê como lê uma entrada que nomeia um slot próprio do Component.
  • O mecanismo de entrega as: (env ou file) deve estar na lista de permissões do array inject: desse slot.
  • Slots marcados como inject: [] (caixa-preta) no featuresSchema do Component não podem aparecer em blocos attachments: do Workload — esses slots são entregues pela estrutura interna da Recipe (por exemplo, via existingSecret do Helm), e não pela exposição no Workload.

Exemplo:

# In the Component
spec:
featuresSchema:
db_password:
required: true
inject: [env, file] # transparent: Workload may dictate delivery
root_password:
required: true
inject: [] # blackbox: Recipe handles internally
# In the Recipe
workload: |
containers:
main:
attachments:
DB_PASSWORD: # OK — db_password slot allows env inject
from: db_password
as: env
# ROOT_PASSWORD: ... # rejected — root_password is blackbox

Probes de integridade: intenção, não mecanismo

Probes do Kubernetes e healthchecks do Docker Compose têm formas diferentes. Uma única forma abstrata de intenção se traduz de maneira limpa para ambos:

health:
ready:
http: /healthz # intent: HTTP GET probe
timeoutSeconds: 5
live:
tcp: 8080 # intent: TCP socket check
timeoutSeconds: 5
startup:
exec: ["check-ready.sh"] # intent: command exec
timeoutSeconds: 30
periodSeconds: 10

Os Providers traduzem cada intenção para sua forma nativa:

IntençãoHelm (K8s)Compose
http: /pathhttpGet.path: /path, httpGet.port: <alphabetically-first port name>CMD-SHELL "curl -f http://localhost:<port>/path"
tcp: <port>tcpSocket.port: <port>CMD-SHELL "nc -z localhost <port>"
exec: [cmd]exec.command: [cmd]CMD [cmd]

A resolução de porta para http: sem uma porta explícita usa o primeiro nome de porta, em ordem alfabética, que o contêiner declara em containers.<name>.ports, nos dois destinos. Um contêiner que não declara nenhuma porta nomeada não pode ter uma probe HTTP, e o build é interrompido nomeando a probe.

O Compose degrada as probes HTTP/TCP para comandos shell de healthcheck, e um serviço do compose traz um único healthcheck: quando mais de uma probe é declarada, uma é traduzida e um aviso nomeia as descartadas.

Tipos de volume

Cinco tipos de volume; nenhum composto:

TipoSemânticaK8s (helm)Compose
ephemeralTmpfs / emptyDir; deixa de existir com o podemptyDir: { sizeLimit }montagem tmpfs:, sem tamanho (um aviso informa um sizeLimit escrito pelo autor)
configmapArquivos de configuração somente leituraReferência a volume ConfigMapreferência configs: no nível do serviço a uma config de nível superior que os artifacts: da Recipe declaram
secretArquivos de secret somente leituraReferência a volume Secretarquivo de secret somente leitura montado via bind
persistentPVC único; sobrevive a reinicializações do podRecurso PVC + volume.persistentVolumeClaimvolume nomeado
persistentTemplatePVC por réplica; acompanha form: statefulStatefulSet.volumeClaimTemplatesvolume nomeado (degradado; aviso emitido)

O Compose não consegue expressar templates por réplica. Quando persistentTemplate é traduzido para compose, ele é degradado para um único volume nomeado compartilhado por todas as réplicas, e um aviso informa a degradação. Um volume persistentTemplate exige form: stateful; declará-lo em qualquer outra forma interrompe o build.

Exposições com vários serviços

Cada serviço é uma exposição independente. Um padrão comum: um serviço HTTP na porta 8080 (ClusterIP interno) + um serviço de métricas na porta 9090 (ClusterIP) + um endpoint de administração na porta 9901 (LoadBalancer):

services:
http:
type: ClusterIP
ports:
web: 8080
metrics:
type: ClusterIP
ports:
prom: 9090
admin:
type: LoadBalancer
ports:
admin: 9901

Cada um se torna um objeto Service do Kubernetes separado quando renderizado pelo provedor helm, que, por outro lado, é interrompido diante de uma entrada Loopback. No compose, serviços NodePort e LoadBalancer publicam suas portas em todas as interfaces de host do serviço compose, os Loopback apenas no endereço de loopback do host, e os ClusterIP e Headless não publicam nada.

Na saída do K8s, os nomes de serviço recebem como prefixo o instance_id do componente, para garantir a unicidade. Os nomes de porta devem corresponder aos nomes de porta do contêiner declarados em containers.<name>.ports.

Contrato de tradução do lado do Provider: workloadSchema

Um Plugin de renderização de provedor (pluginType: provider) declara um spec.provider.workloadSchema — uma declaração em JSON Schema 2020-12 que documenta como os campos do Workload se traduzem na saída nativa desse provedor. Esse é o contrato de tradução autodocumentado. Veja ../language-reference/entities/plugin.md para a superfície de autoria do Plugin, incluindo o bloco spec.provider.

apiVersion: aggrega.ai/v1beta1
kind: Plugin
metadata:
name: helm-renderer
version: 1.0.0
pluginType: provider
spec:
abiVersion: v1beta1
provider:
workloadSchema: | # how Workload translates to K8s manifests
// Each Workload produces: 1 controller object chosen by workload.form
// (stateless -> Deployment, stateful -> StatefulSet, daemon -> DaemonSet, task -> Job)
// + 1..N Services (one per workload.services entry)
// + 1..N PVCs (one per workload.volumes.*.persistent entry)
// + 1..N ConfigMap volume refs (from workload.volumes.*.configmap.source)
// ...

O campo workloadSchema comunica a intenção de tradução aos autores de catálogo e às ferramentas de IDE. Ele é o contrato de tradução documentado, declarado por convenção nos provedores que sintetizam — mas o suporte à síntese é determinado pelo próprio provedor, não pela presença deste campo. Uma Recipe que aponta, com workload:, para um provedor que não consegue sintetizar é rejeitada quando o nó é renderizado — pela verificação de capacidades do provedor — com um erro claro, quer o provedor declare workloadSchema ou não.

O schema do Plugin declara spec.provider.workloadSchema — seu corpo é compilado para JSON Schema 2020-12 quando o Plugin é carregado —, e o consumo de workload: do lado da Recipe já está disponível. O suporte à síntese é imposto no momento da renderização pela verificação de capacidades do provedor, com base na capacidade informada pelo provedor vinculado; workloadSchema é o contrato documentado que o catálogo da biblioteca padrão mantém sincronizado com essa capacidade, e não a entrada da verificação em si. O aggrega validate, executado sobre o catálogo inteiro, também sinaliza antecipadamente, antes de um build, uma Recipe workload: vinculada a um provedor que não sintetiza, quando o catálogo contém a entidade Plugin desse provedor.

Recursos auxiliares ficam fora do Workload

A especificação do Workload não tem campo additionalResources, nem extras, nem declarações inline de ConfigMap/Secret/CRD. O Workload modela apenas a forma da carga de trabalho: contêineres, volumes, serviços, réplicas, agendamento, contexto de segurança, service account — tudo o que descreve como a única unidade de computação é executada.

Recursos auxiliares têm dois lugares legítimos fora do Workload:

  1. Features + FeatureRecipes — o mecanismo para preocupações transversais. Um ServiceMonitor vinculado a “qualquer servidor com métricas expostas” é core/prometheus-exporter como Feature. O recurso de roteamento que publica um servidor em um hostname também é uma Feature, e a forma de roteamento decide qual: core/public-ingress onde o destino reconcilia um Ingress, core/http-route onde ele executa a Gateway API — cada uma realizada por uma FeatureRecipe que o Manifest seleciona para cada Release. Uma NetworkPolicy aplicada a todas as cargas de trabalho de produção é uma Feature que a Release de produção vincula a todo o boundary. As Features se compõem de forma ortogonal e podem ser reutilizadas entre Recipes. Veja 14-extensibility.md sobre a geração de recursos da FeatureRecipe.
  2. artifacts: no nível da Recipe — para recursos que pertencem à implementação desta Recipe específica e para os quais não vale a pena criar uma Feature. Um registro pontual de CRD de que a Recipe precisa. Um PodDisruptionBudget específico da Recipe que só se aplica quando esta Recipe é usada. Um ConfigMap que o Workload da Recipe referencia. Cada entrada é inline ou carregada com $import:; veja a seção sobre o mecanismo de artefatos abaixo.

A linha entre Feature e artefato é uma convenção social. Se um recurso auxiliar é transversal (aplica-se a muitas Recipes ou é vinculado condicionalmente por seletores), ele é uma Feature. Se é intrínseco a esta única Recipe (a Recipe não consegue fazer seu trabalho sem emitir esse recurso), ele é um artefato. Os autores escolhem com base na reutilização e na semântica de vínculo; o compilador não fiscaliza a escolha.

As Features e os artefatos de Recipe, juntos, cobrem os recursos auxiliares de que uma Recipe precisa.

O mecanismo de artefatos

Artefatos inline e carregados de arquivo

O tipo de entrada artifacts emite arquivos de manifesto nativos do provedor baseados em templates diretamente na saída do boundary, ao lado de qualquer saída renderizada a partir da fonte ou sintetizada a partir da carga de trabalho. Os autores o declaram por meio de duas superfícies:

spec:
artifacts:
"servicemonitor.yaml": |
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
name: {{ .context.instance_id }}-monitor
spec:
endpoints:
- port: {{ .workload.services.metrics.ports.prom }}
"networkpolicy.yaml":
$import: ./artifacts/networkpolicy.yaml
"crd-registration.yaml":
$import: ./artifacts/crd-registration.yaml

Os caminhos de $import: são relativos ao diretório da Recipe e devem permanecer dentro dele, porque todo arquivo que uma publicação da Recipe carrega é obtido desse diretório — cada arquivo que uma importação nomeia viaja com ela — e um arquivo fora dele não viajaria. Uma convenção típica os coloca em um subdiretório ./artifacts/, embora o compilador não imponha isso. A chave do mapa nomeia cada arquivo emitido — a próxima seção explica o que isso significa em cada uma das três formas.

Cada entrada (inline ou carregada com $import:) é processada como template Go com base no contexto de template completo antes de ser emitida no diretório de saída.

O que nomeia cada arquivo de saída

O mapa é indexado pelo nome da entrada, e a chave nomeia o que a entrada emite em todas as formas de autoria. Para uma entrada inline, a chave é o nome do arquivo de saída, usado tal como está escrito:

artifacts:
"configmap-config.yaml": |
...
"pdb.yaml": |
...

Produz configmap-config.yaml e pdb.yaml. A chave fixa o nome do arquivo; onde o arquivo vai parar é decisão do destino, e a seção sobre emissão por provedor, abaixo, trata disso.

Para uma entrada $import: de arquivo, a chave também é o nome do arquivo de saída. O arquivo importado fornece o conteúdo; ele não fornece o nome, então um autor que deseja um nome de arquivo de saída específico escreve esse nome como chave:

artifacts:
"monitor.yaml":
$import: ./artifacts/monitor.yaml
"netpol.yaml":
$import: ./artifacts/subdir/some-other-name.yaml

Produz .../monitor.yaml e .../netpol.yaml. O arquivo importado da segunda entrada se chama some-other-name.yaml, e esse nome não chega à saída — a chave chega. Duas entradas que importam arquivos diferentes que por acaso têm o mesmo nome, ./extras/shared.yaml e ./overrides/shared.yaml, são, portanto, duas saídas distintas, cada uma nomeada pela própria chave.

Para uma entrada $import: de biblioteca, que traz um pacote de arquivos como uma unidade, a entrada se expande em uma saída por arquivo do pacote, cada uma aninhada sob a chave como <key>/<filename>. Uma chave nomeia muitos arquivos, então a chave sozinha não pode nomeá-los: ela é o diretório onde os arquivos do pacote vão parar, e não o nome de nenhum deles.

Como toda forma nomeia sua saída a partir da chave, a chave é limitada, na superfície de autoria, ao que um único nome de arquivo pode ser: uma letra ou dígito inicial, seguido de letras, dígitos, pontos, hifens e sublinhados. Os pontos carregam a extensão que um consumidor espera, o que torna uma chave utilizável diretamente como nome de arquivo; e o alfabeto não contém / nem um . inicial, de modo que uma chave nunca pode formar mais de um segmento de caminho nem ser o segmento do diretório pai. Uma chave fora do alfabeto falha na validação do envelope ao carregar o workspace, no aggrega validate e nos diagnósticos do editor.

Duas saídas de artifacts: com o mesmo nome de arquivo interrompem o build quando o nó é renderizado, quaisquer que sejam as formas que as produziram. Duas entradas de um mesmo mapa artifacts: nunca nomeiam a mesma saída: uma chave é única dentro de um documento e é um único nome de arquivo, então o nome de saída de uma entrada de arquivo único é a sua chave, e as saídas de uma entrada de pacote ficam todas sob um diretório nomeado pela sua chave. O primeiro segmento de todo caminho emitido é, portanto, a chave que o produziu, e chaves distintas continuam sendo nomes de saída distintos. O que a interrupção cobre é o caso que atravessa tipos de entrada — um nome de arquivo contribuído por dois deles, um template do chart e uma entrada de artefato que produzem ambos servicemonitor.yaml —, com um diagnóstico que nomeia cada origem contribuinte.

Contexto de template para artefatos

Os templates de artefatos têm acesso ao contexto completo dos pilares:

  • .values, .infra, .context.*, .locals, .provides, .features, .metadata — os pilares padrão do Aggrega descritos em 06-data-taxonomy-and-composition.md.
  • .workload — a especificação do Workload analisada para esta Recipe (se presente). Permite que os artefatos referenciem valores do Workload sem duplicação, por exemplo, um ServiceMonitor que referencia .workload.services.metrics.ports.prom.
  • .source — o conteúdo resolvido do campo source: (se presente).

Os artefatos são avaliados depois que o Workload é analisado, então .workload fica disponível quando presente. Para Recipes sem workload:, .workload é nil; um template que tente desreferenciá-lo falha com um erro claro. Para Recipes sem source:, .source é nil, com o mesmo modo de falha.

A invariante de autocontenção

Os artefatos devem ser autocontidos. Eles só podem referenciar as entradas declaradas da Recipe: o contexto dos pilares, o próprio Workload da Recipe (quando presente) e o próprio valor source: da Recipe. Eles não podem referenciar:

  • Saídas de outras Recipes no mesmo boundary.
  • Recursos do Kubernetes existentes no ambiente que a Recipe não declarou.
  • Secrets, ConfigMaps ou outros recursos que se presume existirem externamente (a menos que referenciados por um pilar declarado).

Um artefato ConfigMap referenciado por volumes.*.configmap.source do Workload deve ser emitido por ESTA Recipe (via artifacts: que produzam esse ConfigMap) ou por uma Feature vinculada a este nó. Dependências entre uma Recipe e outra dentro de um boundary não são suportadas.

Essa invariante preserva a reutilização da Recipe: uma Recipe pode ser inserida em qualquer combinação de Aggregate + Release que satisfaça seu contrato de pilares, sem dependências ocultas.

Labels de proveniência

Após a tradução, todo arquivo emitido carrega a proveniência aggrega.ai/* em seus metadados — seja ele renderizado a partir da fonte, sintetizado a partir da carga de trabalho ou emitido a partir de um template de artefato. Toda superfície de emissão a aplica a partir de um mesmo conjunto compartilhado de builders, de modo que o mesmo arquivo carrega sempre a mesma proveniência, qualquer que seja o tipo de entrada que o produziu. O conjunto se divide conforme um valor satisfaça ou não o charset de valores de label do Kubernetes: as chaves seguras para labels são labels (consultáveis); as chaves inseguras para o charset — recipe-uri (contém um :), boundary-path (um caminho aninhado contém /) e sync-wave (o - inicial de uma wave negativa) — são anotações, cujos valores não têm restrições. Um valor de identidade que o build não submete às regras de labels — o nome do agregado, o ambiente, o nome do provedor, as versões do compilador e do provedor — é um label escrito em uma forma que um label admite e, quando essa forma difere do valor, o valor literal também é uma anotação sob a mesma chave (um Aggregate chamado imported/flow recebe o label imported-flow e a anotação imported/flow). Todos os arquivos que carregam a saída de uma mesma Recipe compartilham a mesma proveniência:

metadata:
labels:
aggrega.ai/component-id: api
# ... plus the recommended app.kubernetes.io/name label
annotations:
aggrega.ai/recipe-uri: api-server-helm:1.0.0
aggrega.ai/boundary-path: production

Essa divisão é uniforme nos três tipos de entrada. (O provedor Compose não tem o conceito de anotação e seus valores de label não têm restrições, então ele emite o conjunto inteiro como labels de serviço.) Veja 11-governance-and-compliance.md sobre a aplicação de proveniência em tempo de compilação.

Como um provedor aplica a proveniência onde seu próprio formato de saída a comporta, um provedor cujo formato não oferece esse lugar para um determinado arquivo emite esse arquivo inalterado e informa isso. O Compose é o caso a conhecer: seu lugar de proveniência é o bloco labels: de um serviço, então um fragmento de artefato compose que contribui apenas com volumes:, configs: ou models: de nível superior não carrega proveniência, e o build emite um aviso “skipped provenance label injection (injeção de labels de proveniência ignorada)” nomeando o artefato. Esse aviso é esperado para um fragmento dessa forma e não é sinal de problema — os serviços que o mesmo componente emite carregam o conjunto completo, e nada nos bytes emitidos muda. O que ele descarta é a terceira possibilidade: um arquivo saindo do build sem proveniência sem ser nomeado.

O CloudFormation é o outro caso a conhecer, e ele difere em onde a proveniência vai parar, e não em se ela vai parar. Um template do CloudFormation não tem um bloco de metadados no nível do documento que acompanhe um recurso, então a proveniência vai no atributo Metadata de cada recurso, sob uma única chave aggrega.ai/provenance que contém o conjunto inteiro:

"StoreBucket": {
"Type": "AWS::S3::Bucket",
"Metadata": {
"aggrega.ai/provenance": {
"aggrega.ai/component-id": "store",
"aggrega.ai/recipe-uri": "store-recipe:1.0.0",
"aggrega.ai/boundary-path": "stack"
}
}
}

Três propriedades decorrem desse lugar. O atributo Metadata está disponível em todos os recursos, qualquer que seja o tipo, então todo recurso que uma stack montada carrega recebe a proveniência — incluindo os muitos tipos de recurso que não aceitam nenhuma tag, nos quais uma marcação baseada em tags não teria lugar. A marcação é adicionada a qualquer Metadata que o autor tenha escrito, em vez de substituí-lo, de modo que as entradas do próprio autor permanecem ao lado dela. E, por ser por recurso e não por template, uma stack que vários componentes montam carrega a identidade contribuinte de cada recurso — seu componente, sua Recipe e seu boundary —, o que uma única entrada válida para o template inteiro não conseguiria expressar.

O conjunto inteiro viaja junto sob essa chave. Um valor Metadata é JSON sem restrições, então não há divisão por charset a fazer; as duas chaves que só um runtime do Kubernetes lê — o nome do label recomendado padrão e a anotação de ordenação de deployment que um controlador GitOps consome — ficam de fora, já que nenhuma delas nomeia nada em uma stack. A entrada simples de proveniência aggrega.ai/sync-wave permanece, porque registra a wave que o componente declarou, em vez de instruir um controlador.

A forma que não tem lugar aqui é um template ou fragmento que não declara nenhum recurso — um que contribui apenas com Parameters, Mappings, Conditions ou Rules. Ele não carrega proveniência, chega à stack montada com seu próprio conteúdo intacto, e o build emite um aviso “skipped provenance injection (injeção de proveniência ignorada)” nomeando-o. Assim como no compose, esse aviso é esperado para uma contribuição dessa forma: os recursos que o mesmo componente contribui em outros lugares carregam o conjunto completo, e os bytes emitidos são os mesmos, haja algo escutando ou não.

Semântica dos artefatos por Provider

A semântica por provider a seguir descreve como cada provider integra os artefatos à sua saída nativa.

provider helm: os artefatos são documentos YAML do Kubernetes gravados em um diretório com o nome do componente que os declarou, dentro do diretório de saída que contém os manifestos renderizados a partir do chart e sintetizados a partir do Workload. O motivo é a nomeação: um manifesto renderizado ou sintetizado é nomeado pelo provider a partir do componente ao qual pertence, enquanto um artefato é nomeado pela chave que seu autor escreveu, que não diz nada sobre qual componente é — assim, dois componentes vinculados a uma mesma Recipe gravariam um único caminho sem que nenhum dos dois autores pudesse separá-los. O diretório tem o próprio nome do componente, de modo que o arquivo que o autor lê de volta na saída tem o nome que ele escreveu, um nível abaixo.

Um operador que queira um layout diferente conta com o template subDirectory: da boundary, que move todos os arquivos que um contribuidor emite, e não apenas os artefatos. Veja ../language-reference/path-template-variables.md.

provider compose: os artefatos são fragmentos de compose. As chaves de nível superior (services:, volumes:, configs:, models:) são mescladas no docker-compose.yaml combinado de cada boundary durante a etapa de composição da boundary.

provider helm-chart (caso especial): os artefatos não são gravados no diretório de saída como arquivos independentes — o Helm é dono do pipeline de renderização. Em vez disso, o provider helm-chart coloca cada entrada de artifacts: dentro do próprio chart, e a forma em que a entrada foi escrita decide onde ela vai parar. Cada entrada é processada como template Go com o contexto de pilares do Aggrega PRIMEIRO, antes de qualquer posicionamento; a partir daí as duas formas divergem. Uma entrada carregada com $import: é um arquivo de template pré-Helm: ela é injetada no diretório templates/ do chart ANTES da renderização do Helm, de modo que o Helm a renderiza junto com os templates do próprio chart de origem. Um escalar de bloco inline é um arquivo solto do chart: ele é colocado na raiz do chart sob a chave escrita, sem prefixo templates/ e sem rótulos de procedência mesclados, de modo que os templates do próprio chart podem lê-lo por meio de .Files.Get / .Files.Glob do Helm — o padrão ConfigMap a partir de arquivos. Isso dá ao provider helm-chart um mecanismo de extensão equivalente ao que artifacts: oferece ao provider helm simples, respeitando o modelo de chart do Helm.

O arquivo injetado vai parar em boundaries/<bp>/charts/<nodeID>/templates/<authored-key> — os arquivos de um bundle aninhados sob essa chave — de modo que fica ao lado dos templates do chart de origem e o Helm o recolhe durante a passagem de renderização seguinte. Um escalar de bloco inline vai parar em boundaries/<bp>/charts/<nodeID>/<authored-key> — a raiz do chart, um nível acima de templates/ — porque um arquivo lido por meio de .Files precisa estar onde o chart o procura, e um arquivo colocado sob templates/ é renderizado como manifesto. As duas formas são nomeadas pela chave sob a qual foram escritas; o que as diferencia é o diretório em que o provider as coloca.

Convenção de delimitadores do helm-chart. A passagem de pré-template do Aggrega sobre as entradas de artefato do helm-chart, tanto as carregadas com $import: quanto as inline, usa os delimitadores [[ ]] em vez dos {{ }} padrão, para que a sintaxe {{ ... }} do próprio Helm dentro do arquivo chegue intacta à passagem de renderização do Helm. Os autores escrevem as substituições do lado do Aggrega como [[ .context.instance_id ]], [[ .values.name ]] etc.; as substituições do lado do Helm continuam como {{ .Values.x }}, {{ .Release.Name }}, {{- include "common.labels" . }} etc. Misturar os dois pares de delimitadores em um mesmo arquivo é a forma de escrita suportada.

Procedência e artefatos do helm-chart. A procedência é mesclada em metadata.labels e metadata.annotations (conforme a divisão por conjunto de caracteres descrita acima) para arquivos carregados com $import: que sobrevivem a um ciclo de ida e volta por YAML com seus tokens do Helm preservados — arquivos que usam apenas o contexto do Aggrega [[ ]] ou com {{ }} do Helm apenas em posições de escalares entre aspas. Arquivos com ações de template do Helm estruturais ({{- include ... }}, {{- if ... }}, {{- range ... }}, {{- with ... }} em posições em que emitem estrutura YAML em vez de folhas escalares), ou arquivos com {{ ... }} sem aspas em posições de valor, não sobrevivem ao ciclo de ida e volta por YAML do Aggrega; o build emite um aviso “skipped provenance label injection (injeção de rótulos de procedência ignorada)” que nomeia o artefato e repassa o arquivo sem alterações. Esse aviso é esperado para qualquer arquivo de artefato do helm-chart carregado com $import: que use ações de template do Helm estruturais ou substituições de valores do Helm sem aspas — é o caso comum na escrita de Helm em produção, não o caso extremo. Autores que precisam de rótulos de procedência nesses arquivos os injetam por meio de um template nomeado que escrevem no próprio _helpers.tpl do chart (por exemplo, um chamado aggrega.commonLabels) ou de um mecanismo equivalente do lado do Helm, e não por meio da injeção pré-template do Aggrega.

Colisões com nomes de arquivo da raiz do chart. Um artefato carregado com $import: cuja chave escrita colide com um nome de arquivo da raiz do chart (Chart.yaml, values.yaml, .helmignore etc.) não é detectado pela verificação de colisão de nomes de arquivo do Aggrega — o artefato vai parar em templates/<authored-key> enquanto o arquivo da raiz fica na raiz do chart, e o prefixo de caminho os torna distintos do ponto de vista do Aggrega. Os autores evitam esses nomes de chave; a consequência de usá-los é que o Helm vê os dois arquivos (um na raiz do chart, outro dentro de templates/) e pode renderizar inesperadamente a cópia do lado de templates.

provider terraform: os artefatos são arquivos de configuração do Terraform, emitidos literalmente no diretório próprio do componente sob a árvore modules/ da boundary. HCL (main.tf) é o padrão mais ergonômico e Terraform JSON (.tf.json) é aceito de forma equivalente; nenhum dos dois é transpilado ou reformatado. A configuração raiz da boundary declara esse componente como um bloco module cujo source aponta para esse diretório, de modo que uma boundary inteira continua sendo um único grafo de dependências; é o mesmo diretório que os arquivos de um módulo vendorizado ocupam, então uma Recipe que declara tanto source: quanto artifacts: os grava lado a lado. A procedência segue como um bloco de comentários do Terraform no início; quando um componente contribui com um corpo JSON, que não tem sintaxe de comentário, cada corpo é emitido sem alterações e a procedência segue em um arquivo .tf complementar, só com comentários, ao lado deles, de modo que o carimbo nunca é duplicado entre os dois. Veja a página do provider terraform.

provider cloudformation: os artefatos são fragmentos de stack — os recursos com que um componente contribui, em vez de um template inteiro. O provider normaliza cada fragmento para funções intrínsecas em forma longa em JSON puro e o mescla na única stack montada para esse diretório de saída, onde os recursos se juntam em um único mapa Resources e os provides do componente aparecem como Outputs da stack sob nomes restritos ao componente que os publica. Quais outras seções de nível superior de um fragmento sobrevivem à montagem é explicado em O que um documento mesclado leva de artifacts:. Veja a página do provider cloudformation.

O escopo da boundary: arquivos para a saída compartilhada de uma boundary

O mecanismo de artefatos tem um segundo escopo. Tudo o que foi descrito acima é gravado na posição própria do componente na saída da sua boundary; o spec.boundary.artifacts de uma Recipe é o mesmo mapa — as mesmas três formas, a mesma regra de chave para nome de arquivo, o mesmo contexto de template — gravado, em vez disso, uma única vez para a boundary como um todo. Ele existe para um arquivo que o destino lê uma única vez para tudo o que uma boundary implanta, e que nenhuma posição própria de um componente consegue conter: a documentação do Terraform diz que um módulo destinado a ser chamado não deve conter blocos provider, e um módulo que os contém não pode ser chamado com depends_on, count ou for_each; por isso, a configuração de um provider pertence à configuração raiz da boundary, e não ao módulo de um componente.

Onde ele vai parar. No diretório que contém a saída montada do grupo de despacho, ao lado dos arquivos que a montagem própria do provider grava ali — no terraform, ao lado da configuração raiz. O compilador avalia cada entrada uma vez por componente que a Recipe renderiza, com o contexto desse componente, e grava o arquivo ele mesmo: nenhum desses arquivos é entregue ao provider, e nada é carimbado neles para dizer de qual componente vieram, porque pertencem a todos os contribuidores que os declararam.

Como os contribuidores se encontram. Os arquivos declarados por cada contribuidor de um mesmo grupo de despacho são mesclados por nome. Um nome declarado com bytes idênticos é um único arquivo; um nome declarado com bytes diferentes, ou um nome que a própria montagem do provider grava, interrompe o build nomeando o arquivo e cada contribuidor — a mesma recusa que dois contribuidores gravando um mesmo caminho de saída encontram. Assim, uma configuração de provider de que duas Recipes precisam é gravada por ambas sob um mesmo nome, e o build verifica se elas coincidem.

Quem o aceita. Se um arquivo colocado ao lado da saída montada de uma boundary significa algo é uma propriedade do destino do provider, então é uma declaração do próprio provider, lida da declaração do próprio provider como seus tipos de entrada. Uma Recipe que declara o bloco para um provider que não o declara é recusada antes de qualquer renderização. A tabela abaixo traz essa declaração na última coluna; dos providers distribuídos com o compilador, o terraform a faz.

O que os artefatos não são

Três distinções estruturais:

Não são multi-provider dentro de uma única Recipe. Uma Recipe declara exatamente uma capability: no início da sua spec. Tudo o que a Recipe produz — saída renderizada a partir do source, saída sintetizada a partir do workload e emissões de artefatos — está no formato nativo desse provider. Os artefatos de uma Recipe helm contêm YAML do Kubernetes. Os artefatos de uma Recipe compose contêm fragmentos de compose. Uma Recipe tem como alvo um único provider; toda saída está no formato nativo desse provider.

A composição multi-provider acontece no nível da Release. As boundaries contêm componentes com providers mistos; os contribuidores de cada provider no caminho avaliado de uma boundary são despachados e montados de forma independente por (caminho, provider). Uma Release com componentes voltados respectivamente para helm, helm-chart e compose pode colocar os três em uma mesma boundary; o agrupamento de despacho os particiona por provider, os contribuidores de cada provider vão parar em sua própria saída montada sob o caminho da boundary, e o operador escreve a coordenação entre providers por meio da estrutura de boundaries que escolher. A coordenação entre providers é responsabilidade do autor da Release.

Não são Recipes dentro de Recipes. Os artefatos não carregam nem compõem outras Recipes. São manifestos inline (ou caminhos de arquivo para manifestos inline), processados como template com os pilares desta Recipe e emitidos para a saída desta Recipe. A reutilização de uma Recipe acontece por meio de três mecanismos: o extends: de um Component (uma Recipe escrita para um Component base atende a todo Component que o estende; o que é herdado são metadados e esquemas, não arquivos de saída — uma Recipe em si não declara nenhum extends:); o mapeamento de URI planos do Manifest (o mesmo Component pode ser resolvido para Recipes diferentes em catálogos diferentes — veja ../language-reference/entities/manifest.md); e Features + FeatureRecipes (preocupações transversais anexadas de forma ortogonal).

Não são uma camada de ligação entre Recipe. Os artefatos não podem referenciar nomes, recursos ou estado que a própria Recipe não tenha declarado. Um artefato ConfigMap referenciado pelo Workload da Recipe precisa ser emitido por esta Recipe. Um artefato que espera um Secret provisionado externamente precisa obter o nome desse Secret pelo pilar .features — a partir dos provides resolvidos do anexo que o emite — em vez de supor que ele existe. Esse é o invariante de autocontenção (acima) formulado do ponto de vista da escrita de artefatos: cada Recipe emite arquivos em um único formato, aplicados por uma única ferramenta, no diretório de saída de uma única boundary.

Matriz de capacidades por Provider

Cada provider declara quais tipos de entrada renderiza; um controle central de tipos de entrada aceita as combinações suportadas e rejeita as demais com um diagnóstico uniforme quando o nó é renderizado. A capacidade é uma propriedade do provider, não da Recipe — um provider renderiza um subconjunto dos três tipos. A coluna artifacts: distingue os artefatos que acompanham ao lado uma entrada principal sourced/synthesized de uma Recipe independente composta só de artefatos (sem source:, sem workload:). As duas últimas colunas são as declarações do provider de que respeita omits: e de que aceita os arquivos com que uma Recipe contribui para a saída compartilhada da sua boundary em boundary.artifacts: (acima); nenhuma das duas é um tipo de entrada.

Leia cada coluna isoladamente. Uma linha diz quais tipos um provider renderiza, tomados um de cada vez. Ela não diz que dois tipos marcados podem ser declarados juntos. Como os tipos se compõem por adição, cada tipo declarado é despachado e emitido separadamente, de modo que um par pode ser recusado por um motivo que nenhuma das duas colunas registra — na maioria das vezes porque os dois tipos produzem um arquivo com o mesmo nome de saída. Quais combinações cada provider realmente aceita é descrito em prosa em O que cada provider aceita, por completo.

Providersource: + valuesMapping:workload:artifacts: (ao lado)somente artefatos (independente)omits:boundary.artifacts:
helm✅✅✅✅✅❌
compose✅✅✅✅✅❌
helm-chart✅❌✅ processado como template com os delimitadores [[ ]]❌❌❌
terraform✅❌✅✅❌✅
cloudformation✅❌✅✅✅❌

Esta tabela cobre os providers distribuídos com o compilador. Um provider fornecido separadamente declara da mesma forma os tipos de entrada que aceita, se respeita omits: e se aceita boundary.artifacts:, e o compilador lê essa declaração pelo mesmo caminho — ele não está listado aqui porque uma página publicada não pode enumerar providers que nunca viu.

As células marcadas com ✅ são renderizadas; ❌ é uma recusa por capacidade do provider sinalizada pelo controle. Os fragmentos de compose por nó são mesclados por caminho de montagem, de modo que boundaries que compartilham um directory: compartilham um único arquivo.

O que cada provider aceita, por completo

helm — todas as combinações. source: + valuesMapping:, workload:, artifacts:, quaisquer dois deles, ou os três. É o único provider distribuído com o compilador que não recusa nenhuma combinação, e o motivo é a forma como nomeia a saída: cada arquivo emitido recebe o nome do recurso que contém, de modo que os manifestos renderizados de um chart e os manifestos de um Workload sintetizado nunca vão parar sob um mesmo nome. Uma Recipe que declara os três emite os arquivos do chart, os arquivos do Workload e os arquivos de artefatos lado a lado no diretório de saída da boundary.

compose — todas as combinações, exceto as duas em que source: e workload: aparecem juntos. Cada tipo sozinho é construído, e artifacts: pode acompanhar qualquer um dos dois. source: com workload: não pode ser construído, nem os três juntos; Por que compose não pode combinar um source com um workload explica o motivo, e não se trata de uma recusa por capacidade.

helm-chart — source: + valuesMapping:, sozinho ou com artifacts: ao lado. Nada mais. Ele não sintetiza um workload: e não tem uma forma composta só de artefatos: uma Recipe cujo único tipo de entrada é artifacts: é interrompida. O motivo é onde esse provider coloca um artefato — dentro do chart próprio do componente — de modo que uma Recipe sem source: não lhe deixa nenhum chart onde colocá-lo.

terraform — três formas: source: + valuesMapping: sozinho, artifacts: sozinho, ou os dois juntos. Ele não sintetiza um workload:.

cloudformation — as mesmas três formas que terraform, com a mesma única exclusão. source: + valuesMapping: sozinho, artifacts: sozinho, ou os dois juntos; sem workload:.

Como é um tipo de entrada recusado

Uma Recipe que declara um tipo de entrada que o provider ao qual está vinculada não renderiza interrompe o build quando o nó é renderizado, e o interrompe independentemente do que mais a Recipe declare junto com esse tipo — combinar um workload: com um source: que o provider consegue renderizar não faz o workload passar. A interrupção nomeia o provider, o tipo que ele não consegue renderizar e os tipos que ele renderiza:

[CATALOG_ERROR E0265] instance unit
provider does not support the node's input kind (node "unit"). provider "terraform" does not support synthesized recipes (this provider supports: sourced, artifacts-only); declare one of the supported input kinds, or target a provider that supports synthesized

A recusa da forma composta só de artefatos é lida da mesma maneira e nomeia essa forma: provider "helm-chart" does not support artifacts-only recipes (this provider supports: sourced). E0265 é o identificador a registrar quando essa interrupção precisa ser nomeada de forma duradoura — em um controle de integração contínua, em uma issue ou em um runbook; a tabela de todas as condições o resolve.

Por que compose não pode combinar um source com um workload

O provider compose produz um fragmento por componente e dá a esse fragmento o nome do componente. A renderização a partir de um source e a síntese do Workload produzem, cada uma, o fragmento desse componente sob esse único nome, de modo que uma Recipe que declara os dois produz dois arquivos com o mesmo nome, e o build é interrompido pela colisão:

[CATALOG_ERROR E0211] instance unit
rendering node "unit"
caused by: [CATALOG_ERROR] aggregate.yaml at .spec.components.unit
filename collision across input kinds: two input-kind blocks produced a file under one output name (output name "unit.compose-fragment.yaml", produced by "source, workload")

O nome do fragmento vem do identificador próprio do componente e não há nenhuma superfície de escrita para ele, de modo que nenhuma alteração no conteúdo da Recipe evita a colisão. A interrupção é uma propriedade do par, e não de qualquer um dos tipos — o compose renderiza um source, o compose sintetiza um Workload, e a tabela está certa em marcar os dois. Para usar as duas formas em um componente com compose, divida-as entre dois componentes ou incorpore o conteúdo do source ao Workload.

O que um documento mesclado leva de artifacts:

Dois providers mesclam seus contribuidores em um único documento por caminho de montagem: compose em um único docker-compose.yaml, cloudformation em um único template de stack. Um documento mesclado só pode conter as seções que seu montador modela, então uma marca em artifacts: diz onde o conteúdo de um fragmento é colocado, e não que cada chave dentro do fragmento sobrevive.

compose leva services:, volumes:, configs: e models: de um fragmento de artefato, junto com suas chaves de extensão com o prefixo x-. Um fragmento que declara qualquer outra coisa no nível superior interrompe o build, nomeando a chave — networks:, porque as redes são derivadas por boundary em vez de acumuladas a partir dos contribuidores, e igualmente um bloco secrets: ou um name: de nível superior. A página do provider compose traz as regras de mesclagem por chave e a alternativa para o roteamento entre redes.

cloudformation leva Resources, Outputs, Parameters, Mappings, Conditions, Metadata e Rules, e constrói Transform a partir dos de cada contribuidor. As transformações são unidas na ordem que o CloudFormation documenta, com os Globals do SAM acompanhando a transformação que os lê, e uma transformação que mudaria a forma como o conteúdo de outro contribuidor é implantado interrompe o build nomeando-a. Description não é levada, e o build avisa: ele emite um aviso de campo não suportado que nomeia a seção e o componente, assim como para qualquer outra chave de nível superior que a stack não leva, de modo que nada é descartado silenciosamente. O aviso é informativo — o template emitido é idêntico byte a byte ao que seria sem ele, e --no-unsupported-field-warnings silencia essa classe. Outputs é levado sob um nome que o provider restringe ao componente contribuidor, de modo que dois componentes que contribuem para uma mesma stack com uma saída de mesmo nome as mantêm separadas. Seções de nível superior na stack montada explica cada seção, uma a uma.

Os outros três providers não mesclam, então nenhuma chave de artefato corre o risco de ser descartada por um montador. helm não monta nada: os manifestos de cada componente chegam ao diretório de saída da boundary tal como são. terraform e helm-chart aninham — os arquivos de cada componente vão parar em um diretório próprio, um diretório de módulo do Terraform ou um subchart, e um documento raiz na boundary os referencia — de modo que uma entrada de artefato é colocada como um arquivo inteiro em vez de lida dentro de um documento compartilhado. Onde uma entrada de artefato do helm-chart vai parar, e por que seu par de delimitadores é diferente, é explicado em Semântica dos artefatos por Provider.