Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

Provider Helm-Chart

Le fournisseur helm-chart produit un chart parapluie Helm empaqueté par chemin d’assemblage. Là où le fournisseur helm émet du YAML Kubernetes plat destiné à une consommation directe par GitOps, helm-chart émet un squelette de chart — un Chart.yaml + values.yaml parapluie plus un sous-chart par nœud contributeur — que l’outillage en aval peut installer via helm install ou copier localement (vendoring) pour une personnalisation supplémentaire par environnement. Le fournisseur assemble par (path, provider) : chaque nœud lié à une Recipe helm-chart contribue au parapluie au directory: évalué de la frontière joint au subDirectory: de chaque composant. Deux frontières qui s’évaluent au même chemin se fondent en un seul chart parapluie fusionné qui liste chaque contributeur comme dépendance de sous-chart.

Les templates d’un sous-chart copiés depuis le chart source portent ce que leur auteur a écrit : la valeur syncWave: <integer> de la frontière, le helm.sh/hook-weight d’un hook et les labels de provenance d’Aggrega ne les atteignent que là où le chart les écrit. C’est le fournisseur helm qui appose argocd.argoproj.io/sync-wave: "<N>", helm.sh/hook-weight: "<N>" et les labels de provenance sur chaque ressource qu’il rend. Un artefact chargé via $import: que ce fournisseur ajoute à un sous-chart porte les labels de provenance et l’annotation argocd.argoproj.io/sync-wave, et aucun helm.sh/hook-weight (voir « Règle d’injection de artifacts: » ci-dessous). ArgoCD lit l’annotation sync-wave, et Helm lit le poids d’un hook.

Cette page est la référence de rédaction du fournisseur helm-chart. Pour la séparation entre helm et helm-chart, voir la section Providers de la page d’état ; pour le modèle de composition des entrées commun aux fournisseurs, voir architecture/16-recipe-input-composition.md.

Types d’entrée pris en charge

Le fournisseur helm-chart accepte deux types d’entrée :

  • Mode issu d’une source. Une Recipe avec source: <chart-path> pointe vers un répertoire de chart Helm sur disque. Le chart est copié dans la structure parapluie en tant que sous-chart, à l’identique à l’exception du propre name du chart — voir « Le nom de chart qui revient au chart parapluie » ; aucun rendu ni aucun traitement de template n’est effectué au niveau de chaque nœud. Le rôle d’Aggrega est la composition (l’assemblage du parapluie à travers les nœuds de la frontière), et non l’évaluation de templates.
  • Mode artifacts: chargé via $import:. Une Recipe avec des entrées artifacts: rédigées entrée par entrée sous forme de $import: déclare des fichiers de template supplémentaires que le fournisseur helm-chart injecte dans le répertoire templates/ du sous-chart après la copie du chart source. Chaque fichier est pré-traité comme template avec le contexte de template d’Aggrega à l’aide des délimiteurs [[ ]] (voir « Règle d’injection de artifacts: » ci-dessous), de sorte que tout templating Helm {{ }} dans le même fichier survit jusqu’au rendu en aval par helm install.

Une Recipe ciblant helm-chart qui déclare workload: est refusée avant son rendu, avec le refus que tout fournisseur oppose à un type d’entrée qu’il ne déclare pas — il nomme le type que ce fournisseur prend en charge et oriente l’auteur vers un fournisseur qui synthétise :

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 (le fournisseur ne prend pas en charge le type d’entrée du nœud (nœud “api”). le fournisseur “helm-chart” ne prend pas en charge les recipes synthétisées (ce fournisseur prend en charge : issu d’une source) ; déclarez l’un des types d’entrée pris en charge, ou ciblez un fournisseur qui prend en charge le type synthétisé)

La séparation est délibérée : la synthèse des charges de travail (la traduction d’un Workload abstrait en ressources Kubernetes) relève exclusivement du fournisseur helm. Le rôle de helm-chart est la composition parapluie + sous-charts pour des charts que l’auteur a déjà produits.

