Commandes de base de Helm avec exemples pratiques : un guide d'exploitation

Introduction

Helm est le gestionnaire de paquets pour Kubernetes, mais sa véritable valeur n'apparaît que lorsqu'on l'utilise avec une discipline opérationnelle. Un chart n'est pas une solution miracle ; c'est un ensemble de manifestes Kubernetes enveloppés de configuration et de hooks de cycle de vie. Chaque helm install ou helm upgrade modifie l'état d'un cluster, les opérateurs doivent donc savoir exactement ce qu'une commande va faire, ce qu'elle va produire et comment récupérer en cas de problème.

Ce guide s'adresse aux développeurs, ingénieurs DevOps et équipes techniques de startups qui connaissent déjà Kubernetes mais souhaitent utiliser Helm de manière sûre et efficace. Il passe en revue les commandes de base que vous utiliserez quotidiennement, avec des exemples concrets, les sorties attendues, les signaux d'échec et les étapes de récupération. L'accent est mis sur les opérations en ligne de commande, pas sur le développement de charts. Nous couvrirons l'inventaire des versions et de l'environnement, les chemins de configuration sûrs, la vérification et le diagnostic, les modes d'échec et une liste de contrôle pratique. Chaque section comprend des commandes réelles et des exemples de sortie pour que vous puissiez suivre dans votre propre cluster.

Avant de commencer, assurez-vous d'avoir :

• Un cluster Kubernetes en cours d'exécution (local comme Minikube ou un service géré)
• kubectl configuré pour communiquer avec ce cluster
• Helm v3 installé (v2 est déconseillé et hors sujet)
• Compréhension de base des objets Kubernetes comme les Pods, Deployments et Services

Pour vérifier votre version de Helm, exécutez :

helm version --short

Exemple de sortie :

v3.12.0+g5e8c1e6

Si vous voyez une version commençant par v2, passez à Helm v3 avant de continuer.

Inventaire des versions et de l'environnement

Avant d'exécuter toute commande Helm, connaissez votre environnement. Cela signifie vérifier la version du client Helm, la version du serveur Kubernetes et l'état actuel des releases existantes. Un inventaire en lecture seule vous protège contre les modifications basées sur des hypothèses obsolètes.

Commencez par vérifier que Helm peut communiquer avec votre cluster :

helm list --all-namespaces

Sortie attendue :

NAME    NAMESPACE       REVISION UPDATED                                 STATUS   CHART           APP VERSION
myapp   default         1        2023-10-01 10:20:30.123456 +0000 UTC deployed myapp-0.1.0     1.16.0

Si vous obtenez une erreur comme Error: Kubernetes cluster unreachable, vérifiez votre kubeconfig et assurez-vous que kubectl get nodes fonctionne. Si la commande renvoie une sortie vide, aucune release n'est actuellement installée.

Ensuite, comparez les versions du client et du serveur Helm. Helm v3 a supprimé le composant côté serveur (Tiller), donc seule la version du client compte :

helm version

Exemple de sortie :

version.BuildInfo{Version:"v3.12.0", GitCommit:"5e8c1e6", GitTreeState:"clean", GoVersion:"go1.20.4"}

Pour voir la version de Kubernetes :

kubectl version --short

Exemple de sortie :

Client Version: v1.27.3
Kustomize Version: v5.0.1
Server Version: v1.27.3

Helm v3 prend en charge les versions de Kubernetes à partir de 1.16, mais si votre cluster est plus ancien, mettez-le à niveau ou utilisez une version plus ancienne de Helm selon la matrice de compatibilité. Gardez une note écrite de ces versions pour chaque environnement ; c'est la première chose que les équipes de support demandent lorsqu'un déploiement échoue.

Dépôts Helm et recherche de charts

Les charts Helm sont stockés dans des dépôts. Le plus courant est le dépôt stable officiel de Helm, mais de nombreux fournisseurs hébergent les leurs. Ajoutez un dépôt une fois et réutilisez-le. Par exemple, pour ajouter le dépôt Bitnami (une source populaire de charts prêts pour la production) :

helm repo add bitnami https://charts.bitnami.com/bitnami

Mettez ensuite à jour le cache local :

helm repo update

Recherchez maintenant des charts :

helm search repo bitnami/wordpress

Exemple de sortie :

NAME                    CHART VERSION   APP VERSION DESCRIPTION
bitnami/wordpress       15.2.7          6.2.2       WordPress is the world's most popular blogging...

Notez la version du chart et la version de l'application : la version du chart suit l'empaquetage, tandis que la version de l'application suit l'application à l'intérieur. Lors de l'installation, soyez explicite sur la version du chart pour éviter les surprises dues aux changements en amont.

Piège courant : Les dépôts changent avec le temps. Si vous voyez Error: no repositories found, exécutez helm repo add et helm repo update. Si un chart disparaît d'un dépôt, épinglez la version dont vous avez besoin dans votre pipeline CI/CD pour éviter les déploiements cassés.

