Provider Helm
O provedor helm produz YAML do Kubernetes renderizado plano para consumidores de GitOps (ArgoCD, Flux). O provedor monta por (path, provider): o YAML renderizado de cada nó destinado ao helm é roteado para o montador indexado pelo directory: avaliado da fronteira unido ao subDirectory: de cada componente, e esse montador emite um arquivo YAML por recurso do Kubernetes. As ferramentas a jusante comparam e aplicam os arquivos diretamente, sem uma etapa de instalação do Helm.
Onde o syncWave: <integer> da fronteira não é 0, cada recurso do Kubernetes emitido o carrega como a anotação argocd.argoproj.io/sync-wave: "<N>"; os hooks do Helm carregam também helm.sh/hook-weight: "<N>". O ArgoCD lê a anotação sync-wave, e o Helm lê o peso de um hook, cada um ordenando os recursos por esse valor; uma fronteira na onda padrão 0 não carrega nenhum dos dois, o que ambas as ferramentas leem como onda 0.
Esta página é a referência de autoria do provedor helm. Para o modelo de composição de entradas comum aos provedores, veja architecture/16-recipe-input-composition.md. Para a prontidão de cada provedor, veja Status da linguagem → Providers.
Tipos de entrada suportados
O provedor helm aceita os três tipos de entrada da Recipe, em papéis diferentes:
- Modo com fonte. Uma Recipe com
source: <chart-path>aponta para um diretório de chart Helm em disco. O SDK Go do Helm carrega o chart, o dicionário de valores da renderização base é mesclado com os padrões do chart, e os templates do chart são renderizados em YAML plano do Kubernetes. - Modo Workload (sintetizado). Uma Recipe com
workload:(em linha ou carregado via$import:) declara um documento Workload. O provedor sintetiza um ou mais recursos do Kubernetes por nó — um objeto controlador escolhido peloformdo Workload, mais Services por serviço e PVCs por volume persistente — diretamente a partir da especificação do Workload; veja Modo Workload (sintetizado). - Modo somente artefatos. Uma Recipe com
artifacts:e semsource:nemworkload:emite os manifestos que o seu autor escreveu, com os rótulos e anotações de proveniência do build inseridos nos próprios metadados de cada recurso.
Os três se combinam: uma Recipe pode declarar juntos um chart, um Workload e artifacts:, e cada um é renderizado e emitido por conta própria, lado a lado na saída do nó — veja O que cada provider aceita, por completo.
Conjunto de chaves de source:
O source: do provedor helm nomeia um chart, e aceita as duas formas que o campo source: assume: uma string simples de caminho do sistema de arquivos e um objeto estruturado cujo url: carrega o local. Sempre que esse local é um caminho do sistema de arquivos, ele é 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 deve permanecer dentro desse diretório: um caminho que sai dele, ou um absoluto, é recusado, porque cada arquivo que uma publicação da Recipe carrega é retirado do seu diretório — veja entities/recipe.md “Content paths stay inside the Recipe’s own directory (Caminhos de conteúdo permanecem dentro do próprio diretório da Recipe)”. Um chart nomeado dessa forma é publicado com a Recipe, com cada arquivo sob ele que as regras de exclusão registradas quando a Recipe foi fixada mantêm — o provedor helm deixa de fora os diretórios de controle de versão e os arquivos ocultos sob o templates/ do chart, respeita o próprio .helmignore do chart, e o .aggregaignore do autor tem a palavra final, como descreve Quais arquivos são distribuídos com uma entidade — enquanto um arquivo ao lado da Recipe que nada do que ela declara nomeia não é. A renderização lê os mesmos arquivos que a publicação carrega, então um chart é renderizado da mesma forma a partir do seu diretório e a partir de um registry. A forma em que você o escreveu não muda isso: um source: estruturado cujo url: é ./charts/api-server é ancorado exatamente como a string simples ./charts/api-server.
spec: capability: helm source: ./charts/api-server # filesystem path to a chart directory valuesMapping: | image: "{{ .values.image }}" replicas: {{ optional .infra `replicas` 2 }}Um source: estruturado diz a mesma coisa com campos nomeados, e o que o seu url: carrega decide se algo é buscado. Quando url: carrega um esquema de transporte — oci://… para um chart OCI, um https://….tgz para um arquivo de chart direto, ou uma raiz de repositório https:// combinada com chart: — o chart é buscado: o tipo vem do esquema da URL ou de um kind: explícito, aggrega pull busca e fixa o chart no lockfile, e o build o extrai do cache. Quando url: nomeia um caminho do sistema de arquivos, nada é buscado e nada é fixado — o chart é lido do disco, ancorado exatamente como a forma de string simples acima.
spec: capability: helm source: kind: helm-oci-chart url: ./charts/api-server # a path, so nothing is fetched and nothing is pinned version: "1.0.0"Somente url: decide de onde um chart é lido. Os outros campos selecionam o que seria buscado, então para um caminho eles não selecionam nada — ainda assim chegam aos próprios templates da Recipe como .source.*.
Copiar um chart localmente (vendoring) é suportado como alternativa a buscá-lo, e não é obrigatório. O esquema aceita um objeto estruturado aberto.
O chart no caminho de origem deve conter um Chart.yaml válido. Renderizações com fonte que não conseguem carregar o chart expõem literalmente o erro subjacente do SDK do Helm. Um source: "" vazio não é uma questão do helm: ele não nomeia nem o modo sem fonte nem o modo com fonte, então a recusa que recebe é a mesma qualquer que seja o provedor a que a Recipe se destina, e vem quando a Recipe é lida, antes de qualquer chart ser carregado e antes do despacho para este provedor. Os comandos que a relatam estão descritos em entities/recipe.md “Source field scheme inventory (Inventário de esquemas do campo source)” e errors/fatal-halts.md “Recipe source: is an empty string (O campo source da Recipe é uma string vazia)”.
Modo com fonte
Uma Recipe com source: <chart-path> e valuesMapping: executa o seguinte pipeline na renderização base:
- O chart em
<chart-path>é carregado por meio do SDK Go do Helm. - O template
valuesMappingé avaliado em relação ao contexto de template da Recipe. A sua saída YAML é tratada como uma sobreposição de valores para o chart. - A sobreposição é mesclada uma única vez com os padrões do
values.yamldo chart; em caso de colisão, as chaves da sobreposição prevalecem (a semântica padrão dehelm install --valuesdo Helm). Uma chave que a sobreposição define comonullremove o padrão do chart para ela — no nível superior, dentro de uma tabela ou nos valores de uma dependência — como fazhelm install --values, de modo que os templates do chart leem a chave como ausente; umnullem uma chave para a qual o chart não dá nenhum padrão chega aos templates comonull. - O SDK do Helm renderiza os templates do chart em relação aos valores mesclados.
- O Aggrega injeta os seus metadados de proveniência nos manifestos renderizados por meio de reescrita de YAML pós-renderização, garantindo que a saída com fonte carregue a mesma rotulagem que a saída do modo Workload. Valores de identidade se tornam rótulos (
app.kubernetes.io/name,aggrega.ai/component-id,aggrega.ai/provider,aggrega.ai/provider-version,aggrega.ai/environmente — quando definidos —aggrega.ai/aggregate-name,aggrega.ai/compiler-version), cada um escrito em uma forma que o Kubernetes aceita como valor de rótulo; valores que um rótulo do Kubernetes não consegue representar se tornam anotações (aggrega.ai/recipe-uri,aggrega.ai/boundary-path,aggrega.ai/sync-waveonde a onda não é0, e o valor literal de qualquer rótulo cujo valor precisou ser reescrito — um Aggregate chamadoimported/flowrecebe o rótuloimported-flowe a anotaçãoimported/flowsob a mesma chave). A regra de reescrita é enunciada em well-known-annotations.md “Rótulos de proveniência emitidos pelos provedores”. - Os arquivos de saída ficam planos no diretório de saída da Recipe, um por recurso renderizado, com o nome
<name-basis>-<kind>[-<namespace>]-<name>.yaml— a mesma base da qual é derivado o nome da release descrito abaixo, seguida do tipo próprio do recurso, do namespace quando ele tem um, e do nome, cada um em minúsculas e com cada sequência de outros caracteres reduzida a um único hífen. Para um componente comum, essa base é a identidade própria do componente, que é também o que o rótuloaggrega.ai/component-iddo recurso carrega; para um chart fornecido pelo autor de uma vinculação de Feature, ela continua sendo a do componente hospedeiro, enquanto o rótulo carrega a identidade própria da vinculação. Um documento que não carrega tipo ou nome é nomeado, em vez disso, pelo caminho do seu template. A estrutura de diretórios do chart é achatada: não há subdiretóriotemplates/na saída renderizada, e dois templates em subdiretórios diferentes que compartilham um nome de arquivo continuam sendo dois arquivos, porque o nome vem do recurso e não do template. Um arquivo que o blocoartifacts:da Recipe nomeia não fica aqui: ele fica um diretório abaixo, sob um diretório com o nome do componente que o declarou, porque esse arquivo é nomeado pela chave que o seu autor escreveu e não pelo recurso que carrega — assim, sem esse diretório, dois componentes associados a uma mesma Recipe escreveriam um único caminho, sem que nenhum dos dois autores pudesse separá-los.
O namespace em relação ao qual o chart é renderizado é lido da anotação aggrega.ai/namespace que desce em cascata a partir da fronteira e chega ao chart como o namespace da sua release; quando nenhuma fronteira declara um, o chart é renderizado em relação a default. Onde uma fronteira declara um, cada recurso com namespace que o chart renderiza sem namespace — sem metadata.namespace, ou com um escrito vazio ou null — é emitido no namespace declarado, que é onde a instalação do chart com o Helm sob esse namespace da release o coloca, e o seu arquivo é nomeado com o segmento do namespace exatamente como um recurso cujo template escreve o campo. Um recurso cujo template escreve um namespace o mantém, qualquer que seja o namespace que ele nomeie. Um recurso com escopo de cluster fica sem namespace. Se um tipo tem namespace é determinado pelo escopo próprio da API do Kubernetes para um tipo que a própria API serve e, para um tipo personalizado, pelo scope que uma CustomResourceDefinition na mesma renderização declara para ele — a partir dos templates do chart ou do seu diretório crds/. Um recurso de um tipo que nenhum dos dois classifica é deixado como o chart o escreveu, e o build o relata, uma vez por tipo, nomeando o tipo e o seu grupo de API; o mesmo vale para um documento kind: List, cujos itens não são colocados. Onde nenhuma fronteira declara um namespace, nada é colocado e nada é relatado: um recurso que o chart escreve sem namespace é emitido sem ele, colocado pelo que a ferramenta que o aplica selecionar.
O relato é um aviso no build, que ainda assim é concluído:
warning: node "store" (provider "helm"): resources of kind "Probe" in API group "monitoring.example.org" write no namespace and are left without one rather than placed in namespace "shop": the kind is not one the Kubernetes API serves itself, and no CustomResourceDefinition in this chart's render gives it a single scope, so whether it is namespaced is not known when the build runs, and they land wherever the tool applying the output places themOnde o chart tem um valor que renderiza a CustomResourceDefinition do tipo, ou um que escreve o próprio namespace, defini-lo por meio do valuesMapping da Recipe coloca esse recurso.
A versão do Kubernetes para a qual um chart é renderizado
Os templates de um chart leem a versão do Kubernetes para a qual são renderizados como .Capabilities.KubeVersion, e muitos escolhem por ela uma versão de API, um campo ou um mecanismo inteiro — um token de conta de serviço projetado a partir da 1.21, por exemplo, e um de primeira parte abaixo disso. O build não tem um cluster para consultar, então a versão é uma que você declara, onde a Release diz onde um componente é implantado: a anotação aggrega.ai/kubernetes-version em uma fronteira, ou em um componente, onde prevalece sobre a da sua fronteira, em cascata exatamente como aggrega.ai/namespace.
spec: boundaries: production: annotations: aggrega.ai/kubernetes-version: "1.31" components: api: {} legacy: annotations: aggrega.ai/kubernetes-version: "1.28" # this component deploys to an older clusterO valor é lido da forma como helm template --kube-version lê a sua flag, então aceita as formas que essa flag aceita e um chart lê exatamente o que essa flag lhe daria: "1.31" é lido como v1.31, "v1.31.2" como v1.31.2, e o texto depois dos números permanece em .Capabilities.KubeVersion.Version como escrito — "1.29.3-gke.100" é lido como v1.29.3-gke.100 — enquanto .Capabilities.KubeVersion impresso por inteiro lê a versão sem ele. Um chart que compara .Capabilities.KubeVersion.Version com semverCompare lê esse sufixo como uma versão de pré-lançamento, então uma restrição sem um piso -0, como ">=1.21", não corresponde a ela, e um valor com espaços ao redor é lido com esses espaços — " 1.30 " é lido como "v 1.30 " — e falha totalmente nessa comparação: escreva a versão pura onde um chart a compara. Um valor que não é uma versão — "one.two", "latest", um único número — interrompe o build sob a condição para um valor que um plugin não consegue representar, nomeando o valor, o componente e a sua fronteira; o chart nunca é renderizado para alguma outra versão no lugar dela. Veja A Kubernetes version the helm provider cannot render a chart for (Uma versão do Kubernetes para a qual o provedor helm não consegue renderizar um chart). Um valor vazio é tratado como não definido.
Onde nenhuma anotação nomeia uma versão, um chart é renderizado para a versão para a qual o helm template padrão da mesma release do helm renderiza, que é a versão da biblioteca cliente do Kubernetes com a qual o provedor é construído: um provedor construído com a biblioteca cliente v0.37 renderiza para o Kubernetes v1.37.0. Assim, um chart é renderizado no Aggrega como o helm template dos seus próprios autores o renderiza, e o padrão só muda quando muda a biblioteca cliente com a qual o provedor é construído. Nomeie a versão do cluster no qual você implanta sempre que ela for diferente: um chart renderizado para uma versão mais nova do que a que o cluster executa pode emitir uma versão de API que esse cluster não serve.
Somente a versão é definida dessa forma. Toda outra capacidade que um chart lê — .Capabilities.APIVersions e .Capabilities.HelmVersion — é a embutida na biblioteca helm, então uma API que um cluster serve a partir de uma CustomResourceDefinition instalada não é informada ao chart. O intervalo kubeVersion próprio de um chart no seu Chart.yaml não é comparado com a versão: helm template recusa um chart cujo intervalo exclui a versão para a qual renderiza, e o build o renderiza. A anotação molda um chart renderizado a partir de uma fonte e nada mais: um Workload sintetizado e um corpo artifacts: não leem .Capabilities, e o provedor helm-chart repassa o seu chart sem renderizá-lo, para que seja renderizado quando for instalado.
Deixar documentos renderizados de fora. Este provedor respeita as entradas omits: que uma Recipe ou uma FeatureRecipe declara, neste modo e em nenhum outro: um Workload sintetizado e um corpo artifacts: são renderizados sem elas. Cada documento que o chart renderiza — a partir de um template ou de um arquivo do seu diretório crds/ — é comparado com cada entrada que se aplica ao build, e um documento que qualquer entrada nomeia é deixado de fora. Uma entrada nomeia um documento pelas palavras que o próprio documento carrega, as mesmas palavras a partir das quais são construídos o seu nome de arquivo de saída e os seus fatos de renderização: o seu kind, o seu metadata.name e, somente onde a entrada nomeia um, o namespace em que o documento está — aquele que o seu template escreve, ou o namespace declarado da fronteira onde este provedor coloca o documento como descrito acima. Nunca é o namespace em relação ao qual o chart é meramente renderizado: sem namespace declarado o chart é renderizado em relação a default, mas um documento cujo template não escreve nenhum namespace não está em nenhum, então uma entrada que nomeia default não corresponde a ele. Um documento que não carrega tipo ou nome não corresponde a nenhuma entrada. Os documentos deixados de fora são renderizados e depois descartados assim que o nome de cada arquivo está definido, então cada documento mantido é nomeado e escrito exatamente como seria sem as entradas, e um documento deixado de fora não chega a nada do que o build faz depois — nenhum arquivo, nenhum nome na comparação que recusa dois contribuidores que chegam ao mesmo nome, nenhum fato de renderização que uma Feature lê, nada que seja entregue a uma etapa do pipeline. O provedor relata quantos documentos corresponderam a cada entrada, e uma entrada à qual nenhum correspondeu interrompe o build; veja An omits entry left out nothing the source rendered (Uma entrada omits não deixou de fora nada do que a fonte renderizou).
A release do Helm sob a qual um chart é renderizado
O provedor renderiza com o SDK do Helm 4, na v4.3, então um chart lê o que o próprio helm template do Helm 4 lhe dá, e o mesmo chart com os mesmos valores renderiza os mesmos bytes em todo build. Um chart escrito e verificado com o Helm 3 pode observar estes comportamentos do Helm 4:
.Capabilities.HelmVersioninforma a versão do Helm 4,v4.3.- A versão padrão do Kubernetes é v1.37.0, porque o Helm 4 na v4.3 é construído com a biblioteca cliente v0.37, e
.Capabilities.APIVersionsé o conjunto de versões de API dessa biblioteca cliente. Nomeie a versão que o seu cluster executa, como descreve A versão do Kubernetes para a qual um chart é renderizado. - Um padrão
nulldo chart é descartado. Uma chave que ovalues.yamldo chart define comonull— no nível superior ou dentro de uma tabela — fica ausente de.Values, a menos que os valores que a Recipe fornece a definam, entãohasKeya informa como ausente,toYamla omite, e ovalues.schema.jsondo chart é verificado em relação aos valores sem ela. - Um escalar de bloco mantém a sua quebra de linha final antes de
---. Um documento que termina em um escalar de bloco e é seguido por outro documento do mesmo template mantém a última quebra de linha desse escalar, então ele é escrito|em vez de|-. .Charté um mapa indexado por nome de campo..Chart.Name,.Chart.Version,.Chart.AppVersione os outros campos são lidos como antes, mastoYaml .ChartoutoJson .Chart.Maintainersimprimem as chaves comoName,AppVersione assim por diante, com os campos vazios presentes, e um campo que os metadados do chart não carregam é lido como vazio em vez de fazer a renderização falhar..Capabilities.KubeVersion.Versionmantém o texto de uma versão como escrito, como descrito acima para a anotaçãoaggrega.ai/kubernetes-version.- Um
values.yamlque contém vários documentos YAML é lido por inteiro, com os documentos posteriores mesclados sobre os anteriores. .Files.Linesde um arquivo vazio não retorna nenhuma linha em vez de fazer a renderização falhar.- As funções de template adicionadas pelo Helm 4 —
mustToYaml,mustToJson,mustToToml,mustToDuratione as conversõesduration…— estão disponíveis para os templates de um chart. - Uma dependência com dois aliases dá a cada alias a sua própria cópia das dependências dessa dependência.
- A validação do esquema de valores aceita ou recusa de forma diferente apenas nos extremos: uma parte local de e-mail entre aspas,
NaNe números infinitos, um número comparado com um não número emenumeconst, e o local relatado para umpropertyNames, umcontentSchemaou um item posterior de array que falha.
Um template que o próprio mecanismo não consegue executar — um valor lido através de uma tabela ausente, por exemplo — é relatado na forma do Helm 4: o arquivo, a linha e a coluna do template em uma linha própria, depois o que estava sendo executado e a mensagem, recuados, para cada template pelo qual a falha passou. O fail ou o required próprio de um chart mantém a sua forma de uma linha execution error at (<file>:<line>:<col>): <message>, assim como um erro que uma função de template retorna.
Como o nome da release é derivado
Um chart com fonte é renderizado com um nome de release, que chega a cada template como .Release.Name. Os charts costumam nomear recursos com base nele, então um nome de release é uma identidade dentro do cluster, e não um rótulo no build.
O nome da release é a forma codificada da mesma base que serve de prefixo ao nome do arquivo de saída do recurso renderizado, então os dois são um único nome escrito duas vezes. Essa base é um instance_id para um componente comum, e a identidade composta que uma Feature vinculada a uma fronteira carrega. Para um chart fornecido pelo autor de uma vinculação de Feature, é o nome do componente hospedeiro: os próprios templates do chart são renderizados com o nome da release, então derivá-lo, em vez disso, da vinculação renomearia recursos que o chart declara, em um cluster onde eles já estão implantados. Esses recursos ainda carregam a própria identidade da vinculação no seu rótulo aggrega.ai/component-id — como um recurso se chama e a que ele pertence são aqui questões separadas, e só para um componente comum elas têm a mesma resposta. Um nome de release do Helm aceita um conjunto de caracteres mais restrito do que uma identidade pode conter: letras minúsculas, dígitos, hifens e pontos, começando e terminando com uma letra minúscula ou um dígito, até 53 caracteres. Em vez de substituir um caractere que o destino não aceita, a derivação o escreve por extenso, de modo que duas identidades de componente que diferem apenas na pontuação ou em maiúsculas e minúsculas sempre chegam a dois nomes de release.
- Uma letra minúscula e um dígito são mantidos exatamente como foram escritos.
- Um hífen é mantido como foi escrito sempre que o caractere depois dele é mantido diretamente e não é um
zminúsculo. Um hífen seguido de umzminúsculo abre uma sequência de escape, então um hífen escrito nessa posição é ele próprio escrito por extenso —api-zonese tornaapi-zhzone, que é o que permite ler qualquer nome de volta sem adivinhar. Um hífen sem nada depois dele é escrito por extenso pelo mesmo motivo, entãodb-dádb-zh. - Qualquer outro caractere é escrito como
-zseguido de uma letra que o nomeia:dpara um ponto,upara um sublinhado,spara um separador de caminho,hpara um hífen que a regra acima não mantém. Todo o resto — inclusive uma letra maiúscula — é escrito comoxe o ponto de código hexadecimal de seis dígitos do caractere, e um byte que não inicia caractere algum comobe o seu próprio valor de dois dígitos. - Um valor vazio é escrito
-ze, que nenhum valor não vazio pode produzir.
Um ponto é escrito por extenso em vez de mantido, embora o Helm aceite um ponto em um nome de release, porque o Helm exige uma letra minúscula ou um dígito de cada lado de um ponto e a derivação coloca hifens próprios.
Como duas Features vinculadas a um mesmo componente são ambas renderizadas com o nome da release desse componente, dois charts que nomeiam cada um um recurso com base em .Release.Name emitem dois recursos com um mesmo nome. Este provedor informa o nome que cada recurso produzido pela sua própria renderização carrega, delimitado ao tipo desse recurso e, para um tipo que o cluster mantém em um namespace, ao seu namespace, e o build recusa dois contribuidores que chegam a um desses nomes em vez de emitir uma saída em que aplicar ambos deixa apenas o último — veja ../errors/fatal-halts.md “The same name is derived more than once inside the output (O mesmo nome é derivado mais de uma vez dentro da saída)”. Um tipo que o cluster mantém fora de qualquer namespace — um ClusterRole, uma CustomResourceDefinition ou um tipo personalizado que uma CustomResourceDefinition na mesma renderização declara com o escopo Cluster — é delimitado apenas ao seu tipo, classificado exatamente como o posicionamento em namespaces descrito acima o classifica, então dois componentes de uma mesma saída que escrevem cada um um objeto desses com um mesmo nome são recusados mesmo quando a Release os coloca em namespaces diferentes. A correção é compor o nome, e de qual coordenada ele precisa depende do arranjo. Duas vinculações em um mesmo componente já compartilham o hospedeiro, então é a vinculação que precisa chegar ao template: passe .attachment_name para o chart por meio do valuesMapping: da FeatureRecipe e defina-o naquele dos próprios valores do chart a partir do qual os nomes dos seus recursos são construídos. Um mesmo chart vinculado a dois componentes é o caso inverso — o nome da release já difere por hospedeiro, então um recurso nomeado com base em .Release.Name carrega um nome próprio em cada um deles, enquanto um nome literal não. Uma FeatureRecipe que entrega os seus recursos por meio de artifacts: é informada nos mesmos termos: este provedor lê o nome que cada documento emitido carrega, quer esse documento venha de um template de chart, quer de um corpo de artefatos, então um nome literal em um corpo desses vinculado a dois componentes também interrompe o build. Um corpo de artefatos é um template, então componha o nome a partir de .context.rendered_name — o nome da release do hospedeiro, que difere por hospedeiro e é escrito nos caracteres que um nome do Kubernetes permite — e de .attachment_name onde ele precisa ser distinto por hospedeiro; em um hospedeiro que coloca sozinho um conjunto de artefatos, que não informa nenhum nome de release, componha-o em vez disso a partir de .context.instance_id. Nem todo nome é informado, então um build que não é interrompido não comparou tudo o que a sua saída vai acabar carregando. O que você tem mais chance de encontrar ao escrever um chart é um recurso que declara generateName, cujo nome fica para o cluster completar e que, portanto, ainda não tem nada a comparar. A página indicada acima traz o conjunto completo.
Assim, um instance_id api dá o nome de release api, data.main-db dá data-zdmain-db, e db_host dá db-zuhost. Uma identidade formada apenas por letras minúsculas, dígitos e hifens que a derivação mantém aparece exatamente como foi escrita. Uma entrada idêntica sempre produz o nome idêntico.
Duas das condições do Helm são propriedades da base, e não da derivação: um nome de release precisa começar com uma letra minúscula ou um dígito, e precisa ter no máximo 53 caracteres. Uma base cujo primeiro caractere é escrito por extenso começa o seu nome com o hífen com que toda sequência de escape se abre, e uma que contém caracteres escritos por extenso fica, codificada, mais longa do que foi escrita. O build consulta este provedor sobre ambas, e age conforme a resposta em tempo de build em vez de deixar a recusa para o cluster no momento da aplicação — veja ../errors/fatal-halts.md “The target will not accept a name derived from an authored identity (O destino não aceita um nome derivado de uma identidade escrita)”. O que ele faz com a resposta depende de quem escreveu a base. Um nome que você escreveu é recusado em vez de alterado, e a recusa nomeia o campo que você escreveu e o limite de que você dispõe; um nome que Aggrega compôs é encurtado até que este provedor o aceite.
O cluster submete os recursos nomeados com base em um componente a uma regra mais rigorosa que as do Helm: o nome de um Service precisa começar com uma letra, enquanto um nome de release pode começar com um dígito. Um chart costuma nomear os seus Services com base no nome da release, e os Services de uma carga de trabalho sintetizada também começam com ele, então este provedor também recusa um nome de componente que começa com um dígito, informando-o como um Service name que o destino não pode usar. Nenhum comprimento corrige um primeiro caractere, então essa recusa não indica nenhum. Portanto, comece um instance_id com uma letra minúscula e mantenha-o curto o bastante para que a sua forma codificada ainda caiba.
Mudar a base da qual um nome de release é derivado renomeia os recursos do cluster que um chart nomeia com base em .Release.Name, e todo recurso que este provedor sintetiza para o componente, e o Kubernetes não renomeia um recurso no lugar. A ferramenta que aplica a saída cria o recurso com o novo nome e remove o que tem o nome antigo, o que, para recursos com estado, significa que o armazenamento associado ao nome antigo é liberado. Trate uma mudança dessas como uma substituição a ser planejada — com drenagem, migração ou uma janela agendada — e não como uma atualização a ser implantada.
Modo Workload (sintetizado)
Uma Recipe com workload: (em linha ou carregado via $import:) sintetiza recursos do Kubernetes a partir da intenção abstrata do Workload. O esquema do Workload está documentado em entities/workload.md; esta seção cobre o que o provedor helm emite.
Para cada nó:
- Um objeto controlador escolhido pelo
formdo Workload:stateless(e o padrão) emite um Deployment,statefulum StatefulSet,daemonum DaemonSet,taskum Job,scheduledum CronJob cujospec.scheduleé o camposcheduledo Workload (uma expressão cron de 5 campos ou uma macro@); uma carga de trabalhoscheduledsem agendamento, ou com um malformado, interrompe o build de forma explícita. Uma carga de trabalhoscheduledque declarasuspend: trueemite o seu CronJob comspec.suspend: true, de modo que nenhuma execução começa a partir do agendamento até que ela seja retomada, enquanto um Job ainda pode ser criado manualmente a partir do CronJob; uma que não o declara não emite nenhuma chavesuspend. O Deployment e o StatefulSet carregam o número de réplicas; DaemonSet, Job e CronJob não carregam nenhum. Um Workloadstatefulexige exatamente um Servicetype: Headlessdeclarado no Workload para governar o StatefulSet; o provedor liga oserviceNamedo StatefulSet ao nome renderizado desse Service, e o build é interrompido se nenhum Service headless for declarado (ou se mais de um for). Um volumepersistentTemplateé um complemento deform: stateful— declarar um em qualquer outra forma interrompe o build com uma mensagem que nomeia a correção. - Um Service por entrada
services:declarada no Workload, expondo as portas nomeadas que a especificação do serviço lista. Otypeda entrada se torna o tipo do Service —ClusterIP,NodePorteLoadBalancerliteralmente, eHeadlesscomo um ServiceClusterIPcomclusterIP: None. Uma entradaLoopbackinterrompe o build em vez disso, nomeando o nó e o serviço: um Service do Kubernetes não tem nenhum tipo que se associe ao endereço de loopback de um host, e em quais endereços de nó um ServiceNodePortescuta é uma configuração do cluster inteiro, então a entrada é recusada em vez de renderizada com um alcance que ela não pediu. Veja A service type the helm provider cannot render (Um tipo de serviço que o provedor helm não consegue renderizar). - Um PersistentVolumeClaim por volume
persistent, dimensionado e configurado a partir da especificação do volume. Um volumepersistentTemplatenão emite nenhuma claim independente: ele se torna uma entradavolumeClaimTemplatesdentro da própria especificação do StatefulSet, e é por isso que é um complemento deform: stateful.
Nomes dos recursos. Todo recurso que este modo emite para um componente é nomeado com base no nome da release do componente — o mesmo nome com que um chart com fonte é renderizado, derivado como expõe Como o nome da release é derivado — e o provedor informa esse nome ao build como {{ .context.rendered_name }}. O objeto controlador carrega o próprio nome da release; cada Service é <release name>-<service key>; cada claim independente é <release name>-<volume>, e o volume do pod referencia exatamente essa claim; um secret entregue como arquivo é montado a partir de um volume do pod chamado <release name>-secret-<slot>, com o slot escrito no alfabeto que o cluster aceita, assim como o nome da release — assim, um slot server_certificate é montado a partir de <release name>-secret-server-zucertificate, e um slot lido por meio de uma conexão tem o ponto depois do nome da conexão escrito da mesma forma; o serviceName de um StatefulSet é o nome do Service headless que ele emite; e um Workload exposto apenas por nome externo emite um único Service que carrega o nome da release. Assim, um componente api emite um Deployment api e um Service default api-default, e um componente my_api emite my-zuapi e my-zuapi-default — nomes que o cluster aceita, onde a identidade como foi escrita não seria aceita. Uma Recipe que publica o endereço de um desses Services o constrói a partir de {{ .context.rendered_name }}, como mostra ../templates/rendered-resource-names.md; para um componente cujo nome não contém sublinhado nem letra maiúscula, o nome da release é igual ao seu instance_id, então os seus nomes se leem exatamente como a identidade. Uma carga de trabalho que uma vinculação de Feature sintetiza é a única exceção: ela é nomeada com base na própria identidade composta da vinculação — o valor que o seu rótulo aggrega.ai/component-id carrega — porque a vinculação é renderizada com o seu componente hospedeiro, e um nome de release derivado ali nomearia a carga de trabalho da vinculação com base no hospedeiro e colidiria com a do próprio hospedeiro. Essa identidade nunca contém uma letra maiúscula: uma maiúscula no nome do hospedeiro ou no da vinculação é escrita por extenso como sequência de escape, como todo outro caractere que um nome de recurso recusa, então uma vinculação worker em um componente myApi emite um Deployment cfr--my-zx000041pi--worker e um Service default cfr--my-zx000041pi--worker-default, e cada nome que a carga de trabalho carrega é um que o cluster aceita.
Comprimentos de nome que dependem do Workload. Dois desses nomes estão sujeitos, no cluster, a limites próprios, e o build verifica ambos assim que o Workload é resolvido, em vez de deixar a recusa para o cluster no momento da aplicação. Um nome de CronJob tem no máximo 52 caracteres, menos que os outros nomes do cluster porque o controlador nomeia o Job de cada execução segundo o CronJob, acrescentando um sufixo; ele é verificado apenas para um Workload scheduled. Cada nome de Service, <release name>-<service key>, tem no máximo 63 caracteres. Além de qualquer um dos limites, o que acontece depende de quem escreveu o nome, exatamente como para o nome da release: um nome de componente que você escreveu é recusado, com o build interrompido na chave spec.components que você escreveu, indicando o tipo de nome, o seu comprimento e o orçamento que o seu nome tem — consulte ../errors/fatal-halts.md “The target will not accept a name derived from an authored identity (O destino não aceitará um nome derivado de uma identidade escrita pelo autor)”; uma identidade composta, como aquela segundo a qual o workload de uma vinculação de Feature é nomeado, é encurtada até que todos os nomes caibam. Um nome de Service é construído a partir do nome do seu componente e de uma chave que o workload declara — na Recipe ou em uma FeatureRecipe —, então uma recusa nomeia essa chave e onde o workload a declara, spec.workload.services.<key>; uma chave que não deixa espaço para nenhum nome de componente precisa ser ela mesma encurtada. Assim, um componente que carrega um Workload scheduled pode ter um nome codificado de até 52 caracteres, e um componente web pode carregar chaves de Service de até 59. Uma Feature vinculada a uma fronteira inteira tem a sua identidade definida antes de o seu Workload ser resolvido, porque o lugar onde a sua saída é montada pode depender dessa identidade, então nenhum dos limites é verificado para os recursos que ela sintetiza.
Cada recurso emitido carrega o conjunto completo de rótulos e anotações de proveniência de Aggrega, mais um par de seletores (app: <instance_id>) ligado entre o Deployment/StatefulSet e os seus Services. Um valor de rótulo admite a identidade como foi escrita, então o seletor a mantém enquanto os nomes acima recebem o nome da release. Os nomes dos contêineres no Deployment renderizado são as chaves de contêiner do Workload com os caracteres . e _ substituídos por - (sanitização de nomes do Kubernetes).
Transporte de portas. Uma porta de contêiner que declara um transporte o emite literalmente como protocol: no containerPort renderizado, e toda porta de Service que nomeia essa porta de contêiner carrega o mesmo valor — o transporte é declarado uma única vez, na porta de contêiner, então a exposição não pode discordar dele. Uma porta que não declara nenhum transporte não emite nenhuma chave protocol em nenhum dos dois recursos, deixando em vigor o padrão do cluster. Os três valores que o Workload admite (TCP, UDP, SCTP) são emitidos literalmente; o helm não precisa de nenhuma degradação, já que o Kubernetes expressa cada um deles diretamente.
Execução na rede do nó. Um Workload que declara hostNetwork: true emite hostNetwork: true na especificação do pod renderizada, de modo que o pod é executado no próprio namespace de rede do nó e as portas que os seus contêineres abrem ficam acessíveis nos endereços do nó. O Kubernetes expressa a escolha diretamente, então nada é degradado. A declaração chega à especificação do pod e a nada mais: não adiciona, não remove e não reescreve nenhuma porta, e os Services emitidos são idênticos com e sem ela. Um Workload que não a declara não emite nenhuma chave hostNetwork.
Quantidades de recursos. Cada quantidade que o provedor copia para os manifestos é emitida literalmente, e cada uma é verificada primeiro em relação à forma de quantidade descrita em Workload → Quantidades de recursos: os valores resources.requests e resources.limits de cada contêiner e de cada contêiner de inicialização — cpu, memory e todo recurso estendido como nvidia.com/gpu — e ephemeral.sizeLimit, persistent.size e persistentTemplate.size de cada volume. A verificação é executada no Workload tal como os templates da Recipe o avaliaram, então um valor que chegou por meio de infra ou de um parâmetro da Release é julgado pelo resultado da sua renderização. Um valor fora da forma interrompe o build com um erro TRANSLATION_ERROR que nomeia o nó, o caminho do campo no Workload e o valor — por exemplo containers.main.resources.requests.cpu: "lots" is not a quantity: it does not begin with a number — onde, de outra forma, o chart seria gerado sem erros e recusado pelo cluster na instalação. Um cpu, memory ou sizeLimit deixado vazio é omitido dos manifestos e, portanto, não é verificado; um valor de recurso estendido ou um tamanho persistente deixado vazio ainda seria emitido, então é recusado. A verificação julga apenas a forma: se o cluster consegue agendar a quantidade não é algo que o provedor possa saber em tempo de build.
A nomeação dos arquivos de saída tem duas formas. O objeto controlador é nomeado com base no nome da release e no seu tipo — <release name>-deployment.yaml, <release name>-statefulset.yaml, <release name>-daemonset.yaml, <release name>-job.yaml, <release name>-cronjob.yaml. Um arquivo por recurso é nomeado com base no recurso que ele carrega, com o tipo por último: <release name>-<svcName>-service.yaml e <release name>-<volName>-pvc.yaml, cada um tirado do próprio metadata.name desse recurso conforme a convenção de nomes sintetizados em entities/workload.md. Um Workload exposto apenas por nome externo emite <release name>-service.yaml, já que não há chave de serviço a carregar.
Fatos de renderização
Além dos arquivos que renderiza, este provedor informa quatro fatos de renderização sobre cada nó: o que os documentos do Kubernetes que ele emitiu dizem sobre os seus pods, os seus seletores, as suas portas e o namespace em que cada um é emitido. Uma FeatureRecipe vinculada ao componente lê os próprios fatos do componente em .context.render_facts; uma que define readsCallerRenderFacts: true também lê, em cada entrada de .context.used_by, os fatos de um componente que se conecta ao seu hospedeiro, e uma que define readsTargetRenderFacts: true lê, em cada entrada de .context.uses, os fatos de um componente ao qual o seu hospedeiro está ligado. É assim que uma Feature pode nomear os pods dos componentes que chamam o seu hospedeiro, ou dos componentes que o seu hospedeiro alcança — uma política de rede que admita exatamente esses, por exemplo — a partir do que as renderizações deles efetivamente emitiram, sem que ninguém repita um rótulo à mão. Os nomes e as entradas abaixo são o contrato deste provedor.
| Fato | Uma entrada por | Cada entrada carrega |
|---|---|---|
pod_template_labels | template de pod emitido: o spec.template de um Deployment, StatefulSet, DaemonSet, ReplicaSet ou Job, o template de job de um CronJob, e um Pod avulso, que é o seu próprio template | kind, name e namespace do recurso que carrega o template; labels, os rótulos do template |
controller_selectors | Deployment, StatefulSet, DaemonSet, ReplicaSet, Job e CronJob emitido | kind, name, namespace; match_labels, os matchLabels do seu seletor |
service_selectors | Service emitido | name, namespace; selector, os rótulos para os quais ele envia tráfego |
container_ports | contêiner de um template de pod que declara uma lista ports, incluindo os contêineres de inicialização | kind, name e namespace do recurso que carrega o template; container, o nome do contêiner; ports, uma entrada por porta com o seu name, container_port e protocol |
Como os fatos são lidos:
- Todo fato é uma lista. Um template sempre itera sobre um fato, mesmo quando ele contém uma única entrada; não há um valor único para ler isoladamente.
- Os quatro, em toda renderização. Cada um é informado sempre que este provedor renderiza um nó, como uma lista vazia quando a renderização não emitiu nada do que ele descreve — um componente cujo chart emite apenas um ConfigMap informa quatro listas vazias. A renderização de outro provedor não informa nenhum desses nomes, e um nome que ninguém informou é lido como nada.
- Lidos a partir do que foi emitido, em todo caminho. Os fatos vêm dos documentos que a renderização emitiu, qualquer que seja o modo que os produziu: os manifestos renderizados de um chart, os de um Workload sintetizado e os manifestos que um autor colocou por meio de
artifacts:, que informam exatamente o que esses manifestos carregam. Eles são lidos na mesma passagem, sobre os mesmos documentos, que os nomes de recursos que este provedor informa para a verificação de nomes duplicados do build. Os próprios rótulos de proveniência de um recurso fazem parte do que ele carrega, então oslabelsde um Pod avulso os incluem; o template de pod de um chart ou de um artefato mantém os rótulos que o seu autor escreveu. - As entradas podem vir da própria renderização do componente e das renderizações das suas Features. Um componente pode ser renderizado por mais de uma chamada — um chart e uma colocação
artifacts:, por exemplo — e as listas que um nome recebe dessas chamadas são unidas em uma só, na ordem em que as chamadas foram executadas. Em.context.used_bye.context.uses, os fatos do componente na outra ponta de uma conexão também reúnem o que as Features vinculadas a ele renderizaram, depois dos seus próprios;.context.render_factscarrega apenas a própria renderização do componente. - Na ordem de emissão. As entradas seguem a ordem em que a renderização emitiu os recursos. Um mapa de rótulos é um mapa com chaves como qualquer outro no contexto, então um template que itera sobre um encontra as suas chaves na ordem das chaves.
- O que um documento deixa de fora, a sua entrada deixa de fora. Um recurso nomeado por
generateNamenão temname; um recurso que não escreve nenhummetadata.namespacenão temnamespace, e tampouco o tem um que o escreve vazio ou null, o que também não nomeia nenhum namespace; um controlador escrito semmatchLabels— um Job que depende do seletor que o cluster gera — não temmatch_labels; um Service sem seletor não temselector; uma porta sem nome ou sem protocolo não tem nenhum dos dois. Qualquer outra parte escrita vazia é informada vazia.protocolé informado apenas onde o documento escreve um, então um template que precisa dele escreve por conta própria o padrão do próprio cluster,TCP.container_porté um número onde quer que o documento escreva um. namespaceé o que o documento escreve, nunca um palpite. É o própriometadata.namespacedo recurso — para um template de pod, o do recurso que o carrega, que é onde os seus pods são executados; um namespace escrito dentro do próprio template de pod não é lido. Um Workload sintetizado escreve o namespace que a sua fronteira declara em cada recurso que emite, então as suas entradas carregam esse namespace. As entradas de um chart carregam o que os seus documentos emitidos escrevem: onde uma fronteira declara um namespace, esse namespace — seja porque os templates do chart o projetam, seja porque o provedor coloca o recurso nele (veja Modo com fonte) — a menos que um template fixe um próprio, que a entrada carrega em vez disso; onde nenhum é declarado, o namespace da release,default, onde os templates o projetam, e nada onde eles não escrevem nenhum. Onde nada é escrito, a entrada não carrega nenhumnamespaceem vez do padrão da fronteira ou do cluster, porque um recurso assim vai parar onde quer que a ferramenta que aplica a saída o coloque, o que não é conhecido quando o build é executado. Um template distingue os dois casos comoptional:{{ optional . "namespace" "" }}é vazio exatamente onde o documento não escreveu nenhum, então uma Feature que coloca algo ao lado dos pods de um componente consegue distinguir um componente cujo namespace dos pods é conhecido de um cujo namespace não é.- Reconhecidos por tipo e grupo de API.
PodeServicesão lidos no grupo core, os quatro controladores emapps,JobeCronJobembatch, em qualquer versão do grupo. Um recurso personalizado de outro grupo que por acaso carregue um desses nomes de tipo não é lido como tal. AsmatchExpressionsde um seletor não são informadas, e tampouco um recurso encapsulado em um documentokind: Listou um valor escrito por meio de uma chave de mesclagem do YAML.
O que os fatos não conseguem ver. Eles descrevem os documentos que o build emite, e nada que o cluster crie depois. Os pods que um controlador cria em tempo de execução a partir de um recurso personalizado — o cluster de banco de dados de um operador, por exemplo — não aparecem em nenhum documento emitido, então estão ausentes por construção; o mesmo vale para qualquer rótulo que um controlador de admissão de mutação adicione quando os manifestos são aplicados. Uma Feature que precisa admitir esses pods obtém os rótulos deles da própria documentação do recurso personalizado, como faria um autor sem esses fatos.
Uma FeatureRecipe que admite nos pods do seu hospedeiro exatamente os pods dos componentes que o chamam, selecionando os próprios pods do hospedeiro pelo seletor do controlador do hospedeiro:
apiVersion: aggrega.ai/v1beta1kind: FeatureRecipemetadata: name: admit-callers version: 1.0.0spec: capability: helm implements: example/admit-callers:1.0.0 readsCallerRenderFacts: true artifacts: allow-callers.yaml: | apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: {{ .context.rendered_name }}-allow-callers spec: podSelector: matchLabels: {{- range .context.render_facts.controller_selectors }} {{- range $k, $v := .match_labels }} {{ $k }}: {{ toJson $v }} {{- end }} {{- end }} policyTypes: - Ingress ingress: - from: {{- range .context.used_by }} {{- range .render_facts.pod_template_labels }} - podSelector: matchLabels: {{- range $k, $v := .labels }} {{ $k }}: {{ toJson $v }} {{- end }} {{- end }} {{- end }}Para um hospedeiro api chamado por um componente web cujo Workload este provedor sintetizou, a política seleciona app: "api" e admite um podSelector que carrega cada rótulo do template de pod de web — os mesmos rótulos que o spec.template.metadata.labels do seu Deployment emitido contém. Como a FeatureRecipe define a chave, a sua vinculação é renderizada depois que todos os componentes foram renderizados, então os fatos estão lá qualquer que seja, entre api e web, aquele que o build alcance primeiro; sem a chave, um template que lê render_facts em .context.used_by interrompe o build antes que qualquer coisa seja renderizada.
Um podSelector no from de uma política corresponde a pods no próprio namespace da política, então a política acima admite chamadores emitidos no namespace em que ela é aplicada. Um chamador cujas entradas carregam outro namespace é admitido combinando o seu podSelector com um namespaceSelector no rótulo kubernetes.io/metadata.name desse namespace, que o Kubernetes define em todo namespace.
Particularidades específicas do Provider
-
Os downloads de charts usam apenas os manipuladores integrados do Helm. Um chart buscado em um repositório Helm é baixado com os próprios manipuladores integrados
httpehttpsdo Helm. Um plugin de download do Helm — um instalado para o comandohelm, ou um que esteja no diretório a partir do qual o build é executado — nunca é consultado, então o que está nesse diretório não pode mudar a forma como um chart é buscado. -
Injeção de proveniência. Os caminhos com fonte e sintetizado convergem no mesmo conjunto de rótulos e anotações; as renderizações com fonte os injetam por meio de reescrita de YAML pós-renderização (depois que o SDK do Helm já renderizou), então os autores de charts não precisam passar os rótulos de Aggrega pelos seus próprios templates.
-
Ordem do ambiente — entradas lidas de Secret primeiro. A lista
envde um contêiner sintetizado carrega dois tipos de entrada: cada entradaattachmentsentregueas: envlê o seu valor de um Secret por meio devalueFrom.secretKeyRef, e cada entradavariablescarrega umvaluesimples. O provedor escreve primeiro cada entrada lida de Secret e depois cada variável simples, cada tipo na ordem em que foi escrito, e lista as fontesenvFromseparadamente sobenvFrom. O Kubernetes expande uma referência$(NAME)em um valor deenva partir das entradas listadas antes dela no mesmo contêiner, nunca de uma listada depois, então essa ordem permite que uma variável simples componha por referência um valor lido de Secret enquanto o próprio segredo permanece no Secret:containers:api:image: "api:1.0"variables:DATABASE_URL: "postgres://app:$(DB_PASSWORD)@db:5432/app"attachments:DB_PASSWORD: { from: db-credentials, as: env }O contêiner renderizado lista
DB_PASSWORDantes deDATABASE_URL, então o processo recebe a URL com a senha no lugar. Uma variável também pode referenciar qualquer variável escrita antes dela, o que mantém significativa a ordem de escrita dentro devariables. Os contêineres de inicialização seguem a mesma ordem. Um contêiner que fornece um mesmo nome tanto como entradavariablesquanto como entradaattachmentsentregueas: envinterrompe o build em vez de escrever as duas entradas, porque então apenas essa ordem decidiria qual valor o processo vê (veja A container gives one environment variable two values (Um contêiner dá dois valores a uma mesma variável de ambiente)). -
Cascata de namespace — os dois modos chegam ao recurso de forma diferente. Ambos leem
aggrega.ai/namespaceda cascata de anotações da fronteira, e nenhum dos dois inventa um namespace quando nenhuma fronteira declara um. No modo sintetizado, o provedor escrevemetadata.namespacediretamente, e omite o campo por completo quando a cascata não produz nenhum valor. No modo com fonte, o provedor fornece o valor como o namespace da release do chart —defaultquando a cascata não produz nenhum — e o próprio template do chart decide se o projeta; onde um namespace é declarado, o provedor então o escreve em cada recurso com namespace que o chart renderizou sem um (veja Modo com fonte). Assim, com um namespace declarado, os dois modos colocam nele cada recurso com namespace — exceto um namespace que um chart fixa por conta própria e um tipo que o provedor não consegue classificar. Sem nenhum declarado, eles se separam: um chart que projeta o namespace da release coloca os seus recursos emdefault, onde a saída sintetizada não escreve nenhum, e um chart que não escreve nenhum namespace não os coloca em nenhum, então eles vão parar onde a ferramenta que aplica os manifestos os puser. Os charts locais que as FeatureRecipes da biblioteca padrão carregam leem, em vez disso, o valor da cascata diretamente por meio do seuvaluesMapping: isso lhes permite omitir o campo quando nenhuma fronteira declara um namespace, em linha com a saída sintetizada, o que o namespace da release sozinho não consegue expressar porque nunca é vazio.
Exemplos práticos
Modo com fonte — Recipe que aponta para um chart copiado localmente:
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: api-server-helm version: 1.0.0spec: capability: helm implements: core/api-server source: ./vendor/charts/api-server valuesMapping: | image: "{{ .values.image }}" replicaCount: {{ optional .infra `replicas` 2 }} service: type: ClusterIP port: {{ .values.port }} env: LOG_LEVEL: "{{ optional .values `log_level` "info" }}"Modo Workload — Recipe que declara um Workload em linha:
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: api-server-workload version: 1.0.0spec: capability: helm implements: core/api-server workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload replicas: {{ optional .infra `replicas` 2 }} containers: api: image: "{{ .values.image }}" ports: web: {{ .values.port }} services: svc: type: ClusterIP ports: web: {{ .values.port }}Referências cruzadas
entities/recipe.md— superfície de autoria da Recipe e os três tipos de entrada.entities/workload.md— esquema do Workload para o modo sintetizado.providers/helm-chart.md— provedor irmão que emite um esqueleto de chart do Helm em vez de manifestos planos.providers/well-known-annotations.md— anotações bem conhecidas que o provedor helm aplica (aggrega.ai/namespaceetc.).architecture/16-recipe-input-composition.md— Matriz de capacidades por Provider comum aos provedores.10-status.md#providers— classificação atual da prontidão.