Une Recipe ciblant helm-chart peut aussi déclarer des entrées artifacts: à contenu en ligne (entrées dont la valeur est un scalaire de bloc portant le corps du fichier en ligne dans la Recipe plutôt qu’une référence chargée via $import:). Une entrée à contenu en ligne est placée à la racine du sous-chart sous sa clé rédigée — pas de préfixe templates/ ni d’insertion de provenance. Les propres templates d’un chart lisent un tel fichier isolé au moyen de .Files.Get / .Files.Glob de Helm (le modèle canonique de ConfigMap à partir de fichiers), de sorte qu’un fichier à la racine du chart est une forme légitime et de premier plan plutôt qu’une erreur.

Les deux formes sont évaluées avec les délimiteurs [[ ]] d’Aggrega avant leur placement, de sorte qu’un corps de l’une ou l’autre forme peut lire le contexte des piliers de la Recipe ; {{ }} dans l’un ou l’autre corps est laissé intact et devient une directive Helm au moment du helm install en aval. Ce qui diffère entre les formes, c’est l’endroit où le fichier aboutit et si la provenance y est fusionnée :

  • Une entrée chargée via $import: est un fichier de template : après évaluation (voir « Règle d’injection de artifacts: » ci-dessous), elle est injectée dans le répertoire templates/ du sous-chart avec la provenance fusionnée, de sorte que Helm la rend comme un manifeste à côté des propres templates du chart.
  • Une entrée à contenu en ligne est un fichier de données isolé : après évaluation, elle aboutit à la racine du chart, inchangée par rapport à ce que l’évaluation a produit et sans provenance fusionnée, pour une consommation basée sur .Files.

Règle d’injection de artifacts:

Lorsqu’une Recipe helm-chart déclare des entrées artifacts: via $import: entrée par entrée, chaque valeur $import: est le chemin d’un fichier de template résolu relativement au propre répertoire de la Recipe (le répertoire contenant le YAML de la Recipe sur disque). Le fournisseur :

  1. Lit le contenu de chaque fichier.
  2. Pré-traite le contenu comme template avec les délimiteurs d’Aggrega [[ ]] par rapport au contexte de template de la Recipe (le même contexte par rapport auquel le valuesMapping: de la Recipe est évalué). {{ }} dans le contenu du fichier est laissé intact — ces expressions deviennent des directives de template Helm au moment du helm install.
  3. Écrit chaque fichier dans charts/<instance-id>/templates/<authored-key> sous le chemin d’assemblage du parapluie, les fichiers d’un bundle étant imbriqués sous cette clé. La clé sous laquelle l’entrée est rédigée nomme le fichier ; le chemin $import: sélectionne son contenu et ne contribue en rien au nom, de sorte que la structure de répertoires à l’intérieur de ce chemin n’atteint jamais la sortie.

La discipline du double délimiteur [[ ]] / {{ }} est le détail porteur. Un fichier d’artefact typique chargé via $import: peut mélanger une interpolation au temps d’Aggrega (par ex. [[ .values.image ]]) avec une interpolation au temps de Helm (par ex. {{ .Release.Namespace }}). Chaque paire de délimiteurs agit dans sa propre phase : Aggrega résout [[ ]] à la compilation, avant que le fichier n’aboutisse ; Helm résout {{ }} à l’installation, après la livraison du parapluie.

Les collisions de noms de fichiers entre les templates du chart source et les injections d’artefacts chargés via $import: déclenchent CATALOG_ERROR — le diagnostic nomme le chemin de sortie en collision, tel que templates/cm.yaml, et les deux types d’entrée qui l’ont produit. Les auteurs résolvent la collision en renommant la clé de l’artefact ou le propre template du chart.

Jeu de clés de source:

Le source: du fournisseur helm-chart nomme un chart, et il accepte les deux formes que prend le champ source:, lues exactement comme le décrit le jeu de clés de source: du fournisseur helm : une simple chaîne de chemin du système de fichiers et un objet structuré dont le url: porte l’emplacement. Là où url: nomme un chemin du système de fichiers, rien n’est récupéré et le chart est lu depuis le disque ; là où il porte un schéma de transport — oci://…, par exemple, avec kind: helm-oci-chart — aggrega pull récupère et épingle le chart, et le build le copie depuis le cache dans le parapluie en tant que sous-chart, aux mêmes conditions qu’un chart lu depuis le disque.

