Composição das entradas de uma Recipe — três tipos de entrada, Workload, artefactos
Uma Recipe produz ficheiros de manifesto para o seu provider de destino. Este capítulo aborda a forma como as Recipes compõem a sua saída a partir de três tipos de entrada ortogonais — sourced, synthesized e artifacts —, como cada tipo de entrada está estruturado e que provider produz que saída. O papel conceptual da entidade Recipe (o template de tradução escrito pela equipa de Ops que mapeia a intenção do programador para um único provider físico) está em 04-entity-taxonomy.md; a superfície de autoria da Recipe ao nível das palavras-chave está em ../language-reference/entities/recipe.md.
Fundamentação
A ferramenta de renderização nativa de cada provider — Helm, Docker Compose — já sabe renderizar manifestos nativos do provider. A função de uma Recipe é declarar O QUE esses manifestos devem dizer: que imagens de contentor, que portas, que variáveis de ambiente, que volumes, que serviços, que limites de recursos.
Uma Recipe tem de exprimir mais do que aquilo que um conjunto fixo de chaves (por exemplo, image, environment, ports, replicas) mapeado sobre um Deployment e um Service consegue conter, nomeadamente:
resources(pedidos/limites de CPU/memória)- Sondas de liveness, readiness ou startup
volumeMounts/volumesnodeSelector/affinity/tolerationsserviceAccount/securityContext- Pods com vários contentores, sidecars
- Recursos ConfigMap / Secret / PVC / CRD
- Services que não são ClusterIP (LoadBalancer, NodePort, Headless)
A camada de abstração precisa de descrever a forma completa de uma carga de trabalho, não um conjunto fixo de chaves. Os três tipos de entrada descritos abaixo são essa abstração: uma Recipe compõe a 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 provider sintetiza em manifestos nativos do provider (workload:) e de manifestos nativos do provider em template que a Recipe emite diretamente (artifacts:).
Os três tipos de entrada
Composição por adição
Há três formas de produzir ficheiros de manifesto nativos do provider a partir de uma Recipe, e compõem-se por adição e não por exclusão mútua:
source:— um artefacto carregado externamente (chart Helm, ficheiro compose) que o provider renderiza nativamente, comvaluesMapping:a fornecer os valores de sobreposição.workload:— uma especificação abstrata de Workload (tipo detido pela plataforma) que o provider sintetiza em manifestos nativos do provider. O campo aceita um block scalar YAML inline ou um$import:para um único ficheiro local ou entrada de biblioteca; o despacho é determinado pela forma do conteúdo.artifacts:— um mapa de manifestos nativos do provider inline ou carregados por$import:, processados como templates Go sobre o contexto completo dos pilares. Cada entrada pode ser escrita inline (o valor da entrada é um block scalar) ou via$import:para um único ficheiro ou conteúdo de biblioteca.
Os três produzem ficheiros que o compilador emite para o diretório de saída da fronteira. Os três podem coexistir numa única Recipe, sujeitos às regras de validação abaixo. A semântica de fusão é apenas de nível superior: cada tipo de entrada produz ficheiros completos; os ficheiros são emitidos lado a lado; uma colisão de nome de ficheiro de saída é um erro fatal.
Nomes descritivos dos modos
Os três «modos» são vocabulário descritivo para a documentação e os diagnósticos. Os autores de Recipes não declaram um modo; escrevem as palavras-chave de que precisam. Uma Recipe caracteriza-se pela sua entrada dominante:
| Palavra(s)-chave dominante(s) | Nome descritivo do modo |
|---|---|
source: + valuesMapping: (sem workload:, sem artifacts) | sourced |
workload: (sem source:, sem artifacts) | synthesized |
artifacts: (sem source:, sem workload:) | artifacts-only (informalmente: «inline») |
| Qualquer combinação de dois ou mais | descrito explicitamente (por exemplo, «sourced com artifacts», «synthesized com artifacts») |
Não existe nenhuma palavra-chave chamada mode: nem nenhum enum. O modo é uma propriedade emergente das entradas que estão presentes.
A forma de uma Recipe num relance
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: ... version: 1.0.0spec: 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 contentTodos os campos acima são aceites pelo esquema 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 provider — que provider renderiza que tipo de entrada —, registado na Matriz de capacidades de Provider no fim deste capítulo.
Regras de validação no carregamento
O esquema da Recipe e a validação no carregamento impõem estas regras de composição:
valuesMapping:requersource:. Sem umsource:sobre o qual sobrepor, não há nada para receber os valores mapeados. Uma Recipe comvaluesMapping:e semsource:é um erro no carregamento. (Umsource:semvaluesMapping:é permitido — o chart ou módulo é renderizado com as suas próprias predefinições.)workload:aceita uma fonte — inline ou$import:, não ambas. Uma Recipe especifica o Workload como um block scalar inline ou como um$import:para um único ficheiro. A forma$import:é de fonte única segundo o vocabulário unificado de importação de ficheiros; a fusão de várias fontes não é suportada emworkload:. Erro no carregamento num despacho malformado.workload:requer um provider capaz de síntese. O suporte de síntese é uma propriedade do próprio provider, não de qualquer campo declarado. Uma Recipeworkload:associada a um provider que não consegue sintetizar é rejeitada quando o nó é renderizado — através da barreira de capacidades do provider (ver a Matriz de capacidades de Provider) — com um diagnóstico claro. O catálogo da biblioteca padrão declaraworkloadSchemanos providers capazes de síntese por convenção, como o contrato de tradução documentado, mas a barreira baseia-se na capacidade reportada pelo próprio provider e não na presença desse campo.- Tem de estar presente pelo menos um tipo de entrada. Uma Recipe sem nenhum de
source:+valuesMapping:,workload:ouartifacts:não produz saída e é um erro no carregamento. - As entradas de artefactos inline e
$import:podem coexistir. Uma Recipe pode declarar algumas entradas deartifacts:inline e outras através de diretivas$import:por entrada. A chave de cada entrada nomeia a sua própria saída, pelo que as entradas das duas formas nunca colidem entre si (ver O que dá nome a cada ficheiro de saída). - As colisões de nomes de ficheiro entre tipos de entrada são erros na renderização. Se dois dos tipos de entrada de uma Recipe — saída renderizada a partir da source, saída sintetizada a partir do workload ou saída emitida a partir de artefactos — produzirem um ficheiro com o mesmo nome, o compilador emite um erro fatal que identifica todos os contribuidores. Esta verificação corre depois da tradução do Workload, pelo que ocorre na renderização e não no carregamento.
O tipo Workload
Propriedade e localização
Workload é um tipo detido pela plataforma em apiVersion: aggrega.ai/v1beta1. A sua declaração JSON Schema 2020-12 está incorporada no binário do compilador no momento do build; os autores de catálogos não editam o esquema do Workload, nem escrevem ficheiros YAML Workload autónomos 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 ficheiro ou uma entrada de WorkloadLibrary) e em mais nenhum lado.
O 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. Do mesmo modo, uma FeatureRecipe declara no máximo um workload: próprio — uma unidade de computação detida pela Feature, sintetizada através do mesmo tipo Workload —, ver FeatureRecipe. Os casos de uso que exigem cargas de trabalho laterais adicionais exprimem-se através 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 laterais transversais (por exemplo, um sidecar de cópia de segurança associado a bases de dados) declaradas como entidades de catálogo separadas, em que a FeatureRecipe sintetiza o seu próprio
workload:(ou renderiza viasource:/artifacts:). Ver 14-extensibility.md para a geração de recursos da FeatureRecipe.
Isto 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 o repetir aqui, onde uma cópia ficaria desatualizada em relação ao contrato sem que nada o assinalasse, este capítulo aponta para as duas superfícies que o contêm na íntegra:
- A referência gerada do esquema do Workload — cada campo, o seu tipo, a sua predefinição e as suas restrições, gerada a partir do JSON Schema publicado e comparada com ele em cada build, pelo que não pode descrever uma forma que o compilador não aceite.
- A página de autoria do Workload — orientações de autoria ao nível do campo: o que cada campo significa, em que cada provider o renderiza e que combinações o build recusa.
A declaração JSON Schema 2020-12 do Workload é autoritativa e é disponibilizada incorporada no binário do compilador. Os providers helm e compose sintetizam o workload: de uma Recipe, inline ou carregado via $import:; ver a Matriz de capacidades de Provider para o suporte por provider.
Integração de segredos com featuresSchema
O bloco containers.<name>.attachments do Workload referencia slots declarados pelo featuresSchema do Component; não declara novos slots. Ver ../language-reference/entities/component.md para a superfície de autoria do featuresSchema.
O contrato de validação:
- Cada valor
attachments.<KEY>.fromtem de corresponder a um nome de slot declarado nofeaturesSchemado Component — ou, para uma entrada que nomeie uma ligação comconnection: <alias>, a um slot que o socket dessa ligação declara emusesSchema.<socket>.featuresSchema. Essa entrada é reescrita para o nome que a associação da ligação assume no componente (<alias>.<slot>) antes de qualquer destas regras ser aplicada, pelo que cada regra abaixo a lê tal como lê uma entrada que nomeia o próprio slot do Component. - O mecanismo de entrega
as:(envoufile) tem de constar da lista de permissões do arrayinject:desse slot. - Os slots marcados como
inject: [](caixa negra) nofeaturesSchemado Component não podem aparecer em blocosattachments:do Workload — esses slots são entregues pela canalização interna da Recipe (por exemplo, viaexistingSecretdo Helm), não através da exposição do Workload.
Exemplo:
# In the Componentspec: featuresSchema: db_password: required: true inject: [env, file] # transparent: Workload may dictate delivery root_password: required: true inject: [] # blackbox: Recipe handles internally
# In the Recipeworkload: | containers: main: attachments: DB_PASSWORD: # OK — db_password slot allows env inject from: db_password as: env # ROOT_PASSWORD: ... # rejected — root_password is blackboxSondas de saúde: intenção, não mecanismo
As sondas do Kubernetes e os healthchecks do Docker Compose têm formas diferentes. Uma única forma de intenção abstrata traduz-se de forma 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: 10Os Providers traduzem cada intenção para a sua forma nativa:
| Intenção | Helm (K8s) | Compose |
|---|---|---|
http: /path | httpGet.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 da porta para http: sem uma porta explícita usa o primeiro nome de porta, por ordem alfabética, que o contentor declara em containers.<name>.ports, em ambos os destinos. Um contentor que não declare nenhuma porta com nome não pode ter uma sonda HTTP, e o build interrompe-se nomeando a sonda.
O Compose degrada as sondas HTTP/TCP para comandos shell de healthcheck, e um serviço compose contém um único healthcheck: quando é declarada mais do que uma sonda, uma é traduzida e um aviso nomeia as descartadas.
Tipos de volume
Cinco tipos de volume; nenhum composto:
| Tipo | Semântica | K8s (helm) | Compose |
|---|---|---|---|
ephemeral | Tmpfs / emptyDir; desaparece com o pod | emptyDir: { sizeLimit } | montagem tmpfs:, sem tamanho (um aviso reporta um sizeLimit escrito pelo autor) |
configmap | Ficheiros de configuração só de leitura | Referência a volume ConfigMap | referência configs: ao nível do serviço a uma configuração de nível superior que os artifacts: da Recipe declaram |
secret | Ficheiros de segredos só de leitura | Referência a volume Secret | ficheiro de segredo só de leitura montado por bind |
persistent | PVC único; sobrevive a reinícios do pod | Recurso PVC + volume.persistentVolumeClaim | volume com nome |
persistentTemplate | PVC por réplica; complemento de form: stateful | StatefulSet.volumeClaimTemplates | volume com nome (degradado; é emitido um aviso) |
O Compose não consegue exprimir templates por réplica. Quando persistentTemplate é traduzido para compose, degrada-se para um único volume com nome partilhado por todas as réplicas, e um aviso reporta a degradação. Um volume persistentTemplate requer 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: 9901Cada um torna-se um objeto Service do Kubernetes separado quando renderizado pelo provider helm, que, em vez disso, interrompe o build perante uma entrada Loopback. No compose, os serviços NodePort e LoadBalancer publicam as suas portas em todas as interfaces do host do serviço compose, os Loopback apenas no endereço de loopback do host, e os ClusterIP e Headless não publicam nada.
Os nomes dos serviços na saída K8s têm como prefixo o instance_id do componente, para garantir unicidade. Os nomes das portas têm de corresponder aos nomes das portas de contentor declarados em containers.<name>.ports.
Contrato de tradução do lado do Provider: workloadSchema
Um Plugin de renderização de provider (pluginType: provider) declara um spec.provider.workloadSchema — uma declaração JSON Schema 2020-12 que documenta como os campos do Workload se traduzem na saída nativa desse provider. Este é o contrato de tradução autodocumentado. Ver ../language-reference/entities/plugin.md para a superfície de autoria do Plugin, incluindo o bloco spec.provider.
apiVersion: aggrega.ai/v1beta1kind: Pluginmetadata: name: helm-renderer version: 1.0.0 pluginType: providerspec: 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álogos e às ferramentas de IDE. É o contrato de tradução documentado, declarado por convenção nos providers que sintetizam — mas o suporte de síntese é determinado pelo próprio provider, não pela presença deste campo. Uma Recipe que vise um provider que não consegue sintetizar com workload: é rejeitada quando o nó é renderizado — através da barreira de capacidades do provider — com um erro claro, quer o provider declare workloadSchema quer não.
O esquema do Plugin declara spec.provider.workloadSchema — o seu corpo é compilado para JSON Schema 2020-12 quando o Plugin é carregado — e o consumo de workload: do lado da Recipe é disponibilizado. O suporte de síntese é imposto na renderização pela barreira de capacidades do provider, com base na capacidade reportada pelo provider associado; workloadSchema é o contrato documentado que o catálogo da biblioteca padrão mantém sincronizado com essa capacidade, não sendo ele próprio a entrada da barreira. O aggrega validate, executado sobre todo o catálogo, assinala adicionalmente, logo de início e antes de um build, uma Recipe workload: associada a um provider que não sintetiza, quando o catálogo contém a entidade Plugin desse provider.
Os recursos auxiliares vivem fora do Workload
A especificação do Workload não tem nenhum campo additionalResources, nenhum extras, nenhuma declaração inline de ConfigMap/Secret/CRD. O Workload modela apenas a forma da carga de trabalho: contentores, volumes, serviços, réplicas, escalonamento, contexto de segurança, conta de serviço — tudo o que descreve como corre a única unidade de computação.
Os recursos auxiliares têm dois lugares legítimos fora do Workload:
- Features + FeatureRecipes — o mecanismo para preocupações transversais. Um ServiceMonitor associado a «qualquer servidor com métricas expostas» é
core/prometheus-exportercomo Feature. O recurso de encaminhamento que publica um servidor num hostname também é uma Feature, e é a forma de encaminhamento que decide qual:core/public-ingressquando o destino reconcilia um Ingress,core/http-routequando executa a Gateway API — cada uma realizada por uma FeatureRecipe que o Manifest seleciona por Release. Uma NetworkPolicy imposta em todas as cargas de trabalho de produção é uma Feature que a Release de produção associa a toda a fronteira. As Features compõem-se ortogonalmente e podem ser reutilizadas entre Recipes. Ver 14-extensibility.md para a geração de recursos da FeatureRecipe. artifacts:ao 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 registo 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 por$import:; ver a secção O mecanismo de artefactos abaixo.
A linha entre Feature e artefacto é uma convenção social. Se um recurso auxiliar é transversal (aplica-se a muitas Recipes, ou é associado condicionalmente através de seletores), é uma Feature. Se é intrínseco a esta Recipe (a Recipe não consegue fazer o seu trabalho sem emitir esse recurso), é um artefacto. Os autores escolhem com base na reutilização e na semântica de associação; o compilador não fiscaliza a escolha.
As Features e os artefactos de Recipe cobrem, em conjunto, os recursos auxiliares de que uma Recipe precisa.
O mecanismo de artefactos
Artefactos inline e carregados de ficheiros
O tipo de entrada artifacts emite ficheiros de manifesto nativos do provider em template diretamente para a saída da fronteira, ao lado de qualquer saída renderizada a partir da source ou sintetizada a partir do workload. Os autores declaram-no através 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.yamlOs caminhos de $import: são relativos ao diretório da Recipe e têm de permanecer dentro dele, porque cada ficheiro que uma publicação da Recipe transporta é tirado desse diretório — cada ficheiro que uma importação nomeia viaja com ela — e um ficheiro fora dele não viajaria. Uma convenção típica coloca-os num subdiretório ./artifacts/, embora o compilador não o imponha. A chave do mapa nomeia cada ficheiro emitido — a secção seguinte explica o que isso significa em cada uma das três formas.
Cada entrada (inline ou carregada por $import:) é processada como template Go sobre o contexto de template completo antes de ser emitida para o diretório de saída.
O que dá nome a cada ficheiro de saída
O mapa tem como chave o 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 ficheiro 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 ficheiro; onde o ficheiro fica é decisão do destino, e a secção sobre a emissão por provider abaixo trata disso.
Para uma entrada $import: de ficheiro, a chave também é o nome do ficheiro de saída. O ficheiro importado fornece o conteúdo; não fornece o nome, pelo que um autor que queira um nome de ficheiro 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.yamlProduz .../monitor.yaml e .../netpol.yaml. O ficheiro importado da segunda entrada chama-se some-other-name.yaml, e esse nome não chega à saída — a chave sim. Duas entradas que importam ficheiros diferentes que por acaso partilham um nome, ./extras/shared.yaml e ./overrides/shared.yaml, são, portanto, duas saídas distintas, cada uma nomeada pela sua própria chave.
Para uma entrada $import: de biblioteca, que traz um pacote de ficheiros como uma única unidade, a entrada expande-se numa saída por cada ficheiro do pacote, cada uma aninhada sob a chave como <key>/<filename>. Uma chave nomeia muitos ficheiros, pelo que a chave sozinha não os pode nomear: é o diretório onde ficam os ficheiros do pacote e não o nome de nenhum deles.
Como todas as formas nomeiam a sua saída a partir da chave, a chave está limitada, na superfície de autoria, ao que um único nome de ficheiro pode ser: uma letra ou um dígito inicial, seguido de letras, dígitos, pontos, hífenes e underscores. Os pontos transportam a extensão que um consumidor espera, o que permite usar uma chave diretamente como nome de ficheiro; e o alfabeto não contém / nem um . inicial, pelo que uma chave nunca pode formar mais do que um segmento de caminho nem ser o segmento do diretório pai. Uma chave fora do alfabeto falha a validação do envelope no carregamento do workspace, em aggrega validate e nos diagnósticos do editor.
Duas saídas de artifacts: com o mesmo nome de ficheiro interrompem o build quando o nó é renderizado, quaisquer que sejam as formas que as produziram. Duas entradas de um mesmo mapa artifacts: nunca nomeiam uma mesma saída: uma chave é única num documento e é um único nome de ficheiro, pelo que o nome de saída de uma entrada de ficheiro ú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 cada caminho emitido é, portanto, a chave que o produziu, e chaves distintas continuam a ser nomes de saída distintos. O que a interrupção abrange é o caso que atravessa tipos de entrada — um nome de ficheiro contribuído por dois deles, um template de chart e uma entrada de artefacto que produzem ambos servicemonitor.yaml — com um diagnóstico que nomeia todas as origens contribuintes.
Contexto de template para artefactos
Os templates de artefactos têm acesso ao contexto completo dos pilares:
.values,.infra,.context.*,.locals,.provides,.features,.metadata— os pilares habituais do Aggrega descritos em 06-data-taxonomy-and-composition.md..workload— a especificação do Workload analisada para esta Recipe (se existir). Permite que os artefactos referenciem valores do Workload sem duplicação, por exemplo, um ServiceMonitor que referencia.workload.services.metrics.ports.prom..source— o conteúdo resolvido do camposource:(se existir).
Os artefactos são avaliados depois de o Workload ser analisado, pelo que .workload está disponível quando existe. 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 artefactos têm de ser autocontidos. Só podem referenciar as entradas declaradas da Recipe: o contexto dos pilares, o próprio Workload da Recipe (quando existe) e o próprio valor source: da Recipe. Não podem referenciar:
- As saídas de outras Recipes na mesma fronteira.
- Recursos ambientes do Kubernetes que a Recipe não declarou.
- Secrets, ConfigMaps ou outros recursos que se assume existirem externamente (a menos que sejam referenciados através de um pilar declarado).
Um artefacto ConfigMap referenciado pelo volumes.*.configmap.source do Workload tem de ser emitido por ESTA Recipe (através de artifacts: que produza esse ConfigMap) ou por uma Feature associada a este nó. As dependências entre Recipes dentro de uma fronteira não são suportadas.
Esta invariante preserva a reutilização das Recipes: uma Recipe pode ser colocada em qualquer combinação Aggregate + Release que satisfaça o seu contrato de pilares, sem dependências ocultas.
Etiquetas de proveniência
Após a tradução, cada ficheiro emitido transporta proveniência aggrega.ai/* nos seus metadados — quer tenha sido renderizado a partir da source, sintetizado a partir do workload ou emitido a partir de um template de artefacto. Todas as superfícies de emissão a carimbam a partir de um mesmo conjunto partilhado de construtores, pelo que o mesmo ficheiro transporta sempre a mesma proveniência, qualquer que seja o tipo de entrada que o produziu. O conjunto divide-se consoante um valor satisfaça ou não o conjunto de caracteres dos valores de etiqueta do Kubernetes: as chaves seguras para etiquetas são etiquetas (consultáveis); as chaves não seguras — recipe-uri (contém um :), boundary-path (um caminho aninhado contém /) e sync-wave (o - inicial de uma onda negativa) — são anotações, cujos valores não têm restrições. Um valor de identidade que o build não sujeita às regras das etiquetas — o nome do agregado, o ambiente, o nome do fornecedor, as versões do compilador e do fornecedor — é uma etiqueta escrita numa forma que uma etiqueta 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 a etiqueta imported-flow e a anotação imported/flow). Todos os ficheiros que transportam a saída de uma mesma Recipe partilham 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: productionEsta divisão é uniforme nos três tipos de entrada. (O provider Compose não tem o conceito de anotação e os seus valores de etiqueta não têm restrições, pelo que emite todo o conjunto como etiquetas de serviço.) Ver 11-governance-and-compliance.md para o carimbo de proveniência em tempo de compilação.
Como um provider carimba a proveniência onde o seu próprio formato de saída a transporta, um provider cujo formato não oferece esse lugar para um dado ficheiro emite esse ficheiro inalterado e di-lo. O Compose é o caso a conhecer: o seu lugar de proveniência é o bloco labels: de um serviço, pelo que um fragmento de artefacto compose que contribua apenas com volumes:, configs: ou models: de nível superior não transporta proveniência, e o build emite um aviso «skipped provenance label injection (injeção da etiqueta de proveniência ignorada)» que nomeia o artefacto. Esse aviso é esperado para um fragmento com essa forma e não é sinal de problema — os serviços que o mesmo componente emite transportam o conjunto completo, e nada nos bytes emitidos muda. O que exclui é a terceira possibilidade: um ficheiro sair do build sem carimbo sem ser nomeado.
O CloudFormation é o outro caso a conhecer, e difere em onde a proveniência fica e não em se fica. Um template CloudFormation não transporta nenhum bloco de metadados ao nível do documento que acompanhe um recurso, pelo que a proveniência vai para o atributo Metadata próprio de cada recurso, sob uma única chave aggrega.ai/provenance que contém todo o conjunto:
"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" } }}Desse lugar decorrem três propriedades. O atributo Metadata está disponível em todos os recursos, qualquer que seja o seu tipo, pelo que todos os recursos que uma stack montada transporta são carimbados — incluindo os muitos tipos de recursos que não aceitam quaisquer tags, nos quais um carimbo baseado em tags não teria lugar. O carimbo é acrescentado a qualquer Metadata que o autor tenha escrito, em vez de o substituir, pelo que as entradas do próprio autor ficam ao lado dele. E, por ser por recurso e não por template, uma stack em que vários componentes se montam transporta a identidade contribuinte de cada recurso — o seu componente, a sua Recipe e a sua fronteira —, o que uma única entrada para todo o template não conseguiria exprimir.
Todo o conjunto viaja junto sob essa chave. Um valor Metadata é JSON sem restrições, pelo que não há divisão por conjunto de caracteres a fazer; as duas chaves que só um runtime Kubernetes lê — o nome normalizado da etiqueta recomendada e a anotação de ordenação da implementação que um controlador GitOps consome — ficam de fora, dado que nenhuma delas nomeia nada numa stack. A entrada de proveniência simples aggrega.ai/sync-wave mantém-se, porque regista a onda que o componente declarou em vez de dar instruções a um controlador.
A forma que aqui não tem lugar é um template ou fragmento que não declara nenhum recurso — um que contribua apenas com Parameters, Mappings, Conditions ou Rules. Não transporta proveniência, chega à stack montada com o seu próprio conteúdo intacto, e o build emite um aviso «skipped provenance injection (injeção de proveniência ignorada)» que o nomeia. Tal como no compose, esse aviso é esperado para uma contribuição com essa forma: os recursos que o mesmo componente contribui noutros sítios transportam o conjunto completo, e os bytes emitidos são os mesmos quer alguém esteja ou não a ouvir.
Semântica dos artefactos por Provider
A semântica por provider abaixo descreve como cada provider integra os artefactos na sua saída nativa.
provider helm: os artefactos são documentos YAML do Kubernetes escritos sob 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. A razão é a nomeação: um manifesto renderizado ou sintetizado é nomeado pelo provider a partir do componente a que pertence, enquanto um artefacto é nomeado pela chave que o seu autor escreveu, a qual nada diz sobre de que componente se trata — pelo que dois componentes associados a uma mesma Recipe escreveriam um mesmo caminho sem que nenhum dos autores os pudesse separar. O diretório é o próprio nome do componente, pelo que o ficheiro que o autor volta a ler na saída tem o nome que escreveu, um nível abaixo.
Um operador que queira uma disposição diferente tem o template subDirectory: da fronteira, que move todos os ficheiros que um contribuidor emite e não apenas os artefactos. Ver ../language-reference/path-template-variables.md.
provider compose: os artefactos são fragmentos compose. As chaves de nível superior (services:, volumes:, configs:, models:) são fundidas no docker-compose.yaml combinado por fronteira durante o passo de composição da fronteira.
provider helm-chart (caso especial): os artefactos não são escritos no diretório de saída como ficheiros autónomos — é o Helm que detém o pipeline de renderização. Em vez disso, o provider helm-chart coloca cada entrada de artifacts: dentro do próprio chart, e a forma de autoria da entrada decide onde fica. Cada entrada é processada como template Go com o contexto dos pilares do Aggrega PRIMEIRO, antes de qualquer colocação; a partir daí, as duas formas divergem. Uma entrada carregada por $import: é um ficheiro de template pré-Helm: é injetada no diretório templates/ do chart ANTES da renderização do Helm, pelo que o Helm a renderiza ao lado dos próprios templates do chart de origem. Um block scalar inline é um ficheiro solto do chart: é colocado na raiz do chart sob a chave com que foi escrito, sem prefixo templates/ e sem etiquetas de proveniência fundidas, para que os próprios templates do chart o possam ler através de .Files.Get / .Files.Glob do Helm — o padrão de ConfigMap a partir de ficheiros. Isto 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 ficheiro injetado fica em boundaries/<bp>/charts/<nodeID>/templates/<authored-key> — com os ficheiros de um pacote aninhados sob essa chave —, pelo que fica ao lado dos templates do chart de origem e o Helm recolhe-o durante a passagem de renderização a jusante. Um block scalar inline fica em boundaries/<bp>/charts/<nodeID>/<authored-key> — a raiz do chart, um nível acima de templates/ — porque um ficheiro lido através de .Files tem de estar onde o chart o procura, e um ficheiro colocado em templates/ é, em vez disso, renderizado como manifesto. Ambas as formas são nomeadas pela chave sob a qual foram escritas; o que difere entre elas é o diretório em que o provider as coloca.
Convenção de delimitadores do helm-chart. A passagem de pré-template do Aggrega sobre entradas de artefactos helm-chart, tanto as carregadas por $import: como as inline, usa os delimitadores [[ ]] em vez dos {{ }} predefinidos, para que a própria sintaxe {{ ... }} do Helm dentro do ficheiro 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 ficam como {{ .Values.x }}, {{ .Release.Name }}, {{- include "common.labels" . }}, etc. Misturar os dois pares de delimitadores num mesmo ficheiro é a forma de autoria suportada.
Proveniência e artefactos helm-chart. A proveniência é fundida em metadata.labels e metadata.annotations (segundo a divisão por conjunto de caracteres acima) para ficheiros carregados por $import: que fazem a ida e volta através de YAML com os seus tokens Helm preservados — ficheiros que usam apenas contexto Aggrega [[ ]] ou com {{ }} do Helm apenas em posições de escalares entre aspas. Os ficheiros com ações estruturais de template Helm ({{- include ... }}, {{- if ... }}, {{- range ... }}, {{- with ... }} em posições onde emitem estrutura YAML e não folhas escalares), ou ficheiros com {{ ... }} sem aspas em posições de valor, não sobrevivem à ida e volta YAML do Aggrega; o build emite um aviso «skipped provenance label injection (injeção da etiqueta de proveniência ignorada)» que nomeia o artefacto e deixa passar o ficheiro inalterado. Este aviso é esperado para qualquer ficheiro de artefacto helm-chart carregado por $import: que use ações estruturais de template Helm ou substituições de valores Helm sem aspas — é o caso comum na autoria Helm em produção, não o caso extremo. Os autores que precisam de etiquetas de proveniência nesses ficheiros injetam-nas através de um template com nome que escrevem no próprio _helpers.tpl do chart (por exemplo, um chamado aggrega.commonLabels) ou de um mecanismo equivalente do lado do Helm, não através da injeção de pré-template do Aggrega.
Colisões de nomes de ficheiro na raiz do chart. Um artefacto carregado por $import: cuja chave de autoria colida com um nome de ficheiro da raiz do chart (Chart.yaml, values.yaml, .helmignore, etc.) não é detetado pela verificação de colisões de nomes de ficheiro do Aggrega — o artefacto fica em templates/<authored-key> enquanto o ficheiro da raiz do chart fica na raiz do chart, e o prefixo de caminho torna-os distintos na perspetiva do Aggrega. Os autores evitam esses nomes de chave; a consequência de os usar é que o Helm vê ambos os ficheiros (um na raiz do chart, outro dentro de templates/) e pode renderizar inesperadamente a cópia do lado dos templates.
provider terraform: os artefactos são ficheiros de configuração Terraform, emitidos literalmente no diretório próprio do componente sob a árvore modules/ da fronteira. O HCL (main.tf) é a predefinição ergonómica e o Terraform JSON (.tf.json) é aceite de forma equivalente; nenhum deles é transpilado nem reformatado. A configuração raiz da fronteira declara esse componente como um bloco module cujo source aponta para esse diretório, pelo que uma fronteira inteira continua a ser um único grafo de dependências; é o mesmo diretório que os ficheiros de um módulo incluído ocupam, pelo que uma Recipe que declare tanto source: como artifacts: escreve-os lado a lado. A proveniência segue como um bloco de comentários Terraform inicial; quando um componente contribui com um corpo JSON, que não tem sintaxe de comentários, todos os corpos são emitidos inalterados e a proveniência viaja num ficheiro .tf complementar só de comentários ao lado deles, para que o carimbo nunca seja duplicado entre os dois. Ver a página do provider terraform.
provider cloudformation: os artefactos são fragmentos de stack — os recursos com que um componente contribui e não um template completo. O provider normaliza cada fragmento para intrínsecas em forma longa JSON pura e funde-o na única stack montada para esse diretório de saída, onde os recursos se juntam num único mapa Resources e os provides do componente surgem como Outputs da stack sob nomes delimitados ao componente que os publica. Quais das outras secções de nível superior de um fragmento sobrevivem à montagem está explicado em O que um documento fundido transporta de artifacts:. Ver a página do provider cloudformation.
O âmbito da fronteira: ficheiros para a saída partilhada de uma fronteira
O mecanismo de artefactos tem um segundo âmbito. Tudo o que está acima é escrito na posição própria do componente na saída da sua fronteira; o spec.boundary.artifacts de uma Recipe é o mesmo mapa — as mesmas três formas, a mesma regra de chave para nome de ficheiro, o mesmo contexto de template — escrito uma única vez para a fronteira como um todo. Existe para um ficheiro que o destino lê uma única vez para tudo o que uma fronteira implementa, que nenhuma posição própria de um componente pode 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 contenha não pode ser chamado com depends_on, count ou for_each, pelo que a configuração de um provider pertence à configuração raiz da fronteira e não ao módulo de um componente.
Onde fica. No diretório que contém a saída montada do grupo de despacho, ao lado dos ficheiros que a própria montagem do provider aí escreve — para o terraform, ao lado da configuração raiz. O compilador avalia cada entrada uma vez por cada componente que a Recipe renderiza, com o contexto desse componente, e escreve ele próprio o ficheiro: nenhum destes ficheiros é entregue ao provider, e nada é carimbado num deles para indicar de que componente veio, porque pertence a todos os contribuidores que o declararam.
Como os contribuidores se encontram. Os ficheiros que todos os contribuidores de um grupo de despacho declararam são fundidos por nome. Um nome declarado com bytes idênticos é um único ficheiro; um nome declarado com bytes diferentes, ou um nome que a própria montagem do provider escreve, interrompe o build nomeando o ficheiro e todos os contribuidores — a mesma recusa que encontram dois contribuidores que escrevem um mesmo caminho de saída. Assim, uma configuração de provider de que duas Recipes precisam é escrita por ambas sob um mesmo nome, e o build verifica que coincidem.
Quem o aceita. Se um ficheiro colocado ao lado da saída montada de uma fronteira significa alguma coisa é uma propriedade do destino do provider, pelo que é uma declaração do próprio provider, lida da declaração do próprio provider tal como os seus tipos de entrada. Uma Recipe que declare o bloco para um provider que não o declare é recusada antes de qualquer renderização. A grelha abaixo apresenta essa declaração na última coluna; dos providers distribuídos com o compilador, o terraform fá-la.
O que os artefactos 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 topo do seu spec. Tudo o que a Recipe produz — saída renderizada a partir da source, saída sintetizada a partir do workload e emissões de artefactos — está no formato nativo desse provider. Os artefactos de uma Recipe helm contêm YAML do Kubernetes. Os artefactos de uma Recipe compose contêm fragmentos compose. Uma Recipe visa um único provider; toda a saída está no formato nativo desse provider.
A composição multi-provider acontece ao nível da Release. As fronteiras contêm componentes de providers mistos; os contribuidores de cada provider no caminho avaliado de uma fronteira são despachados e montados por (caminho, provider) de forma independente. Uma Release com componentes que visam, respetivamente, helm, helm-chart e compose pode colocar os três numa única fronteira; o agrupamento de despacho divide-os por provider, os contribuidores de cada provider ficam na sua própria saída montada sob o caminho da fronteira, e o operador escreve a coordenação entre providers através da estrutura de fronteiras que escolher. A coordenação entre providers é responsabilidade do autor da Release.
Não são Recipes dentro de Recipes. Os artefactos não carregam nem compõem outras Recipes. São manifestos inline (ou caminhos de ficheiros para manifestos inline), processados como templates com os pilares desta Recipe e emitidos para a saída desta Recipe. A reutilização de Recipes acontece através de três mecanismos: o extends: de um Component (uma Recipe escrita para um Component base serve todos os Components que o estendem; o que se herda são metadados e esquemas, não ficheiros de saída — uma Recipe propriamente dita não declara nenhum extends:); o mapeamento de URIs planos do Manifest (o mesmo Component pode resolver-se para Recipes diferentes em catálogos diferentes — ver ../language-reference/entities/manifest.md); e Features + FeatureRecipes (preocupações transversais associadas ortogonalmente).
Não são uma camada de cola entre Recipes. Os artefactos não podem referenciar nomes, recursos ou estado que a própria Recipe não tenha declarado. Um artefacto ConfigMap referenciado pelo Workload da Recipe tem de ser emitido por esta Recipe. Um artefacto que espera um Secret aprovisionado externamente tem de obter o nome desse Secret através do pilar .features — a partir dos provides resolvidos da associação que o emite — e não presumir que existe. Esta é a invariante de autocontenção (acima) enunciada da perspetiva da autoria de artefactos: cada Recipe emite ficheiros num único formato, aplicados por uma única ferramenta, no diretório de saída de uma única fronteira.
Matriz de capacidades de Provider
Cada provider declara que tipos de entrada renderiza; uma barreira central de tipos de entrada aceita as combinações suportadas e rejeita as restantes 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 artefactos que seguem ao lado de uma entrada principal sourced/synthesized de uma Recipe autónoma só com artefactos (sem source:, sem workload:). As duas últimas colunas são as declarações do provider de que respeita omits: e de que aceita os ficheiros que uma Recipe contribui para a saída partilhada da sua fronteira sob boundary.artifacts: (acima); nenhuma delas é um tipo de entrada.
Cada coluna lê-se por si só. Uma linha diz que tipos um provider renderiza, tomados um de cada vez. Não diz que dois tipos assinalados possam ser declarados em conjunto. Como os tipos se compõem por adição, cada tipo declarado é despachado e emitido separadamente, pelo que um par pode ser recusado por uma razão que nenhuma coluna apresenta — na maioria das vezes porque ambos os tipos produzem um ficheiro sob o mesmo nome de saída. As combinações que cada provider efetivamente aceita estão descritas em texto em O que cada provider aceita, na íntegra.
| Provider | source: + valuesMapping: | workload: | artifacts: (ao lado) | só artefactos (autónomo) | omits: | boundary.artifacts: |
|---|---|---|---|---|---|---|
| helm | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| compose | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| helm-chart | ✅ | ❌ | ✅ processado como template com os delimitadores [[ ]] | ❌ | ❌ | ❌ |
| terraform | ✅ | ❌ | ✅ | ✅ | ❌ | ✅ |
| cloudformation | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ |
Esta grelha abrange 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 — 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 de capacidade do provider assinalada pela barreira. Os fragmentos compose por nó são fundidos por caminho de montagem, pelo que as fronteiras que partilham um directory: partilham um único ficheiro.
O que cada provider aceita, na íntegra
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 a razão é a forma como nomeia a saída: cada ficheiro emitido tem o nome do recurso que contém, pelo que os manifestos renderizados de um chart e os manifestos de um Workload sintetizado nunca ficam com o mesmo nome. Uma Recipe que declare os três emite os ficheiros do chart, os ficheiros do Workload e os ficheiros de artefactos lado a lado no diretório de saída da fronteira.
compose — todas as combinações exceto as duas em que source: e workload: aparecem juntos. Cada tipo sozinho faz build, e artifacts: segue ao lado de qualquer um deles. source: com workload: não consegue fazer build, nem os três juntos; Porque é que o compose não pode combinar uma source com um workload explica porquê, e não se trata de uma recusa de capacidade.
helm-chart — source: + valuesMapping:, sozinho ou com artifacts: ao lado. Nada mais. Não sintetiza um workload: e não tem forma só com artefactos: uma Recipe cujo único tipo de entrada seja artifacts: interrompe o build. A razão é o sítio onde este provider coloca um artefacto — dentro do próprio chart do componente — pelo que uma Recipe sem source: não lhe deixa nenhum chart onde o colocar.
terraform — três formas: source: + valuesMapping: sozinho, artifacts: sozinho, ou os dois juntos. Não sintetiza um workload:.
cloudformation — as mesmas três formas que o terraform, com a mesma única exclusão. source: + valuesMapping: sozinho, artifacts: sozinho, ou os dois juntos; sem workload:.
Como é uma recusa de tipo de entrada
Uma Recipe que declare um tipo de entrada que o seu provider associado não renderiza interrompe o build quando o nó é renderizado, e interrompe-o seja o que for que a Recipe declare ao lado desse tipo — emparelhar um workload: com uma source: que o provider consegue renderizar não faz passar o workload. A interrupção nomeia o provider, o tipo que não consegue renderizar e os tipos que 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 synthesizedA recusa de uma Recipe só com artefactos lê-se da mesma forma e nomeia essa forma: provider "helm-chart" does not support artifacts-only recipes (this provider supports: sourced). E0265 é o identificador a registar quando esta interrupção precisa de ser nomeada de forma duradoura — numa barreira de integração contínua, num issue ou num runbook; a tabela de todas as condições resolve-o.
Porque é que o compose não pode combinar uma source com um workload
O provider compose produz um fragmento por componente e dá a esse fragmento o nome do componente. A renderização sourced e a síntese de Workload produzem, cada uma, o fragmento desse componente sob esse mesmo nome, pelo que uma Recipe que declare ambas produz dois ficheiros com o mesmo nome, e o build interrompe-se perante a 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 próprio identificador do componente e não existe nenhuma superfície de autoria para ele, pelo que nenhuma alteração ao conteúdo da própria Recipe evita a colisão. A interrupção é uma propriedade do par e não de qualquer um dos tipos — o compose renderiza uma source, e o compose sintetiza um Workload, e a grelha tem razão em assinalar ambos. Para usar as duas formas num componente sob compose, é necessário dividi-las por dois componentes ou incorporar o conteúdo da source no Workload.
O que um documento fundido transporta de artifacts:
Dois providers fundem os seus contribuidores num único documento por caminho de montagem: o compose num único docker-compose.yaml, o cloudformation num único template de stack. Um documento fundido só pode transportar as secções que o seu montador modela, pelo que um visto em artifacts: diz onde o conteúdo de um fragmento é colocado e não que todas as chaves dentro do fragmento sobrevivem.
O compose transporta services:, volumes:, configs: e models: de um fragmento de artefacto, juntamente com as suas chaves de extensão com o prefixo x-. Um fragmento que declare qualquer outra coisa no nível superior interrompe o build, nomeando a chave — networks:, porque as redes são derivadas por fronteira 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 apresenta as regras de fusão por chave e a alternativa para o encaminhamento entre redes.
O cloudformation transporta Resources, Outputs, Parameters, Mappings, Conditions, Metadata e Rules, e constrói Transform a partir dos de todos os contribuidores. As transformações são juntas pela ordem que o CloudFormation documenta, com os Globals do SAM a viajar ao lado da transformação que os lê, e uma transformação que alteraria a forma como o conteúdo de outro contribuidor é implementado interrompe o build, nomeando-a. Description não é transportado, e o build di-lo: emite um aviso de campo não suportado que nomeia a secção e o componente, tal como para qualquer outra chave de nível superior que a stack não transporte, pelo que nada é descartado silenciosamente. O aviso é consultivo — o template emitido é, byte a byte, o que seria sem ele, e --no-unsupported-field-warnings silencia esta classe. Outputs é transportado sob um nome que o provider delimita ao componente contribuinte, para que dois componentes que contribuam com um output com o mesmo nome para uma mesma stack os mantenham separados. Secções de nível superior na stack montada explica cada secção, uma a uma.
Os outros três fornecedores não fazem fusão, pelo que nenhuma chave de artefacto 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 fronteira tal como são. terraform e helm-chart aninham — os ficheiros de cada componente ficam num diretório próprio, um diretório de módulo Terraform ou um subchart, e um documento raiz na fronteira referencia-os — pelo que uma entrada de artefacto é colocada como um ficheiro inteiro em vez de ser lida para um documento partilhado. O local onde fica uma entrada de artefacto de helm-chart, e o motivo pelo qual o seu par de delimitadores difere, estão em Semântica dos artefactos por Provider.