Installer et configurer un chart

Pourquoi

Le cours Kubernetes a installé Traefik par une commande de deux lignes, en annonçant qu'on y reviendrait. C'est le moment : installer un chart de la communauté est le premier usage de Helm, et celui que l'on pratique le plus souvent, parce que presque tous les logiciels d'infrastructure se distribuent ainsi.

Le risque est de le faire sans comprendre. helm install traefik traefik/traefik fonctionne tout seul, avec des valeurs par défaut conçues pour un cas moyen. Ces valeurs ne sont pas les vôtres : une seule réplique, un Service de type LoadBalancer facturé par le fournisseur, aucun budget de perturbation. Sans les avoir lues, on met en production un composant d'entrée que l'on ne connaît pas. Autre écueil : une valeur passée en ligne de commande prend un type que l'on n'avait pas prévu, et le chart se comporte autrement. Enfin, sans version épinglée, deux installations faites à trois mois d'écart ne produisent pas les mêmes objets.

Cette leçon apprend à trouver un chart, à lire ce qu'il propose, à le configurer de façon reproductible, et à l'installer en sachant ce que fera chaque option.

Les concepts

Où trouver un chart

Artifact Hub (artifacthub.io) est l'annuaire public des charts, et de bien d'autres artefacts de l'écosystème Kubernetes. Il n'héberge pas les charts : il indexe les dépôts que leurs auteurs lui déclarent, et affiche pour chaque chart ses versions, sa documentation, ses valeurs, et des indicateurs de confiance. Ceux qui comptent :

• Official : le chart est publié par l'éditeur du logiciel (le chart Traefik publié par Traefik Labs porte cette mention dans les données d'Artifact Hub).
• Verified publisher : Artifact Hub a vérifié que le dépôt appartient bien à l'organisation qui le revendique.
• Signed : le chart est accompagné d'une signature (leçon 9).
• Les rapports de sécurité sur les images référencées, et la date de la dernière version.

Ces indicateurs ne remplacent pas votre jugement : ils disent qui publie, pas que le chart est adapté à vos besoins. Un chart sans nouvelle version depuis deux ans pour un logiciel qui évolue vite est un signal d'alerte.

La commande helm search hub traefik interroge Artifact Hub depuis la ligne de commande. Elle nécessite un accès à Internet, comme tout ce qui télécharge dans cette leçon.

Dépôt HTTP ou registre OCI

Un chart se récupère de deux façons.

Un dépôt HTTP est un site statique qui publie un fichier index.yaml (la liste de toutes les versions, avec leur adresse de téléchargement et leur empreinte) et les archives. On l'enregistre sous un nom local de son choix, puis on y fait référence par nom/chart :

$ helm repo add traefik https://traefik.github.io/charts
$ helm repo update
$ helm search repo traefik/traefik --versions | head -3

helm repo add enregistre le dépôt dans votre configuration locale ; helm repo update télécharge son index.yaml à jour, et c'est cet index que helm search repo et helm install traefik/traefik consultent. Si vous oubliez helm repo update, vous ne voyez pas les versions récentes.

Un registre OCI est un registre de conteneurs. Un chart y est stocké comme une image, et l'on n'a pas de liste à ajouter ni d'index à mettre à jour : on désigne le chart directement par son adresse, préfixée de oci:// :

$ helm install traefik oci://ghcr.io/traefik/helm/traefik --version 41.6.1