spec:
capability: helm-chart
source: ./charts/api-server # filesystem path to a chart directory
valuesMapping: |
image: "{{ .values.image }}"
replicaCount: {{ optional .infra `replicas` 2 }}

Le chart situé au chemin source doit contenir un Chart.yaml valide à sa racine ; s’il manque, une erreur claire apparaît avant que la copie ne s’exécute. L’arborescence de répertoires du chart est préservée lors de la copie — templates/, values.yaml, Chart.yaml et tous les autres fichiers sont présents dans le répertoire du sous-chart après la composition. Chaque fichier arrive avec les octets que vous avez écrits, jusqu’aux commentaires, à l’ordre des clés et aux guillemets ; la seule exception est le champ name du propre Chart.yaml du chart, que le parapluie définit — voir « Le nom de chart qui revient au chart parapluie ».

Les deux façons de ne pas nommer de chart sont refusées, et les deux refus viennent d’endroits différents — bon à savoir, car un seul d’entre eux change si vous changez de capacité. Un source: présent et qui pourtant ne déclare rien est refusé par le compilateur avant l’exécution de tout fournisseur, de sorte que le résultat est le même quelle que soit la capacité que la Recipe nomme ; le diagnostic vous indique d’omettre le champ pour le mode sans source ou de nommer un chemin non vide. Omettre complètement source: est une rédaction valide — c’est ainsi qu’une Recipe demande le mode sans source — et c’est refusé ici parce que helm-chart ne déclare que le type d’entrée issu d’une source, de sorte que le compilateur refuse la combinaison avec le même message qu’il donne pour toute capacité demandée pour un type d’entrée qu’elle ne déclare pas. Ce qui est propre à helm-chart, c’est la déclaration, pas un refus qui lui serait propre : pour des ressources Kubernetes générées à partir d’un bloc workload:, utilisez plutôt la capacité helm.

Une Recipe déclarant omits: est refusée. La clé omits: laisse hors du build des documents qu’une source rend, et ce fournisseur ne rend aucun document au moment du build : il copie le chart dans le parapluie, et les templates du chart sont rendus lorsque le parapluie est installé. Comme rien n’est rendu, il n’y a rien à laisser de côté, donc ce fournisseur ne déclare pas qu’il respecte la clé, et une Recipe ou une FeatureRecipe qui la déclare est refusée avant que quoi que ce soit ne soit copié — voir The provider does not support omits (Le fournisseur ne prend pas en charge omits). Pour un chart que vous conservez à côté de la Recipe, une ligne dans le .aggregaignore qui s’y trouve laisse plutôt de côté un fichier du chart, à partir du prochain épinglage de la Recipe ; pour un chart récupéré dont la sortie doit perdre un document, rendez-le via le fournisseur helm, qui respecte la clé.

Composition indexée par chemin — la forme parapluie

Le fournisseur s’exécute en deux phases par chemin d’assemblage :

  1. Copie par contributeur. Pour chaque nœud lié à une Recipe helm-chart, le fournisseur copie l’arborescence complète du chart source dans un slot de sous-chart. Les fichiers aboutissent à plat dans la table de sortie par contributeur ; l’assembleur nomme charts comme le sous-répertoire sous lequel se trouvent ses contributeurs, et l’orchestrateur donne à chaque contributeur un répertoire qui lui est propre à cet endroit lors de l’assemblage du parapluie — charts/<instance_id>/ pour un composant. Un rattachement de Feature est aussi un contributeur — qu’il copie localement un chart ou qu’il rende des manifestes via le fournisseur helm — et obtient un répertoire à côté de celui du composant plutôt qu’à l’intérieur ; voir « Où aboutit le chart d’un rattachement ».
  2. Assemblage du parapluie par (path, provider). Une fois toutes les copies par nœud du chemin terminées, l’assembleur émet un Chart.yaml + values.yaml parapluie à la racine du chemin d’assemblage. Le parapluie déclare une dépendance par nœud contributeur et achemine les valeurs par nœud sous des sous-blocs indexés par instance-id. Lorsque le chemin d’assemblage reçoit des contributeurs de plus d’une frontière (frontières avec un directory: partagé), chaque contributeur aboutit comme dépendance dans le même parapluie.