Installation d'un chart

La commande helm install déploie un chart en tant que release. Une release est une instance spécifique d'un chart avec sa propre configuration. Nommez toujours votre release explicitement ; sinon Helm génère un nom aléatoire difficile à suivre.

Syntaxe de base :

helm install <nom-de-release> <chart> [options]

Exemple : installez WordPress depuis le dépôt Bitnami avec un nom de release my-blog dans l'espace de noms par défaut :

helm install my-blog bitnami/wordpress --version 15.2.7

Sortie attendue (tronquée) :

NAME: my-blog
LAST DEPLOYED: Mon Oct  2 10:00:00 2023
NAMESPACE: default
STATUS: deployed
REVISION: 1
NOTES:
1. Get the application URL by running these commands:
  export POD_NAME=$(kubectl get pods --namespace default -l "app.kubernetes.io/name=wordpress,app.kubernetes.io/instance=my-blog" -o jsonpath="{.items[0].metadata.name}")
  kubectl port-forward --namespace default $POD_NAME 8080:80
  echo "Visit http://127.0.0.1:8080 to use your application"

Prérequis pour cette commande :

• Vous avez ajouté le dépôt Bitnami et exécuté helm repo update.
• Votre espace de noms existe (créez-le avec kubectl create namespace default si nécessaire).
• Vous disposez des autorisations RBAC suffisantes pour créer des ressources dans cet espace de noms.

Rayon d'impact : Cette commande crée plusieurs ressources Kubernetes : Deployments, Services, PVC, Secrets, etc. Dans un cluster partagé, installez toujours dans un espace de noms dédié pour isoler votre application.

Vérification : Après l'installation, vérifiez l'état de la release :

helm status my-blog

Cela montre les ressources créées et les notes éventuelles. Exécutez également kubectl get pods pour voir si les Pods sont en cours d'exécution.

Récupération : Si l'installation échoue, Helm ne laissera pas de release cassée. Vérifiez le message d'erreur, corrigez le problème (par exemple, ressources insuffisantes) et réessayez. Vous pouvez aussi utiliser helm uninstall my-blog pour nettoyer les ressources partielles.

Inspection des releases

Après l'installation, vous devez inspecter régulièrement les releases. La commande helm list affiche toutes les releases dans l'espace de noms actuel ou dans tous les espaces de noms :

helm list --namespace default

Exemple de sortie :

NAME    NAMESPACE REVISION UPDATED                                 STATUS   CHART           APP VERSION
my-blog default   1        2023-10-02 10:00:00.000000 +0000 UTC deployed wordpress-15.2.7 6.2.2

Pour plus de détails sur une release spécifique, utilisez helm status :

helm status my-blog

Cela montre la révision actuelle, l'espace de noms et les ressources créées. Pour voir les manifestes Kubernetes calculés sans les appliquer, utilisez helm get manifest :

helm get manifest my-blog | less

C'est une commande en lecture seule qui peut vous aider à comprendre ce que Helm a réellement déployé.

Pour voir les valeurs utilisées pour une release, combinez helm get values :

helm get values my-blog

Exemple de sortie :

USER-SUPPLIED VALUES:
null

Si aucune valeur personnalisée n'a été fournie, elle affiche null. C'est important pour déboguer les problèmes de configuration.

Mise à niveau et retour en arrière

Les mises à niveau modifient l'application en direct. Avant de mettre à niveau, sauvegardez la configuration actuelle de la release. Helm stocke la configuration sous forme de Secret dans le cluster, mais vous pouvez aussi l'exporter :

helm get values my-blog -o yaml > my-blog-values-backup.yaml

Effectuez ensuite la mise à niveau avec de nouvelles valeurs à partir d'un fichier :

helm upgrade my-blog bitnami/wordpress --version 15.2.7 -f my-new-values.yaml

Si vous omettez --version, Helm utilisera la dernière version du chart, ce qui pourrait introduire des changements cassants. Épinglez toujours la version ou utilisez une plage avec --version.

Vérification après la mise à niveau :

helm history my-blog

Exemple de sortie :

REVISION UPDATED                 STATUS     CHART           DESCRIPTION
1        Mon Oct  2 10:00:00 2023 superseded wordpress-15.2.7 Install complete
2        Mon Oct  2 11:00:00 2023 deployed   wordpress-15.2.7 Upgrade complete

Si la mise à niveau échoue, Helm revient automatiquement à la révision précédente. Vous pouvez aussi revenir manuellement à une révision spécifique :

helm rollback my-blog 1

Cela revient à la révision 1. Vérifiez avec helm status my-blog.