Le README du chart Traefik donne les deux voies, dépôt HTTP (traefik.github.io/charts) et registre OCI (oci://ghcr.io/traefik/helm/traefik). Les deux publient les mêmes versions. Les différences pratiques :

Le futur est le registre OCI : un seul type de serveur pour les images et les charts, les mêmes droits, les mêmes contrôles, et la même signature. Un dépôt HTTP reste très répandu pour les logiciels tiers.

Lire avant d'installer

La famille de commandes helm show affiche le contenu d'un chart sans l'installer :

helm show values est l'étape la plus utile. Les auteurs de charts documentent chaque clé par un commentaire, et le fichier fait souvent plusieurs centaines de lignes : on le redirige vers un fichier que l'on lit, au lieu de le survoler.

$ helm show values traefik/traefik --version 41.6.1 > traefik-defaults.yaml
$ wc -l traefik-defaults.yaml
1696 traefik-defaults.yaml

Ce nombre est celui du fichier de la version 41.6.1 du chart. Voici, dans ce fichier, les clés qui intéressent un déploiement sur Kapsule (extraits abrégés des valeurs par défaut) :

deployment:
  kind: Deployment
  replicas: 1
  terminationGracePeriodSeconds: 60

podDisruptionBudget:
  enabled: false

providers:
  kubernetesGateway:
    enabled: false

gateway:
  enabled: true

ports:
  web:
    port: 8000
    expose:
      default: true
    exposedPort: 80

service:
  enabled: true
  spec:
    type: LoadBalancer

On y lit sans rien exécuter : une seule réplique, aucun budget de perturbation, le fournisseur Gateway API désactivé, une Gateway par défaut créée dès qu'on l'active, le point d'entrée web qui écoute sur le port 8000 du pod et que le Service expose sur le port 80, et un Service de type LoadBalancer. Chacun de ces choix est une décision à prendre, pas à subir.

Fournir ses valeurs

Il y a deux façons de surcharger les valeurs par défaut : un fichier (-f, ou --values) et la ligne de commande (--set et ses variantes). Le fichier est la bonne méthode de travail : il est relu, versionné dans Git, identique d'une exécution à l'autre. --set sert aux essais et aux valeurs que l'on ne veut pas écrire dans un fichier.

Un fichier ne contient que ce qui diffère des valeurs par défaut, pas une copie du values.yaml. Copier tout le fichier fige les défauts de la version du moment, et vous ne bénéficiez plus de leur évolution.

L'ordre de priorité

Quand une même clé est définie à plusieurs endroits, la plus prioritaire gagne. De la moins à la plus prioritaire :

1. les valeurs par défaut du chart (values.yaml) ;
2. les fichiers donnés par -f, dans l'ordre : le dernier l'emporte ;
3. les valeurs de la ligne de commande : --set-json, puis --set, puis --set-string, puis --set-file, puis --set-literal.

Cet ordre est celui du code de Helm (MergeValues, dans pkg/cli/values/options.go) : les fichiers sont fusionnés d'abord, puis les familles d'options --set* s'appliquent, dans cet ordre-là, quel que soit l'ordre dans lequel vous les avez tapées entre -f et --set. Une clé donnée par --set l'emporte toujours sur un fichier, même si -f est écrit plus loin dans la commande.

Vérifions-le avec le chart de Signalements, que la leçon 4 construit (il est ici utilisé tel quel). Deux fichiers de valeurs, et une surcharge :

$ cat v-a.yaml
replicaCount: 3
image: {tag: "1.2.1"}
$ cat v-b.yaml
replicaCount: 5
$ helm template s signalements --set databaseSecretName=x \
    -f v-a.yaml -f v-b.yaml --show-only templates/deployment.yaml | grep -E "replicas:|image:"
  replicas: 5
          image: "ghcr.io/lyneko-formation/signalements:1.2.1"
$ helm template s signalements --set databaseSecretName=x \
    -f v-a.yaml -f v-b.yaml --set replicaCount=7 \
    --show-only templates/deployment.yaml | grep -E "replicas:|image:"
  replicas: 7
          image: "ghcr.io/lyneko-formation/signalements:1.2.1"

replicaCount vaut 5 (le second fichier gagne sur le premier), puis 7 avec --set. image.tag n'est défini que dans v-a.yaml : la fusion est récursive pour les tableaux associatifs (les « maps »), donc image.repository garde sa valeur par défaut. La fusion s'arrête au niveau des listes : une liste n'est pas fusionnée, elle est remplacée entièrement par celle du fichier le plus prioritaire.

Cette dernière règle surprend. Avec un chart qui définit env comme une liste de deux variables, un fichier qui fournit une liste d'une variable donne une liste d'une variable :

# valeurs par défaut du chart d'exemple
env:
  - {name: LOG_LEVEL, value: info}
  - {name: TZ, value: Europe/Paris}
etiquettes:
  equipe: voirie
  cycle: prod

# v-liste.yaml
env:
  - {name: LOG_LEVEL, value: debug}
etiquettes:
  cycle: recette

Sortie réelle de helm template s scratch -f v-liste.yaml (extrait, chart d'exemple qui affiche ses valeurs) :

env:
- name: LOG_LEVEL
  value: debug
etiquettes:
  cycle: recette
  equipe: voirie

La variable TZ a disparu avec sa liste, alors que equipe a été conservée : une map se fusionne, une liste se remplace.

Les pièges de --set

La syntaxe de --set est compacte, et son interprétation des valeurs est source d'erreurs.

Le typage. --set essaie de deviner le type : true et false deviennent des booléens, null devient nul, les entiers deviennent des entiers. Tout le reste reste une chaîne. Sortie réelle, avec un chart d'exemple qui affiche .Values :

$ helm template s scratch --set a=0123 --set b=true --set c=null --set d=12345 \
    --set e=1.20 --set f=yes --set g=0x1F
a: "0123"
b: true
c: null
d: 12345
e: "1.20"
f: "yes"
g: "0x1F"

0123 et 1.20 restent des chaînes (heureusement), yes n'est pas un booléen, mais 12345 est un entier. Pour une version d'image comme --set image.tag=12345 ou un nom comme --set nom=true, le modèle recevra un entier ou un booléen, ce qu'un champ qui attend une chaîne peut refuser. Deux remèdes : --set-string, qui force la chaîne, et --set-json, qui laisse le contrôle complet du type.

$ helm template s scratch --set-string port=8000 --set-json 'q={"a":[1,2]}'

La virgule sépare les valeurs. --set a=1,b=2 définit deux clés. Une valeur qui contient une virgule doit être protégée par une barre oblique inverse, ou passer par --set-literal :

$ helm template s signalements --set databaseSecretName=a,b
Error: failed parsing --set data: key "b" has no value
$ helm template s scratch --set 'm=a\,b' --set-literal 'r=a,b=c'
m: a,b
r: a,b=c

Le point sépare les clés. --set a.b=1 définit b dans a. Pour une clé qui contient un point (fréquent pour les annotations, comme service.beta.kubernetes.io/...), il faut protéger le point : --set 'annotations.example\.com/nom=x'. Mieux vaut un fichier de valeurs, qui n'a pas cette difficulté.

Les listes. --set 'liste={a,b}' définit une liste de deux éléments ; --set 'liste[0]=x' définit le premier élément. L'indice crée une liste, qui remplace celle du chart (règle ci-dessus) : sur la liste env du chart d'exemple, --set 'env[0].value=debug' produit une liste d'un seul élément {value: debug}, sans le champ name. Pour modifier une liste, on la fournit en entier dans un fichier.

null supprime une clé par défaut. --set etiquettes=null retire la clé du chart d'exemple, ce qui permet de désactiver un bloc par défaut. Le chart doit le prévoir.

Un secret en --set reste dans l'historique du shell et, plus grave, dans la release (leçon 3). Les valeurs sensibles ne se passent pas ainsi.

Pour toutes ces raisons, la règle de ce cours est simple : un fichier de valeurs pour tout ce qui doit durer, --set seulement pour essayer.

Choisir et épingler la version

Sans --version, helm install prend la dernière version stable du chart au moment de l'appel. Deux installations à trois mois d'écart peuvent donc différer, et un helm upgrade sans version installe la plus récente. En production, on épingle : --version 41.6.1, qui désigne une version exacte. L'option accepte aussi une contrainte (^41.0.0), pratique pour les essais, mais elle réintroduit l'imprévu.

Ne confondez pas version du chart et version de l'application. Le chart Traefik 41.6.1 a pour appVersion v3.7.13 : c'est le logiciel installé par défaut. Une même version de chart peut changer l'image de l'application avec une valeur (image.tag), et une nouvelle version du chart peut changer les manifestes sans changer l'application. Les deux se suivent, séparément.

Un chart déclare aussi la version de Kubernetes qu'il accepte, dans kubeVersion de son Chart.yaml (le chart Traefik 41.6.1 exige >=1.25.0-0). Helm refuse d'installer un chart sur un cluster trop ancien, avec un message qui cite la contrainte.

En pratique

Les commandes qui parlent au cluster ou à Internet sont expliquées sans sortie inventée ; les rendus locaux sont réels. On installe Traefik sur le cluster kind formation du cours Kubernetes.

1. Écrire le fichier de valeurs

Dans un dépôt de déploiement, créez traefik-values.yaml. Il ne contient que ce qui diffère des défauts lus plus haut :

# traefik-values.yaml (chart traefik 41.6.1)
deployment:
  replicas: 2

podDisruptionBudget:
  enabled: true
  minAvailable: 1

providers:
  kubernetesGateway:
    enabled: true     # active le fournisseur Gateway API

gateway:
  enabled: false      # la Gateway est écrite par l'application, pas par le chart

Quatre choix, chacun justifié par les défauts : deux répliques et un budget d'au moins un pod disponible (un seul pod coupe l'entrée à chaque maintenance), le fournisseur Gateway API actif parce que Lyneko publie ses applications par HTTPRoute, et la Gateway par défaut du chart désactivée, parce que l'équipe applicative écrit la sienne (leçon 11 du cours Kubernetes). Tout le reste (ports, type de Service) garde sa valeur par défaut.

2. Vérifier le rendu avant d'installer

Avec le dépôt traefik ajouté (ce qui demande Internet) :

$ helm template traefik traefik/traefik --version 41.6.1 \
    --namespace traefik -f traefik-values.yaml | grep '^kind:' | sort | uniq -c

Cette commande compte les types d'objets que le chart produira, avec vos valeurs. Vous devez y trouver notamment un Deployment, un Service, un ServiceAccount, un PodDisruptionBudget (absent sans votre fichier), et la GatewayClass. L'option --namespace indique à helm template le namespace de la release, que les modèles peuvent lire (.Release.Namespace). Comparer ce rendu avec et sans votre fichier montre exactement ce que vos valeurs changent :

$ diff <(helm template traefik traefik/traefik --version 41.6.1 -n traefik) \
       <(helm template traefik traefik/traefik --version 41.6.1 -n traefik -f traefik-values.yaml)

3. Installer

$ helm install traefik traefik/traefik \
    --version 41.6.1 \
    --namespace traefik --create-namespace \
    -f traefik-values.yaml \
    --wait --timeout 5m

Chaque option a un rôle :

• traefik (premier argument) est le nom de la release ; traefik/traefik désigne le chart, nom-local/chart.
• --version 41.6.1 épingle la version du chart.
• --namespace traefik installe la release dans ce namespace, et c'est dans ce namespace que le Secret de release est écrit. --create-namespace le crée s'il n'existe pas. Sans lui, l'installation échoue si le namespace est absent. Le namespace est créé sans étiquette : s'il doit en porter (comme le profil de sécurité des pods), créez-le vous-même, ou avec un manifeste, avant l'installation.
• -f traefik-values.yaml fournit les valeurs.
• --wait fait attendre la fin de l'installation : Helm ne rend la main que lorsque les pods sont prêts, les Services ont leurs points de terminaison, et les Deployments leurs répliques disponibles. --timeout (5 minutes par défaut) borne l'attente. Sans --wait, helm install rend la main dès que les objets sont créés, et une installation qui a réussi peut produire des pods qui ne démarrent jamais.

La sortie d'une installation réussie commence par un résumé : nom de la release, date de dernière modification, namespace, état (STATUS: deployed), numéro de révision, puis le contenu de NOTES.txt du chart. Les notes sont du texte écrit par l'auteur du chart, avec des commandes pour vérifier l'installation ; on les relit avec helm get notes traefik.

4. Les options de sécurité de l'installation

--atomic ajoute un filet : si l'installation échoue ou si l'attente expire, Helm désinstalle la release (pour une mise à jour, il la restaure à la révision précédente). La documentation précise qu'il active --wait automatiquement.

$ helm install traefik traefik/traefik --version 41.6.1 -n traefik --create-namespace \
    -f traefik-values.yaml --atomic --timeout 5m

Avec Helm 4, cette option est renommée --rollback-on-failure. L'ancien nom --atomic continue de fonctionner et affiche un avertissement de dépréciation, d'après la page de présentation de Helm 4. Dans vos scripts et vos pipelines, vous pouvez déjà écrire le nom récent si votre version de Helm le connaît, ou conserver --atomic tant que vous êtes sur Helm 3. Le comportement attendu est le même.

Côté attente, Helm 4 documente que --wait accepte une stratégie : watcher (le nouveau mode, fondé sur kstatus), legacy (le comportement de Helm 3) ou hookOnly. Utilisé seul, --wait prend la stratégie watcher. Sans l'option, seule l'attente des hooks a lieu (hookOnly).

5. Vérifier

$ helm list --namespace traefik
$ kubectl get pods,service --namespace traefik
$ kubectl get gatewayclass

helm list montre la release traefik, son état deployed, la révision 1, et le chart traefik-41.6.1 avec sa version d'application. Les deux dernières commandes sont celles du cours Kubernetes : deux pods Traefik prêts, un Service traefik de type LoadBalancer, et la GatewayClass traefik acceptée.

Sous le capot

Ce que fait helm install, dans l'ordre. Le client résout le chart (cherche dans l'index du dépôt, ou interroge le registre), télécharge l'archive, la met en cache dans HELM_CACHE_HOME, puis vérifie la contrainte kubeVersion. Il fusionne les valeurs, rend les modèles, vérifie que les manifestes sont du YAML valide, puis les trie par type pour l'installation : un Namespace avant un Secret, un Service avant un Deployment, et ainsi de suite, selon une liste fixe écrite dans le code de Helm. Il vérifie qu'aucun objet n'existe déjà sans appartenir à une autre release (c'est l'origine du message cannot re-use a name et de ses cousins). Il écrit un premier enregistrement de release à l'état pending-install, applique les objets, attend si on le lui a demandé, et passe l'état à deployed.

