Recipe
O papel conceitual da entidade Recipe (o template de tradução escrito por Ops que mapeia o Developer Intent para o formato físico) está descrito em architecture/04-entity-taxonomy.md. Esta página cobre a superfície de autoria da Recipe — o ponteiro (source), o mapeador (valuesMapping:), o suporte nativo a IaC e exemplos completos.
A arquitetura da Recipe: ponteiros e mapeadores
Uma Recipe cumpre exatamente duas funções:
- O ponteiro (
source): informa ao compilador exatamente onde fica o código de infraestrutura. - O mapeador (
valuesMapping): injeta o contexto abstrato da Aggrega nas variáveis específicas que o código subjacente espera. O campo é uma única superfície de template Go com três modos de autoria — block scalar inline,$import:de arquivo ou$import:de biblioteca — selecionados pelo formato do conteúdo. Consulte O campovaluesMapping— três modos de autoria abaixo.
Como uma Recipe corresponde estritamente 1:1 a uma capacidade de renderização, essa capacidade (spec.capability) é declarada explicitamente no nível raiz, garantindo que o compilador Go saiba exatamente qual plugin de renderização Wasm downstream invocar.
spec.implements declara qual tipo de componente do catálogo a Recipe é capaz de implementar. O compilador o usa para verificar os mapeamentos do Manifest (o implements de uma Recipe mapeada deve corresponder ao tipo mapeado) e para sugerir candidatas — as recipes listadas em um diagnóstico de mapeamento ausente e classificadas primeiro no autocompletar do editor. Ele nunca resolve um build: o mapeamento do Manifest é a escolha explícita de implantação do usuário, fixada no lockfile. Uma Recipe cujo implements é sem versão, exato ou um intervalo compatível com a versão major ainda assim apenas se oferece para um tipo; o usuário fixa a escolha. FeatureRecipe.spec.implements cumpre o mesmo papel para tipos de feature.
A. Esquemas de origem orientados por Wasm
Para manter vieses de implementação fora do compilador, o bloco source não é um conjunto fixo de campos de infraestrutura. O campo source aceita dois formatos:
- A string universal (rápida e limpa): ideal para caminhos locais, artefatos OCI e repositórios Git. O compilador deduz o método de obtenção pelo prefixo e pelo sufixo da string (
./src,https://github.com/example/module.git,oci://...): uma URL que termina em.git, ou escrita comgit://oussh://, é um repositório Git obtido em seu branch padrão, e uma URLhttps://que não indica nem um repositório nem um chart.tgzou um fragmento.yamlé recusada por ser ambígua. - O objeto estruturado aberto: um dicionário aberto (
additionalProperties: true) cujas chaves são definidas pelo provider e expostas aos templates da Recipe como.source.*(por exemplo,.source.chart). A intenção do design é que o socket WebAssembly de cada provider defina e valide seu próprio formato de origem (por exemplo,registry/chart/appVersionpara Helm).
O que o núcleo resolve. Nenhum provider valida chaves de origem próprias. Uma origem obtida é resolvida por uma identidade nativa cujo kind seleciona um resolvedor — helm-oci-chart, helm-https-chart, compose-https-fragment e git-repository. Uma origem destinada a ser obtida deve conter kind e url; a coordenada adicional que seleciona o conteúdo depende do kind. Os kinds de chart e de fragmento aceitam version e a fixam como está escrita. git-repository aceita ref — uma tag, um branch ou um commit — e, opcionalmente, module_subdir, que indica o diretório dentro do repositório que constitui o artefato; como apenas um commit identifica conteúdo que não pode ser reapontado, a referência é resolvida no momento do lock e o lockfile registra tanto a referência escrita quanto o commit para o qual ela foi resolvida. Um module_subdir que, como está escrito, sobe acima do repositório — uma barra invertida conta como separador — é recusado antes que qualquer coisa seja obtida. O repositório é arquivado a partir do seu próprio checkout: um link simbólico incluído em um commit é arquivado como o arquivo ou diretório para o qual aponta, quando este fica dentro do repositório, e um que sai dele interrompe o pull, indicando o link pela sua posição no repositório. Uma origem estruturada cujo url: indica um caminho do sistema de arquivos não é obtida: ela é lida do disco nas mesmas condições que uma string de caminho simples, com um url: relativo ancorado no diretório que contém o arquivo da entidade que o declara. Uma origem estruturada que omite kind/url também não é obtida e, se uma obtenção era pretendida, o build é interrompido de forma explícita na descida de origens no momento do lock, em vez de ser resolvido silenciosamente para nada. O conteúdo é sempre fixado antecipadamente; o compilador nunca obtém estado de runtime ao vivo.
O que é fixado ao lado da Recipe. Para uma origem obtida cujos kind, url, chart, module_subdir, version e ref estão todos escritos por extenso em vez de gerados por template, aggrega pin registra o digest do que obteve em entity.lock, um arquivo no próprio diretório da Recipe que você inclui em um commit ao lado dela. Fixar é uma etapa do autor da Recipe e não precisa de nenhuma Release; um pull sobre uma Recipe cujo lock não registra a fixação é interrompido e a indica, a menos que seja pedido ao pull que execute a mesma etapa. Um build compara esse digest com o que o lockfile da Release registra para a mesma origem e é interrompido quando os dois divergem — exceto para uma origem escrita com um ref: git, cuja linha é registrada no commit para o qual a ref foi resolvida e não é comparada. Uma origem obtida cujas coordenadas são preenchidas a partir de um template é fixada por Release, em vez disso, no lockfile de cada Release. Uma origem que indica um diretório ou um arquivo ao lado da Recipe não é obtida: aggrega pin registra um digest por arquivo que ela contribui para o que uma publicação da Recipe contém — todos os arquivos no diretório da Recipe, para uma origem escrita como template — e, depois que o lock os registra, um build compara a origem com eles antes que o provider a leia, sendo interrompido por um arquivo adicionado, alterado ou removido desde a fixação — com E0305, ou antes com E0130 quando o lockfile da Release, escrito antes da alteração, registra a Recipe pelo que ela contém. Um lock que não registra nenhuma fixação para essa origem não deixa nada para um build comparar, e um pull ou uma publicação que não fixa a recusa. O próprio arquivo da Recipe nunca é escrito. aggrega pull descreve o arquivo e como responder a cada interrupção.
spec.capability pode conter uma fixação de versão nas formas que implements aceita — exata (helm:<version>) ou um intervalo com circunflexo (helm:^<version>) — selecionando qual versão do plugin do provider renderiza a Recipe; uma fixação que nenhuma versão disponível satisfaz interrompe o build. Sem fixação (spec.capability: "helm"), a versão disponível mais alta a renderiza. As versões disponíveis são as que aggrega plugin list mostra: os providers integrados ao aggrega têm a versão do próprio compilador. A fixação não faz parte do nome da Recipe: um Manifest mapeia uma Recipe que declara capability: "compose:1.2.3" como compose/<name>:<version>, exatamente como uma sem fixação, e alterar a fixação nunca a renomeia; um valor de mapeamento que escreve a fixação no nome (compose:1.2.3/<name>:<version>) é recusado como referência de recipe malformada (E0095) antes de qualquer busca.
Modelo mental: spec.capability indica o formato de saída desejado (por exemplo, helm, terraform, compose); o compilador o resolve para o plugin Wasm que renderiza esse formato (por exemplo, provider/helm). Você declara o formato; a Aggrega vincula a ferramenta.
B. Injeção de contexto: a camada de mapeamento semântico
Para evitar que o compilador execute deep-merges perigosos e não determinísticos entre vários ambientes, uma Recipe permite apenas uma única fonte de verdade para sua camada de mapeamento.
Engenheiros de Ops escrevem o conteúdo de mapeamento para traduzir o contexto abstrato antes que o plugin de renderização Wasm seja executado. A linguagem de mapeamento é o template Go (text/template + Sprig); a biblioteca Sprig vem pré-registrada; as ações padrão define e template são suportadas, e include não é registrada.
| Nome do campo | Escopo e fase de execução | Melhor caso de uso |
|---|---|---|
injectMapping (apenas FeatureRecipe) | Interceptação pré-renderização. Avaliado na memória Go antes da Recipe base. Faz nativamente um deep-merge do seu dicionário de saída estritamente sobre o pipe .context.inject do chamador. Intencionalmente ausente do schema Recipe base — consulte entities/featurerecipe para a justificativa arquitetural. | Reescrever cirurgicamente variáveis env injetadas ou formatar FQDNs para um chamador sem exigir JSONPatch Wasm. |
valuesMapping | Renderização base (template Go). Avaliado para mapear variáveis para o chart/módulo de infraestrutura source subjacente. Campo único, três modos de autoria (inline, $import: de arquivo, $import: de biblioteca). Consulte a subseção abaixo para o mecanismo de seleção. | Mapear variáveis padrão (como réplicas ou tags de imagem) para um chart Helm diretamente no YAML da Recipe, ou referenciar um template compartilhado via $import: para reutilização entre uma Recipe e outra. |
Observação: injectMapping é exclusivo das FeatureRecipes e isola a interceptação de variáveis do valuesMapping. O valuesMapping da Recipe base consome, sem saber, as strings .context.inject reescritas geradas pelos blocos injectMapping da FeatureRecipe, de modo que os dois permanecem desacoplados.
Uma chave que o valuesMapping escreve como null chega ao provider como null, e o que ela faz ali cabe ao provider definir, por isso cada página de provider informa: helm remove o padrão do chart para essa chave, helm-chart a escreve nos values do umbrella, compose a escreve no arquivo compose, terraform a escreve como um argumento de módulo null, e cloudformation a recusa.
O campo valuesMapping — três modos de autoria
O valuesMapping: de uma Recipe é uma única superfície de template Go que aceita três modos de seleção. O compilador seleciona com base no formato do conteúdo do campo; nenhuma anotação $mode: é necessária.
Modo 1: template Go inline (block scalar YAML). O valor do campo é uma string escrita na forma block scalar YAML |:
spec: valuesMapping: | {{- with .values -}} image: tag: {{ optional .image `tag` "11.4.4-debian-12-r0" }} pullPolicy: {{ optional .image `pullPolicy` "IfNotPresent" }} architecture: {{ optional . `architecture` "standalone" }} primary: replicaCount: {{ optional .primary `replicaCount` 1 }} {{- end }}O modo inline é a forma de autoria típica para Recipes cujo conteúdo de mapeamento é de pequeno a médio porte (menos de ~50 linhas). O corpo do template fica inline com o restante do envelope da Recipe; o conteúdo da Recipe é autocontido.
Modo 2: $import: de arquivo. O valor do campo é um mapa contendo apenas $import: com um caminho de arquivo local:
spec: valuesMapping: $import: ./mappings/api-server.tmplO compilador carrega o conteúdo do arquivo (um template Go), o renderiza com o contexto de template padrão da Recipe e trata o resultado como a saída do mapeamento. A resolução do caminho é relativa ao diretório da Recipe — um caminho relativo é ancorado no diretório que contém o recipe.yaml que o declara, não no diretório a partir do qual o build é invocado — e o caminho deve permanecer dentro desse diretório, como explica Os caminhos de conteúdo ficam dentro do próprio diretório da Recipe. O modo de arquivo é adequado para conteúdo de mapeamento de médio a grande porte (~50+ linhas) e para fluxos de revisão em que as alterações de mapeamento aparecem como diffs de arquivos independentes.
Modo 3: $import: de biblioteca. O valor do campo é um mapa contendo apenas $import: com uma referência de identidade por nome simples a uma entrada de MappingLibrary:
spec: valuesMapping: $import: DatastoreHelpers#/mappings/MariaDBCoreO compilador resolve a referência em relação ao conjunto resolvido de MappingLibrary (o catálogo local mais quaisquer bibliotecas fixadas no lockfile), carrega o conteúdo da entrada e o trata como a saída do mapeamento; uma entrada cujo corpo é ele próprio um $import: na raiz do campo é resolvida recursivamente. A referência não contém nenhum host de registry — o nome da biblioteca é resolvido por identidade e a versão vem do lockfile por Release, com um piso de versão mínima opcional :<version> (<Library>:<version>#/mappings/<entry>). O conteúdo da biblioteca compartilha o contexto de template padrão da Recipe. O modo de biblioteca é adequado para reutilização entre uma Recipe e outra — padrões de mapeamento que se repetem em muitas Recipes (várias Recipes de datastore compartilhando lógica auxiliar de datastore; várias Recipes do provider Helm compartilhando padrões de pod template). A entidade MappingLibrary fornece versionamento, fixação no lockfile e exibição na interface do hub.
Regras de seleção. O compilador percorre o nó YAML e seleciona pelo formato do conteúdo:
- Se o nó for um escalar de string, o modo inline (Modo 1) é selecionado.
- Caso contrário, o nó é um mapa; a chave
$import:é verificada. - Se o valor de
$import:for uma referência de biblioteca por nome simples (<Library>#/mappings/<Entry>, opcionalmente com um piso:<version>), o modo de biblioteca (Modo 3) é selecionado. - Caso contrário (um caminho de arquivo local), o modo de arquivo (Modo 2) é selecionado.
- Qualquer outro formato (um mapa sem
$import:, um mapa com chaves extras além de$import:etc.) produz um erro em tempo de build.
Apenas $import: de origem única. $import: aceita uma única origem. O merge de várias origens não é suportado em valuesMapping:. Uma Recipe que precise compor vários fragmentos de mapeamento usa uma entrada de MappingLibrary com composição interna define / template de template Go, um arquivo local com diretivas template de template Go que invocam arquivos vizinhos, ou composição inline para conteúdo curto. Consulte entities/mappinglibrary para a entidade de biblioteca e vocabulary/cross-document-ref para a distinção mais ampla $ref: / $import:.
Proveniência. As mensagens de erro de falhas de renderização de template citam a proveniência apropriada a cada modo: templates inline citam o arquivo:linha da Recipe onde o block scalar começa; imports de arquivo citam o conteúdo do arquivo importado; imports de biblioteca citam a posição de origem da entrada da MappingLibrary, com a identidade de biblioteca sem host (<Library>#/mappings/<entry>) como ponteiro canônico para referências estáveis — um host de registry em uma referência é recusado, de modo que a localização física nunca entra no ponteiro.
C. Suporte nativo a IaC
Uma equipe de Ops que traz seu próprio infrastructure-as-code o mantém no próprio diretório da Recipe — um diretório de módulo ou de template como ./src, indicado por source: — ou o obtém com um source: estruturado (um módulo Terraform do seu repositório git, com kind: git-repository), ou o escreve como corpos com template em artifacts:. A camada de mapeamento (valuesMapping: — inline, import de arquivo ou import de biblioteca) fornece o contexto abstrato a esse código, e o provider emite o resultado no formato próprio do destino; nenhuma linguagem de configuração é convertida em outra:
- Terraform: um módulo é copiado arquivo por arquivo, e um corpo escrito pelo autor é emitido exatamente como foi escrito, tanto HCL nativo (
main.tf) quanto Terraform JSON (.tf.json) — a CLIterraformlê ambos. A configuração raiz do boundary,aggrega.modules.tf, chama o diretório de cada componente como um blocomodule, e a saída devaluesMapping:de um módulo com origem se torna os argumentos desse bloco. Consulte o provider terraform. - CloudFormation: um template com origem, YAML ou JSON, e os fragmentos de recurso que uma Recipe escreve são normalizados em JSON de forma longa e mesclados em um único template de stack por boundary, com a saída de
valuesMapping:preenchendo os parâmetros que um template com origem declara. Consulte o provider cloudformation.
Um valor que só existe depois que a infraestrutura é aplicada permanece um ponteiro que o destino resolve — uma interpolação ${ ... } do Terraform, um Ref ou Fn::GetAtt do CloudFormation — e nunca é avaliado em tempo de build.
Exemplo A: o chart Helm remoto (mapping inline e contrato de locals)
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: mariadb-chart version: 1.0.0spec: capability: helm implements: core/datastore/mariadb:1.0.0 source: # The shipped fetch form: { kind, url, version }. 'kind' selects a built-in # resolver (helm-oci-chart, helm-https-chart, compose-https-fragment). kind: helm-oci-chart url: oci://registry-1.docker.io/bitnamicharts/mariadb # Default chart version. Override via infra.source_version. version: "{{ optional .infra `source_version` \"25.0.8\" }}"
locals: primary_compute: mariadb listen_port: "3306" volumes_path: "/spec/template/spec/volumes" root_path: "/-" # The Base Recipe EXPLICITLY dictates the physical secret name to the Wasm # pipeline: the suffix it follows the rendered name with. A local cannot read # .context.rendered_name, so each template writing the full name joins the two. secret_target_db_password: "mariadb-auth"
provides: # The chart's primary Service, named by the fullnameOverride pinned below host: "{{ .context.rendered_name }}" port: "3306" # Every key the Component's provides contract declares is published user: "{{ .values.user }}" database: "{{ .values.database }}" protocol: "mariadb"
valuesMapping: | fullnameOverride: "{{ .context.rendered_name }}" auth: # Reads the suffix from the local rather than restating it, so the secret # name is authored once and every reader follows that one definition existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_db_password }}" primary: persistence: size: "{{ .infra.storage.size }}"Exemplo B: o módulo Terraform local (mapping por arquivo)
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: aws-s3-tf version: 1.0.0spec: capability: terraform implements: aws/s3-bucket:1.0.0 source: "./src"
locals: primary_compute: bucket_instance resource_path: "/resource/aws_s3_bucket/main" root_path: "/data"
# Guaranteeing global uniqueness across multiple AWS environments valuesMapping: | bucket_name: "{{ .metadata.release_name }}-{{ .context.instance_id }}-data" region: "{{ .infra.aws_region }}"Exemplo C: Recipe de Component concreta (vincula a infraestrutura) Ops mapeia a interface genérica para a realidade física. (É aqui que os detalhes de rede L4 são vinculados — seja fixados no código, seja, como com a porta do proxy abaixo, obtidos do bloco infra que a Release preenche.)
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: kong-gateway version: 1.0.0spec: capability: helm implements: core/gateway/kong:1.0.0 source: # A chart repository root paired with the chart's name. kind: helm-https-chart url: https://charts.konghq.com chart: kong version: "{{ optional .infra `source_version` \"3.4.1\" }}"
provides: # The chart's proxy Service: it suffixes the name pinned below with "-proxy" host: "{{ .context.rendered_name }}-proxy" port: "{{ .infra.proxy_port }}" protocol: "http" # The contract's other keys: empty while nothing is wired to the models # socket, and while metrics are off endpoint: '{{ with optional .values "model" "" }}http://{{ $.context.rendered_name }}-proxy:{{ $.infra.proxy_port }}/{{ . }}/v1{{ end }}' model: '{{ optional .values "model" "" }}' metrics_endpoint: '{{ if .values.metrics_enabled }}http://{{ .context.rendered_name }}-status:8100/metrics{{ end }}'
valuesMapping: | fullnameOverride: "{{ .context.rendered_name }}"Disciplina de nomenclatura de recursos de nuvem.
Recipes que emitem nomes de recursos de nuvem — nomes de buckets S3, identificadores de bancos de dados RDS, nomes de roles IAM, nomes de stacks CloudFormation e qualquer outro campo cujo valor ocupe um namespace global no provedor de nuvem — devem concatenar {{ .metadata.release_name }} e/ou {{ .context.instance_id }} ao nome renderizado para evitar colisões quando a mesma Recipe é executada em várias Releases ou instâncias de componente. O bucket_name: "{{ .metadata.release_name }}-{{ .context.instance_id }}-data" do Exemplo B é o padrão canônico.
A disciplina se aplica onde quer que um único namespace global restrinja o nome. Os nomes de buckets AWS S3 compartilham um namespace global entre todas as contas de uma região; duas Releases do mesmo Aggregate (prod-billing e staging-billing) não podem ambas implantar buckets chamados customer-data — a segunda implantação falha em tempo de execução com uma rejeição do lado da AWS. Concatenar release_name diferencia a Release; concatenar context.instance_id diferencia por instância de componente; concatenar ambos diferencia por componente e por Release.
O que o compilador verifica e o que não verifica. O compilador não inspeciona as saídas de valuesMapping: em busca de campos de nomes de recursos de nuvem sem essas interpolações. A disciplina é mantida pelos autores de Recipe (que sabem quais campos nomeiam recursos globalmente únicos para o provider de destino) e pelos revisores (que identificam padrões de recursos sem nome na revisão de PR). Um plugin linter poderia sinalizar Recipes cujas saídas de valuesMapping: referenciem campos de nomes de recursos de nuvem sem interpolação de release_name / instance_id; o socket de linter é distribuído e executado por meio de aggrega lint (veja plugins/plugin-contract.md “Critério de posicionamento: o socket de linter versus os papéis de veredito de governança”), e nenhuma das regras do linter de publicação verifica isso.
Essa disciplina é um de vários contratos sociais mantidos por convenção — disciplina de autoria que os autores aprendem com a documentação, e não com a imposição do compilador. Veja vocabulary/social-contracts.md para a lista completa de convenções e a justificativa arquitetural da classificação de cada contrato.
Templates no campo source. O campo source de uma Recipe é ele próprio uma superfície de templates. Ambas as formas de source aceitam templates Go: a forma de string universal
source: "{{ optional .infra `module_path` \"./src\" }}"e a forma de objeto estruturado (cada subcampo com valor string é avaliado como template; subcampos que não são string passam inalterados). O que um template de source pode ler depende de o source nomear ou não um artefato remoto. A coordenada de um source remoto — version, chart, ref e module_subdir de um bloco estruturado que nomeia um registry, um repositório de charts ou um repositório git — é avaliada quando aggrega pull resolve o artefato para fixá-lo, somente em relação a .values, .infra e .locals, com os helpers próprios do Aggrega (optional, capitalizedWords e index) e nenhuma das funções do Sprig. .context não está nessa superfície, então qual artefato é fixado para um componente é decidido pelos values e pelo infra que ele recebe, e nunca pelo nome de sua instância. As entradas de locals: avaliadas ali são as que esses campos leem, e as que uma dessas entradas lê por sua vez: uma entrada que nenhum campo de source lê não é avaliada enquanto o source é resolvido, de modo que um local de que só o render precisa — um que chama uma função do Sprig, ou que lê .context.instance_id — não afeta o pinning e é avaliado quando o nó é renderizado. Um campo que lê .locals de uma forma que não nomeia nenhuma entrada específica, como {{ index .locals "version" }}, faz com que todas as entradas sejam avaliadas. Um source que nomeia um caminho no workspace, como o de cima, não é resolvido para pinning: seu template é avaliado quando o nó é renderizado, em relação ao mesmo contexto autocontido dos locals de uma Recipe — .context.instance_id, .values, .infra e .locals, todo o bloco resolvido do nó — de modo que admite e recusa as mesmas raízes de referência que uma entrada de locals:, com uma diferença a seu favor: pode ler qualquer entrada que o bloco declare, não apenas as entradas acima dele. Uma coordenada remota pode igualmente ler qualquer entrada que o bloco declare. .provides não está em nenhum dos dois contextos, e um template de source que tenta alcançar os provides de seu próprio nó interrompe o build e nomeia a referência problemática. Essa é uma propriedade fixa da superfície, e não uma lacuna à espera de trabalho futuro — os locals de um nó são resolvidos antes de seus provides para que provides: possa ler .locals, e um template de source lê esses mesmos locals resolvidos em vez de avançar até os provides. Referências a .context.inject e .context.uses são proibidas pelos mesmos motivos de autocontenção; a URI do source precisa ser resolvida antes que o pipe da topologia seja hidratado e antes que qualquer coisa a jusante carregue o chart, o módulo ou o corpo do artefato para o qual a URI aponta. As regras completas de disponibilidade e a justificativa das referências proibidas estão na linha #5 da matriz de expansão de templates. O uso canônico é um override infra.source_version exposto pelo Component e repassado ao campo de versão do source — veja entities/component “O pilar infra” — para que um catálogo não precise republicar uma Recipe a cada incremento compatível de versão upstream.
Inventário de esquemas do campo source. O campo source: aceita várias variantes de forma no esquema. O suporte em tempo de execução de cada variante varia conforme o provider; a tabela abaixo documenta o que cada forma faz.
| Forma | Exemplo | Status |
|---|---|---|
| Caminho relativo simples do sistema de arquivos | source: "./charts/postgres" | available — todo provider distribuído (helm, helm-chart, compose, terraform, cloudformation) aceita uma string de caminho simples do sistema de arquivos. |
| Caminho absoluto simples do sistema de arquivos | source: "/abs/path/to/chart" | accepted but blocked — o esquema o aceita e todo comando que lê a Recipe o recusa: um caminho absoluto nomeia um lugar na máquina em que foi escrito, e não conteúdo dentro do próprio diretório da Recipe, então ele não viajaria com a Recipe. Mova o chart para o diretório da Recipe e nomeie-o relativamente a ele; veja Caminhos de conteúdo permanecem dentro do próprio diretório da Recipe. |
| String vazia | source: "" | accepted but blocked — o esquema aceita a string vazia e todo comando que carrega a Recipe a recusa no momento em que a Recipe é lida, porque uma string vazia não nomeia nenhum dos dois modos. A recusa nomeia a ambiguidade junto com as duas formas de sair dela: omitir o campo para o modo sem source, ou dar a ele um caminho ou URI real para o modo com source. aggrega validate <recipe-file> a informa para a Recipe, e aggrega pull, aggrega build e aggrega validate --release a informam para uma Release que alcança a Recipe. Veja errors/fatal-halts.md “Recipe source: is an empty string (O campo source da Recipe é uma string vazia)”. |
Objeto estruturado cujo url: traz um esquema de transporte | source: { url: "oci://…/mariadb", version: "25.0.8" } | available — o source-resolver nativo lê a forma {kind, url, version, chart, ref, module_subdir} (o esquema de url: seleciona o tipo — oci:// → chart OCI, https://….tgz → arquivo compactado de chart, raiz de repositório https:// combinada com chart: → chart de repositório — ou você o nomeia com kind:), busca e fixa o artefato em aggrega pull, e o build o extrai do cache. Fazer vendoring de um chart localmente é suportado como alternativa, e não é obrigatório. O esquema aceita um objeto estruturado aberto. Veja providers/helm.md “Conjunto de chaves de source:”. |
Objeto estruturado cujo url: nomeia um caminho do sistema de arquivos | source: { kind: helm-oci-chart, url: "./charts/postgres", version: "1.0.0" } | available — um url: sem esquema de transporte nomeia um caminho, então nada é buscado e nada é fixado; o build lê o conteúdo do disco. Um url: relativo é ancorado ao diretório que contém o recipe.yaml que o declara, e um que sai desse diretório — inclusive um absoluto — é recusado: a mesma leitura que recebem as duas linhas de caminho simples acima, e a forma em que você o escreveu não a altera. Só url: decide de onde o conteúdo é lido; os outros campos selecionam o que seria buscado, e continuam chegando aos templates da Recipe como .source.*. |
URI OCI (oci://...) | source: "oci://hub.aggrega.ai/recipe/helm/postgres:1.0.0" | planned — objetivo de design para a distribuição de catálogos. O resolvedor atual de três níveis (os arquivos que uma Release nomeia por caminho, catálogos do workspace, registry OCI remoto) está documentado em architecture/13-catalog-and-registry.md; o resolvedor no nível da entidade consome URIs OCI por meio dessa cascata, mas a forma OCI do campo source: de cada Recipe não está conectada nos providers hoje. |
Outros esquemas de URL (https://, git+https:// etc.) | (ilustrativo) | planned — documentado como intenção de design no roadmap de sources plugáveis da arquitetura; nenhum suporte de provider hoje. |
Como um caminho de source: é ancorado. A ancoragem se aplica a caminhos do sistema de arquivos e a nada mais, e se aplica qualquer que seja a das duas formas que traz o caminho. Um caminho relativo é ancorado ao diretório que contém o recipe.yaml que o declara, e um caminho que sai desse diretório — inclusive um caminho absoluto — é recusado, como explica Caminhos de conteúdo permanecem dentro do próprio diretório da Recipe. Uma referência que traz um esquema de transporte — oci://, https://, http://, git://, ssh://, git+ssh://, ou qualquer referência que termine em .git — nomeia algo a ser buscado, e não um caminho, então é repassada exatamente como você a escreveu e nunca é unida a um diretório.
Na forma estruturada, o caminho é o campo url:, e ele é lido da mesma maneira: um url: relativo é ancorado ao diretório que contém o recipe.yaml, um que sai desse diretório é recusado, e um que traz um esquema de transporte é buscado. Todos os outros campos de um source: estruturado são repassados intactos, inclusive os definidos pelo provider.
Um source: escrito como template é ancorado em relação ao valor que o template produz, e não ao próprio texto do template. Um template não nomeia nada até ter sido avaliado, então a leitura acima é aplicada ao seu resultado: um resultado que é um caminho relativo é ancorado ao diretório que contém o recipe.yaml, um que sai desse diretório — inclusive um caminho absoluto — interrompe o build, e um que traz um esquema de transporte é repassado e buscado. Um template está, portanto, livre para produzir qualquer uma das formas do inventário acima, e cada uma é tratada exatamente como o mesmo valor escrito literalmente seria; a diferença está apenas em quando o caminho pode ser julgado, o que, para um template, é quando o build o avalia, e não quando a Recipe é lida.
Um template que não produz nada — um resultado vazio — deixa a Recipe sem source, que é o modo sem source. Isso é diferente de você mesmo escrever source: "", que não nomeia nenhum dos dois modos e é recusado; veja a linha do inventário acima.
O inventário é a referência canônica do que os autores podem colocar em source:; seus rótulos são os que 10-status.md define.
Caminhos de conteúdo permanecem dentro do próprio diretório da Recipe
O conteúdo de uma Recipe fica no próprio diretório da Recipe, porque todo arquivo que uma publicação dela carrega é tirado dali. Todo caminho que uma Recipe escreve para o conteúdo que carrega — seu source:, seja um caminho simples ou o url: da forma estruturada, e cada arquivo que suas entradas valuesMapping:, workload: e artifacts: importam com $import: — é lido em relação ao diretório que contém o recipe.yaml e precisa permanecer dentro dele. Esses caminhos são também o que uma publicação carrega: os arquivos que eles nomeiam viajam com a Recipe, e nada mais do seu diretório viaja (veja aggrega push). Um caminho que sai do diretório aponta para um arquivo que não viajaria com a Recipe, então o arquivo não está lá para quem a consome, e um pin registrado sobre ele atestaria bytes que essa pessoa não consegue obter.
Duas formas saem do diretório, e ambas são recusadas:
- um caminho que sobe acima dele, como
../shared/charts/app; - um caminho absoluto, como
/opt/charts/app, que nomeia um lugar na máquina em que foi escrito.
Um caminho que sobe e volta para dentro é um caminho comum dentro do diretório: ./charts/../values.tmpl nomeia o values.tmpl ao lado da Recipe. O que se julga é onde o caminho chega, medido a partir do diretório da Recipe sem sair dele — então uma subida para fora que nomeia o diretório novamente na volta, como ../1.0.0/values.tmpl escrito em um diretório chamado 1.0.0, também é recusada. O próprio nome do diretório não viaja: uma Recipe publicada é lida de um diretório que o cache do consumidor nomeia, onde esse nome não encontra nada.
Onde é recusado. Todo comando que lê a Recipe recusa esse caminho ao lê-lo, antes que qualquer coisa seja buscada, renderizada ou publicada: aggrega validate, sobre o catálogo ou sobre o próprio arquivo da Recipe, aggrega pull, aggrega build, aggrega pin e aggrega push. Um source: escrito como template não nomeia nada até que o build o avalie, então um template que produz um caminho fora do diretório é recusado pelo build, no momento em que o valor existe. A interrupção é A path names content outside the entity’s own directory (Um caminho nomeia conteúdo fora do diretório da própria entidade), e ela nomeia o caminho que você escreveu.
O que fazer em vez disso. Coloque o arquivo no diretório da Recipe, ou em um diretório abaixo dele, e nomeie-o relativamente à Recipe: ./charts/app, ./extras/netpol.yaml. Um chart usado por várias Recipes é copiado para o diretório de cada Recipe, já que cada Recipe é publicada por conta própria; um corpo de mapping, workload ou artefato compartilhado por várias Recipes pertence a uma MappingLibrary, WorkloadLibrary ou ArtifactLibrary, que cada Recipe referencia por identidade.
Por que uma Release é diferente. Uma Release aponta para outras entidades — seu Aggregate, seu Manifest, a Release que ela estende — e nunca é publicada, então nada do que ela lê viaja para lugar algum. Essas referências, e o arquivo que seu parameters: importa, são lidos como estão escritos, e é isso que permite que um Aggregate seja compartilhado por variantes de Release em subdiretórios. Veja entities/release.md.
O mesmo limite vale para uma FeatureRecipe, e para todo esquema que um Component ou uma Feature importa.
O campo workload: — tipo de entrada sintetizado
Recipe.spec.workload: declara o corpo de Workload que o compilador sintetiza em recursos nativos do provider. É um dos três tipos de entrada que uma Recipe pode declarar junto com source: (renderização a partir de source) e artifacts: (manifestos auxiliares). Pelo menos um dos três precisa estar presente em todo provider; um serviço que o build não provisiona declara um workload: com form: reference.
O campo aceita três modos de autoria — block scalar inline, $import: de arquivo ou $import: de biblioteca. O compilador despacha de acordo com a forma do conteúdo do campo; nenhuma anotação $mode: é necessária.
Modo 1: inline (escalar string de template Go). O valor é um block scalar YAML cuja saída é interpretada como aggrega.ai/v1beta1 Workload:
spec: capability: helm implements: core/web-server:1.0.0 workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload replicas: {{ optional .infra "replicas" 1 }} containers: app: image: "{{ .values.image }}" ports: http: 8080Os campos de um Workload ficam na raiz do documento — não há wrapper spec: — e containers: e os ports: de cada contêiner são mapas indexados por nome em vez de sequências, com a ordem do autor preservada. O provider traduz essa forma para sua própria forma nativa, de modo que uma entrada do mapa de contêineres aparece na saída renderizada do helm como um elemento containers[] nomeado por sua chave; a forma escrita é o mapa, não a lista renderizada.
Modo 2: $import: de arquivo. O valor é um mapa com uma única chave $import: apontando para um arquivo local de template Go:
spec: workload: $import: ./workload/web-server.yaml.tmplA resolução de caminhos é a mesma de valuesMapping:: um caminho relativo é ancorado ao diretório que contém o recipe.yaml que o declara, não ao diretório a partir do qual o build é invocado, e precisa permanecer dentro desse diretório. O corpo importado é um template Go avaliado no contexto de render da Recipe, exatamente como um corpo inline.
Modo 3: $import: de biblioteca. O valor é um mapa com uma única chave $import: que traz uma referência de identidade por nome simples a uma entrada de uma WorkloadLibrary:
spec: workload: $import: BaseWorkloads#/workloads/StatelessServiceO fragmento #/workloads/ é o que seleciona uma entrada de Workload, e é o fragmento que distingue esta referência da forma #/mappings/ que valuesMapping: usa — aquela endereça uma entrada de uma MappingLibrary e não nomeia um corpo de Workload. A referência não traz host de registry, a versão resolvida vem do lockfile por Release, um piso de versão mínima :<version> opcional pode ser declarado como <Library>:<version>#/workloads/<Entry>, e uma entrada cujo corpo é ele próprio um $import: na raiz do campo é resolvida recursivamente. O corpo importado é um template Go avaliado no contexto de render da Recipe que o consome, de modo que .values, .infra e .features fluem para ele exatamente como para um corpo inline. Veja entities/workloadlibrary para a entidade de biblioteca e a gramática completa da referência.
O provider de destino precisa suportar síntese (o catálogo da biblioteca padrão declara workloadSchema nesses providers por convenção); apontar para um provider que não consegue sintetizar é recusado quando o nó é renderizado, com o diagnóstico de capacidade do provider — baseado na capacidade do provider, não na presença de workloadSchema. Para a gramática completa de Workload, os campos repassados no formato K8s e o comportamento de tradução por provider, veja entities/workload.md. Para o modelo mais amplo dos três tipos de entrada e o montador que mescla a síntese com a saída renderizada a partir de source e os artefatos, veja architecture/16-recipe-input-composition.md.
Entregar os valores próprios de um componente à imagem do próprio desenvolvedor. Pela convenção do catálogo da biblioteca padrão, espera-se que uma Recipe que executa uma imagem construída pelo desenvolvedor entregue tudo o que os blocos inject: do desenvolvedor resolveram, a partir de .context.inject, e ela pode também entregar os valores próprios do componente com nomes escolhidos por ela. Onde o Component declara spec.inject, é o próprio bloco do desenvolvedor que escolhe os nomes, e .context.self_inject informa à Recipe o único valor próprio que o template de cada entrada lê — values.<key> para uma entrada que lê exatamente um valor próprio e nada mais. A convenção do catálogo da biblioteca padrão é tratar os nomes que uma Recipe dá a esses valores como padrões, e não como um contrato que o código do desenvolvedor precisa ler, entregando um valor com seu nome padrão somente quando nenhuma entrada o mapeia; um catálogo corporativo pode escolher de outra forma. O contrato do contexto de templates apresenta as regras exatas do mapa e um template de exemplo completo.
O campo artifacts: — manifestos auxiliares
Recipe.spec.artifacts: é um mapa de nome de entrada → definição do corpo de um artefato, cujas entradas emitem arquivos de manifesto adicionais ao lado da saída principal da Recipe, obtida de uma fonte ou sintetizada. É um dos três tipos de entrada (de fonte / sintetizada / artefatos) — uma Recipe pode declarar artifacts: sozinho, ou junto com workload: e/ou source:.
O valor de cada entrada adota um de três modos, escolhidos pela forma do conteúdo e paralelos aos de workload: — conteúdo inline, um $import: de arquivo ou um $import: de biblioteca. O compilador escolhe o modo pela forma do conteúdo do valor; nenhuma anotação $mode: é necessária. Nos três modos, a chave do mapa nomeia o que a entrada emite: nos dois modos de arquivo único, é o nome do arquivo de saída, e no modo bundle, é o diretório sob o qual os arquivos do bundle ficam aninhados. Como a chave nomeia a saída, ela se limita ao que um único nome de arquivo pode ser: uma letra ou um dígito inicial, depois letras, dígitos, pontos, hifens e sublinhados. Os pontos preservam a extensão que uma chave carrega por convenção — main.tf, template.yaml, serviceaccount.yaml —, enquanto o alfabeto não admite /, que faria uma chave nomear um caminho em vez de um arquivo, nem um . inicial, de modo que uma chave nunca pode ser o segmento do diretório pai. Uma chave fora desse alfabeto falha na validação do envelope ao carregar o espaço de trabalho, em aggrega validate e nos diagnósticos do editor.
spec: capability: helm implements: core/web-server:1.0.0 artifacts: extra-configmap.yaml: | apiVersion: v1 kind: ConfigMap metadata: name: "{{ .context.instance_id }}-extras" data: threshold: "{{ .values.threshold }}" network-policy.yaml: $import: ./artifacts/network-policy.tmpl operator-support: $import: PlatformArtifacts#/artifacts/OperatorSupportModo 1: inline (escalar de string com template Go). O valor é um escalar de bloco, e a chave do mapa é o nome do arquivo de saída, usado como está escrito — a primeira entrada acima emite extra-configmap.yaml.
Modo 2: $import: de arquivo. O valor é um mapa com uma única chave $import: que aponta para um arquivo local de template Go, e a chave do mapa é o nome do arquivo de saída, exatamente como no modo 1. O arquivo importado fornece o conteúdo; ele não fornece o nome. A segunda entrada acima tem a chave network-policy.yaml e emite network-policy.yaml, mesmo que o arquivo que ela importa se chame network-policy.tmpl. Assim, um autor que quer um nome de arquivo de saída específico o escreve como chave, e duas entradas que importam arquivos diferentes que por acaso têm o mesmo nome — ./extras/shared.yaml e ./overrides/shared.yaml — são duas saídas distintas. A resolução de caminhos é a mesma de valuesMapping: e workload:: um caminho relativo é ancorado ao diretório que contém o recipe.yaml que o declara, não ao diretório a partir do qual o build é invocado, e precisa permanecer dentro desse diretório.
Modo 3: $import: de biblioteca. O valor é um mapa com uma única chave $import: que carrega uma referência de identidade por nome simples a um bundle de uma ArtifactLibrary, <Library>#/artifacts/<name>. Um bundle é um conjunto de arquivos importados como uma única unidade, então uma entrada se expande em uma saída por arquivo do bundle, cada uma aninhada sob a chave do mapa como <key>/<filename> — a chave nomeia o ponto de uso e é o diretório em que esses arquivos ficam, e não o nome de nenhum deles. A terceira entrada acima tem a chave operator-support; se PlatformArtifacts#/artifacts/OperatorSupport declara crd.yaml e rbac.yaml, essa única entrada emite operator-support/crd.yaml e operator-support/rbac.yaml. A referência não carrega nenhum host de registry — uma forma oci://… com host é rejeitada —, a versão resolvida vem do lockfile por Release, e um piso de versão mínima :<version> opcional pode ser indicado como <Library>:<version>#/artifacts/<name>. Veja entities/artifactlibrary para a entidade de biblioteca e a gramática completa da referência.
Um $import: de arquivo é fixado ao lado da Recipe. aggrega pin registra o digest dos bytes de cada arquivo importado no arquivo entity.lock do diretório da Recipe, indexado pela chave do mapa da entrada, e aggrega build recalcula o digest do arquivo e interrompe com [CATALOG_ERROR E0026] quando ele não corresponde mais — ou antes com E0130 quando o lockfile da Release, escrito antes da edição, registra a Recipe pelo que ela contém —, de modo que um arquivo editado depois de fixado nunca é renderizado sem verificação. Se a mudança foi intencional, execute aggrega pin na Recipe para registrar o novo digest; caso contrário, restaure o arquivo. Uma entrada inline faz parte do arquivo da Recipe, e uma entrada de biblioteca é fixada pela versão da biblioteca que o lockfile registra, então nenhuma das duas carrega um pin próprio. aggrega pull descreve o arquivo.
O template de cada entrada de artefato é avaliado com o mesmo contexto de template de valuesMapping:, qualquer que seja o modo que forneceu seu corpo. Duas saídas com o mesmo nome de arquivo interrompem o build quando o nó é renderizado. Duas entradas de um mesmo mapa artifacts: não podem nomear uma mesma saída: uma chave de mapa é única dentro de um documento e escreve um único nome de arquivo, então a saída de uma entrada de arquivo único é a sua chave e os arquivos de uma entrada bundle ficam sob um diretório com o nome da sua chave — o primeiro segmento de cada caminho que uma entrada emite é a chave que o produziu, de modo que chaves distintas continuam sendo nomes de saída distintos, seja qual for o nome dos arquivos importados. O que a interrupção cobre é um mesmo nome de arquivo fornecido por dois tipos de entrada diferentes — um template de chart e uma entrada de artefato que produzem ambos servicemonitor.yaml —, relatado para essa Recipe com um diagnóstico que nomeia cada origem que contribui.
Casos de uso. artifacts: é o lugar dos recursos auxiliares que o chart ou o módulo principal não produz: uma NetworkPolicy que acompanha uma carga de trabalho, um HPA emparelhado com um Deployment, um ConfigMap sidecar com instance_id como chave. Recursos auxiliares transversais que se aplicam a muitos componentes (um sidecar de backup anexado a cada datastore, por exemplo) pertencem à Resource Generation da FeatureRecipe, e não aos artifacts: de cada Recipe — veja entities/featurerecipe.md para a superfície de extensão da FeatureRecipe.
O bloco boundary: — arquivos para a saída compartilhada da boundary
A maioria das Recipes nunca precisa disso. Todo o resto que uma Recipe escreve pertence ao seu próprio componente: o provedor o coloca na posição própria desse componente na saída da boundary. Alguns arquivos pertencem, em vez disso, à boundary como um todo — um arquivo que o destino lê uma única vez para tudo o que a boundary implanta. A configuração de provedores do Terraform é o caso comum: a documentação do Terraform mantém blocos provider fora de um módulo que outra configuração chama, e um módulo que carrega um bloco próprio não pode ser chamado com depends_on, count ou for_each. spec.boundary.artifacts é onde uma Recipe escreve um arquivo assim.
spec: capability: terraform implements: core/api-gateway/azure-api-management:1.0.0 artifacts: main.tf: $import: ./module/main.tf boundary: artifacts: # Terraform reads this beside the root configuration; one copy serves every # component of the boundary that declares it. provider-azurerm.tf: | provider "azurerm" { features {} }O bloco é artifacts: em um segundo escopo. artifacts é seu único membro, e ele tem exatamente a forma do próprio artifacts: da Recipe: os mesmos três modos — conteúdo inline, um $import: de arquivo, um $import: de biblioteca cujos arquivos ficam aninhados sob a chave da entrada como <key>/<filename> —, a mesma regra de chave para nome de arquivo e o mesmo alfabeto para uma chave, e o mesmo contexto de template, de modo que uma entrada lê .values, .infra, .locals e o resto exatamente como uma entrada de artifacts: faz. Ele precisa de pelo menos uma entrada, e qualquer outro membro sob boundary: é recusado quando a Recipe é lida. Uma FeatureRecipe não tem um bloco assim.
Onde um arquivo é escrito. Uma única vez, no diretório que contém a saída montada da boundary, ao lado dos arquivos que a montagem do próprio provedor escreve ali — no terraform, ao lado da configuração raiz aggrega.modules.tf, e não dentro do módulo do componente. Nenhum desses arquivos é entregue ao provedor: o compilador os avalia e os escreve ele mesmo, e não marca em nenhum deles de qual componente veio, porque o arquivo pertence a todos os componentes que o declararam. Uma entrada cujo template não renderiza nada não escreve nenhum arquivo.
Como vários contribuidores se encontram. Cada entrada é avaliada para cada componente que a Recipe renderiza na boundary, e os arquivos que todos os contribuidores da boundary declararam são mesclados por nome. Um nome avaliado para os mesmos bytes — por dois componentes vinculados a uma mesma Recipe, ou por duas Recipes que configuram um mesmo provedor de forma idêntica — é um único arquivo. Um nome avaliado para bytes diferentes interrompe o build, nomeando o arquivo e cada contribuidor, porque nenhum arquivo único é o que todos escreveram; o mesmo vale para um nome que a montagem do próprio provedor escreve, como aggrega.modules.tf. Ambos são a colisão da saída montada. Duas Recipes que configuram um mesmo provedor sob dois nomes de arquivo diferentes não são mescladas — cada arquivo é escrito — e é então o destino que relata a configuração duplicada; assim, Recipes destinadas a compartilhar uma configuração de provedor compartilham o nome do arquivo, por convenção um nome dado pelo provedor que ele configura.
Quais provedores o aceitam. Se um arquivo colocado ao lado da saída montada de uma boundary significa algo é uma propriedade do destino do provedor, então faz parte da declaração do próprio provedor. Uma Recipe que declara o bloco e cujo provedor não o aceita é recusada antes de qualquer renderização, seja qual for o resultado da renderização de suas entradas; veja The provider does not support boundary artifacts (O provedor não oferece suporte a artefatos de fronteira). A tabela de capacidades lista o que cada provedor declara.
| Provider | boundary.artifacts: |
|---|---|
terraform | Aceito. Cada arquivo é escrito ao lado da configuração raiz da boundary, que o Terraform lê junto com todos os outros arquivos de configuração desse diretório. |
helm, compose, helm-chart, cloudformation | Recusado antes de qualquer renderização. |
Um $import: de arquivo aqui é fixado como um que uma entrada de artifacts: importa. O lock da entidade registra seu digest na mesma lista artifactDigests, sob boundary/<key> em vez de apenas sob a chave, de modo que uma entrada de cada bloco escrita sob uma mesma chave é fixada separadamente. A etapa de pin o registra, um pull que não fixa interrompe onde o seu pin está ausente ou não corresponde mais, e um build recusa um arquivo editado desde que foi fixado exatamente como recusa um arquivo de artifacts:.
O campo outputLabels: — rótulos declarados pelo autor na saída renderizada
Recipe.spec.outputLabels: é um mapa de chave de rótulo → valor que o provedor aplica a cada objeto que a saída renderizada da Recipe produz. É o lugar honesto para um traço de realização — uma propriedade de como uma Recipe específica realiza um componente, em oposição ao que o componente é. Tome o armazenamento com que uma realização persiste seus dados, escrito abaixo com a chave ilustrativa example.io/storage-backing: uma Recipe do Helm que monta um PersistentVolumeClaim e uma Recipe do Compose que monta um volume nomeado realizam o mesmo componente com mecanismos diferentes, então carregam outputLabels diferentes, e as ferramentas posteriores (alocação de custos, políticas, inventário) podem distingui-las nos recursos emitidos. A chave é ilustrativa — example.io/ é um namespace de exemplo, e um catálogo escolhe as chaves que suas próprias ferramentas leem.
spec: capability: helm implements: core/datastore/postgres:1.0.0 outputLabels: example.io/storage-backing: persistent-volume example.io/team: platformOs rótulos de saída seguem pelo mesmo trilho que os rótulos fixos de proveniência do build: são mesclados no conjunto de rótulos que cada superfície de emissão aplica, então chegam aonde quer que a proveniência chegue. O que difere é a titularidade — as chaves de proveniência pertencem ao compilador, as outputLabels ao autor da Recipe.
O rótulo de identidade próprio de um componente não é digitado aqui — uma convenção do catálogo, não uma regra que o compilador impõe. As chaves que dizem o que o componente é, e não como uma Recipe o realiza — sua categoria cognitiva, seu tipo operacional, seus rótulos de capacidade por papel, quem opera o recurso subjacente, a classe de licença do que ele encapsula — são declaradas nos metadata.labels do Component; veja entities/component “A taxonomia semântica de rótulos” para os eixos. Uma Recipe coloca um deles na sua saída renderizada nomeando a chave em outputComponentLabels: abaixo, não digitando aqui a chave e um valor. O motivo é que uma entrada literal é uma segunda cópia de um valor que o componente já carrega, e uma segunda cópia pode divergir da primeira: o autor de uma Recipe pode digitar uma postura em um nó cujo Component declara outra, dizendo a um leitor posterior algo que o grafo não diz. Uma entrada promovida copia por referência e, portanto, não tem segunda cópia para divergir. O núcleo aceita o que quer que você escreva, salvo pela regra de namespaces reservados abaixo; a convenção é mantida pelos autores de catálogos.
Namespaces reservados. Os namespaces aggrega.ai/ e app.kubernetes.io/ são reservados para a proveniência nativa da plataforma. Uma Recipe que declara uma chave de outputLabels sob qualquer um dos dois prefixos é rejeitada no carregamento com um erro de catálogo claro que nomeia a chave em questão. Qualquer outra chave é aceita. Fora isso, o núcleo não fiscaliza a chave nem o valor — uma chave ou valor que não seja válido para a superfície de rótulos do mecanismo de destino é responsabilidade do autor, e o runtime posterior o rejeita; o compilador não interfere além da regra de namespaces reservados.
Exposição por provedor. Cada provedor transpõe os rótulos para a sua própria superfície de saída:
- helm, síntese de workload — tanto nos
metadata.labelsdo objeto quanto nosmetadata.labelsdo template de pod, correspondendo a onde a síntese coloca a proveniência. - helm, renderização a partir da fonte e artefatos — nos
metadata.labelsdo objeto. - compose — no mapa
labels:de cada serviço. - terraform — como tags por recurso em corpos de artefato
.tf.jsonendereçáveis estruturalmente, na base do melhor esforço: um bloco de recurso que já declara um mapatags(AWS/azurerm) oulabels(Google) recebe ali os rótulos de saída, uma chave declarada pelo autor nunca é sobrescrita, e um recurso sem esse atributo é deixado intacto (um atributo nunca é inventado). Corpos em HCL nativo (main.tf,*.tf) e módulos vendorizados são emitidos literalmente e não carregam tags injetadas. A proveniência do Terraform continua viajando no seu arquivo de comentários associado, separado do trilho de tags.
Os rótulos de saída são apenas rótulos; não existe uma superfície separada de anotações de saída. outputLabels é declarado pelo autor da Recipe (a camada de realização escrita por Ops), não pelo Aggregate — descreve a realização, nunca a identidade do grafo abstrato do desenvolvedor.
O campo outputComponentLabels: — promovendo os rótulos próprios de um componente
Recipe.spec.outputComponentLabels: é uma lista de chaves de rótulo, não de pares chave-valor. Para cada chave que nomeia, o provedor aplica essa chave à saída renderizada com o valor que a chave tem na instância do componente sendo renderizada. Onde outputLabels declara um valor, outputComponentLabels indica de onde o valor deve ser lido.
spec: capability: helm implements: core/datastore/postgres:1.0.0 outputLabels: example.io/team: platform outputComponentLabels: - component.aggrega.ai/hostingDado um Component cujos metadata.labels declaram component.aggrega.ai/hosting: managed, cada objeto que esta Recipe renderiza para esse componente carrega component.aggrega.ai/hosting: managed. Vincule a mesma Recipe a um componente que declara self-hosted e os objetos desse componente carregam self-hosted em vez disso — uma Recipe, uma chave nomeada, um valor por componente.
A promoção é por referência, e esse é o ponto. O valor é lido do componente sempre que a saída é renderizada, então não pode divergir da identidade de onde veio: não há segunda cópia para manter em sincronia quando o rótulo do componente muda. Uma entrada literal de outputLabels que repete o rótulo de um componente é essa segunda cópia, e as duas divergem no momento em que qualquer uma delas muda. Então use outputLabels quando o valor é uma propriedade de como esta Recipe realiza o componente, e outputComponentLabels quando o valor já existe no componente e a saída renderizada também deve carregá-lo.
Uma chave promovida chega exatamente à mesma superfície que uma literal — a exposição por provedor descrita acima se aplica sem alterações, e nenhum provedor distingue uma chave que foi promovida de uma que foi escrita diretamente.
Namespaces reservados. Os namespaces aggrega.ai/ e app.kubernetes.io/ são reservados para a proveniência nativa da plataforma, e uma chave promovida sob qualquer um dos dois prefixos é rejeitada no carregamento com um erro de catálogo que nomeia a chave e o campo em que ela aparece. O critério é o prefixo puro: uma chave como component.aggrega.ai/hosting fica em um namespace próprio, e não sob a raiz reservada, e pode ser promovida.
Uma chave pertence a um bloco ou ao outro. Declarar a mesma chave tanto em outputLabels quanto em outputComponentLabels é rejeitado no carregamento, de modo que cada chave aplicada tem uma única fonte — ou o valor literal escrito na Recipe ou o rótulo próprio do componente, nunca ambos.
Uma chave promovida que o componente não declara não aplica nada. O build continua e emite um aviso que nomeia o nó, a Recipe e a chave ausente. Isso é deliberado: uma Recipe vinculada a componentes cujos conjuntos de rótulos diferem ainda é renderizada, e a discrepância é relatada em vez de interromper o build.
Componentes de postura única — uma convenção, não uma regra. A promoção carrega qualquer valor que o componente declare, e o compilador não interpreta esse valor. Um componente cujo rótulo de identidade contém um marcador que representa “varia” promove, portanto, esse marcador para cada objeto renderizado para ele. Quando um componente realmente tem mais de uma postura, a convenção do catálogo da biblioteca padrão é que cada Recipe declare a postura da sua própria realização por meio de uma chave de outputLabels que pertence à Recipe, e não por meio da chave de identidade do componente, que a mesma convenção encaminha por outputComponentLabels: — ou que não aplique nada. As duas chaves respondem a perguntas diferentes e nenhuma substitui a outra: a chave de identidade diz o que o componente é em todas as realizações, a chave da Recipe diz o que esta realização específica faz. Essa é uma convenção do catálogo mantida pelos seus autores, não uma restrição que o compilador impõe.
O bloco locals:
Recipe.spec.locals: é o estado privado de Ops — um mapa de strings de template Go nomeadas cuja saída renderizada expõe um mapa .locals.* aos templates posteriores da Recipe. É o espaço de trabalho para calcular realidades físicas (contêineres de destino, caminhos JSON, nomes de host derivados) uma única vez e reutilizá-las nos payloads de provides:, source:, valuesMapping:, workload:, artifacts:, assertions: e pipeline[].with sem recálculo. A saída renderizada de cada entrada é armazenada sem os espaços em branco iniciais e finais.
spec: capability: helm implements: core/postgres-db:1.0.0 source: ./charts/postgresql locals: primary_compute: postgresql listen_port: "5432" secret_target_db_password: "postgres-auth" volumes_path: "/spec/template/spec/volumes" valuesMapping: | primary: auth: existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_db_password }}"locals: nunca é exposto a chamadores — componentes posteriores que consomem esta Recipe via uses: veem apenas provides:. Os templates provides:, source:, valuesMapping:, workload:, artifacts:, assertions: e pipeline[].with da própria Recipe veem todos o mapa .locals.* resolvido. Os valores por chave podem ser strings simples ou templates Go; o compilador resolve o bloco inteiro no preâmbulo dos locals, antes do provides: desse nó, de modo que todo template posterior observa valores resolvidos estáveis.
Cada entrada é avaliada contra um contexto autocontido e local ao nó: .context.instance_id, .values, .infra e as entradas deste mesmo bloco já resolvidas. Um local não pode ler .provides — esse pilar não está nesta superfície, e uma entrada que tenta alcançá-lo interrompe o build. Ele também não pode ler .context.rendered_name, o nome que um provedor como helm dá aos recursos que renderiza para o nó; assim, um local que nomeia um desses recursos carrega apenas a parte depois desse nome, como secret_target_db_password faz acima, e o template que escreve o nome completo junta as duas partes.
A ordem de escrita é determinante
As entradas são resolvidas na ordem em que são escritas, e uma entrada pode ler uma entrada irmã definida acima dela, recebendo o valor resolvido dessa entrada irmã:
spec: locals: db_identifier: "{{ .context.instance_id }}-postgres" # defined first secret_target: "{{ .locals.db_identifier }}-auth" # reads the entry aboveO encadeamento corre apenas para baixo. Quando uma entrada lê outra, a ordem das entradas decide se o build tem sucesso: mova db_identifier para baixo de secret_target e o build é interrompido. O compilador nunca ordena nem reordena o bloco para fazer uma referência se resolver, então a ordem escrita é o contrato — reordenar um bloco locals: é uma mudança de comportamento, não cosmética.
Duas interrupções distintas separam os dois erros que um autor pode cometer, porque eles têm correções diferentes:
- Uma referência a uma entrada que o bloco define mais adiante interrompe o build nomeando o erro de ordem; a correção é mover a definição para cima de quem a lê.
- Uma referência a uma chave que o bloco não declara de forma alguma interrompe o build nomeando a chave; a correção é corrigir a grafia.
A verificação acompanha um alias do bloco. Uma chave alcançada pelo ponto que um corpo with .locals reassocia, ou por uma variável associada a .locals, é verificada exatamente nas mesmas condições que a escrita direta: {{ with .locals }}{{ .nope }}{{ end }} e {{ $l := .locals }}{{ $l.nope }} interrompem ambos o build nomeando .locals.nope, assim como {{ .locals.nope }}, e o mesmo fazem {{ (.locals).nope }} e {{ ($.locals).nope }}, porque os parênteses produzem o próprio bloco e nada mais. Uma única escrita escapa da verificação: uma chave alcançada por uma chamada cujo resultado o texto do template não consegue nomear — {{ index .locals "nope" }}, ou {{ (default dict .locals).nope }} —, porque o que essa chamada produz é decidido quando o template é executado, e não pelo que está escrito. Uma chave ausente lida como campo do resultado dessa chamada não interrompe o build, e é renderizada como o texto literal <no value> em vez de nada. Uma chave ausente alcançada por index interrompe o build, nomeando a chave, porque index interrompe em todas as superfícies de template quando o mapa que lê não contém a chave pedida — um relato diferente do desta verificação, documentado em errors/fatal-halts.md em “A template indexes a map with a key the map does not hold (Um template indexa um mapa com uma chave que o mapa não contém)”. Portanto, index continua sendo a forma de alcançar uma chave cujo nome é ele mesmo calculado, como {{ index .locals (printf "secret_target_%s" .values.slot) }}, e um nome calculado que o bloco não declara continua sendo relatado pela sua chave.
provides: lê .locals e recebe valores resolvidos, porque os locals de um nó são resolvidos antes dos seus provides. Um template provides: que nomeia uma chave que o bloco locals não declara interrompe o build. Isso significa que um valor de que tanto uma entrada de provides: quanto um artefato precisam é escrito uma vez, em locals:, e lido dos dois lugares.
Para a contraparte de API pública, veja O bloco provides: abaixo. A superfície da FeatureRecipe segue as mesmas regras — veja entities/featurerecipe.md “O bloco locals:”.
O bloco provides:
Recipe.spec.provides: é a API pública para desenvolvedores — um mapa de nome → string de template Go que declara os valores com que esta Recipe contribui para os pipes .context.inject e .context.uses dos chamadores a jusante. O compilador avalia os templates provides: na avaliação de provides (autocontida, em qualquer ordem); as chaves inject dos chamadores são resolvidas em relação a esses valores na hidratação de inject.
spec: capability: helm implements: core/postgres-db:1.0.0 source: ./charts/postgresql provides: # The Service this chart names after its release name, suffixed "-postgresql" host: "{{ .context.rendered_name }}-postgresql" port: "5432" database: "{{ .values.db_name }}"O template de cada entrada é avaliado sobre a superfície autocontida de avaliação de provides — .context.instance_id, .context.rendered_name quando o provedor do nó informa um, .values, .infra, os .locals resolvidos do nó e texto estático. O namespace em que o nó é colocado não faz parte dela, então um host publicado não carrega nenhum: um consumidor em outro namespace o qualifica do seu próprio lado. .locals faz parte dela porque os locals do nó são resolvidos no preâmbulo da mesma etapa, antes de seus provides; um template provides que nomeia uma chave que o bloco locals não declara interrompe o build. Separar a avaliação de provides da hidratação de inject é fundamental: o provides: de uma Recipe não pode referenciar o estado de nenhum chamador porque os chamadores ainda não foram resolvidos quando a avaliação de provides é executada — provides: é autocontido conforme o invariante arquitetural. Os chamadores então leem esses valores via .context.uses.<alias>.provides.<provided-name> em seus próprios templates — os nomes fornecidos ficam aninhados sob provides na aresta, ao lado dos outros campos da aresta. Um chamador que declara uma allowlist inject: na aresta alcança, em vez disso, os mesmos valores por meio de seu pipe .context.inject.
As chaves provides: fazem parte da superfície contratual da Recipe. Renomear ou remover uma chave é uma mudança incompatível para todo chamador que dependa do nome antigo; a versão de interface implements: deve refletir a evolução do contrato. Para a semântica de resolução em cascata, o contrato do pipe de inject e exemplos completos que cobrem roteamento entre namespaces e entre regiões, consulte architecture/06-data-taxonomy-and-composition.md §3 e templates/expansion-matrix.md.
Lendo os valores publicados de uma vinculação
Uma Recipe lê as Features vinculadas ao seu componente em .features.<instance-name> e as Features de credenciais em .features.<slot>. Ambas têm a mesma forma de vinculação — .type, .values, .infra, .provides —, de modo que uma vinculação é lida da mesma maneira seja qual for o mapa que a contém; o que as diferencia é o que a vinculação produz.
.provides é a saída publicada da vinculação, resolvida a partir da FeatureRecipe associada a ela. É a contraparte do bloco provides: acima, vista do lado consumidor: onde uma Recipe publica para seus chamadores, uma vinculação publica para seu componente hospedeiro.
workload: | # The identity attachment emits a ServiceAccount and publishes its name; # the pod binds to that published name rather than restating it. serviceAccount: "{{ .features.identity.provides.name }}" containers: main: env: DB_SECRET: "{{ .features.app_credentials.provides.name }}"Ler o valor publicado em vez de recalculá-lo a partir das mesmas entradas values/infra é a diferença entre uma única declaração de um nome e duas que podem divergir. A forma completa campo a campo, incluindo as regras de disponibilidade, está em templates/template-context-contract.md.
Uma vinculação escrita em uma das conexões do componente — uma credencial que o componente apresenta a um destino — é lida na mesma forma sob essa conexão, em .context.uses.<alias>.features.<slot>, e nunca está entre as .features. Uma Recipe que alcança vários destinos lê a credencial própria de cada destino sob o alias desse destino, e um laço sobre .features que seleciona vinculações por tipo encontra apenas as do próprio componente:
artifacts: routes.yaml: | {{- range $alias, $edge := .context.uses }} - name: {{ $alias }} {{- with $edge.features }}{{ with .credential }} api_key_secret: {{ .provides.name }} {{- end }}{{ end }} {{- end }}Consulte As vinculações de uma conexão para a forma e para a ordem em que um template percorre as conexões.
O campo pipeline:
Recipe.spec.pipeline: é um array sequencial de etapas de pipeline Wasm que são executadas após a renderização sobre o conjunto de documentos renderizados, cada uma retornando patches RFC 6902 e efeitos colaterais. Cada entrada declara um id (identificador por etapa: letras, dígitos e sublinhados), um plugin (a entidade Plugin que a etapa executa, delimitada pelo seu tipo de plugin — pipeline-step/<name>, opcionalmente com uma versão; uma referência .wasm simples ou a um artefato é recusada), uma function (o export do plugin a ser invocado), um corpo de template Go with: opcional que fornece o payload do plugin e um template Go when: opcional que determina se a etapa é executada — um resultado falso pula a etapa como pass-through, deixando o conjunto de documentos inalterado. A condição when:, sua independência de optional: e sua regra de veracidade são tratadas por completo em entities/featurerecipe.md “Etapas condicionais — when:”:
spec: capability: helm implements: core/web-server:1.0.0 source: { kind: helm-oci-chart, url: "oci://…", version: "…" } pipeline: - id: inject_sidecar plugin: pipeline-step/envoy-sidecar:1.0.0 function: Inject with: | target_container: "{{ .locals.primary_compute }}" envoy_version: "{{ .values.envoy_version | default "1.30.0" }}"O compilador executa as etapas pipeline: de uma Recipe base na ordem declarada, da mesma forma que executa o pipeline: de uma FeatureRecipe: ele invoca o plugin Wasm nomeado por cada etapa sobre a saída renderizada, aplica as operações JSON Patch retornadas aos documentos endereçados e emite os efeitos colaterais da etapa. O campo pipeline: da FeatureRecipe compartilha a mesma forma de schema e a mesma execução — consulte entities/featurerecipe.md “Contrato de autoria” e Status da linguagem para o estado de execução de cada superfície.
A mecânica do campo espelha a semântica da FeatureRecipe: avaliação sequencial na ordem declarada, operações JSON Patch aplicadas aos documentos renderizados, efeitos colaterais emitidos junto com elas e erros reportados com uma procedência que aponta para a etapa causadora. Uma etapa cuja condição when: é renderizada como falsa é pulada como pass-through, deixando o conjunto de documentos inalterado para a etapa seguinte.
O bloco assertions:
Recipe.spec.assertions: é um mapa opcional de regras nomeadas que expressam invariantes de implementação da Recipe — regras entre campos que valem dado o chart ou módulo específico do qual a Recipe obtém sua fonte. Cada chave é um identificador de regra que aparece na mensagem de falha; cada valor é um corpo de template Go. Ao contrário das asserções do Component (que expressam invariantes no nível do contrato independentemente de qual Recipe seja associada), as asserções da Recipe são propriedades da implementação específica escolhida.
spec: implements: core/datastore/mariadb:^1.0.0 source: kind: helm-oci-chart url: oci://registry-1.docker.io/bitnamicharts/mariadb version: "20.0.0" assertions: # Bitnami 20.x: serviceMonitor namespace requirement. service-monitor-namespace-required: | {{- if and (eq .values.architecture "replication") .values.metrics.serviceMonitor.enabled -}} {{- if not .values.metrics.serviceMonitor.namespace -}} {{- fail "Bitnami MariaDB 20.x requires metrics.serviceMonitor.namespace when architecture=replication and metrics.serviceMonitor.enabled=true" -}} {{- end -}} {{- end -}}A regra acima é específica do chart Bitnami 20.x; ela não se aplica se uma Recipe MariaDB diferente for associada. As regras no nível do Component provenientes do contrato continuam a se aplicar em paralelo, avaliadas em uma fase anterior do pipeline.
As asserções da Recipe são avaliadas após a associação da Recipe e antes da renderização, depois que os locals e provides de cada nó são resolvidos. O contexto do template inclui .provides, .locals e .recipe.source da Recipe, além dos campos da instância da entidade (.values, .infra, .uses, .features). Ali, .uses e .features são as formas mais restritas da superfície de asserções, não as de um template de Recipe: a entrada de uma conexão carrega seu destino e seu alias, as labels do destino, os values próprios da conexão e as vinculações escritas nela sob features, mas nada do que o destino publica; e a entrada de uma vinculação, seja do próprio componente ou de uma conexão, carrega seu type, sua resolved_version e seus values, mas nem seu infra nem seu provides — a FeatureRecipe de uma vinculação ainda não resolveu seus provides quando a asserção é executada. Uma referência a .features.<name>.provides portanto interrompe o build, e uma leitura que considera a presença retorna seu valor de fallback. Para a gramática de autoria completa, a divisão de responsabilidades entre regras no nível do contrato e no nível da implementação, e exemplos completos, consulte templates/assertions-block.md.
O campo omits: — deixar documentos renderizados fora de uma fonte
A maioria das Recipes nunca precisa disso. Serve para uma fonte que você usa como ela é — na maioria das vezes, um chart obtido de um registry — que renderiza um documento que sua Release não deve entregar: um Secret que o chart gera de novo a cada renderização, por exemplo, o que faz dois builds diferirem e, uma vez aplicado, sobrescreve o Secret fornecido pelo operador. Você não edita um chart obtido, e nenhuma regra de exclusão alcança o interior de um, então omits: é a forma como uma Recipe deixa um documento desses fora do build. Um arquivo compose obtido é o mesmo caso: ele pode incluir um serviço, um volume ou uma config que a Release não deve ter, e um overlay valuesMapping: pode alterar um deles, mas nunca removê-lo. O mesmo vale para um template CloudFormation obtido, que pode declarar um recurso que a Release não deve criar: um valuesMapping: pode preencher os parâmetros que ele declara, mas nunca remover um de seus recursos.
spec: capability: helm implements: core/gateway/kong:1.0.0 source: kind: helm-oci-chart url: oci://registry.example.com/charts/gateway version: "2.4.0" omits: # The chart generates this key on every render; the operator supplies it. - kind: Secret name: "{{ .context.rendered_name }}-session-key" # Left out only where the Release asks for it. - when: "{{ .infra.without_dashboards }}" kind: ConfigMap name: "{{ .context.rendered_name }}-dashboards" namespace: monitoringO que abrange. Apenas o que source: renderiza. Um workload: e as entradas de artifacts: nunca são filtrados: você os escreve na Recipe, então um documento que você não quer ali é um que você simplesmente não escreve. A chave exige source:; um documento que viole essa regra é recusado quando é lido, indicando a regra.
Uma entrada. Cada entrada nomeia o que deixar de fora por meio de três campos, e um quarto decide se ela se aplica. O que os três primeiros nomeiam é o vocabulário próprio do provedor para o que sua fonte renderiza, apresentado por provedor na tabela abaixo:
kind— o tipo do que a fonte renderiza: para um chart, o kind de um documento renderizado —Secret,ConfigMap,Deployment; para um arquivo compose,service,volumeouconfig; para um template CloudFormation, oTypede um recurso —AWS::S3::Bucket. Não tem relação com okind:que umsource:estruturado carrega, que indica como a fonte é obtida.name— seu nome: ometadata.namede um documento; a chave de uma unidade compose sobservices:,volumes:ouconfigs:; o ID lógico de um recurso CloudFormation, sua chave sobResources.namespace(opcional) — o namespace em que o documento está, para um provedor cuja saída tem namespaces. Sem ele, a entrada nomeia o kind e o nome em qualquer namespace; umnamespaceque renderiza vazio é tratado como ausente.when(opcional) — se a entrada se aplica a este build. É avaliado primeiro e lido pela mesma regra que owhen:de uma etapa de pipeline: um resultado falso descarta a entrada, de modo que seus outros campos não são avaliados e ela não é entregue ao provedor nem verificada, enquanto umwhen:ausente ou vazio a mantém.
kind e name são obrigatórios, e uma entrada que carregue qualquer outro campo é recusada quando a Recipe é lida.
Todo valor é um template, avaliado no mesmo contexto que valuesMapping:. Esse contexto carrega .context.rendered_name, o nome que o provedor dá aos recursos do nó e aquele a partir do qual um chart normalmente os nomeia, de modo que uma entrada pode nomear um documento exatamente como o chart fará. Um template que falha ao renderizar interrompe o build como um template valuesMapping: com falha.
Toda entrada que se aplica deve deixar algo de fora. O provedor informa quantas unidades cada entrada deixou de fora, e uma entrada que não deixou nenhuma de fora interrompe o build, nomeando a entrada; consulte An omits entry left out nothing the source rendered (Uma entrada omits não deixou de fora nada do que a fonte renderizou). Uma atualização da fonte que renomeia ou remove o documento é a causa habitual, e a interrupção é o que impede que um documento renomeado chegue à sua saída sem ser notado. Para deixar um documento de fora apenas às vezes, diga isso com when: em vez de contar com a ausência do documento.
A fonte ainda é renderizada por completo. Apenas sua saída é filtrada: todo template do chart ainda é executado, então um template que falha ainda faz o build falhar, e um documento deixado de fora é renderizado e depois descartado. Uma vez descartado, ele não alcança nada do que o build faz em seguida — nenhum arquivo emitido, nenhum nome comparado com os nomes de outros componentes, nenhum fato que uma Feature lê sobre a renderização, nada que seja entregue a uma etapa de pipeline.
Uma Release alcança a chave por meio de infra e parameters. A chave pertence à Recipe, então uma Release não pode escrevê-la. Ainda assim, ela pode decidir o que uma entrada faz: os templates de uma entrada leem o infra que a Release preenche, e os parameters que ela fornece chegam aos .values da Recipe onde quer que o Aggregate os encaminhe. Assim, uma Release liga ou desliga uma entrada com when:, como faz a segunda entrada acima, ou decide o que ela nomeia.
O que você deixa de fora é responsabilidade sua. Nada no build sabe para que serve um documento. Deixar de fora um do qual o resto do chart depende em tempo de execução — o Secret que um Deployment monta, a ServiceAccount com a qual um pod é executado — produz uma saída que compila sem problemas e depois falha quando é aplicada, a menos que outra coisa aplicada ao lado forneça esse documento. Para um arquivo compose e um template CloudFormation o build verifica, sim, porque cada um declara as próprias referências: o que resta e ainda nomeia uma unidade deixada de fora — um serviço que nomeia um serviço deixado de fora, um recurso ou uma saída que nomeia um recurso deixado de fora — interrompe o build, como descreve a tabela abaixo.
Quais provedores o respeitam. Deixar um documento de fora é algo que só o provedor pode fazer, porque só o provedor sabe o que sua fonte renderiza; por isso, se um provedor respeita a chave faz parte da declaração própria do provedor. Uma Recipe que declara omits: cujo provedor não o respeita é recusada antes que qualquer coisa seja renderizada, seja qual for o resultado da renderização dos when: de suas entradas; consulte The provider does not support omits (O provedor não oferece suporte a omits).
| Provider | omits: |
|---|---|
helm | Respeitado. Uma entrada nomeia um documento que o chart renderiza — a partir de um template ou de seu diretório crds/ — pelo kind e pelo metadata.name próprios do documento e, quando a entrada nomeia um, pelo namespace em que o documento está. Consulte helm → Modo com fonte. |
compose | Respeitado. Uma entrada nomeia um service, um volume ou um config do arquivo compose de origem pela sua chave sob services:, volumes: ou configs:, comparada depois que valuesMapping: é mesclado ao arquivo, e não nomeia nenhum namespace: uma entrada que nomeia outro kind, ou um namespace, interrompe o build quando o componente é renderizado. Um arquivo em que o que resta ainda nomeia uma unidade deixada de fora — por depends_on, links, volumes_from, um modo de rede ou de namespace service:, extends, um contexto de build, ou uma entrada volumes: ou configs: — interrompe o build, nomeando cada referência. Consulte compose → Modo com fonte. |
cloudformation | Respeitado. Uma entrada nomeia um recurso do template de origem pelo seu Type e pelo seu ID lógico, em todo template de uma fonte de diretório, e não nomeia nenhum namespace: uma entrada que carregue um interrompe o build quando o componente é renderizado. Um template em que o que resta ainda nomeia um recurso deixado de fora — por Ref, Fn::GetAtt, DependsOn ou uma variável Fn::Sub — interrompe o build, nomeando cada referência. Consulte cloudformation → Deixando recursos de fora de um template de origem. |
helm-chart, terraform | Recusado: o provedor repassa sua fonte para ser renderizada quando é implantada, então nenhum documento existe no momento do build para ser deixado de fora. Para um chart ou módulo local, uma linha no .aggregaignore ao lado da Recipe deixa de fora, em vez disso, um arquivo dele. |
A mesma chave é escrita em uma FeatureRecipe; consulte entities/featurerecipe.md.
Para um exemplo completo — o Secret gerado de um chart obtido deixado de fora, a interrupção por determinismo que o mesmo chart encontra sem a entrada, e a interrupção em uma entrada que não corresponde a nada, cada um de um build real — consulte ai-gateway-own-webhook-certificate.