Piège courant : Les mises à niveau peuvent modifier les ressources de calcul (CPU/mémoire) des Pods, ce qui les recrée. Assurez-vous que votre application gère correctement les mises à jour progressives. Utilisez kubectl rollout status deployment/my-blog pour suivre la progression.

Désinstallation des releases

Lorsque vous n'avez plus besoin d'une release, supprimez-la proprement :

helm uninstall my-blog

Cela supprime toutes les ressources Kubernetes associées à la release, mais ne supprime pas l'espace de noms lui-même ni les revendications de volume persistant (PVC) provisionnées dynamiquement, sauf si vous spécifiez --keep-history ou que le chart utilise un hook de nettoyage. Pour supprimer également l'espace de noms :

kubectl delete namespace default

Attention : La désinstallation est irréversible pour les ressources gérées par Helm. Assurez-vous d'avoir des sauvegardes et qu'aucun autre service n'en dépend. Par exemple, si vous avez une release de base de données et qu'une autre release l'utilise, désinstaller la base de données cassera l'application dépendante.

Configuration et valeurs Helm

Les charts Helm sont configurés via des valeurs. Les valeurs par défaut sont définies dans le fichier values.yaml du chart. Vous pouvez les remplacer par votre propre fichier de valeurs ou par des options --set.

Exemple de fichier de valeurs my-values.yaml :

replicaCount: 2
image:
  tag: "6.2.2"
service:
  type: LoadBalancer

Installez avec des valeurs personnalisées :

helm install my-blog bitnami/wordpress --version 15.2.7 -f my-values.yaml

Pour voir les valeurs attendues par un chart, utilisez helm show values :

helm show values bitnami/wordpress --version 15.2.7 | less

C'est essentiel avant de remplacer ; de nombreux charts ont des configurations imbriquées faciles à manquer.

Gestion des secrets : Ne stockez jamais de véritables informations d'identification dans des fichiers de valeurs que vous validez dans le contrôle de version. Utilisez les Secrets Kubernetes et référencez-les via existingSecret ou utilisez des fichiers de valeurs spécifiques à l'environnement. Par exemple :

existingSecret: my-blog-secret

Créez ensuite le Secret séparément :

kubectl create secret generic my-blog-secret --from-literal=password='S3cret!'

Helm utilisera le Secret existant au lieu d'en générer un nouveau.

Vérification et diagnostic

La vérification est un processus continu. Après tout changement, vérifiez l'état réel par rapport à l'état attendu. Des commandes comme helm test peuvent exécuter des tests définis par le chart :

helm test my-blog

Cela exécute les hooks de test définis dans le chart. Cela peut lancer un Pod qui vérifie que l'application répond. La sortie affichera le statut de réussite ou d'échec.

Pour un diagnostic plus approfondi, utilisez kubectl pour inspecter les ressources gérées par Helm :

kubectl get pods --namespace default -l app.kubernetes.io/instance=my-blog

Exemple de sortie :

NAME                        READY   STATUS    RESTARTS   AGE
my-blog-wordpress-0         1/1     Running   0          5m
my-blog-mariadb-0          1/1     Running   0          5m

Si les Pods ne fonctionnent pas, utilisez kubectl describe pod <nom-du-pod> et kubectl logs <nom-du-pod> pour enquêter. Helm lui-même a également une option de débogage :

helm install my-blog bitnami/wordpress --debug --dry-run

L'option --dry-run affiche les manifestes qui seraient envoyés à Kubernetes sans les appliquer. C'est une étape de sécurité critique pour tout changement.

Sortie attendue pour --dry-run : les manifestes YAML générés. Examinez-les pour vérifier leur exactitude avant l'exécution réelle.

Modes d'échec et récupération

Les échecs Helm peuvent survenir à différentes étapes. Voici les modes d'échec courants et comment récupérer :

1. Chart introuvable

Erreur : Error: chart "bitnami/wordpress" not found

Pourquoi : Le dépôt n'est pas ajouté ou le nom du chart est mal orthographié.

Récupération : Ajoutez le dépôt et mettez à jour : helm repo add bitnami https://charts.bitnami.com/bitnami puis helm repo update. Vérifiez avec helm search repo bitnami/wordpress.

2. Le nom de release existe déjà

Erreur : Error: cannot re-use a name that is still in use

Pourquoi : Vous essayez d'installer une release avec un nom qui existe déjà.

Récupération : Soit désinstallez l'ancienne release (helm uninstall my-blog) soit utilisez un nom différent. Si vous voulez mettre à niveau, utilisez helm upgrade au lieu de install.

3. Échec de mise à niveau dû à des valeurs invalides

Erreur : Error: UPGRADE FAILED: cannot patch "my-blog" with kind Deployment: Deployment.apps "my-blog-wordpress" is invalid: spec.template.spec.containers[0].image: Required value

Pourquoi : Le fichier de valeurs a omis un champ obligatoire ou fourni un type invalide.