Le cache et l'index. helm repo add écrit une entrée dans le fichier de configuration repositories.yaml de HELM_CONFIG_HOME ; helm repo update télécharge index.yaml dans HELM_CACHE_HOME. C'est là que helm search repo cherche, sans réseau. Un helm install traefik/traefik utilise l'index local pour trouver l'adresse du chart. C'est aussi pourquoi un dépôt supprimé du poste n'est plus utilisable, même si le serveur existe encore.

Le typage de --set. Le décodage de --set est écrit dans le paquet strvals de Helm. Il lit une valeur, essaie de la convertir en booléen (true, false), en nul (null) ou en entier de 64 bits, et retombe sur la chaîne sinon. Il n'interprète pas les nombres à virgule : 1.20 reste donc la chaîne "1.20", ce qui est une bonne nouvelle pour les numéros de version. Les valeurs d'un fichier sont lues par un lecteur YAML complet, avec les règles de typage de YAML : dans un fichier, 1.20 est un nombre, et yes peut être un booléen selon l'analyseur. Pour les versions, mettez toujours des guillemets dans un fichier : tag: "1.20".

La fusion des valeurs. La fonction de fusion de Helm parcourt les maps récursivement ; pour tout autre type (liste, chaîne, nombre), la valeur la plus prioritaire remplace entièrement l'autre. Une clé à null dans une source plus prioritaire supprime la clé héritée du chart.

