Aller au contenu

Introduction aux Helm Charts : structure, lint et package

Si tu veux déployer ton application sur un service type Kubernetes, tu vas forcément tomber sur du Helm. En quelques mots, cela va te permettre de packager ton application avec l'image Docker de ton service, pour donner les spécifications et autres indications à K8s sur la manière dont :

  • est déployée ton application dans ton cluster
  • sont gérés sa haute disponibilité, son scaling, et sa résilience si le service est down
  • est géré son accès à un disque dur
  • est géré son accès aux ressources RAM et CPU
  • etc.

Concrètement, un chart Helm, c'est un ensemble de templates de manifests Kubernetes et un fichier de values qui les paramètre. Le même chart sert à déployer ton application en dev, en recette et en production : seules les values changent.

Packaging de ton application

Initialisation

On commence par initialiser un Helm chart, avec un template de base dans ton application via helm create un_nom_de_projet

un_nom_de_projet/
  |- .helmignore        # fichiers à ignorer au packaging
  |- Chart.yaml         # infos globales du chart
  |- values.yaml        # values par défaut pour les templates
  |- charts/            # sous-charts (dépendances déclarées dans Chart.yaml)
  |- templates/         # fichiers de template
  |- templates/tests/   # fichiers de test de template

Le fichier Chart.yaml

C'est la carte d'identité de ton chart. Deux champs se ressemblent mais n'ont rien à voir :

1
2
3
4
5
6
apiVersion: v2
name: mon-api
description: API de démonstration
type: application
version: 1.4.0      # version du CHART, à incrémenter à chaque modification du chart
appVersion: "2.7.1" # version de l'APPLICATION déployée, souvent le tag de l'image

version suit le versionnement sémantique et identifie le paquet que tu publies : si tu modifies un template sans changer version, tu publies deux contenus différents sous le même numéro. appVersion est purement informatif, mais beaucoup de charts s'en servent comme tag d'image par défaut.

Le templating en bref

Les templates utilisent le moteur de template de Go, enrichi par Helm. Quelques réflexes à prendre tout de suite :

# templates/deployment.yaml (extrait)
spec:
  replicas: {{ .Values.replicaCount }}
  template:
    spec:
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
          env:
            - name: LOG_LEVEL
              value: {{ .Values.logLevel | quote }}
          resources:
            {{- toYaml .Values.resources | nindent 12 }}
  • default fournit une valeur de repli, ici l'appVersion du chart si aucun tag n'est fourni ;
  • quote force une chaîne : sans lui, une valeur comme true ou 8080 serait interprétée comme un booléen ou un nombre, ce qu'une variable d'environnement refuse ;
  • toYaml ... | nindent injecte un bloc YAML complet avec la bonne indentation, la source d'erreurs n°1 dans un chart ;
  • les morceaux réutilisés (labels communs, nom complet de la release) se rangent dans templates/_helpers.tpl sous forme de named templates, appelés avec include.

Pour une valeur sans laquelle le chart n'a aucun sens, utilise required : le rendu échoue avec ton message plutôt que de produire un manifest incomplet.

host: {{ required "ingress.host est obligatoire" .Values.ingress.host }}

Dry run

Tu peux utiliser helm template <mon_chart> pour avoir un rendu de ton chart avec les values qui le paramètrent. Cela te donne une idée de ce que tu vas installer, et te permet de vérifier que tu as bien ce que tu souhaites de templatisé. Ajoute --debug pour voir le rendu même quand il est invalide, et -f values-prod.yaml pour tester les values d'un environnement précis.

Pour aller plus loin que le rendu local, helm install --dry-run=server envoie les manifests à l'API server sans rien créer : tu détectes ainsi les erreurs de schéma Kubernetes et les ressources inconnues du cluster cible.

Valider les values avec un schéma

Une faute de frappe dans une clé de values (replicacount au lieu de replicaCount) est ignorée silencieusement : le template retombe sur la valeur par défaut. Pour l'éviter, ajoute un fichier values.schema.json à la racine du chart. Helm le valide automatiquement à chaque install, upgrade, lint et template :

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["image"],
  "properties": {
    "replicaCount": { "type": "integer", "minimum": 1 },
    "image": {
      "type": "object",
      "required": ["repository"],
      "properties": {
        "repository": { "type": "string" },
        "tag": { "type": "string" }
      }
    }
  }
}

Lint du chart

helm lint <mon_chart>

Le lint vérifie la structure du chart, le rendu des templates et le respect du schéma. Ajoute --strict pour que les avertissements fassent aussi échouer la commande, et passe-lui les mêmes fichiers de values que ceux de tes environnements (-f values-prod.yaml) : un chart peut être valide avec ses values par défaut et cassé avec celles de la production.

Packaging de ton chart

Tu peux avoir besoin de packager ton chart, par exemple pour le stocker sur un registry afin de pouvoir le distribuer : un repository Helm classique comme Artifactory, ou un registry OCI, le même que pour tes images Docker (GitLab Container Registry, Harbor, etc.). Tu peux notamment en avoir besoin si tu passes par du déploiement continu, par FluxCD par exemple, d'avoir un .tgz de ton chart, permettant une installation simplifiée au sein de ton cluster Kubernetes.

Pour cela tu devras utiliser helm package <mon_chart>

Pour le pousser sur un registry OCI, supporté nativement depuis Helm 3.8 :

1
2
3
helm registry login registry.example.com
helm push mon-chart-0.1.0.tgz oci://registry.example.com/charts
helm install mon-release oci://registry.example.com/charts/mon-chart --version 0.1.0

Pour automatiser le lint, le packaging et la validation de ton chart dans une pipeline, vois le stage Helm en CI.

Déployer proprement

Redémarrer les pods quand la configuration change

Si ton application lit un ConfigMap au démarrage, modifier ce ConfigMap ne redémarre pas les pods : ils continuent de tourner avec l'ancienne configuration. L'astuce documentée par Helm consiste à ajouter au Deployment une annotation qui contient l'empreinte du ConfigMap. Quand il change, l'empreinte change, et Kubernetes déclenche un rolling update :

spec:
  template:
    metadata:
      annotations:
        checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}

Revenir en arrière automatiquement

helm upgrade --install mon-release ./mon-chart -f values-prod.yaml --wait --timeout 5m --rollback-on-failure

--wait attend que les ressources soient prêtes avant de déclarer le déploiement réussi, et --rollback-on-failure revient à la révision précédente en cas d'échec. Sur Helm 3, cette dernière option s'appelle --atomic : Helm 4 l'a renommée, l'ancien nom fonctionne encore mais affiche un avertissement de dépréciation.

Pièges courants

  • Oublier d'incrémenter version : deux contenus différents sous le même numéro. Selon le registry, le push est refusé (tags immuables) ou écrase silencieusement l'ancienne version, et tes clusters ne déploient plus forcément la même chose.
  • Modifier les labels du sélecteur : spec.selector d'un Deployment est immuable. Si tu changes les labels utilisés par selector.matchLabels après la première installation, l'upgrade échoue. Fige-les dès le départ dans _helpers.tpl.
  • Mettre des secrets dans values.yaml : le fichier finit dans Git et la release Helm stocke les values dans le cluster. Passe par un gestionnaire de secrets (External Secrets, Sealed Secrets, ou le plugin helm-secrets).
  • Valider uniquement avec les values par défaut : lint et template doivent tourner avec les values réelles de chaque environnement.
  • Déployer à la main en production : une fois le chart publié, laisse un outil GitOps comme Argo CD appliquer les values versionnées, plutôt que des helm upgrade lancés depuis un poste.

Pour aller plus loin