Récupération : Helm revient automatiquement à la dernière révision réussie. Corrigez le fichier de valeurs, vérifiez avec helm upgrade --dry-run, puis réessayez.

4. Pods en attente en raison de contraintes de ressources

Symptôme : kubectl get pods affiche le statut Pending.

Pourquoi : Pas assez de CPU/mémoire dans le cluster.

Récupération : Réduisez les demandes de ressources dans les valeurs ou ajoutez des nœuds. Ensuite, kubectl delete pod <pod-en-attente> pour replanifier.

5. Secrets de release perdus

Symptôme : helm list ne montre rien, mais des ressources existent.

Pourquoi : Le secret de release Helm (un Secret Kubernetes) a été supprimé accidentellement.

Récupération : Vous pouvez récupérer en créant une nouvelle release avec le même nom et en utilisant helm adopt si disponible, ou réinstaller à partir de sauvegardes. Prévention : ne supprimez pas les secrets de release Helm ; utilisez helm uninstall à la place.

Chemin de configuration sûr

Suivez un chemin sûr pour tout changement de configuration :

1. Observer l'état actuel avec des commandes en lecture seule : helm list, helm status, helm get values.
2. Sauvegarder la configuration actuelle : helm get values my-blog -o yaml > backup.yaml.
3. Modifier un élément à la fois. Utilisez un fichier de valeurs et --dry-run pour prévisualiser.
4. Appliquer le changement avec helm upgrade ou helm install.
5. Vérifier avec helm test, kubectl get pods et des vérifications au niveau de l'application.
6. Documenter le changement et les étapes de récupération.

Par exemple, pour changer le nombre de réplicas de 1 à 3 :

• Observer : helm get values my-blog (notez le replicaCount actuel)
• Sauvegarder : helm get values my-blog -o yaml > my-blog-values-$(date +%Y%m%d).yaml
• Modifier le fichier de valeurs : définissez replicaCount: 3
• Dry-run : helm upgrade my-blog bitnami/wordpress --version 15.2.7 -f my-values.yaml --dry-run
• Appliquer : helm upgrade my-blog bitnami/wordpress --version 15.2.7 -f my-values.yaml
• Vérifier : kubectl get deployment my-blog-wordpress -o jsonpath='{.spec.replicas}' doit afficher 3.

Liste de contrôle opérationnelle

Utilisez cette liste de contrôle avant toute opération Helm dans un environnement de production :

• [ ] Confirmer que la version du client Helm (helm version --short) correspond à la plage attendue.
• [ ] Confirmer que le kubeconfig pointe vers le bon cluster (pas staging vs production).
• [ ] Lister les releases actuelles (helm list --all-namespaces) et noter la release cible.
• [ ] Sauvegarder les valeurs actuelles (helm get values <release> -o yaml > backup.yaml).
• [ ] Examiner les changements du chart avec helm show values et helm show readme.
• [ ] Exécuter un dry-run : helm upgrade <release> <chart> --dry-run ou helm install --dry-run.
• [ ] Définir explicitement --namespace et --version pour éviter toute ambiguïté.
• [ ] Si vous utilisez --set, vérifiez les guillemets et la syntaxe YAML.
• [ ] Avoir un plan de retour en arrière : connaître la révision précédente (helm history <release>).
• [ ] Désigner un propriétaire pour le changement (par exemple, Priya Shah, responsable ingénierie) et une heure de revue (par exemple, revue hebdomadaire des releases).
• [ ] Après l'application, vérifier avec helm status, helm test et les vérifications de santé de l'application.
• [ ] Documenter le changement, le propriétaire et tout problème dans le journal des changements de l'équipe.

Piège à éviter : Exécuter helm install au lieu de helm upgrade sur une release existante. Cela provoque une erreur ; vérifiez toujours helm list d'abord.

Résumé des pièges courants

Voici une référence rapide des erreurs courantes et comment les éviter :

Conclusion

Les commandes de base de Helm deviennent des opérations sûres lorsque vous appliquez les principes d'observation, de changement minimal, de vérification et de récupération. Les commandes couvertes ici—repo add, install, list, status, get, upgrade, rollback, uninstall et test—sont la boîte à outils quotidienne de tout opérateur Kubernetes. Utilisez-les avec des dry-runs, l'épinglage de versions et des sauvegardes pour garder le contrôle sur vos déploiements.

Comme prochaine étape, choisissez une vérification à faible risque : exécutez helm list --all-namespaces pour inventorier vos releases actuelles, puis choisissez une release et exécutez helm get values pour comprendre sa configuration. Examinez les changements récents et assurez-vous d'avoir un plan de retour en arrière. Ensuite, adoptez la liste de contrôle opérationnelle pour votre équipe. Helm est un outil qui récompense la discipline : plus vous observez avant de changer, moins vous rencontrerez de surprises.