Pièges courants

Error: INSTALLATION FAILED: cannot re-use a name that is still in use. Une release de ce nom existe déjà dans le namespace. Vous vouliez peut-être mettre à jour : helm upgrade --install (leçon 3) fait l'un ou l'autre.

Error: Kubernetes cluster unreachable. Le kubeconfig actif ne désigne aucun cluster joignable. Sortie réelle avec un kubeconfig volontairement vide :

$ helm list -n traefik
Error: Kubernetes cluster unreachable: Get "https://127.0.0.1:1/version": dial tcp 127.0.0.1:1: connect: connection refused

Vérifiez kubectl config current-context avant toute commande Helm : Helm utilise le même contexte, et une mauvaise cible est l'erreur la plus coûteuse (installer sur le mauvais cluster).

failed to download "traefik/traefik" (hint: running 'helm repo update' may help). L'index local est périmé ou le dépôt n'est pas ajouté.

Un --set qui passe un nombre là où une chaîne est attendue. Voir plus haut : --set-string.

Installer sans --create-namespace dans un namespace absent, ou l'utiliser quand le namespace devait porter des étiquettes de sécurité. Dans le second cas, le namespace créé par Helm n'en a aucune, et le profil restricted n'est pas appliqué.

Sécurité

• Lisez le rendu avant d'installer. helm template montre les rôles, les liaisons de rôles, les webhooks et les définitions de ressources que le chart crée. Un chart d'ingress crée normalement un ClusterRole en lecture sur plusieurs ressources, et c'est attendu ; un chart de simple application qui crée un ClusterRoleBinding vers cluster-admin ne l'est pas.
• Épinglez la version, et idéalement l'empreinte. Une version de chart est une étiquette ; avec Helm 4, une installation par empreinte (oci://.../traefik@sha256:...) garantit le contenu exact. La leçon 9 traite de la signature.