Le Chart.yaml parapluie a la forme :

apiVersion: v2
name: <effective-chart-name> # see "Chart-name resolution" below
version: 0.1.0
description: 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 directory

Résolution du nom de chart

Le name du chart parapluie est résolu au moyen de la cascade d’annotations des frontières. L’annotation aggrega.ai/chart-name effective de chaque frontière contributrice (la valeur résolue par la cascade, en remontant l’arbre des frontières) détermine le nom du parapluie ; la valeur résolue est encodée pour la position du nom de chart exactement comme toute autre identité, de sorte qu’une valeur ne comportant que des lettres, des chiffres, des traits de soulignement et des tirets que la règle ci-dessous conserve atteint le chart telle quelle. Lorsque le chemin d’assemblage reçoit des contributeurs de plus d’une frontière, l’annotation aggrega.ai/chart-name effective de chaque contributeur DOIT se résoudre en la même valeur ; les divergences arrêtent le build avec un diagnostic nommant les valeurs en conflit et les frontières contributrices.

La cascade résout naturellement la tension DRY : déclarez aggrega.ai/chart-name une seule fois sur la frontière parente et les frontières enfants en héritent via la cascade ; des frontières sœurs sans parent commun doivent déclarer explicitement des valeurs concordantes. Les frontières qui ne déclarent aggrega.ai/chart-name nulle part dans leur cascade se rabattent sur le nom de l’agrégat et sur le chemin d’assemblage — le répertoire de sortie du parapluie sous dist/, tel que boundaries/data/helm-chart — chacun encodé et joint comme décrit ci-dessous.

Le name de chaque entrée de dépendance est le nom que porte le sous-chart placé — l’identité encodée propre de l’instance de composant, la même valeur que l’alias — pour les raisons exposées dans « Le nom de chart qui revient au chart parapluie ». Sa version reste la version issue du propre Chart.yaml du chart source. L’alias délimite les valeurs du sous-chart sous values.yaml.<alias>.*, conformément à la convention de Helm pour les valeurs parapluie, de sorte que les valeurs par instance se propagent correctement lorsque le parapluie est installé.

Le répertoire de sous-chart d’un composant conserve l’instance_id exactement tel qu’il a été rédigé, de sorte que charts/<instance_id>/ est l’endroit où ses fichiers aboutissent et ce vers quoi pointe le repository de la dépendance. Deux instances du même chart source coexistent donc sans collision dans le système de fichiers, et chacune conserve son propre bloc de valeurs sous son propre alias.

Le name de la dépendance et son repository sont des chaînes différentes, et c’est voulu. name est ce que le chart à cet emplacement DÉCLARE, car Helm lie une dépendance à un chart enfant par le nom déclaré de l’enfant lui-même ; repository est l’endroit où se trouve ce chart. Pour un composant, les deux se trouvent se lire pareillement, puisqu’ils dérivent tous deux du même identifiant d’instance. Pour un rattachement de Feature, ils diffèrent — le nom déclaré porte l’identité composée du rattachement tandis que le répertoire porte ses deux coordonnées jointes — de sorte que lire l’un comme l’autre nomme quelque chose qui n’existe pas.

Où aboutit le chart d’un rattachement

Un rattachement de Feature qui copie localement un chart obtient un répertoire qui lui est propre à côté du composant auquel il est rattaché, un niveau sous 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 component

Une Feature rattachée à une frontière plutôt qu’à un composant n’a pas de composant hôte à nommer, donc son répertoire est son seul nom d’instance : charts/aux/.

