Provider Helm-Chart
O fornecedor helm-chart produz um chart guarda-chuva do Helm empacotado por caminho de montagem. Enquanto o fornecedor 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 através de helm install ou copiar localmente (vendoring) para personalização adicional por ambiente. O fornecedor 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 fundem-se num único chart guarda-chuva combinado que lista cada contribuidor como dependência de subchart.
Os templates de um subchart copiados do chart de origem têm o que o seu autor escreveu: o valor syncWave: <integer> da fronteira, o helm.sh/hook-weight num hook e as etiquetas de proveniência do Aggrega só lhes chegam onde o chart os escreve. É o fornecedor helm que carimba argocd.argoproj.io/sync-wave: "<N>", helm.sh/hook-weight: "<N>" e as etiquetas de proveniência em cada recurso que renderiza. Um artefacto carregado através de $import: que este fornecedor acrescenta a um subchart tem as etiquetas de proveniência e a anotação argocd.argoproj.io/sync-wave, e nenhum helm.sh/hook-weight (consulte «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 fornecedor helm-chart. Para a divisão entre helm e helm-chart, consulte a secção Providers da página de estado; para o modelo de composição de entradas comum aos fornecedores, consulte architecture/16-recipe-input-composition.md.
Tipos de entrada suportados
O fornecedor 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, tal como está, exceto onamedo próprio chart — consulte «O nome do chart que pertence ao chart guarda-chuva»; não é efetuada nenhuma renderização nem nenhum processamento de templates ao nível de cada nó. O papel do Aggrega é a composição (a montagem do guarda-chuva entre os nós da fronteira), e não a avaliação de templates. - Modo
artifacts:carregado através de$import:. Uma Recipe com entradasartifacts:escritas como$import:por entrada declara ficheiros de template adicionais que o fornecedor helm-chart injeta no diretóriotemplates/do subchart depois da cópia do chart de origem. Cada ficheiro é pré-processado como template em relação ao contexto de template do Aggrega com os delimitadores[[ ]](consulte «Regra de injeção deartifacts:» abaixo), para que qualquer templating Helm{{ }}no mesmo ficheiro sobreviva até à renderização a jusante dohelm install.
Uma Recipe destinada ao helm-chart que declare workload: é recusada antes de ser renderizada, com a recusa que qualquer fornecedor dá a um tipo de entrada que não declara — indica o tipo que este fornecedor suporta e aponta ao autor um fornecedor 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 fornecedor não suporta o tipo de entrada do nó (nó “api”). o fornecedor “helm-chart” não suporta recipes sintetizadas (este fornecedor suporta: proveniente de uma fonte); declare um dos tipos de entrada suportados, ou aponte para um fornecedor que suporte o tipo sintetizado)
A divisão é deliberada: a síntese de cargas de trabalho (traduzir um Workload abstrato em recursos do Kubernetes) é da responsabilidade exclusiva do fornecedor 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 pode também declarar entradas artifacts: com conteúdo em linha (entradas cujo valor é um escalar de bloco que tem o corpo do ficheiro em linha na Recipe em vez de uma referência carregada através de $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 um ficheiro avulso deste tipo através de .Files.Get / .Files.Glob do Helm (o padrão canónico de ConfigMap a partir de ficheiros), pelo que um ficheiro 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, pelo que um corpo de qualquer das formas pode ler o contexto de pilares da Recipe; {{ }} em qualquer dos corpos é deixado intacto e torna-se uma diretiva Helm no momento do helm install a jusante. O que difere entre as formas é onde o ficheiro vai parar e se a proveniência é fundida nele:
- Uma entrada carregada através de
$import:é um ficheiro de template: após a avaliação (consulte «Regra de injeção deartifacts:» abaixo), é injetada no diretóriotemplates/do subchart com a proveniência fundida, 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 ficheiro de dados avulso: após a avaliação, vai parar à raiz do chart, inalterada em relação ao que a avaliação produziu e sem proveniência fundida, para consumo baseado em
.Files.
Regra de injeção de artifacts:
Quando uma Recipe helm-chart declara entradas artifacts: através de $import: por entrada, cada valor $import: é o caminho para um ficheiro 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 fornecedor:
- Lê o conteúdo de cada ficheiro.
- 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 ficheiro é deixado intacto — essas expressões tornam-se diretivas de template Helm no momento dohelm install. - Escreve cada ficheiro em
charts/<instance-id>/templates/<authored-key>sob o caminho de montagem do guarda-chuva, com os ficheiros de um bundle aninhados sob essa chave. A chave sob a qual a entrada é escrita dá nome ao ficheiro; o caminho de$import:seleciona o seu conteúdo e não contribui em nada para o nome, pelo que a estrutura de diretórios dentro desse caminho nunca chega à saída.
A disciplina do duplo delimitador [[ ]] / {{ }} é o pormenor essencial. Um ficheiro de artefacto típico carregado através de $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 ficheiro ser colocado; o Helm resolve {{ }} em tempo de instalação, depois de o guarda-chuva ser entregue.
As colisões de nomes de ficheiros entre os templates do chart de origem e as injeções de artefactos carregados através de $import: geram CATALOG_ERROR — o diagnóstico indica 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 mudando o nome da chave do artefacto ou do próprio template do chart.
Conjunto de chaves de source:
O source: do fornecedor helm-chart indica um chart e aceita as duas formas que o campo source: assume, lidas exatamente como as descreve o conjunto de chaves de source: do fornecedor helm: uma cadeia simples de caminho do sistema de ficheiros e um objeto estruturado cujo url: indica a localização. Onde url: indica um caminho do sistema de ficheiros, nada é obtido e o chart é lido do disco; onde indica um esquema de transporte — oci://…, por exemplo, com kind: helm-oci-chart — aggrega pull obtém e fixa o chart, e a compilação copia-o da 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 tem de conter um Chart.yaml válido na sua raiz; se 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 ficheiros estão presentes no diretório do subchart após a composição. Cada ficheiro chega com os bytes que escreveu, até aos comentários, à ordem das chaves e às aspas; a única exceção é o campo name do próprio Chart.yaml do chart, que o guarda-chuva define — consulte «O nome do chart que pertence ao chart guarda-chuva».
As duas formas de não indicar um chart são recusadas, e as duas recusas vêm de sítios diferentes — convém sabê-lo, porque só uma delas muda se mudar de capacidade. Um source: presente e que, no entanto, não declara nada é recusado pelo compilador antes de qualquer fornecedor ser executado, pelo que o resultado é o mesmo seja qual for a capacidade que a Recipe indique; o diagnóstico indica que deve omitir o campo para o modo sem fonte ou indicar 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, pelo que o compilador recusa a combinação com a mesma mensagem que dá para qualquer capacidade pedida para um tipo de entrada que ela não declara. O que é próprio do helm-chart é a declaração, e não uma recusa própria: para recursos do Kubernetes gerados a partir de um bloco workload:, utilize antes a capacidade helm.
Uma Recipe que declare omits: é recusada. A chave omits: deixa de fora da compilação documentos que uma origem renderiza, e este fornecedor não renderiza nenhum documento no momento da compilação: 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, pelo que este fornecedor não declara que respeita a chave, e uma Recipe ou FeatureRecipe que a declare é recusada antes de ser copiado o que quer que seja — consulte The provider does not support omits (O fornecedor não suporta omits). Para um chart que mantém ao lado da Recipe, uma linha no .aggregaignore desse local deixa de fora, em alternativa, um ficheiro do chart, a partir da próxima vez que a Recipe for fixada; para um chart obtido cuja saída tenha de perder um documento, renderize-o através do fornecedor helm, que respeita a chave.
Composição indexada por caminho — a forma guarda-chuva
O fornecedor é executado em duas fases por caminho de montagem:
- Cópia por contribuidor. Para cada nó associado a uma Recipe helm-chart, o fornecedor copia a árvore de diretórios completa do chart de origem para um slot de subchart. Os ficheiros ficam planos no mapa de saída por contribuidor; o montador indica
chartscomo o subdiretório sob o qual ficam os seus contribuidores, e o orquestrador dá a cada contribuidor um diretório próprio aí ao montar o guarda-chuva —charts/<instance_id>/para um componente. Um anexo de Feature é também um contribuidor — quer copie localmente um chart, quer renderize manifestos através do fornecedor helm — e recebe um diretório ao lado do diretório do componente em vez de dentro dele; consulte «Onde vai parar o chart de um anexo». - 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:partilhado), cada contribuidor fica 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 através da 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, pelo que um valor que contenha apenas letras, dígitos, sublinhados e hífenes que a regra abaixo mantém chega ao chart tal como está. Quando o caminho de montagem recebe contribuidores de mais de uma fronteira, a anotação aggrega.ai/chart-name efetiva de cada contribuidor TEM DE ser resolvida para o mesmo valor; as divergências interrompem a compilação com um diagnóstico que indica os valores em conflito 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 herdam-na através da cascata; fronteiras irmãs sem um pai comum têm de declarar explicitamente valores correspondentes. As 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 tem — 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 a ser 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 do 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 foi escrito, pelo que charts/<instance_id>/ é onde os seus ficheiros vão parar e aquilo para que aponta o repository da dependência. Duas instâncias do mesmo chart de origem coexistem, portanto, sem colisão no sistema de ficheiros, 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 cadeias diferentes, e isso é propositado. name é o que o chart nessa 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 se encontra. Para um componente, os dois por acaso leem-se da mesma forma, já que ambos derivam do mesmo ID de instância. Para um anexo de Feature diferem — o nome declarado tem a identidade composta do anexo, enquanto o diretório tem as suas duas coordenadas unidas —, pelo que ler um como o outro indica algo que não existe.
Onde vai parar o chart de um anexo
Um anexo de Feature que copia localmente um chart recebe um diretório próprio ao lado do componente ao qual está anexado, 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 anexada a uma fronteira em vez de a um componente não tem componente anfitrião a indicar, pelo que o seu diretório é apenas o seu nome de instância: charts/aux/.
Porquê ao lado e não dentro. O Helm descobre um chart filho em charts/* — um nível, não um percurso recursivo. Um chart colocado a maior profundidade não é filho de nada; é um dado dentro do diretório de outro filho, acessível apenas através de .Files. Assim, um chart colocado dentro do próprio diretório de chart do componente seria copiado para a saída, faria a compilação ter êxito e não contribuiria com nenhum dos seus recursos para aquilo que implementa — sem que nada o assinale. Colocar cada contribuidor no seu próprio diretório de nível superior é o que faz com que os recursos do anexo sejam renderizados.
O guarda-chuva declara também o anexo 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 com que o guarda-chuva se recuse a carregar.
As duas coordenadas são unidas, não concatenadas. Um nome de diretório é composto a partir do anfitrião e da instância através da mesma regra de escape descrita abaixo, aplicada a cada coordenada antes de serem unidas por --. Juntá-las diretamente com -- seria ambíguo: um anfitrião chamado a--b com uma instância c, e um anfitrião a com uma instância b--c, chegariam a um mesmo diretório. Codificar primeiro cada coordenada mantém-nas separadas, pelo 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 final e o sublinhado passam tal como os escreveu, pelo que API--aux e web.api--aux se leem como seria de esperar. Um hífen que escreveu é mantido sempre que o carácter seguinte for um desses, pelo que web-api--aux fica inalterado; um hífen duplo é escapado, porque o par é a junção. Tudo o resto é escapado pela mesma regra de um nome de chart. O conjunto é delimitado assim porque estes 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 carácter aceitável num nome de ficheiro pode truncar um URL ou fazer com que seja descodificado 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, pelo que 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.
Nunca escreve essa chave pessoalmente. Escreve os valores no anexo, e o values.yaml do guarda-chuva é composto automaticamente com o bloco já no endereço pelo qual o chart colocado é endereçado. Para uma Feature anexada a um componente, são os values: que declara no anexo, lidos pelo próprio valuesMapping: da FeatureRecipe; para uma Feature anexada a uma fronteira, é o infra: que declara aí, já que uma Feature anexada a uma fronteira não tem pilar de valores do componente. Seja qual for, o mapa para o qual o valuesMapping: se resolve torna-se o próprio bloco do anexo 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 ficheiros tal como o seu autor os escreveu — exceto o único campo do manifesto descrito em «O nome do chart que pertence ao chart guarda-chuva» —, pelo que 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 avariado: renderiza os valores predefinidos que o seu próprio values.yaml traz e reporta sucesso, pelo que convém dar a um valor predefinido um valor que se note, se quiser ver a diferença durante a autoria.
Um anexo cuja FeatureRecipe é renderizada através do fornecedor helm
Uma FeatureRecipe da capacidade helm, anexada a um componente neste destino, traz manifestos do Kubernetes acabados em vez de um chart. Vão parar ao próprio diretório do anexo exatamente como o fornecedor helm os renderizou, e o fornecedor 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 do anexo na versão 0.1.0, e um único template, templates/rendered.yaml, que emite cada ficheiro YAML renderizado através 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 é o que declararia um chart copiado localmente pelo mesmo anexo, pelo 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 devolve os bytes de um ficheiro tal como estão em vez de os avaliar uma segunda vez, pelo que um manifesto que contém chavetas 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 fornecedor helm os renderizou, pelo que o bloco que o values.yaml do guarda-chuva tem 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 copiado 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 que o alias da dependência — e a entrada de dependência do guarda-chuva também indica esse valor, pelo que os dois lados concordam sempre.
Um chart que um anexo de Feature traz é um contribuidor de pleno direito, e declara a sua própria identidade em vez de repetir a do componente ao qual está anexado. Essa identidade é composta a partir de duas coisas escritas pelo autor — o componente que acolhe o anexo e o nome sob o qual a Feature é anexada — atrás de um breve prefixo que a marca como identidade de um anexo e não de um componente; o valor composto é depois escrito para a posição do nome do chart através da derivação abaixo, exatamente como qualquer outra identidade.
Assim, anexar 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 a declarar api. Os dois são contribuidores separados, e cada um declara um nome próprio em vez de ambos declararem o do anfitrião.
Nada mais no chart é alterado. Todos os outros ficheiros chegam byte a byte tal como foram escritos, 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 noutro ponto do manifesto que também se chame name — o nome de um responsável pela manutenção, por exemplo — é deixada como está.
Porque é que o guarda-chuva precisa desse campo. O name de um chart é aquilo a que o Helm associa uma dependência do guarda-chuva. É escrito por quem criou o chart, que, para um chart obtido a montante, não é a pessoa que o implementa — pelo que dois componentes num 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 partilhado, 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 continuariam a chegar, pelo que a saída pareceria completa e estaria errada. Derivar o nome colocado da instância do componente elimina totalmente o nome partilhado, e é por isso que nada tem de 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 é partilhado por construção, e copiar localmente um chart que não foi escrito por si, cujo nome não pode alterar.
A única coisa que é possível observar. Um template que lê o nome do próprio chart — {{ .Chart.Name }}, e tudo o que dele deriva, como o idioma comum de atribuição de nomes a recursos {{ .Chart.Name }}-{{ .Release.Name }} — lê a identidade codificada da instância, e 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 ficheiro 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 tiver de conter o nome escrito do chart, coloque esse nome no values.yaml do chart e leia-o a partir daí — um valor pertence ao autor e o Aggrega não lhe toca.
Como é derivado um nome
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 aquele que um nome de agregado, um caminho de fronteira ou um instance_id podem conter. Em vez de substituir um carácter que o destino não aceita, a derivação escreve-o por extenso, pelo que duas identidades que diferem apenas na pontuação chegam sempre a dois nomes — e um valor escrito sob um alias só pode chegar ao subchart que esse alias indica.
- Uma letra, um dígito e um sublinhado são mantidos exatamente como foram escritos.
- Um hífen é mantido tal como foi escrito sempre que o carácter a seguir a ele é mantido diretamente e não é um
zminúsculo. Um hífen seguido de umzminúsculo abre uma sequência de escape, pelo que um hífen escrito nessa posição é ele próprio escrito por extenso —api-zonepassa aapi-zhzone, o que permite ler de volta qualquer nome sem adivinhar. - Qualquer outro carácter é escrito como
-zseguido de uma letra que o identifica:dpara um ponto,spara um separador de caminho,hpara um hífen que a regra acima não mantém. Tudo o resto é escrito comoxe o ponto de código hexadecimal de seis dígitos do carácter, e um byte que não inicia nenhum carácter comobe o seu próprio valor de dois dígitos — pelo que um nome que não é texto válido continua a ser escrito por extenso de forma distinta em vez de ser 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 — são unidas por
--. Uma única identidade codificada nunca contém esse par, pelo que o nome unido indica 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 produz sempre 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 este sub-bloco indexado por alias. Isto vale para todos os contribuidores do guarda-chuva, e não apenas para os componentes: um anexo de Feature que copia localmente um chart é um contribuidor de pleno direito, pelo que o valuesMapping: da sua FeatureRecipe preenche um bloco próprio, indexado pelo nome que o seu chart colocado declara. Consulte «Onde vai parar o chart de um anexo».
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 só remove o valor predefinido do subchart para essa chave quando a instalação também fornece valores para esse subchart; uma instalação que não forneça nenhum para ele descarta o null, e o valor predefinido do subchart mantém-se. Um null nos valores passados a helm install remove o valor predefinido 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 a compilação antes de a etapa do guarda-chuva ser executada. - O
namedo chart colocado pertence ao guarda-chuva. É 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 um anexo de Feature traz, a própria identidade desse anexo — e é a única coisa dentro de um chart copiado localmente que o Aggrega altera. Consulte «O nome do chart que pertence ao chart guarda-chuva». - Um chart de origem tem de 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, pelo que um chart que não declara nenhuma versão interrompe a compilação em vez de lhe ser atribuída uma — uma dependência fixada numa versão que o subchart não tem 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 a compilação 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 carácter que um nome de chart do Helm ou um alias de dependência não aceita aparece codificado no guarda-chuva renderizado, conforme «Como é derivado um nome» acima. Uma identidade formada apenas por letras, dígitos, sublinhados e hífenes 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 indica o próprio diretório do chart filho —file://charts/<instance_id>para um componente, e o próprio diretório do anexo para um chart que uma Feature traz. Esta é a convenção do sistema de ficheiros local para charts filhos dentro da árvore e permite quehelm dependency buildresolva o guarda-chuva sem chamadas a registos externos. O ponteiro indica uma localização e nunca o nome declarado do chart; os dois diferem para um anexo, ehelm dependency buildé a etapa que recusa um ponteiro que indica um diretório que não existe. - Nenhuma renderização de templates ao nível do helm-chart. O fornecedor não invoca o pipeline de renderização do SDK do Helm; copia e compõe. Os autores que precisem de manifestos planos pré-renderizados devem usar, em vez disso, o modo com fonte do fornecedor 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 predefinição dist/<boundary-directory>/<capability>/, porque subDirectory: tem como valor predefinido {{ .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 tem o nome da sua própria instância no seu Chart.yaml — o que permite copiar localmente um mesmo chart duas vezes num único guarda-chuva. Tudo o resto nas duas cópias é idêntico à origem.
Um helm install <release-name> dist/<boundary-directory>/helm-chart sobre esta estrutura instala as duas instâncias como uma única release do Helm, com os valores do guarda-chuva indexados por alias a conduzir os templates de cada subchart.
Referências cruzadas
providers/helm.md— fornecedor irmão que emite YAML do Kubernetes renderizado plano em vez de um esqueleto de chart; trata 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 de Provider comum aos fornecedores.10-status.md#providers— classificação atual da prontidão.