En production

• Un fichier de valeurs par chart tiers et par environnement, dans un dépôt Git, relu comme du code. Le chart est référencé par version, le fichier fait le reste.
• Mise à jour des charts tiers par demande de fusion. Un outil de veille (Renovate, Dependabot) propose un changement de version ; vous lisez le journal des modifications du chart, rendez avant et après (helm template des deux versions, puis diff), et fusionnez. C'est la seule manière de ne pas découvrir en production qu'une valeur par défaut a changé.
• Les mises à jour majeures d'un chart sont des événements. Une nouvelle version majeure peut renommer des valeurs, changer des défauts, migrer des définitions de ressources. Lisez les notes, testez en recette.
• Les définitions de ressources. Helm installe les CRD placées dans le répertoire crds/ d'un chart à la première installation, mais ne les met pas à jour ni ne les supprime. Beaucoup de charts proposent donc de gérer les CRD séparément : suivez leur documentation (le sujet revient à la leçon 7 et dans le cours sur les opérateurs).
• Quel namespace. Un composant d'infrastructure vit dans son propre namespace (traefik, cert-manager), séparé des applications.
• Chez Lyneko, ces installations ne se font pas à la main : Argo CD les rend avec ces mêmes fichiers de valeurs (leçon 10). La commande helm install de cette leçon est celle du poste de travail et de la recette.