Pourquoi à côté plutôt qu’à l’intérieur. Helm découvre un chart enfant dans charts/* — un niveau, pas un parcours récursif. Un chart placé plus profondément n’est l’enfant de rien ; c’est une donnée à l’intérieur du répertoire d’un autre enfant, accessible uniquement via .Files. Ainsi, un chart placé à l’intérieur du propre répertoire de chart du composant serait copié dans la sortie, ferait réussir le build et n’apporterait aucune de ses ressources à ce que vous déployez — sans que rien ne le signale. Placer chaque contributeur dans son propre répertoire de premier niveau est ce qui fait que les ressources du rattachement sont rendues.

Le parapluie déclare aussi le rattachement comme l’une de ses dépendances. Les deux moitiés sont nécessaires : un chart présent sous charts/ et absent de dependencies: est une erreur de lint, et un chart déclaré dans dependencies: sans chart enfant correspondant présent fait que le parapluie refuse de se charger.

Les deux coordonnées sont jointes, pas concaténées. Un nom de répertoire est composé à partir de l’hôte et de l’instance au moyen de la même règle d’échappement décrite ci-dessous, appliquée à chaque coordonnée avant qu’elles ne soient jointes par --. Les accoler directement avec -- serait ambigu : un hôte nommé a--b avec une instance c, et un hôte a avec une instance b--c, aboutiraient au même répertoire. Encoder d’abord chaque coordonnée les maintient distinctes, de sorte qu’un -- rédigé à l’intérieur d’une coordonnée apparaît comme -zh-.

Ce que le nom de répertoire admet. Les lettres ASCII dans les deux casses, les chiffres, le point et le trait de soulignement passent tels que vous les avez écrits, de sorte que API--aux et web.api--aux se lisent comme vous vous y attendez. Un tiret que vous avez écrit est conservé partout où le caractère qui le suit est l’un de ceux-ci, de sorte que web-api--aux reste inchangé ; un double tiret est échappé, car la paire est la jonction. Tout le reste est échappé selon la même règle qu’un nom de chart. L’ensemble est délimité ainsi parce que ces noms de répertoire sont à la fois des chemins sur disque et l’emplacement que résout le pointeur file:// d’une dépendance, et qu’un caractère acceptable dans un nom de fichier peut tronquer une URL ou la faire redécoder.

Les valeurs suivent le nom déclaré, pas le répertoire. Les valeurs d’un chart enfant sont délimitées sous le nom que ce chart déclare, de sorte que les valeurs du chart ci-dessus sont adressées par le nom déclaré de api--guardrail — cfr-zh-api-zh-guardrail — plutôt que par son répertoire.

Vous n’écrivez jamais cette clé vous-même. Vous écrivez les valeurs sur le rattachement, et le values.yaml du parapluie est composé pour vous avec le bloc déjà à l’adresse par laquelle le chart placé est adressé. Pour une Feature rattachée à un composant, il s’agit des values: que vous déclarez sur le rattachement, lues par le propre valuesMapping: de la FeatureRecipe ; pour une Feature rattachée à une frontière, il s’agit de l’infra: que vous y déclarez, puisqu’une Feature rattachée à une frontière n’a pas de pilier de valeurs de composant. Quel qu’il soit, la table en laquelle se résout le valuesMapping: devient le propre bloc du rattachement dans le parapluie :

# the umbrella's values.yaml, composed for you
api: # the component's own chart
replicaCount: 3
cfr-zh-api-zh-guardrail: # the chart the Feature attached under `guardrail` brought
auditEndpoint: "https://audit.internal"

C’est la seule voie qu’ont ces valeurs. Un chart qu’apporte une Feature arrive avec ses fichiers tels que son auteur les a écrits — à l’exception de l’unique champ du manifeste décrit dans « Le nom de chart qui revient au chart parapluie » — donc rien n’écrit vos valeurs dans ce chart, et c’est le bloc du parapluie qui les fournit. Un chart dont le bloc n’est jamais arrivé n’est pas un chart cassé : il rend les valeurs par défaut que livre son propre values.yaml et signale un succès, donc donnez à une valeur par défaut une valeur que vous remarqueriez si vous voulez voir la différence pendant la rédaction.

Un rattachement dont la FeatureRecipe effectue le rendu via le fournisseur helm

Une FeatureRecipe de la capacité helm, rattachée à un composant sur cette cible, apporte des manifestes Kubernetes finis plutôt qu’un chart. Ils aboutissent dans le propre répertoire du rattachement exactement tels que le fournisseur helm les a rendus, et le fournisseur donne à ce répertoire les deux éléments qui en font un chart que Helm installe : un Chart.yaml minimal, qui déclare le propre nom du rattachement à la version 0.1.0, et un seul template, templates/rendered.yaml, qui émet chaque fichier YAML rendu au moyen de .Files.Get de Helm d’après son nom :

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" }}

Le nom déclaré est celui que déclarerait un chart copié localement par le même rattachement, de sorte que l’entrée de dépendance du parapluie et son bloc de valeurs sont adressés exactement comme décrit ci-dessus. .Files.Get renvoie les octets d’un fichier tels quels plutôt que de les évaluer une seconde fois, de sorte qu’un manifeste portant des accolades de template littérales — le {{ $labels.instance }} d’une règle d’alerte, la requête d’un tableau de bord — s’installe avec celles-ci intactes. Ses valeurs ont été résolues dans ces manifestes lorsque le fournisseur helm les a rendus, de sorte que le bloc que le values.yaml du parapluie porte sous ce nom n’est lu par rien.

Le nom de chart qui revient au chart parapluie

La seule chose qu’Aggrega modifie dans un chart que vous avez copié localement est le propre champ name de ce chart. Dans le Chart.yaml du chart placé, name est défini sur l’identité encodée de ce qui a fourni ce chart.

Pour un composant, il s’agit de la propre identité de l’instance du composant — la même valeur que l’alias de la dépendance — et l’entrée de dépendance du parapluie nomme aussi cette valeur, de sorte que les deux côtés concordent toujours.

Un chart qu’apporte un rattachement de Feature est un contributeur à part entière, et il déclare sa propre identité plutôt que de répéter celle du composant auquel il est rattaché. Cette identité est composée de deux éléments que vous avez écrits — le composant qui héberge le rattachement, et le nom sous lequel la Feature est rattachée — derrière un court préfixe qui la marque comme l’identité d’un rattachement plutôt que d’un composant ; la valeur composée est ensuite écrite pour la position du nom de chart au moyen de la dérivation ci-dessous, exactement comme toute autre identité.

Ainsi, rattacher une Feature qui copie localement un chart à un composant nommé api sous le nom guardrail place un chart qui déclare cfr-zh-api-zh-guardrail, tandis que le propre chart de ce composant déclare toujours api. Les deux sont des contributeurs distincts, et chacun déclare un nom qui lui est propre plutôt que de déclarer tous deux celui de l’hôte.

Rien d’autre dans le chart n’est modifié. Tout autre fichier arrive octet pour octet tel que vous l’avez écrit, et dans Chart.yaml tout autre champ, chaque commentaire, l’ordre des clés et les guillemets sont exactement tels que rédigés. Une clé imbriquée ailleurs dans le manifeste qui s’appelle elle aussi name — le nom d’un mainteneur, par exemple — est laissée telle quelle.

Pourquoi le parapluie a besoin de ce champ. Le name d’un chart est ce à quoi Helm lie une dépendance du parapluie. Il est écrit par l’auteur du chart, qui, pour un chart obtenu en amont, n’est pas la personne qui le déploie — de sorte que deux composants dans un même chemin d’assemblage peuvent tout à fait raisonnablement copier localement des charts dont les manifestes déclarent le même nom. Si les deux sous-charts conservaient ce nom partagé, les deux dépendances du parapluie se résoudraient vers celui des deux que Helm a chargé en premier : le chart d’un composant serait rendu deux fois et celui de l’autre pas du tout, tandis que les valeurs de chaque composant arriveraient quand même, de sorte que la sortie paraîtrait complète et serait fausse. Dériver le nom placé de l’instance du composant supprime entièrement le nom partagé, et c’est pourquoi rien n’a à être refusé — y compris les deux cas qui n’ont pas d’autre remède : copier localement le même chart sous deux composants, où le nom est partagé par construction, et copier localement un chart que vous n’avez pas écrit, dont vous ne pouvez pas changer le nom.

La seule chose que vous pouvez observer. Un template qui lit le nom de son propre chart — {{ .Chart.Name }}, et tout ce qui en dérive, comme l’idiome courant de nommage de ressources {{ .Chart.Name }}-{{ .Release.Name }} — lit l’identité encodée de l’instance, et non le nom écrit dans le Chart.yaml du chart source. C’est ce qu’un tel template lisait déjà avant que le champ ne soit défini, car Helm présente un sous-chart sous l’alias par lequel son parent le lie ; définir le champ met le fichier sur disque en accord avec ce que le rendu produisait déjà. Ainsi, pour l’exemple détaillé ci-dessous, un template dans le sous-chart api-east lit api-east.

Si un nom de ressource doit porter le nom rédigé du chart, placez ce nom dans le values.yaml du chart et lisez-le à partir de là — une valeur vous appartient et Aggrega n’y touche pas.

Comment un nom est dérivé

Un nom de chart Helm et un alias de dépendance Helm acceptent chacun un ensemble de caractères plus restreint que ce que peuvent contenir un nom d’agrégat, un chemin de frontière ou un instance_id. Plutôt que de remplacer un caractère que la cible n’accepte pas, la dérivation l’écrit en toutes lettres, de sorte que deux identités qui ne diffèrent que par la ponctuation aboutissent toujours à deux noms — et qu’une valeur écrite sous un alias ne peut jamais atteindre que le sous-chart que cet alias nomme.

  • Une lettre, un chiffre et un trait de soulignement sont conservés exactement tels que rédigés.
  • Un tiret est conservé tel que rédigé partout où le caractère qui le suit est conservé directement et n’est pas un z minuscule. Un tiret suivi d’un z minuscule ouvre une séquence d’échappement, de sorte qu’un tiret rédigé à cette position est lui-même écrit en toutes lettres — api-zone devient api-zhzone, ce qui permet de relire n’importe quel nom sans avoir à deviner.
  • Tout autre caractère est écrit -z suivi d’une lettre qui le nomme : d pour un point, s pour un séparateur de chemin, h pour un tiret que la règle ci-dessus ne conserve pas. Tout le reste est écrit x suivi du point de code hexadécimal à six chiffres du caractère, et un octet qui ne commence aucun caractère est écrit b suivi de sa propre valeur à deux chiffres — de sorte qu’un nom qui n’est pas un texte valide est quand même écrit en toutes lettres de manière distincte plutôt que fusionné.
  • Une valeur vide est écrite -ze, ce qu’aucune valeur non vide ne peut produire.
  • Là où deux identités composent un même nom de chart — un nom d’agrégat qualifiant un chemin d’assemblage — elles sont jointes par --. Une identité encodée unique ne contient jamais cette paire, de sorte que le nom joint indique sans ambiguïté quelle identité est laquelle.

Ainsi, un instance_id data.main-db donne l’alias data-zdmain-db, et l’agrégat fullstack-app avec le chemin d’assemblage boundaries/data/helm-chart donne le nom de chart fullstack-app--boundaries-zsdata-zshelm-chart. Une entrée identique produit toujours le nom identique.

Le values.yaml du parapluie est indexé par alias :

api-server: # sub-chart alias = encoded instance_id
image: "registry/api-server:v2"
replicaCount: 3
billing-svc:
image: "registry/billing:v1"
replicaCount: 2

Lorsque le valuesMapping: d’un sous-chart est évalué par rapport à son contexte de template, la table de valeurs résultante remplit automatiquement ce sous-bloc indexé par alias. Cela vaut pour chaque contributeur du parapluie, pas seulement pour les composants : un rattachement de Feature qui copie localement un chart est un contributeur à part entière, de sorte que le valuesMapping: de sa FeatureRecipe remplit un bloc qui lui est propre, indexé par le nom que déclare son chart placé. Voir « Où aboutit le chart d’un rattachement ».

Une clé que le valuesMapping: définit à null est écrite dans son bloc sous la forme null. Lors d’une installation avec Helm 4, un null dans le propre values.yaml du parapluie ne supprime la valeur par défaut du sous-chart pour cette clé que lorsque l’installation fournit aussi des valeurs pour ce sous-chart ; une installation qui n’en fournit aucune pour lui écarte le null, et la valeur par défaut du sous-chart s’applique. Un null dans les valeurs passées à helm install supprime la valeur par défaut dans tous les cas.

Particularités spécifiques au Provider

  • Le Chart.yaml du sous-chart est obligatoire. L’opération de copie impose la présence d’un Chart.yaml à la racine du chemin source. Son absence arrête le build avant l’exécution de l’étape du parapluie.
  • Le name du chart placé revient au parapluie. Il est défini sur l’identité encodée de ce qui a fourni le chart — la propre identité d’une instance de composant ou, pour un chart qu’apporte un rattachement de Feature, la propre identité de ce rattachement — et c’est la seule chose qu’Aggrega modifie dans un chart copié localement. Voir « Le nom de chart qui revient au chart parapluie ».
  • Un chart source doit déclarer une version, et un nom. La version de l’entrée de dépendance est celle que déclare le propre Chart.yaml du chart source, de sorte qu’un chart qui ne déclare aucune version arrête le build plutôt que d’en recevoir une — une dépendance épinglée à une version que le sous-chart ne porte pas laisserait les valeurs par instance du parapluie incapables de l’atteindre. Un chart dont le Chart.yaml ne déclare aucun nom, contient plus d’un document YAML ou ne peut pas être analysé arrête le build pour la même raison : le parapluie ne peut pas composer un sous-chart qu’il ne peut pas lire.
  • Alias et noms de chart encodés. Un instance_id, un nom d’agrégat ou un chemin de frontière contenant un caractère qu’un nom de chart Helm ou un alias de dépendance n’accepte pas apparaît encodé dans le parapluie rendu, selon « Comment un nom est dérivé » ci-dessus. Une identité construite uniquement de lettres, de chiffres, de traits de soulignement et de tirets que la dérivation conserve apparaît exactement telle que rédigée.
  • Pointeur de dépôt file://. Les entrées de dépendance du parapluie utilisent un pointeur de dépôt file:// qui nomme le propre répertoire du chart enfant — file://charts/<instance_id> pour un composant, et le propre répertoire du rattachement pour un chart qu’apporte une Feature. C’est la convention du système de fichiers local pour les charts enfants présents dans l’arborescence, et elle permet à helm dependency build de résoudre le parapluie sans appels à un registre externe. Le pointeur nomme un emplacement et jamais le nom déclaré du chart ; les deux diffèrent pour un rattachement, et helm dependency build est l’étape qui refuse un pointeur nommant un répertoire qui n’existe pas.
  • Aucun rendu de template au niveau de helm-chart. Le fournisseur n’invoque pas le pipeline de rendu du SDK Helm ; il copie et compose. Les auteurs qui ont besoin de manifestes plats pré-rendus devraient plutôt utiliser le mode avec source du fournisseur helm.

Exemple détaillé

Une frontière à deux nœuds, chaque nœud lié à une Recipe helm-chart pointant vers le même chart source :

# Recipe — used by both `api-east` and `api-west` instances
apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: api-server-helmchart
version: 1.0.0
spec:
capability: helm-chart
implements: core/api-server
source: ./charts/api-server
valuesMapping: |
image: "{{ .values.image }}"
replicaCount: {{ optional .infra `replicas` 2 }}

Après la composition, le chemin d’assemblage évalué de la frontière (par défaut dist/<boundary-directory>/<capability>/, car subDirectory: vaut par défaut {{ .capability }}) contient :

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.yaml

Les deux sous-charts sont des copies de l’unique chart source, et chacun porte le nom de sa propre instance dans son Chart.yaml — ce qui permet de copier localement un même chart deux fois dans un seul parapluie. Tout le reste dans les deux copies est identique à la source.

Un helm install <release-name> dist/<boundary-directory>/helm-chart sur cette disposition installe les deux instances comme une seule release Helm, les valeurs du parapluie indexées par alias pilotant les templates de chaque sous-chart.

Références croisées