Provider Helm-Chart
O provedor helm-chart produz um chart guarda-chuva do Helm empacotado por caminho de montagem. Enquanto o provedor helm emite YAML plano do Kubernetes para consumo direto via GitOps, o helm-chart emite um esqueleto de chart — um Chart.yaml + values.yaml guarda-chuva mais um subchart por nó contribuinte — que as ferramentas a jusante podem instalar via helm install ou copiar localmente (vendoring) para personalização adicional por ambiente. O provedor monta por (path, provider): cada nó associado a uma Recipe helm-chart contribui para o guarda-chuva no directory: avaliado da fronteira unido ao subDirectory: de cada componente. Duas fronteiras que são avaliadas para o mesmo caminho se fundem em um único chart guarda-chuva mesclado que lista cada contribuidor como dependência de subchart.
Os templates de um subchart copiados do chart de origem levam o que o seu autor escreveu: o valor syncWave: <integer> da fronteira, o helm.sh/hook-weight em um hook e os rótulos de proveniência do Aggrega só chegam a eles onde o chart os escreve. O provedor helm é o que carimba argocd.argoproj.io/sync-wave: "<N>", helm.sh/hook-weight: "<N>" e os rótulos de proveniência em cada recurso que renderiza. Um artefato carregado via $import: que este provedor adiciona a um subchart leva os rótulos de proveniência e a anotação argocd.argoproj.io/sync-wave, e nenhum helm.sh/hook-weight (veja “Regra de injeção de artifacts:” abaixo). O ArgoCD lê a anotação sync-wave, e o Helm lê o peso de um hook.
Esta página é a referência de autoria do provedor helm-chart. Para a divisão entre helm e helm-chart, veja a seção Providers da página de status; para o modelo de composição de entradas comum aos provedores, veja architecture/16-recipe-input-composition.md.
Tipos de entrada suportados
O provedor helm-chart aceita dois tipos de entrada:
- Modo proveniente de uma fonte. Uma Recipe com
source: <chart-path>aponta para um diretório de chart Helm em disco. O chart é copiado para a estrutura guarda-chuva como subchart, literalmente, exceto pelonamedo próprio chart — veja “O nome do chart que pertence ao chart guarda-chuva”; nenhuma renderização ou processamento de templates é feito no nível de cada nó. O papel do Aggrega é a composição (a montagem do guarda-chuva entre os nós da fronteira), não a avaliação de templates. - Modo
artifacts:carregado via$import:. Uma Recipe com entradasartifacts:escritas como$import:por entrada declara arquivos de template adicionais que o provedor helm-chart injeta no diretóriotemplates/do subchart depois da cópia do chart de origem. Cada arquivo é pré-processado como template em relação ao contexto de template do Aggrega usando os delimitadores[[ ]](veja “Regra de injeção deartifacts:” abaixo), para que qualquer templating Helm{{ }}no mesmo arquivo sobreviva até a renderização a jusante dohelm install.
Uma Recipe destinada ao helm-chart que declara workload: é recusada antes de renderizar, com a recusa que qualquer provedor dá para um tipo de entrada que não declara — ela nomeia o tipo que este provedor suporta e aponta ao autor um provedor que sintetiza:
provider does not support the node’s input kind (node “api”). provider “helm-chart” does not support synthesized recipes (this provider supports: sourced); declare one of the supported input kinds, or target a provider that supports synthesized (o provedor não suporta o tipo de entrada do nó (nó “api”). o provedor “helm-chart” não suporta recipes sintetizadas (este provedor suporta: proveniente de uma fonte); declare um dos tipos de entrada suportados, ou direcione para um provedor que suporte o tipo sintetizado)
A divisão é proposital: a síntese de cargas de trabalho (traduzir um Workload abstrato em recursos do Kubernetes) é responsabilidade exclusiva do provedor helm. O papel do helm-chart é a composição de guarda-chuva + subcharts para charts que o autor já produziu.
Uma Recipe destinada ao helm-chart também pode declarar entradas artifacts: com conteúdo em linha (entradas cujo valor é um escalar de bloco que leva o corpo do arquivo em linha na Recipe em vez de uma referência carregada via $import:). Uma entrada com conteúdo em linha é colocada na raiz do subchart sob a sua chave escrita — sem prefixo templates/ e sem inserção de proveniência. Os próprios templates de um chart leem esse arquivo avulso por meio de .Files.Get / .Files.Glob do Helm (o padrão canônico de ConfigMap a partir de arquivos), então um arquivo na raiz do chart é uma forma legítima e de primeira classe, e não um erro.
As duas formas são avaliadas com os delimitadores [[ ]] do Aggrega antes da colocação, de modo que um corpo de qualquer das formas pode ler o contexto de pilares da Recipe; {{ }} em qualquer dos corpos é deixado intacto e se torna uma diretiva Helm no momento do helm install a jusante. O que difere entre as formas é onde o arquivo vai parar e se a proveniência é mesclada nele:
- Uma entrada carregada via
$import:é um arquivo de template: após a avaliação (veja “Regra de injeção deartifacts:” abaixo), ela é injetada no diretóriotemplates/do subchart com a proveniência mesclada, para que o Helm a renderize como um manifesto ao lado dos próprios templates do chart. - Uma entrada com conteúdo em linha é um arquivo de dados avulso: após a avaliação, ela vai para a raiz do chart, sem alterações em relação ao que a avaliação produziu e sem proveniência mesclada, para consumo baseado em
.Files.
Regra de injeção de artifacts:
Quando uma Recipe helm-chart declara entradas artifacts: via $import: por entrada, cada valor $import: é o caminho para um arquivo de template resolvido em relação ao próprio diretório da Recipe (o diretório que contém o YAML da Recipe em disco). O provedor:
- Lê o conteúdo de cada arquivo.
- Pré-processa o conteúdo como template com os delimitadores do Aggrega
[[ ]]em relação ao contexto de template da Recipe (o mesmo contexto em relação ao qual ovaluesMapping:da Recipe é avaliado).{{ }}dentro do conteúdo do arquivo é deixado intacto — essas expressões se tornam diretivas de template Helm no momento dohelm install. - Escreve cada arquivo em
charts/<instance-id>/templates/<authored-key>sob o caminho de montagem do guarda-chuva, com os arquivos de um bundle aninhados sob essa chave. A chave sob a qual a entrada é escrita dá nome ao arquivo; o caminho de$import:seleciona o seu conteúdo e não contribui em nada para o nome, então a estrutura de diretórios dentro desse caminho nunca chega à saída.
A disciplina do duplo delimitador [[ ]] / {{ }} é o detalhe essencial. Um arquivo de artefato típico carregado via $import: pode misturar interpolação em tempo de Aggrega (por exemplo, [[ .values.image ]]) com interpolação em tempo de Helm (por exemplo, {{ .Release.Namespace }}). Cada par de delimitadores atua na sua própria fase: o Aggrega resolve [[ ]] em tempo de compilação, antes de o arquivo ser colocado; o Helm resolve {{ }} em tempo de instalação, depois que o guarda-chuva é entregue.
Colisões de nomes de arquivo entre os templates do chart de origem e as injeções de artefatos carregados via $import: geram CATALOG_ERROR — o diagnóstico nomeia o caminho de saída em colisão, como templates/cm.yaml, e os dois tipos de entrada que o produziram. Os autores resolvem a colisão renomeando a chave do artefato ou o próprio template do chart.
Conjunto de chaves de source:
O source: do provedor helm-chart nomeia um chart, e aceita as duas formas que o campo source: assume, lidas exatamente como as descreve o conjunto de chaves de source: do provedor helm: uma string simples de caminho do sistema de arquivos e um objeto estruturado cujo url: carrega a localização. Onde url: nomeia um caminho do sistema de arquivos, nada é buscado e o chart é lido do disco; onde carrega um esquema de transporte — oci://…, por exemplo, com kind: helm-oci-chart — aggrega pull busca e fixa o chart, e o build o copia do cache para o guarda-chuva como subchart, nas mesmas condições de um chart lido do disco.
spec: capability: helm-chart source: ./charts/api-server # filesystem path to a chart directory valuesMapping: | image: "{{ .values.image }}" replicaCount: {{ optional .infra `replicas` 2 }}O chart no caminho de origem deve conter um Chart.yaml válido na sua raiz; se ele faltar, surge um erro claro antes de a cópia ser executada. A estrutura de diretórios do chart é preservada na cópia — templates/, values.yaml, Chart.yaml e quaisquer outros arquivos estão presentes no diretório do subchart após a composição. Cada arquivo chega com os bytes que você escreveu, até os comentários, a ordem das chaves e as aspas; a única exceção é o campo name do próprio Chart.yaml do chart, que o guarda-chuva define — veja “O nome do chart que pertence ao chart guarda-chuva”.
As duas maneiras de deixar de nomear um chart são recusadas, e as duas recusas vêm de lugares diferentes — vale a pena saber, porque só uma delas muda se você trocar de capacidade. Um source: presente e que mesmo assim não declara nada é recusado pelo compilador antes de qualquer provedor ser executado, então o resultado é o mesmo qualquer que seja a capacidade que a Recipe nomeie; o diagnóstico diz para você omitir o campo para o modo sem fonte ou nomear um caminho não vazio. Omitir source: por completo é uma autoria válida — é assim que uma Recipe pede o modo sem fonte — e é recusado aqui porque o helm-chart declara apenas o tipo de entrada proveniente de uma fonte, então o compilador recusa a combinação com a mesma mensagem que dá para qualquer capacidade solicitada para um tipo de entrada que ela não declara. O que é próprio do helm-chart é a declaração, não uma recusa própria: para recursos do Kubernetes gerados a partir de um bloco workload:, use a capacidade helm em vez disso.
Uma Recipe que declara omits: é recusada. A chave omits: deixa fora do build documentos que uma fonte renderiza, e este provedor não renderiza nenhum documento no momento do build: ele copia o chart para o guarda-chuva, e os templates do chart são renderizados quando o guarda-chuva é instalado. Sem nada renderizado não há nada a deixar de fora, então este provedor não declara que respeita a chave, e uma Recipe ou FeatureRecipe que a declare é recusada antes de qualquer coisa ser copiada — veja The provider does not support omits (O provedor não oferece suporte a omits). Para um chart que você mantém ao lado da Recipe, uma linha no .aggregaignore desse local deixa de fora, em vez disso, um arquivo do chart, a partir da próxima vez que a Recipe for fixada; para um chart buscado cuja saída precise perder um documento, renderize-o pelo provedor helm, que respeita a chave.
Composição indexada por caminho — a forma guarda-chuva
O provedor é executado em duas fases por caminho de montagem:
- Cópia por contribuidor. Para cada nó associado a uma Recipe helm-chart, o provedor copia a árvore de diretórios completa do chart de origem para um slot de subchart. Os arquivos ficam planos no mapa de saída por contribuidor; o montador nomeia
chartscomo o subdiretório sob o qual ficam os seus contribuidores, e o orquestrador dá a cada contribuidor um diretório próprio ali ao montar o guarda-chuva —charts/<instance_id>/para um componente. Uma vinculação de Feature também é um contribuidor — quer copie localmente um chart, quer renderize manifestos pelo provedor helm — e recebe um diretório ao lado do diretório do componente em vez de dentro dele; veja “Onde o chart de uma vinculação vai parar”. - Montagem do guarda-chuva por
(path, provider). Quando todas as cópias por nó do caminho terminam, o montador emite umChart.yaml+values.yamlguarda-chuva na raiz do caminho de montagem. O guarda-chuva declara uma dependência por nó contribuinte e encaminha os valores por nó para sub-blocos indexados por instance-id. Quando o caminho de montagem recebe contribuidores de mais de uma fronteira (fronteiras comdirectory:compartilhado), cada contribuidor entra como dependência no mesmo guarda-chuva.
O Chart.yaml guarda-chuva tem a forma:
apiVersion: v2name: <effective-chart-name> # see "Chart-name resolution" belowversion: 0.1.0description: Aggrega umbrella chart for boundary "<assembly-path>"dependencies: - name: <encoded-instance-id> # the name the placed sub-chart carries version: <user-chart-version> # from the source chart's Chart.yaml alias: <encoded-instance-id> # see "How a name is derived" below repository: file://charts/<instance_id> # the sub-chart's own directoryResolução do nome do chart
O name do chart do guarda-chuva é resolvido pela cascata de anotações das fronteiras. A anotação aggrega.ai/chart-name efetiva de cada fronteira contribuinte (o valor resolvido pela cascata, subindo pela árvore de fronteiras) determina o nome do guarda-chuva; o valor resolvido é codificado para a posição do nome do chart exatamente como qualquer outra identidade, então um valor que contenha apenas letras, dígitos, sublinhados e hifens que a regra abaixo mantém chega ao chart literalmente. Quando o caminho de montagem recebe contribuidores de mais de uma fronteira, a anotação aggrega.ai/chart-name efetiva de cada contribuidor DEVE ser resolvida para o mesmo valor; divergências interrompem o build com um diagnóstico que nomeia os valores conflitantes e as fronteiras contribuintes.
A cascata resolve naturalmente a tensão DRY: declare aggrega.ai/chart-name uma única vez na fronteira pai e as fronteiras filhas a herdam pela cascata; fronteiras irmãs sem um pai comum precisam declarar explicitamente valores correspondentes. Fronteiras que não declaram aggrega.ai/chart-name em nenhum ponto da sua cascata recorrem ao nome do agregado e ao caminho de montagem — o diretório de saída do guarda-chuva sob dist/, como boundaries/data/helm-chart —, cada um codificado e unido como descrito abaixo.
O name de cada entrada de dependência é o nome que o subchart colocado carrega — a identidade codificada da própria instância do componente, o mesmo valor do alias — pelos motivos expostos em “O nome do chart que pertence ao chart guarda-chuva”. A sua version continua sendo a versão do próprio Chart.yaml do chart de origem. O alias delimita os valores do subchart sob values.yaml.<alias>.*, de acordo com a convenção do Helm para valores de guarda-chuva, para que os valores por instância se propaguem corretamente quando o guarda-chuva é instalado.
O diretório de subchart de um componente mantém o instance_id exatamente como escrito, então charts/<instance_id>/ é onde os seus arquivos vão parar e aquilo para o qual o repository da dependência aponta. Duas instâncias do mesmo chart de origem, portanto, coexistem sem colisão no sistema de arquivos, e cada uma mantém o seu próprio bloco de valores sob o seu próprio alias.
O name da dependência e o seu repository são strings diferentes, e isso é proposital. name é o que o chart naquela localização DECLARA, porque o Helm associa uma dependência a um chart filho pelo nome declarado do próprio filho; repository é onde esse chart fica. Para um componente, os dois por acaso se leem iguais, já que ambos derivam do mesmo ID de instância. Para uma vinculação de Feature eles diferem — o nome declarado carrega a identidade composta da vinculação, enquanto o diretório carrega as suas duas coordenadas unidas —, então ler um como o outro nomeia algo que não está lá.
Onde o chart de uma vinculação vai parar
Uma vinculação de Feature que copia localmente um chart recebe um diretório próprio ao lado do componente ao qual está vinculada, um nível abaixo de charts/:
charts/├── api/ # the component's own chart├── api--guardrail/ # a Feature attached to `api` under `guardrail`└── api--audit/ # a second Feature attached to the same componentUma Feature vinculada a uma fronteira em vez de a um componente não tem componente hospedeiro para nomear, então o seu diretório é apenas o seu nome de instância: charts/aux/.
Por que ao lado e não dentro. O Helm descobre um chart filho em charts/* — um nível, não uma varredura recursiva. Um chart colocado mais fundo do que isso não é filho de nada; é um dado dentro do diretório de outro filho, alcançável apenas por .Files. Então um chart colocado dentro do próprio diretório de chart do componente seria copiado para a saída, faria o build ter sucesso e não contribuiria com nenhum dos seus recursos para o que você implanta — sem nada que o reporte. Colocar cada contribuidor no seu próprio diretório de nível superior é o que faz os recursos da vinculação serem renderizados.
O guarda-chuva também declara a vinculação como uma das suas dependências. As duas metades são necessárias: um chart presente sob charts/ e ausente de dependencies: é um erro de lint, e um chart declarado em dependencies: sem um chart filho correspondente presente faz o guarda-chuva se recusar a carregar.
As duas coordenadas são unidas, não concatenadas. Um nome de diretório é composto a partir do hospedeiro e da instância pela mesma regra de escape descrita abaixo, aplicada a cada coordenada antes de serem unidas por --. Juntá-las diretamente com -- seria ambíguo: um hospedeiro chamado a--b com uma instância c, e um hospedeiro a com uma instância b--c, chegariam a um mesmo diretório. Codificar primeiro cada coordenada as mantém separadas, de modo que um -- escrito dentro de uma coordenada aparece como -zh-.
O que o nome de diretório admite. Letras ASCII maiúsculas e minúsculas, dígitos, o ponto e o sublinhado passam como você os escreveu, então API--aux e web.api--aux se leem como você esperaria. Um hífen que você escreveu é mantido sempre que o caractere seguinte for um desses, então web-api--aux fica inalterado; um hífen duplo é escapado, porque o par é a junção. Todo o resto é escapado pela mesma regra de um nome de chart. O conjunto é delimitado assim porque esses nomes de diretório são ao mesmo tempo caminhos em disco e a localização que o ponteiro file:// de uma dependência resolve, e um caractere que serve em um nome de arquivo pode truncar uma URL ou fazê-la ser decodificada de novo.
Os valores seguem o nome declarado, não o diretório. Os valores de um chart filho são delimitados sob o nome que esse chart declara, então os valores para o chart acima são endereçados pelo nome declarado de api--guardrail — cfr-zh-api-zh-guardrail — e não pelo seu diretório.
Você mesmo nunca escreve essa chave. Você escreve os valores na vinculação, e o values.yaml do guarda-chuva é composto para você com o bloco já no endereço pelo qual o chart colocado é endereçado. Para uma Feature vinculada a um componente, são os values: que você declara na vinculação, lidos pelo próprio valuesMapping: da FeatureRecipe; para uma Feature vinculada a uma fronteira, é o infra: que você declara ali, já que uma Feature vinculada a uma fronteira não tem pilar de valores do componente. Seja qual for, o mapa para o qual o valuesMapping: se resolve se torna o próprio bloco da vinculação no guarda-chuva:
# the umbrella's values.yaml, composed for youapi: # the component's own chart replicaCount: 3cfr-zh-api-zh-guardrail: # the chart the Feature attached under `guardrail` brought auditEndpoint: "https://audit.internal"Este é o único caminho que esses valores têm. Um chart que uma Feature traz chega com os seus arquivos como o seu autor os escreveu — exceto pelo único campo do manifesto descrito em “O nome do chart que pertence ao chart guarda-chuva” —, então nada escreve os seus valores nesse chart, e é o bloco do guarda-chuva que os fornece. Um chart cujo bloco nunca chegou não é um chart quebrado: ele renderiza os valores padrão que o seu próprio values.yaml traz e reporta sucesso, então dê a um valor padrão um valor que você notaria, se quiser ver a diferença durante a autoria.
Uma vinculação cuja FeatureRecipe é renderizada por meio do provedor helm
Uma FeatureRecipe da capacidade helm, vinculada a um componente neste destino, traz manifestos do Kubernetes prontos em vez de um chart. Eles vão para o próprio diretório da vinculação exatamente como o provedor helm os renderizou, e o provedor dá a esse diretório as duas coisas que fazem dele um chart que o Helm instala: um Chart.yaml mínimo, que declara o próprio nome da vinculação na versão 0.1.0, e um único template, templates/rendered.yaml, que emite cada arquivo YAML renderizado por meio de .Files.Get do Helm pelo seu nome:
charts/api--guardrail/├── Chart.yaml # apiVersion: v2, name: cfr-zh-api-zh-guardrail, version: 0.1.0├── guardrail-config.yaml # the manifest the helm provider rendered└── templates/ └── rendered.yaml # {{ .Files.Get "guardrail-config.yaml" }}O nome declarado é aquele que um chart copiado localmente pela mesma vinculação declararia, de modo que a entrada de dependência do guarda-chuva e o seu bloco de valores são endereçados exatamente como descrito acima. .Files.Get retorna os bytes de um arquivo como estão em vez de avaliá-los uma segunda vez, então um manifesto que carrega chaves de template literais — o {{ $labels.instance }} de uma regra de alerta, a consulta de um painel — é instalado com elas intactas. Os seus valores foram resolvidos nesses manifestos quando o provedor helm os renderizou, então o bloco que o values.yaml do guarda-chuva carrega sob esse nome não é lido por nada.
O nome do chart que pertence ao chart guarda-chuva
A única coisa que o Aggrega altera dentro de um chart que você copiou localmente é o próprio campo name desse chart. No Chart.yaml do chart colocado, name é definido como a identidade codificada daquilo que contribuiu com esse chart.
Para um componente, é a própria identidade da instância do componente — o mesmo valor do alias da dependência — e a entrada de dependência do guarda-chuva também nomeia esse valor, então os dois lados sempre concordam.
Um chart que uma vinculação de Feature traz é um contribuidor por direito próprio, e declara a sua própria identidade em vez de repetir a do componente ao qual está vinculado. Essa identidade é composta a partir de duas coisas que você escreveu — o componente que hospeda a vinculação e o nome sob o qual a Feature é vinculada — atrás de um breve prefixo que a marca como identidade de uma vinculação e não de um componente; o valor composto é então escrito para a posição do nome do chart por meio da derivação abaixo, exatamente como qualquer outra identidade.
Assim, vincular uma Feature que copia localmente um chart a um componente chamado api sob o nome guardrail coloca um chart que declara cfr-zh-api-zh-guardrail, enquanto o próprio chart desse componente continua declarando api. Os dois são contribuidores separados, e cada um declara um nome próprio em vez de ambos declararem o do hospedeiro.
Nada mais no chart é alterado. Todos os outros arquivos chegam byte a byte como você os escreveu, e dentro de Chart.yaml todos os outros campos, cada comentário, a ordem das chaves e as aspas estão exatamente como foram escritos. Uma chave aninhada em outro lugar do manifesto que também se chame name — o nome de um mantenedor, por exemplo — é deixada como está.
Por que o guarda-chuva precisa desse campo. O name de um chart é aquilo a que o Helm associa uma dependência do guarda-chuva. Ele é escrito por quem criou o chart, que, para um chart obtido do upstream, não é a pessoa que o implanta — então dois componentes em um mesmo caminho de montagem podem, de forma perfeitamente razoável, copiar localmente charts cujos manifestos declaram o mesmo nome. Se os dois subcharts mantivessem esse nome compartilhado, as duas dependências do guarda-chuva seriam resolvidas para aquele dos dois que o Helm carregou primeiro: o chart de um componente seria renderizado duas vezes e o do outro nenhuma, enquanto os valores de cada componente ainda chegariam, então a saída pareceria completa e estaria errada. Derivar o nome colocado da instância do componente elimina totalmente o nome compartilhado, e é por isso que nada precisa ser recusado — incluindo os dois casos que não têm outro remédio: copiar localmente o mesmo chart sob dois componentes, em que o nome é compartilhado por construção, e copiar localmente um chart que você não escreveu, cujo nome você não pode alterar.
A única coisa que você pode observar. Um template que lê o nome do próprio chart — {{ .Chart.Name }}, e tudo o que deriva dele, como o idioma comum de nomeação de recursos {{ .Chart.Name }}-{{ .Release.Name }} — lê a identidade codificada da instância, não o nome escrito no Chart.yaml do chart de origem. É o que esse template já lia antes de o campo ser definido, porque o Helm apresenta um subchart sob o alias pelo qual o seu pai o associa; definir o campo faz o arquivo em disco concordar com o que a renderização já produzia. Assim, no exemplo prático abaixo, um template no subchart api-east lê api-east.
Se o nome de um recurso precisar carregar o nome escrito do chart, coloque esse nome no values.yaml do chart e leia-o de lá — um valor é seu e o Aggrega não o toca.
Como um nome é derivado
Um nome de chart do Helm e um alias de dependência do Helm aceitam, cada um, um conjunto de caracteres mais restrito do que um nome de agregado, um caminho de fronteira ou um instance_id podem conter. Em vez de substituir um caractere que o destino não aceita, a derivação o escreve por extenso, de modo que duas identidades que diferem apenas na pontuação sempre chegam a dois nomes — e um valor escrito sob um alias só pode chegar ao subchart que esse alias nomeia.
- Uma letra, um dígito e um sublinhado 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 de volta qualquer nome sem adivinhar. - Qualquer outro caractere é escrito como
-zseguido de uma letra que o nomeia:dpara um ponto,spara um separador de caminho,hpara um hífen que a regra acima não mantém. Todo o resto é 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 — de modo que um nome que não é texto válido ainda é escrito por extenso de forma distinta em vez de colapsado. - Um valor vazio é escrito
-ze, que nenhum valor não vazio pode produzir. - Quando duas identidades compõem um único nome de chart — um nome de agregado que qualifica um caminho de montagem — elas são unidas por
--. Uma única identidade codificada nunca contém esse par, então o nome unido diz sem ambiguidade qual identidade é qual.
Assim, um instance_id data.main-db dá o alias data-zdmain-db, e o agregado fullstack-app com o caminho de montagem boundaries/data/helm-chart dá o nome de chart fullstack-app--boundaries-zsdata-zshelm-chart. Uma entrada idêntica sempre produz o nome idêntico.
O values.yaml do guarda-chuva é indexado por alias:
api-server: # sub-chart alias = encoded instance_id image: "registry/api-server:v2" replicaCount: 3billing-svc: image: "registry/billing:v1" replicaCount: 2Quando o valuesMapping: de um subchart é avaliado em relação ao seu contexto de template, o mapa de valores resultante preenche automaticamente esse sub-bloco indexado por alias. Isso vale para todo contribuidor do guarda-chuva, não apenas para os componentes: uma vinculação de Feature que copia localmente um chart é um contribuidor por direito próprio, então o valuesMapping: da sua FeatureRecipe preenche um bloco próprio, indexado pelo nome que o seu chart colocado declara. Veja “Onde o chart de uma vinculação vai parar”.
Uma chave que o valuesMapping: define como null é escrita no seu bloco como null. Na instalação com o Helm 4, um null no próprio values.yaml do guarda-chuva remove o padrão do subchart para essa chave somente quando a instalação também fornece valores para esse subchart; uma instalação que não fornece nenhum para ele descarta o null, e o padrão do subchart prevalece. Um null nos valores passados a helm install remove o padrão em qualquer caso.
Particularidades específicas do Provider
- O
Chart.yamldo subchart é obrigatório. A operação de cópia exige a presença de umChart.yamlna raiz do caminho de origem. A sua ausência interrompe o build antes que a etapa do guarda-chuva seja executada. - O
namedo chart colocado pertence ao guarda-chuva. Ele é definido como a identidade codificada daquilo que contribuiu com o chart — a própria identidade de uma instância de componente ou, para um chart que uma vinculação de Feature traz, a própria identidade dessa vinculação — e é a única coisa dentro de um chart copiado localmente que o Aggrega altera. Veja “O nome do chart que pertence ao chart guarda-chuva”. - Um chart de origem deve declarar uma versão, e um nome. A versão da entrada de dependência é a que o próprio
Chart.yamldo chart de origem declara, então um chart que não declara nenhuma versão interrompe o build em vez de receber uma — uma dependência fixada em uma versão que o subchart não carrega deixaria os valores por instância do guarda-chuva sem conseguir alcançá-lo. Um chart cujoChart.yamlnão declara nenhum nome, contém mais de um documento YAML ou não pode ser analisado interrompe o build pelo mesmo motivo: o guarda-chuva não pode compor um subchart que não consegue ler. - Aliases e nomes de chart codificados. Um instance_id, um nome de agregado ou um caminho de fronteira que contenha um caractere que um nome de chart do Helm ou um alias de dependência não aceita aparece codificado no guarda-chuva renderizado, conforme “Como um nome é derivado” acima. Uma identidade formada apenas por letras, dígitos, sublinhados e hifens que a derivação mantém aparece exatamente como foi escrita.
- Ponteiro de repositório
file://. As entradas de dependência do guarda-chuva usam um ponteiro de repositóriofile://que nomeia o próprio diretório do chart filho —file://charts/<instance_id>para um componente, e o próprio diretório da vinculação para um chart que uma Feature traz. Essa é a convenção do sistema de arquivos local para charts filhos dentro da árvore e permite quehelm dependency buildresolva o guarda-chuva sem chamadas a registries externos. O ponteiro nomeia um local e nunca o nome declarado do chart; os dois diferem para uma vinculação, ehelm dependency buildé a etapa que recusa um ponteiro que nomeia um diretório que não existe. - Nenhuma renderização de templates no nível do helm-chart. O provedor não invoca o pipeline de renderização do SDK do Helm; ele copia e compõe. Autores que precisam de manifestos planos pré-renderizados devem usar, em vez disso, o modo com fonte do provedor helm.
Exemplo prático
Uma fronteira de dois nós, cada nó associado a uma Recipe helm-chart que aponta para o mesmo chart de origem:
# Recipe — used by both `api-east` and `api-west` instancesapiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: api-server-helmchart version: 1.0.0spec: capability: helm-chart implements: core/api-server source: ./charts/api-server valuesMapping: | image: "{{ .values.image }}" replicaCount: {{ optional .infra `replicas` 2 }}Após a composição, o caminho de montagem avaliado da fronteira (por padrão dist/<boundary-directory>/<capability>/, porque subDirectory: tem como padrão {{ .capability }}) contém:
dist/<boundary-directory>/helm-chart/├── Chart.yaml # umbrella; lists api-east and api-west as dependencies├── values.yaml # alias-keyed: api-east + api-west values blocks└── charts/ ├── api-east/ # ./charts/api-server, name: api-east │ ├── Chart.yaml │ ├── values.yaml │ └── templates/ │ └── deployment.yaml └── api-west/ # ./charts/api-server, name: api-west ├── Chart.yaml ├── values.yaml └── templates/ └── deployment.yamlOs dois subcharts são cópias do único chart de origem, e cada um carrega o nome da sua própria instância no seu Chart.yaml — que é o que permite copiar localmente um mesmo chart duas vezes em um único guarda-chuva. Todo o resto nas duas cópias é idêntico à origem.
Um helm install <release-name> dist/<boundary-directory>/helm-chart sobre essa estrutura instala as duas instâncias como uma única release do Helm, com os valores do guarda-chuva indexados por alias conduzindo os templates de cada subchart.
Referências cruzadas
providers/helm.md— provedor irmão que emite YAML do Kubernetes renderizado plano em vez de um esqueleto de chart; cuida da síntese de cargas de trabalho.entities/recipe.md— superfície de autoria da Recipe e os três tipos de entrada.entities/release.md— semântica das fronteiras da Release e diretórios de saída por fronteira.architecture/16-recipe-input-composition.md— Matriz de capacidades por Provider comum aos provedores.10-status.md#providers— classificação atual da prontidão.