Exercices

1. Prédire une valeur (niveau 100). Le chart a replicaCount: 2. On lance helm template s signalements -f a.yaml --set replicaCount=4 -f b.yaml, avec replicaCount: 3 dans a.yaml et replicaCount: 6 dans b.yaml. Quelle valeur le modèle reçoit-il ?

2. Le tag numérique (niveau 200). Un chart utilise image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}". Quelle différence entre --set image.tag=1.20, --set image.tag=2024 et --set image.tag=0123 pour ce modèle, et comment forcer le comportement voulu ?

3. Installer proprement (niveau 300). Rédigez la commande qui installe Traefik 41.6.1 dans le namespace traefik depuis le registre OCI, avec le fichier de valeurs de la leçon, en annulant tout si l'installation échoue en moins de cinq minutes. Que choisissez-vous pour la version dans un pipeline, et quel risque évitez-vous ?

Récapitulatif

• Artifact Hub indexe les charts et affiche des indicateurs (officiel, éditeur vérifié, signé) ; ils renseignent sur l'origine, pas sur l'adéquation.
• Un chart vient d'un dépôt HTTP (helm repo add, helm repo update, nom/chart) ou d'un registre OCI (oci://..., sans index à mettre à jour).
• helm show values est la référence de configuration : lisez-le avant d'installer ; helm template montre l'effet de vos valeurs.
• Priorité : défauts du chart, puis -f (le dernier gagne), puis --set-json, --set, --set-string, --set-file, --set-literal. Les maps se fusionnent, les listes se remplacent.
• --set devine le type (booléen, nul, entier), sépare sur la virgule et sur le point : préférez un fichier de valeurs minimal, --set-string pour les chaînes, et des guillemets sur les versions.
• Épinglez --version ; --create-namespace crée un namespace sans étiquettes ; --wait attend la disponibilité ; --atomic (--rollback-on-failure avec Helm 4) annule en cas d'échec.
• Les installations de production passent par Git et Argo CD, pas par une commande tapée.

Pour aller plus loin

• La page Helm Install de la documentation, pour la liste complète des options, et la page Use OCI-based registries pour helm registry login, helm pull et helm push.
• Le fichier pkg/strvals/parser.go du dépôt helm/helm, pour voir comment --set découpe et type une valeur.
• Le values.yaml et le README du chart Traefik, qui montrent comment un chart sérieux documente chaque clé.
• La leçon suivante, Les releases et leur cycle de vie, qui met à jour, inspecte et annule la release que vous venez de créer.