Recipe
O papel conceptual da entidade Recipe (o modelo de tradução escrito pelas Ops que mapeia a intenção do programador para o formato físico) encontra-se 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 de IaC e exemplos completos.
A arquitetura da Recipe: ponteiros e mapeadores
Uma Recipe desempenha exatamente duas funções:
- O ponteiro (
source): indica ao compilador exatamente onde se encontra 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 — escalar de bloco inline,$import:de ficheiro ou$import:de biblioteca — despachados pela forma 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 ao nível da raiz, garantindo que o compilador Go sabe exatamente que plugin de renderização Wasm a jusante deve invocar.
spec.implements declara que tipo de componente do catálogo a Recipe é capaz de implementar. O compilador usa-o para verificar os mapeamentos do Manifest (o implements de uma Recipe mapeada tem de corresponder ao tipo mapeado) e para sugerir candidatas — as recipes listadas num diagnóstico de mapeamento em falta e classificadas em primeiro lugar no preenchimento automático do editor. Nunca resolve uma compilação: o mapeamento do Manifest é a escolha explícita de implementação do utilizador, fixada no lockfile. Uma Recipe cujo implements não tem versão, é exato ou é um intervalo compatível com a versão principal continua apenas a oferecer-se para um tipo; é o utilizador quem fixa a escolha. FeatureRecipe.spec.implements desempenha o mesmo papel para os tipos de feature.
A. Esquemas de source orientados por Wasm
Para manter os enviesamentos de implementação fora do compilador, o bloco source não é um conjunto fixo de campos de infraestrutura. O campo source suporta dois formatos:
- A string universal (rápida e limpa): ideal para caminhos locais, artefactos 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://...): um URL que termine em.git, ou escrito comgit://oussh://, é um repositório Git obtido no seu ramo predefinido, e um URLhttps://que não indique nem um repositório nem um chart.tgzou um fragmento.yamlé recusado por ser ambíguo. - 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 a sua própria forma de source (por exemplo,registry/chart/appVersionpara o Helm).
O que o núcleo resolve. Nenhum provider valida chaves de source próprias. Um source obtido é resolvido por uma identidade nativa cujo kind seleciona um resolvedor — helm-oci-chart, helm-https-chart, compose-https-fragment e git-repository. Um source destinado a ser obtido tem de 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 fixam-na tal como está escrita. git-repository aceita ref — uma tag, um ramo ou um commit — e, opcionalmente, module_subdir, que indica o diretório dentro do repositório que constitui o artefacto; como apenas um commit identifica conteúdo que não pode ser reapontado, a referência é resolvida no momento do bloqueio e o lockfile regista tanto a referência escrita como o commit para o qual foi resolvida. Um module_subdir que, tal como está escrito, sobe acima do repositório — uma barra invertida conta como separador — é recusado antes de qualquer obtenção. O repositório é arquivado a partir do seu próprio checkout: uma ligação simbólica incluída num commit é arquivada como o ficheiro ou diretório para que aponta, quando este se encontra dentro do repositório, e uma que saia dele interrompe o pull, indicando a ligação pela sua posição no repositório. Um source estruturado cujo url: indica um caminho do sistema de ficheiros não é obtido: é lido do disco nas mesmas condições que uma string de caminho simples, com um url: relativo ancorado no diretório que contém o ficheiro da entidade que o declara. Um source estruturado que omita kind/url também não é obtido e, se se pretendia uma obtenção, a compilação é interrompida de forma explícita na descida de sources no momento do bloqueio, em vez de se resolver silenciosamente em nada. O conteúdo é sempre fixado antecipadamente; o compilador nunca obtém estado de runtime em tempo real.
O que é fixado ao lado da Recipe. Para um source obtido cujos kind, url, chart, module_subdir, version e ref estão todos escritos por extenso em vez de gerados por template, aggrega pin regista o digest do que obteve em entity.lock, um ficheiro no próprio diretório da Recipe que se faz commit ao lado dela. A fixação é o passo do autor da Recipe e não precisa de nenhuma Release; um pull sobre uma Recipe cujo lock não registe a fixação é interrompido e indica-a, a menos que se peça ao pull que execute o mesmo passo. Uma compilação compara esse digest com o que o lockfile da Release regista para o mesmo source, e é interrompida quando os dois divergem — exceto no caso de um source escrito com um ref: git, cuja linha é registada no commit para o qual a ref foi resolvida e não é comparada. Um source obtido cujas coordenadas são preenchidas a partir de um template é fixado por Release, no lockfile de cada Release. Um source que indique um diretório ou um ficheiro ao lado da Recipe não é obtido: aggrega pin regista um digest por cada ficheiro com que contribui para o que uma publicação da Recipe transporta — todos os ficheiros do diretório da Recipe, no caso de um source escrito como template — e, assim que o lock os regista, uma compilação compara o source com eles antes de o provider o ler, interrompendo-se perante um ficheiro adicionado, alterado ou removido desde a fixação — com E0305, ou primeiro com E0130 quando o lockfile da Release, escrito antes da alteração, regista a Recipe pelo que ela transporta. Um lock que não registe nenhuma fixação para esse source não dá a uma compilação nada com que comparar, e um pull ou uma publicação que não fixe recusa-o. O próprio ficheiro da Recipe nunca é escrito. aggrega pull descreve o ficheiro 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 acento circunflexo (helm:^<version>) — que seleciona a versão do plugin do provider que renderiza a Recipe; uma fixação que nenhuma versão disponível satisfaça interrompe a compilação. Sem fixação (spec.capability: "helm"), é a versão disponível mais alta que a renderiza. As versões disponíveis são as que aggrega plugin list mostra: os providers incorporados no 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 declare capability: "compose:1.2.3" como compose/<name>:<version>, exatamente como uma sem fixação, e alterar a fixação nunca lhe muda o nome; um valor de mapeamento que escreva a fixação no nome (compose:1.2.3/<name>:<version>) é recusado como referência de recipe malformada (E0095) antes de qualquer pesquisa.
Modelo mental: spec.capability indica o formato de saída pretendido (por exemplo, helm, terraform, compose); o compilador resolve-o para o plugin Wasm que renderiza esse formato (por exemplo, provider/helm). O autor declara o formato; a Aggrega associa a ferramenta.
B. Injeção de contexto: a camada de mapeamento semântico
Para impedir que o compilador execute deep-merges perigosos e não determinísticos entre vários ambientes, uma Recipe admite apenas uma única fonte de verdade para a sua camada de mapeamento.
Os engenheiros de Ops escrevem o conteúdo de mapeamento para traduzir o contexto abstrato antes de o plugin de renderização Wasm ser executado. A linguagem de mapeamento é o template Go (text/template + Sprig); a biblioteca Sprig está pré-registada; as ações habituais define e template são suportadas, e include não está registada.
| Nome do campo | Âmbito e fase de execução | Melhor caso de utilização |
|---|---|---|
injectMapping (apenas FeatureRecipe) | Interceção pré-renderização. Avaliado na memória Go antes da Recipe base. Faz nativamente deep-merge do seu dicionário de saída estritamente sobre o pipe .context.inject do chamador. Intencionalmente ausente do esquema base de Recipe — consulte entities/featurerecipe para a fundamentação 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 ficheiro, $import: de biblioteca). Consulte a subsecção abaixo para o mecanismo de despacho. | Mapear variáveis comuns (como réplicas ou tags de imagem) para um chart Helm diretamente no YAML da Recipe, ou referenciar um template partilhado através de $import: para reutilização entre Recipes. |
Nota: injectMapping é exclusivo das FeatureRecipes e isola a interceção de variáveis do valuesMapping. O valuesMapping da Recipe base consome, sem o saber, as strings .context.inject reescritas geradas pelos blocos injectMapping da FeatureRecipe, pelo que os dois se mantêm desacoplados.
Uma chave que o valuesMapping escreve como null chega ao provider como null, e o que acontece aí cabe ao provider decidir, pelo que cada página de provider o indica: helm remove o valor predefinido do chart para essa chave, helm-chart escreve-o nos values do umbrella, compose escreve-o no ficheiro compose, terraform escreve-o como argumento de módulo null, e cloudformation recusa-o.
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 despacho. O compilador despacha com base na forma do conteúdo do campo; não é necessária nenhuma anotação $mode:.
Modo 1: template Go inline (escalar de bloco YAML). O valor do campo é uma string escrita na forma de escalar de bloco 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 é pequeno a médio (menos de ~50 linhas). O corpo do template fica inline com o resto do envelope da Recipe; o conteúdo da Recipe é autocontido.
Modo 2: $import: de ficheiro. O valor do campo é um mapa que contém apenas $import: com um caminho de ficheiro local:
spec: valuesMapping: $import: ./mappings/api-server.tmplO compilador carrega o conteúdo do ficheiro (um template Go), renderiza-o como template contra o contexto de template habitual da Recipe e trata o resultado como a saída do mapeamento. A resolução de caminhos é 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 a compilação é invocada — e o caminho tem de permanecer dentro desse diretório, como explica Os caminhos de conteúdo permanecem dentro do próprio diretório da Recipe. O modo de ficheiro adequa-se a conteúdo de mapeamento médio a grande (~50+ linhas) e a padrões de revisão em que as alterações ao mapeamento aparecem como diffs de ficheiros autónomos.
Modo 3: $import: de biblioteca. O valor do campo é um mapa que contém 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 contra o conjunto MappingLibrary resolvido (o catálogo local mais quaisquer bibliotecas fixadas no lockfile), carrega o conteúdo da entrada e trata-o como a saída do mapeamento; uma entrada cujo corpo seja ele próprio um $import: na raiz do campo é resolvida recursivamente. A referência não contém nenhum host de registo — o nome da biblioteca é resolvido por identidade e a versão provém do lockfile de cada Release, com um limite mínimo de versão opcional :<version> (<Library>:<version>#/mappings/<entry>). O conteúdo da biblioteca partilha o contexto de template habitual da Recipe. O modo de biblioteca adequa-se à reutilização entre Recipes — padrões de mapeamento que se repetem em muitas Recipes (várias Recipes de datastore que partilham lógica auxiliar de datastore; várias Recipes do provider Helm que partilham padrões de pod-template). A entidade MappingLibrary fornece controlo de versões, fixação no lockfile e apresentação na interface do hub.
Regras de despacho. O compilador percorre o nó YAML e despacha pela forma do conteúdo:
- Se o nó for um escalar de string, despacha como modo inline (Modo 1).
- Caso contrário, o nó é um mapa; verifica a existência da chave
$import:. - Se o valor de
$import:for uma referência de biblioteca por nome simples (<Library>#/mappings/<Entry>, opcionalmente com um limite:<version>), despacha como modo de biblioteca (Modo 3). - Caso contrário (um caminho de ficheiro local), despacha como modo de ficheiro (Modo 2).
- Qualquer outra forma (um mapa sem
$import:, um mapa com chaves adicionais além de$import:, etc.) produz um erro em tempo de compilação.
Apenas $import: de source único. $import: aceita um único source. A fusão de vários sources não é suportada em valuesMapping:. Uma Recipe que precise de compor vários fragmentos de mapeamento utiliza uma entrada de MappingLibrary com composição interna define / template do template Go, um ficheiro local com diretivas template do template Go que invocam ficheiros vizinhos, ou composição inline para conteúdo curto. Consulte entities/mappinglibrary para a entidade da biblioteca e vocabulary/cross-document-ref para a distinção mais geral $ref: / $import:.
Proveniência. As mensagens de erro de falhas de renderização de templates citam a proveniência adequada a cada modo: os templates inline citam o ficheiro:linha da Recipe onde começa o escalar de bloco; as importações de ficheiro citam o conteúdo do ficheiro importado; as importações de biblioteca citam a posição de origem da entrada de MappingLibrary, com a identidade da biblioteca sem host (<Library>#/mappings/<entry>) como ponteiro canónico para referências estáveis — um host de registo numa referência é rejeitado, pelo que a localização física nunca entra no ponteiro.
C. Suporte nativo de IaC
Uma equipa de Ops que traga o seu próprio infrastructure-as-code mantém-no no diretório da própria Recipe — um diretório de módulo ou de template como ./src, indicado por source: — ou obtém-no com um source: estruturado (um módulo Terraform a partir do seu repositório git, com kind: git-repository), ou escreve-o como corpos com template em artifacts:. A camada de mapeamento (valuesMapping: — inline, importação de ficheiro ou importação 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 noutra:
- Terraform: um módulo é copiado ficheiro a ficheiro, e um corpo escrito pelo autor é emitido exatamente como está escrito, tanto em HCL nativo (
main.tf) como em 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 source torna-se os argumentos desse bloco. Consulte o provider terraform. - CloudFormation: um template com source, YAML ou JSON, e os fragmentos de recursos que uma Recipe escreve são normalizados em JSON de forma longa e fundidos num único template de stack por boundary, com a saída de
valuesMapping:a preencher os parâmetros que um template com source declara. Consulte o provider cloudformation.
Um valor que só existe depois de a infraestrutura ser aplicada continua a ser um ponteiro que o destino resolve — uma interpolação ${ ... } do Terraform, um Ref ou Fn::GetAtt do CloudFormation — e nunca é avaliado no momento da compilação.
Exemplo A: o chart Helm remoto (mapeamento 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 (mapeamento por ficheiro)
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 (associa a infraestrutura) O Ops mapeia a interface genérica para a realidade física. (É aqui que os detalhes de rede L4 são associados — seja definidos diretamente no código, seja, como acontece com a porta do proxy abaixo, obtidos a partir 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 cloud.
As Recipes que emitem nomes de recursos cloud — nomes de buckets S3, identificadores de bases de dados RDS, nomes de funções IAM, nomes de stacks CloudFormation e qualquer outro campo cujo valor ocupe um espaço de nomes global no fornecedor de cloud — têm de concatenar {{ .metadata.release_name }} e/ou {{ .context.instance_id }} no nome renderizado para evitar colisões quando a mesma Recipe é executada em várias Releases ou instâncias de componentes. O bucket_name: "{{ .metadata.release_name }}-{{ .context.instance_id }}-data" do Exemplo B é o padrão canónico.
A disciplina aplica-se sempre que um único espaço de nomes global restringe o nome. Os nomes de buckets AWS S3 partilham um espaço de nomes global entre todas as contas de uma região; duas Releases do mesmo Aggregate (prod-billing e staging-billing) não podem ambas implementar buckets chamados customer-data — a segunda implementação falha em runtime 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 não verifica. O compilador não inspeciona as saídas de valuesMapping: à procura de campos de nomes de recursos cloud sem estas interpolações. A disciplina é mantida pelos autores de Recipes (que sabem que campos identificam recursos globalmente únicos para o provider de destino) e pelos revisores (que detetam padrões de recursos sem nome na revisão de PR). Um plugin linter poderia assinalar Recipes cujas saídas de valuesMapping: referenciem campos de nomes de recursos cloud sem interpolação de release_name / instance_id; o socket do linter é disponibilizado e executado através de aggrega lint (consulte plugins/plugin-contract.md «Critério de colocação: o socket do linter vs. os papéis de veredicto de governação»), e nenhuma das regras do linter de publicação verifica isto.
Esta 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. Consulte vocabulary/social-contracts.md para a lista completa de convenções e a fundamentação arquitetural da classificação de cada contrato.
Templating do campo source. O próprio campo source de uma Recipe é uma superfície de templating. 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 de string é avaliado como template; os subcampos que não são strings passam inalterados). O que um template de source pode ler depende de o source indicar ou não um artefacto remoto. A coordenada de um source remoto — o version, chart, ref e module_subdir de um bloco estruturado que indica um registo, um repositório de charts ou um repositório git — é avaliada quando aggrega pull resolve o artefacto para o fixar, apenas contra .values, .infra e .locals, com os helpers próprios da Aggrega (optional, capitalizedWords e index) e nenhuma das funções do Sprig. .context não está nessa superfície, pelo que o artefacto fixado para um componente é decidido pelos values e infra que recebe e nunca pelo nome da sua instância. As entradas de locals: avaliadas aí são as que esses campos leem, e as que essas entradas, por sua vez, leem: uma entrada que nenhum campo de source lê não é avaliada enquanto o source é resolvido, pelo que um local de que só a renderização precisa — um que chame uma função do Sprig, ou que leia .context.instance_id — não afeta a fixação e é avaliado quando o nó é renderizado. Um campo que leia .locals de uma forma que não nomeia nenhuma entrada concreta, como {{ index .locals "version" }}, faz com que todas as entradas sejam avaliadas. Um source que indique um caminho no workspace, como o acima, não é resolvido para fixação: o seu template é avaliado quando o nó é renderizado, contra o mesmo contexto autocontido que os locals da Recipe — .context.instance_id, .values, .infra e .locals, todo o bloco resolvido do nó — pelo 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, e não apenas as entradas acima dela. Uma coordenada remota pode igualmente ler qualquer entrada que o bloco declare. .provides não está em nenhum dos contextos, e um template de source que tente aceder aos provides do seu próprio nó interrompe a compilação e indica a referência em causa. Trata-se de uma propriedade fixa da superfície e não de uma lacuna à espera de trabalho futuro — os locals de um nó são resolvidos antes dos seus provides para que provides: possa ler .locals, e um template de source lê esses mesmos locals resolvidos em vez de avançar para os provides. As referências a .context.inject e .context.uses são proibidas pelos mesmos motivos de autocontenção; o URI de source tem de ser resolvido antes de o pipe da topologia ser hidratado e antes de qualquer coisa a jusante carregar o chart, o módulo ou o corpo do artefacto para que o URI aponta. As regras completas de disponibilidade e a fundamentação das referências proibidas encontram-se na linha n.º 5 da matriz de expansão de templates. O uso canónico é uma substituição infra.source_version exposta pelo Component, encaminhada para o campo de versão do source — consulte entities/component «O pilar infra» — para que um catálogo não tenha de republicar uma Recipe a cada incremento de versão compatível do upstream.
Inventário de esquemas do campo source. O campo source: aceita várias variantes de forma no esquema. O suporte em runtime de cada variante varia consoante o provider; a tabela abaixo documenta o que faz cada forma.
| Forma | Exemplo | Estado |
|---|---|---|
| Caminho relativo simples do sistema de ficheiros | source: "./charts/postgres" | available — todos os providers disponibilizados (helm, helm-chart, compose, terraform, cloudformation) aceitam uma string de caminho simples do sistema de ficheiros. |
| Caminho absoluto simples do sistema de ficheiros | source: "/abs/path/to/chart" | accepted but blocked — o esquema aceita-o e todos os comandos que leem a Recipe recusam-no: um caminho absoluto indica um local na máquina onde foi escrito, e não conteúdo dentro do próprio diretório da Recipe, pelo que não viajaria com a Recipe. Mova o chart para o diretório da Recipe e indique-o relativamente a ele; consulte Os 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 todos os comandos que carregam a Recipe recusam-na quando a Recipe é lida, porque uma string vazia não indica nenhum dos modos. A recusa indica a ambiguidade juntamente com as duas saídas possíveis: omitir o campo para o modo sem source, ou dar-lhe um caminho ou URI real para o modo com source. aggrega validate <recipe-file> reporta-a para a Recipe, e aggrega pull, aggrega build e aggrega validate --release reportam-na para uma Release que alcança a Recipe. Consulte errors/fatal-halts.md «Recipe source: is an empty string (O source da Recipe é uma string vazia)». |
Objeto estruturado cujo url: contém um esquema de transporte | source: { url: "oci://…/mariadb", version: "25.0.8" } | available — o resolvedor de source nativo lê a forma {kind, url, version, chart, ref, module_subdir} (o esquema de url: seleciona o kind — oci:// → chart OCI, https://….tgz → arquivo de chart, raiz de repositório https:// emparelhada com chart: → chart de repositório — ou indique-o com kind:), obtém e fixa o artefacto em aggrega pull, e a compilação extrai-o da cache. Incluir um chart localmente (vendoring) é suportado como alternativa, e não é obrigatório. O esquema aceita um objeto estruturado aberto. Consulte providers/helm.md «Conjunto de chaves source:». |
Objeto estruturado cujo url: indica um caminho do sistema de ficheiros | source: { kind: helm-oci-chart, url: "./charts/postgres", version: "1.0.0" } | available — um url: sem esquema de transporte indica um caminho, pelo que nada é obtido e nada é fixado; a compilação lê o conteúdo do disco. Um url: relativo é ancorado no diretório que contém o recipe.yaml que o declara, e um que saia desse diretório — incluindo um absoluto — é recusado: a mesma leitura que as duas linhas de caminho simples acima recebem, e a forma em que foi escrito não a altera. Apenas url: decide de onde o conteúdo é lido; os outros campos selecionam o que seria obtido, e continuam a chegar 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 de três níveis atual (os ficheiros que uma Release indica por caminho, catálogos do workspace, registo OCI remoto) está documentado em architecture/13-catalog-and-registry.md; o resolvedor ao nível da entidade consome URIs OCI através dessa cascata, mas a forma OCI do campo source: de cada Recipe ainda não está ligada nos providers. |
Outros esquemas de URL (https://, git+https://, etc.) | (ilustrativo) | planned — documentado como intenção de design no roteiro de sources conectáveis da arquitetura; sem suporte em nenhum provider hoje. |
Como um caminho source: é ancorado. A ancoragem aplica-se a caminhos do sistema de ficheiros e a nada mais, e aplica-se qualquer que seja das duas formas a que contém o caminho. Um caminho relativo é ancorado no diretório que contém o recipe.yaml que o declara, e um caminho que saia desse diretório — incluindo um caminho absoluto — é recusado, como explica Os caminhos de conteúdo permanecem dentro do próprio diretório da Recipe. Uma referência que contenha um esquema de transporte — oci://, https://, http://, git://, ssh://, git+ssh://, ou qualquer referência terminada em .git — indica algo a obter e não um caminho, pelo que é transportada exatamente como foi escrita e nunca é unida a um diretório.
Na forma estruturada, o caminho é o campo url:, e é lido da mesma forma: um url: relativo é ancorado no diretório que contém o recipe.yaml, um que saia desse diretório é recusado, e um que contenha um esquema de transporte é obtido. Todos os outros campos de um source: estruturado são transportados sem alterações, incluindo os definidos pelo provider.
Um source: escrito como template é ancorado contra o valor que o template produz, não contra o próprio texto do template. Um template não indica nada até ter sido avaliado, pelo que a leitura acima é aplicada ao seu resultado: um resultado que seja um caminho relativo é ancorado no diretório que contém o recipe.yaml, um que saia desse diretório — incluindo um caminho absoluto — interrompe a compilação, e um que contenha um esquema de transporte é transportado e obtido. Um template é, portanto, livre de produzir qualquer uma das formas do inventário acima, e cada uma é tratada exatamente como seria o mesmo valor escrito literalmente; a diferença está apenas em quando o caminho pode ser avaliado, o que, para um template, é quando a compilação o avalia e não quando a Recipe é lida.
Um template que não produz nada — um resultado vazio — deixa a Recipe sem source, o que corresponde ao modo sem source. Isso é diferente de escrever source: "" diretamente, o que não indica nenhum dos modos e é recusado; consulte a linha do inventário acima.
O inventário é a referência canónica do que os autores podem colocar em source:; as suas etiquetas são as que 10-status.md define.
Os caminhos de conteúdo permanecem dentro do próprio diretório da Recipe
O conteúdo de uma Recipe encontra-se no próprio diretório da Recipe, porque todos os ficheiros que uma publicação dela transporta são retirados daí. Todos os caminhos que uma Recipe escreve para o conteúdo que transporta — o seu source:, seja um caminho simples ou o url: da forma estruturada, e cada ficheiro que as suas entradas valuesMapping:, workload: e artifacts: importam com $import: — são lidos relativamente ao diretório que contém o recipe.yaml e têm de permanecer dentro dele. Esses caminhos são também o que uma publicação transporta: os ficheiros que indicam viajam com a Recipe, e nada mais no seu diretório o faz (consulte aggrega push). Um caminho que saia do diretório aponta para um ficheiro que não viajaria com a Recipe, pelo que o ficheiro não está lá para quem o consome, e uma fixação registada sobre ele garantiria bytes que essas pessoas não conseguem obter.
Há duas formas que 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 indica um local na máquina onde foi escrito.
Um caminho que sobe e volta a entrar é um caminho normal dentro do diretório: ./charts/../values.tmpl indica o values.tmpl ao lado da Recipe. O que se avalia é onde o caminho termina, medido a partir do diretório da Recipe sem sair dele — pelo que uma subida para fora que volta a nomear o diretório no regresso, como ../1.0.0/values.tmpl escrito num diretório chamado 1.0.0, também é recusada. O nome do próprio diretório não viaja: uma Recipe publicada é lida a partir de um diretório cujo nome é dado pela cache do consumidor, onde esse nome não encontra nada.
Onde é recusado. Todos os comandos que leem a Recipe recusam esse caminho ao lê-lo, antes de qualquer obtenção, renderização ou publicação: aggrega validate, sobre o catálogo ou sobre o próprio ficheiro da Recipe, aggrega pull, aggrega build, aggrega pin e aggrega push. Um source: escrito como template não indica nada até a compilação o avaliar, pelo que um template que produza um caminho fora do diretório é recusado pela compilação, no momento em que o valor existe. A interrupção é A path names content outside the entity’s own directory (Um caminho indica conteúdo fora do próprio diretório da entidade), e indica o caminho escrito.
O que fazer em alternativa. Coloque o ficheiro no diretório da Recipe, ou num diretório abaixo dele, e indique-o relativamente à Recipe: ./charts/app, ./extras/netpol.yaml. Um chart que várias Recipes usam é copiado para o diretório de cada Recipe, uma vez que cada Recipe é publicada separadamente; um corpo de mapeamento, workload ou artefacto que várias Recipes partilhem pertence a uma MappingLibrary, WorkloadLibrary ou ArtifactLibrary, que cada Recipe referencia por identidade.
Porque é que uma Release é diferente. Uma Release aponta para outras entidades — o seu Aggregate, o seu Manifest, a Release que estende — e nunca é publicada, pelo que nada do que lê viaja para lado nenhum. Essas referências, e o ficheiro que o seu parameters: importa, são lidos tal como estão escritos, o que permite que um Aggregate seja partilhado por variantes de Release em subdiretórios. Consulte entities/release.md.
O mesmo limite aplica-se a uma FeatureRecipe, e a todos os esquemas que um Component ou uma Feature importem.
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, a par de source: (renderização com source) e artifacts: (manifestos auxiliares). Pelo menos um dos três tem de estar presente em qualquer provider; um serviço que a compilação não aprovisiona declara um workload: com form: reference.
O campo aceita três modos de autoria — escalar de bloco inline, $import: de ficheiro ou $import: de biblioteca. O compilador despacha com base na forma do conteúdo do campo; não é necessária nenhuma anotação $mode:.
Modo 1: inline (escalar de string de template Go). O valor é um escalar de bloco 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 existe um invólucro spec: — e containers: e os ports: de cada contentor são mapas indexados por nome em vez de sequências, com a ordem do autor preservada. O provider traduz essa forma para a sua própria forma nativa, pelo que uma entrada do mapa de contentores surge na saída renderizada do helm como um elemento containers[] com o nome da sua chave; a forma escrita é o mapa, não a lista renderizada.
Modo 2: $import: de ficheiro. O valor é um mapa com uma única chave $import: que aponta para um ficheiro de template Go local:
spec: workload: $import: ./workload/web-server.yaml.tmplA resolução de caminhos é igual à de valuesMapping:: 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 a compilação é invocada, e tem de permanecer dentro desse diretório. O corpo importado é um template Go avaliado no contexto de renderização da Recipe, exatamente como um corpo inline.
Modo 3: $import: de biblioteca. O valor é um mapa com uma única chave $import: que contém uma referência de identidade por nome simples a uma entrada de 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 — essa endereça uma entrada de MappingLibrary e não indica um corpo de Workload. A referência não contém nenhum host de registo, a versão resolvida provém do lockfile de cada Release, um limite mínimo de versão opcional :<version> pode ser indicado como <Library>:<version>#/workloads/<Entry>, e uma entrada cujo corpo seja ele próprio um $import: na raiz do campo é resolvida recursivamente. O corpo importado é um template Go avaliado no contexto de renderização da Recipe consumidora, pelo que .values, .infra e .features fluem para ele exatamente como fluem para um corpo inline. Consulte entities/workloadlibrary para a entidade de biblioteca e a gramática completa das referências.
O provider de destino tem de suportar síntese (o catálogo da biblioteca standard declara workloadSchema nesses providers por convenção); apontar para um provider que não consegue sintetizar é rejeitado 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 de passagem com forma K8s e o comportamento de tradução por provider, consulte entities/workload.md. Para o modelo mais amplo dos três tipos de entrada e o montador que funde a síntese com a saída renderizada a partir do source e com os artefactos, consulte architecture/16-recipe-input-composition.md.
Entregar os valores próprios de um componente à imagem do próprio programador. Pela convenção do catálogo da biblioteca padrão, espera-se que uma Recipe que executa uma imagem construída pelo programador entregue tudo o que os blocos inject: do programador resolveram, a partir de .context.inject, e pode também entregar os valores próprios do componente com nomes da sua escolha. Quando o Component declara spec.inject, é o próprio bloco do programador que escolhe os nomes, e .context.self_inject indica à 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 consiste em tratar os nomes que uma Recipe atribui a esses valores como predefinições, e não como um contrato que o código do programador tenha de ler, entregando um valor com o seu nome predefinido apenas quando nenhuma entrada o mapeia; um catálogo empresarial pode optar 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 → autoria de corpo de artefacto cujas entradas emitem ficheiros de manifesto adicionais ao lado da saída primária da Recipe, com source ou sintetizada. É um dos três tipos de entrada (com source / sintetizado / artefactos) — uma Recipe pode declarar artifacts: sozinho, ou a par de workload: e/ou source:.
O valor de cada entrada utiliza um de três modos despachados pela forma do conteúdo, paralelos aos de workload: — conteúdo inline, um $import: de ficheiro ou um $import: de biblioteca. O compilador despacha com base na forma do conteúdo do valor; não é necessária nenhuma anotação $mode:. A chave do mapa indica o que a entrada emite nos três: nos dois modos de ficheiro único é o nome do ficheiro de saída, e no modo de pacote é o diretório sob o qual os ficheiros do pacote ficam aninhados. Como a chave indica a saída, está limitada ao que um único nome de ficheiro pode ser: uma letra ou dígito inicial, seguido de letras, dígitos, pontos, hífenes e sublinhados. Os pontos mantêm a extensão que uma chave normalmente contém — main.tf, template.yaml, serviceaccount.yaml — enquanto o alfabeto não admite /, que faria com que uma chave indicasse um caminho e não um ficheiro, nem um . inicial, pelo que uma chave nunca pode ser o segmento do diretório pai. Uma chave fora desse alfabeto falha a validação do envelope no carregamento do workspace, 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 de template Go). O valor é um escalar de bloco, e a chave do mapa é o nome do ficheiro de saída, usado tal como está escrito — a primeira entrada acima emite extra-configmap.yaml.
Modo 2: $import: de ficheiro. O valor é um mapa com uma única chave $import: que aponta para um ficheiro de template Go local, e a chave do mapa é o nome do ficheiro de saída, exatamente como no modo 1. O ficheiro importado fornece o conteúdo; não fornece o nome. A segunda entrada acima tem a chave network-policy.yaml e emite network-policy.yaml, embora o ficheiro que importa se chame network-policy.tmpl. Assim, um autor que pretenda um determinado nome de ficheiro de saída escreve-o como chave, e duas entradas que importem ficheiros diferentes que por acaso partilham um nome — ./extras/shared.yaml e ./overrides/shared.yaml — são duas saídas distintas. A resolução de caminhos é igual à de valuesMapping: e workload:: 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 a compilação é invocada, e tem de permanecer dentro desse diretório.
Modo 3: $import: de biblioteca. O valor é um mapa com uma única chave $import: que contém uma referência de identidade por nome simples a um pacote de ArtifactLibrary, <Library>#/artifacts/<name>. Um pacote é um conjunto de ficheiros importados como uma unidade, pelo que uma entrada expande-se numa saída por cada ficheiro do pacote, cada uma aninhada sob a chave do mapa como <key>/<filename> — a chave indica o local de consumo e é o diretório onde esses ficheiros ficam, e não o nome de nenhum deles. A terceira entrada acima tem a chave operator-support; se PlatformArtifacts#/artifacts/OperatorSupport declarar crd.yaml e rbac.yaml, essa única entrada emite operator-support/crd.yaml e operator-support/rbac.yaml. A referência não contém nenhum host de registo — uma forma oci://… com host é rejeitada — a versão resolvida provém do lockfile de cada Release, e um limite mínimo de versão opcional :<version> pode ser indicado como <Library>:<version>#/artifacts/<name>. Consulte entities/artifactlibrary para a entidade de biblioteca e a gramática completa das referências.
Um $import: de ficheiro é fixado ao lado da Recipe. aggrega pin regista o digest dos bytes de cada ficheiro importado no entity.lock do diretório da Recipe, indexado pela chave do mapa da entrada, e aggrega build volta a calcular o digest do ficheiro e é interrompido com [CATALOG_ERROR E0026] quando já não corresponde — ou primeiro com E0130 quando o lockfile da Release, escrito antes da edição, regista a Recipe pelo que ela transporta — pelo que um ficheiro editado depois de ter sido fixado nunca é renderizado sem verificação. Se a alteração foi intencional, execute aggrega pin sobre a Recipe para registar o novo digest; caso contrário, restaure o ficheiro. Uma entrada inline faz parte do ficheiro da Recipe, e uma entrada de biblioteca é fixada pela versão da biblioteca que o lockfile regista, pelo que nenhuma delas tem uma fixação própria. aggrega pull descreve o ficheiro.
O template de cada entrada de artefacto é avaliado com o mesmo contexto de template que valuesMapping:, qualquer que seja o modo que forneceu o seu corpo. Duas saídas com o mesmo nome de ficheiro interrompem a compilação quando o nó é renderizado. Duas entradas de um mapa artifacts: não podem indicar uma mesma saída: uma chave de mapa é única num documento e corresponde a um único nome de ficheiro, pelo que a saída de uma entrada de ficheiro único é a sua chave e os ficheiros de uma entrada de pacote ficam sob um diretório com o nome da sua chave — o primeiro segmento de todos os caminhos que uma entrada emite é a chave que o produziu, pelo que chaves distintas continuam a ser nomes de saída distintos, independentemente do nome dos ficheiros importados. O que a interrupção cobre é um nome de ficheiro com contribuições de dois tipos de entrada diferentes — um template de chart e uma entrada de artefacto que produzem ambos servicemonitor.yaml — reportado sobre essa Recipe com um diagnóstico que indica todas as origens que contribuíram.
Casos de utilização. artifacts: é o lugar para recursos auxiliares que o chart ou módulo principal não produz: uma NetworkPolicy que acompanha um workload, um HPA emparelhado com um Deployment, um ConfigMap sidecar baseado em instance_id. Os recursos auxiliares transversais que se aplicam a muitos componentes (um sidecar de backup ligado a todos os datastores, por exemplo) pertencem à Resource Generation da FeatureRecipe e não a artifacts: por Recipe — consulte entities/featurerecipe.md para a superfície de extensão da FeatureRecipe.
O bloco boundary: — ficheiros para a saída partilhada da fronteira
A maioria das Recipes nunca precisa disto. Tudo o resto que uma Recipe escreve pertence ao seu próprio componente: o provider coloca-o sob a posição do próprio componente na saída da fronteira. Alguns ficheiros pertencem, em vez disso, à fronteira como um todo — um ficheiro que o destino lê uma vez para tudo o que a fronteira implementa. A configuração de providers do Terraform é o caso habitual: a documentação do Terraform mantém os blocos provider fora de um módulo que outra configuração chama, e um módulo que contenha um bloco próprio não pode ser chamado com depends_on, count ou for_each. spec.boundary.artifacts é onde uma Recipe escreve esse ficheiro.
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: num segundo âmbito. artifacts é o seu único membro, e tem exatamente a forma do próprio artifacts: da Recipe: os mesmos três modos — conteúdo inline, um $import: de ficheiro, um $import: de biblioteca cujos ficheiros ficam aninhados sob a chave da entrada como <key>/<filename> — a mesma regra de chave para nome de ficheiro e o mesmo alfabeto para uma chave, e o mesmo contexto de template, pelo que uma entrada lê .values, .infra, .locals e o resto exatamente como uma entrada de artifacts: o faz. Precisa de pelo menos uma entrada, e qualquer outro membro sob boundary: é recusado quando a Recipe é lida. Uma FeatureRecipe não tem um bloco deste tipo.
Onde um ficheiro é escrito. Uma vez, no diretório que contém a saída montada da fronteira, ao lado dos ficheiros que a própria montagem do provider escreve aí — no caso do terraform, ao lado da configuração raiz aggrega.modules.tf e não dentro do módulo do componente. O provider não recebe nenhum destes ficheiros: o compilador avalia-os e escreve-os ele próprio, e não marca nenhum deles com o componente de onde veio, porque pertence a todos os componentes que o declararam. Uma entrada cujo template renderize para nada não escreve nenhum ficheiro.
Como se juntam vários contribuidores. Cada entrada é avaliada para cada componente que a Recipe renderiza na fronteira, e os ficheiros que todos os contribuidores da fronteira declararam são fundidos por nome. Um nome avaliado para os mesmos bytes — por dois componentes associados a uma Recipe, ou por duas Recipes que configuram um provider de forma idêntica — é um ficheiro. Um nome avaliado para bytes diferentes para a compilação, indicando o ficheiro e todos os contribuidores, porque nenhum ficheiro único corresponde ao que todos escreveram; o mesmo acontece com um nome que a própria montagem do provider escreve, como aggrega.modules.tf. Ambos são a colisão na saída montada. Duas Recipes que configuram um provider com dois nomes de ficheiro diferentes não são fundidas — cada ficheiro é escrito — e é o destino que então reporta a configuração duplicada, pelo que as Recipes destinadas a partilhar uma configuração de provider partilham o nome do ficheiro, por convenção um com o nome do provider que configura.
Que providers o aceitam. Se um ficheiro colocado ao lado da saída montada de uma fronteira significa alguma coisa é uma propriedade do destino do provider, pelo que faz parte da própria declaração do provider. Uma Recipe que declare o bloco e cujo provider não o aceite é recusada antes de qualquer renderização, seja qual for o resultado da renderização das suas entradas; consulte The provider does not support boundary artifacts (O provider não suporta artefactos de fronteira). A grelha de capacidades lista a declaração de cada provider.
| Provider | boundary.artifacts: |
|---|---|
terraform | Aceite. Cada ficheiro é escrito ao lado da configuração raiz da fronteira, que o Terraform lê juntamente com todos os outros ficheiros de configuração desse diretório. |
helm, compose, helm-chart, cloudformation | Recusado antes de qualquer renderização. |
Um $import: de ficheiro aqui é fixado tal como um que uma entrada de artifacts: importa. O lock da entidade regista o seu digest na mesma lista artifactDigests, sob boundary/<key> em vez de apenas sob a chave, pelo que uma entrada de cada bloco escrita sob a mesma chave é fixada separadamente. O passo de fixação regista-o, um pull que não fixe é interrompido quando a sua fixação está em falta ou já não corresponde, e uma compilação recusa um ficheiro editado desde a fixação exatamente como recusa um ficheiro de artifacts:.
O campo outputLabels: — etiquetas declaradas pelo autor na saída renderizada
Recipe.spec.outputLabels: é um mapa de chave de etiqueta → valor que o provider marca em todos os objetos produzidos pela saída renderizada da Recipe. É o lugar adequado para um traço de realização — uma propriedade da forma como uma determinada Recipe realiza um componente, por oposição ao que o componente é. Considere-se o armazenamento com que uma realização persiste, escrito abaixo como a chave ilustrativa example.io/storage-backing: uma Recipe Helm que monta um PersistentVolumeClaim e uma Recipe Compose que monta um volume com nome realizam o mesmo componente com mecanismos diferentes, pelo que têm outputLabels diferentes e as ferramentas a jusante (imputação de custos, políticas, inventário) conseguem distingui-las nos recursos emitidos. A chave é ilustrativa — example.io/ é um espaço de nomes de exemplo, e um catálogo escolhe as chaves que as 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: platformAs etiquetas de saída seguem o mesmo percurso que as etiquetas fixas de proveniência da compilação: são fundidas no conjunto de etiquetas que todas as superfícies emissoras marcam, pelo que chegam a todo o lado onde a proveniência chega. O que difere é a titularidade — as chaves de proveniência pertencem ao compilador, os outputLabels pertencem ao autor da Recipe.
A etiqueta de identidade do próprio componente não se escreve aqui — uma convenção de catálogo, não uma regra que o compilador imponha. As chaves que indicam o que o componente é, e não como uma Recipe o realiza — a sua categoria cognitiva, o seu tipo operacional, as suas etiquetas de capacidade por papel, quem opera o recurso subjacente, a classe de licenciamento do que envolve — são declaradas no metadata.labels do Component; consulte entities/component «A taxonomia semântica de etiquetas» para os eixos. Uma Recipe coloca uma dessas chaves na sua saída renderizada indicando a chave em outputComponentLabels: abaixo, e não escrevendo aqui a chave e um valor. O motivo é que uma entrada literal é uma segunda cópia de um valor que o componente já tem, e uma segunda cópia pode divergir da primeira: um autor de Recipe pode escrever uma postura num nó cujo Component declara outra, dizendo a um leitor a jusante algo que o grafo não diz. Uma entrada promovida copia por referência e, por isso, não tem segunda cópia que possa divergir. O núcleo aceita o que for escrito, para além da regra dos espaços de nomes reservados abaixo; a convenção é mantida pelos autores de catálogos.
Espaços de nomes reservados. Os espaços de nomes aggrega.ai/ e app.kubernetes.io/ estão reservados para a proveniência nativa da plataforma. Uma Recipe que declare uma chave de outputLabels sob qualquer desses prefixos é rejeitada no carregamento com um erro de catálogo claro que indica a chave em causa. Todas as outras chaves são aceites. O núcleo não controla de outra forma a chave nem o valor — uma chave ou um valor que não seja válido para a superfície de etiquetas do motor de destino é responsabilidade do autor, e o runtime a jusante rejeita-o; o compilador não interfere para além da regra dos espaços de nomes reservados.
Apresentação por provider. Cada provider traduz as etiquetas para a sua própria superfície de saída:
- helm, síntese de workload — tanto no
metadata.labelsdo objeto como nometadata.labelsdo pod-template, de acordo com o local onde a síntese coloca a proveniência. - helm, renderização de source e artefactos — no
metadata.labelsdo objeto. - compose — no mapa
labels:de cada serviço. - terraform — como tags por recurso em corpos de artefacto
.tf.jsonendereçáveis estruturalmente, na medida do possível: um bloco de recurso que já declare um mapatags(AWS/azurerm) oulabels(Google) recebe aí as etiquetas de saída, uma chave declarada pelo autor nunca é sobrescrita, e um recurso sem esse atributo fica intacto (nunca se inventa um atributo). Os corpos HCL nativos (main.tf,*.tf) e os módulos incluídos (vendored) são emitidos literalmente e não recebem tags injetadas. A proveniência do Terraform continua a viajar no seu ficheiro de comentários associado, separado do percurso das tags.
As etiquetas de saída são apenas etiquetas; 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 pelas Ops), não pelo Aggregate — descreve a realização, nunca a identidade do grafo abstrato do programador.
O campo outputComponentLabels: — promover as etiquetas do próprio componente
Recipe.spec.outputComponentLabels: é uma lista de chaves de etiquetas, não de pares chave-valor. Para cada chave que indica, o provider marca essa chave na saída renderizada com o valor que a chave tem na instância de componente a renderizar. Enquanto outputLabels indica 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 cujo metadata.labels declara component.aggrega.ai/hosting: managed, todos os objetos que esta Recipe renderiza para esse componente têm component.aggrega.ai/hosting: managed. Associe a mesma Recipe a um componente que declare self-hosted e os objetos desse componente passam a ter self-hosted — uma Recipe, uma chave indicada, um valor por componente.
A promoção é por referência, e é esse o objetivo. O valor é lido do componente sempre que a saída é renderizada, pelo que não pode divergir da identidade de onde veio: não existe uma segunda cópia a manter sincronizada quando a etiqueta do componente muda. Uma entrada literal de outputLabels que repita a etiqueta de um componente é essa segunda cópia, e as duas divergem no momento em que qualquer uma delas muda. Por isso, recorra a outputLabels quando o valor é uma propriedade da forma como esta Recipe realiza o componente, e a outputComponentLabels quando o valor já existe no componente e a saída renderizada também o deve ter.
Uma chave promovida chega exatamente à mesma superfície que uma literal — a apresentação por provider descrita acima aplica-se sem alterações, e nenhum provider distingue uma chave que foi promovida de uma que foi escrita no local.
Espaços de nomes reservados. Os espaços de nomes aggrega.ai/ e app.kubernetes.io/ estão reservados para a proveniência nativa da plataforma, e uma chave promovida sob qualquer desses prefixos é rejeitada no carregamento com um erro de catálogo que indica a chave e o campo onde aparece. O teste é o prefixo simples: uma chave como component.aggrega.ai/hosting está num espaço de nomes 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 em outputLabels e em outputComponentLabels é rejeitado no carregamento, pelo que cada chave marcada tem uma única origem — ou o valor literal escrito na Recipe, ou a própria etiqueta do componente, nunca ambos.
Uma chave promovida que o componente não declara não marca nada. A compilação continua e emite um aviso que indica o nó, a Recipe e a chave em falta. Isto é deliberado: uma Recipe associada a componentes cujos conjuntos de etiquetas diferem continua a ser renderizada, e a discrepância é sinalizada em vez de interromper a compilação.
Componentes de postura única — uma convenção, não uma regra. A promoção transporta qualquer valor que o componente declare, e o compilador não interpreta esse valor. Um componente cuja etiqueta de identidade contenha um marcador de posição que represente «varia» promove, portanto, esse marcador para todos os objetos renderizados para ele. Quando um componente tem genuinamente mais do que uma postura, a convenção do catálogo da biblioteca standard é que cada Recipe indique a postura da sua própria realização através de uma chave de outputLabels que a Recipe detém, e não através da chave de identidade do componente, que a mesma convenção encaminha através de outputComponentLabels: — ou que não marque 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 detida pela Recipe diz o que esta realização faz. Trata-se de uma convenção de catálogo mantida pelos seus autores, não de uma restrição que o compilador imponha.
O bloco locals:
Recipe.spec.locals: é o estado privado de Ops — um mapa de strings de template Go com nome cuja saída renderizada expõe um mapa .locals.* aos templates posteriores da Recipe. É o espaço de trabalho para calcular realidades físicas (contentores de destino, caminhos JSON, nomes de host derivados) uma vez e reutilizá-las em provides:, source:, valuesMapping:, workload:, artifacts:, assertions: e payloads de pipeline[].with sem as recalcular. A saída renderizada de cada entrada é guardada 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 aos chamadores — os componentes a jusante que consomem esta Recipe através de 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 de cada chave podem ser strings simples ou templates Go; o compilador resolve todo o bloco no preâmbulo de locals, antes do provides: desse nó, pelo que todos os templates posteriores observam valores resolvidos estáveis.
Cada entrada é avaliada contra um contexto local do nó autocontido: .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 tente aceder-lhe interrompe a compilação. Também não pode ler .context.rendered_name, o nome que um provider como o helm dá aos recursos que renderiza para o nó, pelo que um local que indique um desses recursos contém apenas a parte após esse nome, como faz secret_target_db_password acima, e o template que escreve o nome completo junta os dois.
A ordem de criação é determinante
As entradas são resolvidas pela ordem em que estão escritas, e uma entrada pode ler uma irmã definida acima dela, recebendo o valor resolvido dessa irmã:
spec: locals: db_identifier: "{{ .context.instance_id }}-postgres" # defined first secret_target: "{{ .locals.db_identifier }}-auth" # reads the entry aboveO encadeamento funciona apenas para baixo. Quando uma entrada lê outra, a ordem das entradas decide se a compilação é bem-sucedida: mova db_identifier para baixo de secret_target e a compilação é interrompida. O compilador nunca ordena nem reordena o bloco para que uma referência seja resolvida, pelo que a ordem escrita é o contrato — reordenar um bloco locals: é uma alteração de comportamento, não uma alteração cosmética.
Duas interrupções distinguem os dois erros que um autor pode cometer, porque têm correções diferentes:
- Uma referência a uma entrada que o bloco define mais abaixo interrompe a compilação indicando o erro de ordem; a correção é mover a definição para cima do seu leitor.
- Uma referência a uma chave que o bloco não declara de todo interrompe a compilação indicando a chave; a correção é corrigir a ortografia.
A verificação acompanha um alias do bloco. Uma chave alcançada através do ponto que um corpo with .locals volta a associar, ou através de uma variável associada a .locals, é verificada exatamente nas mesmas condições que a forma direta: {{ with .locals }}{{ .nope }}{{ end }} e {{ $l := .locals }}{{ $l.nope }} interrompem ambos a compilação indicando .locals.nope, tal 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 forma escapa à verificação: uma chave alcançada através de 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 devolve é 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 a compilação e renderiza o texto literal <no value> em vez de nada. Uma chave ausente alcançada através de index interrompe a compilação, indicando 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 relatório 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)». index continua, portanto, a ser a forma de alcançar uma chave cujo nome é ele próprio calculado, como {{ index .locals (printf "secret_target_%s" .values.slot) }}, e um nome calculado que o bloco não declara continua a ser reportado 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 indique uma chave que o bloco de locals não declara interrompe a compilação. Isto significa que um valor de que tanto uma entrada provides: como um artefacto precisam é escrito uma vez, em locals:, e lido de ambos os locais.
Para o equivalente da API pública, consulte O bloco provides: abaixo. A superfície da FeatureRecipe segue as mesmas regras — consulte entities/featurerecipe.md «O bloco locals:».
O bloco provides:
Recipe.spec.provides: é a API pública do programador — um mapa de nome → string de template Go que declara os valores 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 contra estes valores na hidratação do 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 contra a superfície autocontida de avaliação de provides — .context.instance_id, .context.rendered_name quando o provider do nó reporta um, .values, .infra, os .locals resolvidos do nó e texto estático. O espaço de nomes em que o nó é colocado não está nela, pelo que um host publicado não contém nenhum: um consumidor noutro espaço de nomes qualifica-o do seu próprio lado. .locals está nela porque os locals do nó são resolvidos no preâmbulo da mesma fase, antes dos seus provides; um template provides que indique uma chave que o bloco de locals não declara interrompe a compilação. Separar a avaliação de provides da hidratação do inject é essencial: 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 de acordo com o invariante arquitetural. Os chamadores leem depois estes valores através de .context.uses.<alias>.provides.<provided-name> nos seus próprios templates — os nomes fornecidos ficam aninhados sob provides na aresta, a par dos outros campos da aresta. Um chamador que declare uma allowlist inject: na aresta alcança os mesmos valores através do seu pipe .context.inject.
As chaves de provides: fazem parte da superfície de contrato da Recipe. Mudar o nome de uma chave ou removê-la é uma alteração incompatível para todos os chamadores que dependem do nome antigo; a versão da 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 o encaminhamento entre espaços de nomes e entre regiões, consulte architecture/06-data-taxonomy-and-composition.md §3 e templates/expansion-matrix.md.
Ler os valores publicados de um anexo
Uma Recipe lê as Features anexadas ao seu componente em .features.<instance-name> e as Features de credenciais em .features.<slot>. Ambas têm a mesma forma de anexo — .type, .values, .infra, .provides — pelo que um anexo é lido da mesma forma, seja qual for o mapa que o contém; o que difere entre eles é o que o anexo produz.
.provides é a saída publicada do anexo, resolvida a partir da FeatureRecipe associada a ele. É o equivalente do bloco provides: acima, visto do lado do consumidor: enquanto uma Recipe publica para os seus chamadores, um anexo publica para o seu componente anfitrião.
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 o recalcular 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, encontra-se em templates/template-context-contract.md.
Um anexo escrito numa das ligações do componente — uma credencial que o componente apresenta a um destino — é lido com a mesma forma sob essa ligação, em .context.uses.<alias>.features.<slot>, e nunca está entre os .features. Uma Recipe que alcança vários destinos lê a credencial própria de cada destino sob o alias desse destino, e um ciclo sobre .features que seleciona anexos por tipo encontra apenas os 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 Os anexos de uma ligação para a forma e para a ordem pela qual um template percorre as ligações.
O campo pipeline:
Recipe.spec.pipeline: é um array sequencial de passos de pipeline Wasm que são executados após a renderização sobre o conjunto de documentos renderizados, devolvendo cada um patches RFC 6902 e efeitos secundários. Cada entrada declara um id (identificador do passo: letras, dígitos e sublinhados), um plugin (a entidade Plugin que o passo executa, delimitada pelo seu tipo de plugin — pipeline-step/<name>, opcionalmente com uma versão; uma referência .wasm simples ou a um artefacto é recusada), uma function (o export do plugin a invocar), um corpo de template Go with: opcional que fornece o payload do plugin, e um template Go when: opcional que determina se o passo é executado — um resultado falso ignora o passo como pass-through, deixando o conjunto de documentos inalterado. A condição when:, a sua independência de optional: e a sua regra de veracidade são tratadas em pormenor em entities/featurerecipe.md «Passos 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 os passos pipeline: de uma Recipe base pela ordem declarada, da mesma forma que executa o pipeline: de uma FeatureRecipe: despacha o plugin Wasm indicado em cada passo contra a saída renderizada, aplica as operações JSON Patch devolvidas aos documentos endereçados e emite os efeitos secundários do passo. O campo pipeline: da FeatureRecipe partilha a mesma forma de esquema e a mesma execução — consulte entities/featurerecipe.md «Contrato de autoria» e Estado 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 pela ordem declarada, operações JSON Patch aplicadas aos documentos renderizados, efeitos secundários emitidos a par deles e erros apresentados com a proveniência a apontar para o passo em causa. Um passo cuja condição when: renderize um valor falso é ignorado como pass-through, deixando o conjunto de documentos inalterado para o passo seguinte.
O bloco assertions:
Recipe.spec.assertions: é um mapa opcional de regras com nome que exprimem invariantes de implementação da Recipe — regras entre campos que se verificam dado o chart ou módulo específico de que a Recipe obtém o source. 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 exprimem invariantes ao nível do contrato, independentemente da Recipe 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; não se aplica se for associada uma Recipe MariaDB diferente. As regras ao nível do Component provenientes do contrato continuam a aplicar-se em paralelo, avaliadas numa fase anterior do pipeline.
As asserções da Recipe são avaliadas após a associação da Recipe e antes da renderização, quando os locals e provides de todos os nós estão resolvidos. O contexto de template inclui .provides, .locals e .recipe.source da Recipe, além dos campos da instância da entidade (.values, .infra, .uses, .features). .uses e .features são aí as formas mais restritas da superfície de asserções, e não as de um template de Recipe: a entrada de uma ligação contém o seu destino e alias, as labels do destino, os values próprios da ligação e os anexos escritos nela sob features, mas nada do que o destino publica; e a entrada de um anexo, seja do próprio componente ou de uma ligação, contém o seu type, resolved_version e values, mas nem o seu infra nem os seus provides — a FeatureRecipe de um anexo ainda não resolveu os seus provides quando a asserção é executada. Uma referência a .features.<name>.provides interrompe, portanto, a compilação, e uma leitura sensível à presença devolve o seu valor alternativo. Para a gramática completa de autoria, a divisão de responsabilidades entre regras ao nível do contrato e ao nível da implementação, e exemplos completos, consulte templates/assertions-block.md.
O campo omits: — deixar documentos renderizados de fora de uma origem
A maioria das Recipes nunca precisa disto. Destina-se a um source que se usa tal como está — na maioria dos casos, um chart obtido de um registo — e que renderiza um documento que a Release não pode disponibilizar: um Secret que o chart gera de novo em cada renderização, por exemplo, o que faz com que duas compilações difiram e, uma vez aplicado, sobrescreve o Secret fornecido pelo operador. Um chart obtido não se edita, e nenhuma regra de exclusão chega a ele, pelo que omits: é a forma de uma Recipe deixar esse documento fora da compilação. Um ficheiro compose obtido é o mesmo caso: pode incluir um serviço, um volume ou uma config que a Release não pode ter, e uma sobreposição de valuesMapping: pode alterar um deles, mas nunca removê-lo. O mesmo se aplica a um template CloudFormation obtido, que pode declarar um recurso que a Release não pode criar: um valuesMapping: pode preencher os parâmetros que ele declara, mas nunca remover um dos 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: são escritos na Recipe, pelo que um documento que não se quer aí é um que se deixa por escrever. A chave exige source:; um documento que viole essa regra é recusado quando é lido, indicando a regra.
Uma entrada. Cada entrada indica o que deixar de fora através de três campos, e um quarto decide se se aplica. O que os três primeiros indicam pertence ao vocabulário próprio do provider para o que o seu source renderiza, descrito por provider na tabela abaixo:
kind— o tipo do que o source renderiza: para um chart, o kind de um documento renderizado —Secret,ConfigMap,Deployment; para um ficheiro compose,service,volumeouconfig; para um template CloudFormation, oTypede um recurso —AWS::S3::Bucket. Não tem relação com okind:que umsource:estruturado contém, que indica como o source é obtido.name— o seu nome: ometadata.namede um documento; a chave de uma unidade compose emservices:,volumes:ouconfigs:; o ID lógico de um recurso CloudFormation, a sua chave emResources.namespace(opcional) — o namespace em que o documento se encontra, para um provider cuja saída tem namespaces. Sem ele, a entrada indica o kind e o nome em qualquer namespace; umnamespaceque renderize para nada é tratado como ausente.when(opcional) — se a entrada se aplica a esta compilação. É avaliado primeiro e lido pela mesma regra que owhen:de um passo de pipeline: um resultado falso descarta a entrada, pelo que os seus outros campos não são avaliados e a entrada não é entregue ao provider nem verificada, enquanto umwhen:ausente ou vazio a mantém.
kind e name são obrigatórios, e uma entrada que contenha qualquer outro campo é recusada quando a Recipe é lida.
Todos os valores são templates, avaliados contra o mesmo contexto que valuesMapping:. Esse contexto contém .context.rendered_name, o nome que o provider dá aos recursos do nó e aquele com base no qual um chart normalmente os nomeia, pelo que uma entrada pode indicar um documento exatamente como o chart o fará. Um template que não consiga ser renderizado interrompe a compilação tal como um template valuesMapping: com falha.
Todas as entradas que se aplicam têm de deixar algo de fora. O provider reporta quantas unidades cada entrada deixou de fora, e uma entrada que não deixou nenhuma de fora para a compilação, indicando a entrada; consulte An omits entry left out nothing the source rendered (Uma entrada de omits não deixou de fora nada do que o source renderizou). Uma atualização do source que mude o nome do documento ou o remova é a causa habitual, e a interrupção é o que impede que um documento renomeado chegue à saída sem ser notado. Para deixar um documento de fora apenas algumas vezes, indique-o com when: em vez de depender da ausência do documento.
O source continua a ser renderizado na íntegra. Apenas a sua saída é filtrada: todos os templates do chart continuam a ser executados, pelo que um template que falhe continua a fazer falhar a compilação, e um documento deixado de fora é renderizado e depois descartado. Uma vez descartado, não chega a nada do que a compilação faz a seguir — nenhum ficheiro emitido, nenhum nome comparado com os nomes de outros componentes, nenhum facto que uma Feature leia sobre a renderização, nada que seja entregue a um passo de pipeline.
Uma Release chega à chave através de infra e parameters. A chave pertence à Recipe, pelo que uma Release não a pode escrever. Pode, ainda assim, 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 sempre que o Aggregate os encaminha para lá. Assim, uma Release ativa ou desativa uma entrada com when:, como faz a segunda entrada acima, ou decide o que ela indica.
O que se deixa de fora é da responsabilidade de quem o faz. Nada na compilação sabe para que serve um documento. Deixar de fora um de que o resto do chart depende em runtime — o Secret que um Deployment monta, a ServiceAccount com que 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 ficheiro compose e um template CloudFormation, a compilação verifica, porque cada um declara as suas próprias referências: o que resta e ainda indica uma unidade deixada de fora — um serviço que indica um serviço deixado de fora, um recurso ou um output que indica um recurso deixado de fora — para a compilação, como descreve a tabela abaixo.
Que providers a respeitam. Deixar um documento de fora é algo que só o provider pode fazer, porque só o provider sabe o que o seu source renderiza, pelo que o facto de um provider respeitar a chave faz parte da própria declaração do provider. Uma Recipe que declare omits: e cujo provider não o respeite é recusada antes de qualquer renderização, seja qual for o resultado da renderização dos when: das suas entradas; consulte The provider does not support omits (O provider não suporta omits).
| Provider | omits: |
|---|---|
helm | Respeitado. Uma entrada indica um documento que o chart renderiza — a partir de um template ou do seu diretório crds/ — pelo kind e pelo metadata.name do próprio documento e, quando a entrada o indica, pelo namespace em que o documento se encontra. Consulte helm → Modo com source. |
compose | Respeitado. Uma entrada indica um service, um volume ou uma config do ficheiro compose de origem pela sua chave em services:, volumes: ou configs:, correspondida depois de o valuesMapping: ser fundido no ficheiro, e não indica nenhum namespace: uma entrada que indique outro kind, ou um namespace, para a compilação quando o componente é renderizado. Um ficheiro em que o que resta ainda indica uma unidade deixada de fora — através de depends_on, links, volumes_from, um modo de rede ou de namespace service:, extends, um contexto de build, ou uma entrada de volumes: ou configs: — para a compilação, indicando cada referência. Consulte compose → Modo com source. |
cloudformation | Respeitado. Uma entrada indica um recurso do template de origem pelo seu Type e pelo seu ID lógico, em todos os templates de um source de diretório, e não indica nenhum namespace: uma entrada que contenha um para a compilação quando o componente é renderizado. Um template em que o que resta ainda indica um recurso deixado de fora — através de Ref, Fn::GetAtt, DependsOn ou de uma variável Fn::Sub — para a compilação, indicando cada referência. Consulte cloudformation → Deixar recursos fora de um template de origem. |
helm-chart, terraform | Recusado: o provider passa o seu source para ser renderizado quando é implementado, pelo que não existe nenhum documento em tempo de compilação para deixar de fora. Para um chart ou módulo local, uma linha no .aggregaignore ao lado da Recipe deixa, em alternativa, um ficheiro dele de fora. |
A mesma chave é escrita numa 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 numa entrada que não corresponde a nada, cada um de uma compilação real — consulte ai-gateway-own-webhook-certificate.