Surveillance et alertes Helm avec exemples pratiques : guide d'implémentation

Helm orchestre le cycle de vie des applications sur Kubernetes, mais ses modes de défaillance ne sont pas toujours évidents à partir des métriques génériques du cluster. Les hooks peuvent échouer avant même que les déploiements n'existent. Les rollouts peuvent s'arrêter avant d'atteindre le nombre de répliques souhaité. Une release peut rester en état d'échec après un apply partiel. Ce guide vous donne des étapes pratiques pour surveiller et alerter sur les signaux spécifiques à Helm, avec du PromQL concret, des tactiques de rollout et rollback sûres, et une liste de contrôle opérationnelle compacte utilisable au quotidien.

L'objectif est une tranche de surveillance petite mais fiable qui détecte : 1) les échecs de jobs de hooks, 2) l'indisponibilité des workloads par release, et 3) les redémarrages bruyants qui s'agrègent autour d'une release Helm spécifique. On commence petit, on vérifie localement, et on grandit à partir de là.

Inventaire des versions et de l'environnement

Avant d'ajouter des règles ou des tableaux de bord, capturez un instantané de l'environnement. Cela évite les fausses hypothèses sur les labels, la disponibilité des métriques et les versions.

Prérequis :

• Helm v3.12+ et kubectl v1.25+.
• Accès à l'API Kubernetes sur les namespaces à surveiller.
• Prometheus qui scrape kube-state-metrics et les métriques kubelet/cAdvisor.
• Optionnel : Alertmanager pour le routage des alertes ; Grafana pour les tableaux de bord.

Commandes d'inventaire :

helm version --short
kubectl version --short
kubectl get ns
kubectl get deploy -A -l app.kubernetes.io/managed-by=Helm -o wide
kubectl get jobs -A -l "helm.sh/hook" --show-labels

Confirmez l'utilisation des labels dans vos charts. Pour un PromQL maintenable, vous voulez que ces labels existent sur toutes les ressources gérées par le chart :

• app.kubernetes.io/instance : le nom de la release Helm.
• app.kubernetes.io/name : le nom du chart ou du composant.
• app.kubernetes.io/managed-by=Helm

Extrayez une portée pilote cible (exemple) :

• Namespace : staging
• Release : webapp
• Charts : webapp, worker

Pourquoi cela importe : tout ce qui suit groupe par app.kubernetes.io/instance pour attribuer les signaux à une release Helm.

Chemin de configuration sûr

Cette section fournit un chemin minimal et à faible risque pour mettre en ligne une surveillance Helm utile rapidement.

1. Définir un pilote étroit

• Choisissez un namespace et une ou deux releases. Le premier pilote doit être étroit, mesurable et facile à inspecter localement avant le déploiement.
• Critères de succès (exemple) : une alerte se déclenche quand un job de hook Helm échoue en staging, et une alerte séparée se déclenche quand les répliques déployées pour la release webapp tombent en dessous du souhaité pendant 10 minutes.

1. Valider les labels et les hooks

• Assurez-vous que vos charts incluent les labels de métadonnées sur les Deployments, StatefulSets, DaemonSets, Jobs et CronJobs.
• Pour les hooks Helm, confirmez que vos Jobs de hook incluent l'annotation et le label pour pouvoir les attribuer :
• annotation : "helm.sh/hook: pre-install, post-upgrade"
• label : helm.sh/hook: "pre-install" (kube-state-metrics l'exposera comme label_helm_sh_hook)

Ci-dessous sont des motifs PromQL qui reposent sur kube-state-metrics et les métriques kubelet. Remplacez les namespaces et noms de release par les vôtres. Les requêtes et seuils sont des exemples ; ajustez pour votre environnement.

1. Ajouter des règles d'enregistrement et alertes (Prometheus)

3.1 Indisponibilité des workloads par release Helm

Objectif : détecter quand la somme des répliques disponibles est inférieure aux répliques souhaitées pour tout Deployment dans la release.

Règle d'enregistrement (optionnelle, rend les alertes moins coûteuses) :

# Enregistrer desired et available par release (groupé par namespace et instance)
record: helm_release:deploy_spec_replicas
expr: sum by (namespace, label_app_kubernetes_io_instance) (kube_deployment_spec_replicas{label_app_kubernetes_io_instance!=""})
---
record: helm_release:deploy_available_replicas
expr: sum by (namespace, label_app_kubernetes_io_instance) (kube_deployment_status_replicas_available{label_app_kubernetes_io_instance!=""})
---
record: helm_release:deploy_unavailable_ratio
expr: (helm_release:deploy_spec_replicas - helm_release:deploy_available_replicas) / clamp_min(helm_release:deploy_spec_replicas, 1)

Alerte (se déclenche si au moins 20% indisponible pendant 10m ; seuil d'exemple) :

- alert: HelmReleaseWorkloadUnavailable
  expr: helm_release:deploy_unavailable_ratio > 0.2
  for: 10m
  labels:
    severity: warning
  annotations:
    summary: "Release Helm avec répliques indisponibles"
    description: "{{ $labels.namespace }}/{{ $labels.label_app_kubernetes_io_instance }} est en dessous du SLO de disponibilité"

3.2 Échecs ou blocages des jobs de hooks Helm

Détecter tout job de hook échoué :

- alert: HelmHookJobFailed
  expr: max by (namespace, job, label_helm_sh_hook) (kube_job_status_failed{label_helm_sh_hook!=""}) > 0
  for: 1m
  labels:
    severity: critical
  annotations:
    summary: "Job de hook Helm échoué"
    description: "{{ $labels.namespace }}/{{ $labels.job }} ({{ $labels.label_helm_sh_hook }}) a échoué"

Détecter un job de hook qui tourne trop longtemps (blocage possible) :

- alert: HelmHookJobStalled
  expr: (time() - kube_job_status_start_time{label_helm_sh_hook!=""}) > 600 and kube_job_status_succeeded{label_helm_sh_hook!=""} == 0
  for: 5m
  labels:
    severity: warning
  annotations:
    summary: "Job de hook Helm qui tourne trop longtemps"
    description: "{{ $labels.namespace }}/{{ $labels.job }} tourne depuis > 10m"

3.3 Redémarrages groupés par release Helm

Utile pour repérer les états instables post-upgrade.

record: helm_release:pod_container_restarts:rate5m
expr: sum by (namespace, label_app_kubernetes_io_instance) (rate(kube_pod_container_status_restarts_total{label_app_kubernetes_io_instance!=""}[5m]))
---
- alert: HelmReleaseHighRestartRate
  expr: helm_release:pod_container_restarts:rate5m > 0.1
  for: 15m
  labels:
    severity: warning
  annotations:
    summary: "Taux de redémarrage élevé dans la release"
    description: "{{ $labels.namespace }}/{{ $labels.label_app_kubernetes_io_instance }} redémarre > 0.1/s"

Astuce de routage (optionnelle) : ajoutez une route Alertmanager qui groupe par namespace et label_app_kubernetes_io_instance pour que l'on-call voie un incident unique et cohérent par release.

1. Garder le changement sûr et réversible

• Appliquez les règles sur le staging d'abord. Utilisez un PrometheusRule dédié ou un fichier de règles séparé pour pouvoir revenir en arrière sans toucher aux alertes existantes.
• Nommez tout avec un préfixe clair (exemple) : helm_release: pour les règles d'enregistrement et Helm pour les alertes.
• Chemin de rollback : si bruyant ou faux positifs, désactivez ou supprimez seulement les nouvelles règles, pas les partagées.

Vérification et diagnostics

Après l'application des règles, vérifiez les métriques et alertes attendues sans faire de changements en production.

Exécutez ces requêtes PromQL dans votre UI Prometheus :

1. Métriques attendues existent

• Spec et disponibilité des workloads par release :

     sum by (namespace, label_app_kubernetes_io_instance) (kube_deployment_spec_replicas{label_app_kubernetes_io_instance!=""})
     sum by (namespace, label_app_kubernetes_io_instance) (kube_deployment_status_replicas_available{label_app_kubernetes_io_instance!=""})

• Labels des jobs de hooks visibles :

     max by (namespace, job, label_helm_sh_hook) (kube_job_status_start_time{label_helm_sh_hook!=""})

Si une requête retourne vide, vérifiez que kube-state-metrics scrape votre cluster, que les hooks sont définis comme Jobs, et que les labels sont présents.

1. Tests fonctionnels avec une release non-prod (exemple)

• Déclenchez un échec de job de hook inoffensif en référençant une image inexistante dans un hook pre-install d'un chart de test.
• Observez HelmHookJobFailed se déclencher dans les 1-2 minutes.
• Corrigez l'image et relancez pour regarder l'alerte se résoudre.

1. Vérifications Helm CLI et Kubernetes

• Inspectez une release :

     helm status webapp -n staging
     helm history webapp -n staging

• Inspectez les pods et logs des jobs de hook :

     kubectl get jobs -n staging -l "helm.sh/hook"
     kubectl logs job/<job-name> -n staging

• Vérifiez la santé du rollout :

     kubectl rollout status deploy -n staging -l app.kubernetes.io/instance=webapp
     kubectl get deploy -n staging -l app.kubernetes.io/instance=webapp -o wide

Résultats attendus :

• Une release saine montre des workloads déployés avec répliques disponibles égales aux souhaitées.
• Hooks échoués ou bloqués apparaissent comme Jobs avec compteurs failed non-nul ou durées longues.

1. Tableau de bord Grafana minimal (exemple de mise en page)

• Panneau A : helm_release:deploy_unavailable_ratio par namespace et instance (barres empilées ou tableau). Lignes de seuil à 0.1 et 0.2.
• Panneau B : helm_release:pod_container_restarts:rate5m top 10 par instance (série temporelle).
• Panneau C : Jobs de hooks dernières 24h : sum by (label_helm_sh_hook, namespace, job) (kube_job_status_succeeded) et sum by (...) (kube_job_status_failed).

Quoi surveiller pour Helm (Référence rapide)

Le tableau suivant résume les signaux clés et leurs sources typiques. Toutes les entrées sont des exemples adaptables.

Règles d'alerte d'un coup d'œil

Modes de défaillance et récupération

Voici les façons courantes dont les opérations liées à Helm échouent, avec des étapes de récupération pratiques. Les commandes et durées sont des exemples ; adaptez à vos SLOs et outillages.

Hook pre-install ou pre-upgrade échoue

Symptômes : Helm signale une release échouée ; le Job de hook montre des pods Failed.

Récupération :

1. Inspectez les logs pour trouver la cause racine :

   kubectl logs job/<failed-hook-job> -n <ns>

1. Corrigez le manifeste ou les valeurs du hook, puis relancez :

   helm upgrade --install <release> <chart> -n <ns> --wait --timeout 10m --atomic

--atomic fait un rollback automatique en cas d'échec, gardant le cluster cohérent.

1. Si la release est bloquée dans un état échoué, soit corrigez en avant avec la même version, soit faites un rollback vers la dernière bonne révision :

   helm history <release> -n <ns>
   helm rollback <release> <revision> -n <ns> --wait --timeout 10m

Changement de champ immuable à l'upgrade (ex: ClusterIP, selector)

Symptômes : erreur d'upgrade se plaignant de champs immuables.

Récupération :

1. Identifiez la ressource fautive via helm status et l'erreur côté serveur.
2. Pour un changement de selector Deployment, créez une ressource de remplacement sous un nouveau nom, ou supprimez et recréez pendant une fenêtre de maintenance :

   kubectl delete deploy <name> -n <ns> --cascade=orphan
   helm upgrade <release> <chart> -n <ns> --wait --timeout 10m

1. Préférez les changements de chart qui évitent les diffs immuables (ex: gardez les selectors stables).

Échecs ou apply partiel des upgrades CRD

Symptômes : changements CRD non appliqués ; ressources dépendantes échouent à la réconciliation.

Récupération :

1. Appliquez les CRDs explicitement avant helm upgrade si votre chart livre des CRDs sous crds/ (ceux-ci ne sont pas templatés) :

   kubectl apply -f crds/ -n <ns>
   helm upgrade --install <release> <chart> -n <ns> --wait --timeout 10m

1. Validez les versions CRD et conversions avec kubectl explain et manifestes d'exemple.

Timeouts et rollouts longs

Symptômes : helm upgrade timeout pendant que les workloads rollout lentement.

Récupération :

1. Augmentez le timeout et assurez-vous que les readiness probes sont réalistes :

   helm upgrade <release> <chart> -n <ns> --wait --timeout 20m

1. Vérifiez le rollout directement :

   kubectl rollout status deploy -n <ns> -l app.kubernetes.io/instance=<release>

1. Envisagez une stratégie canary ou surge dans le chart, puis réappliquez.

Uninstall bloqué par des finalizers

Symptômes : helm uninstall ne se termine jamais ; ressources coincées en Terminating.

Récupération :

1. Identifiez les ressources avec finalizers :

   kubectl get all -n <ns> -o json | jq -r '.items[] | select(.metadata.finalizers!=null) | .kind+" / " +.metadata.name+" " +(.metadata.finalizers|join(" ,

1. Supprimez les finalizers sûrs à supprimer cas par cas, puis relancez l'uninstall.

Vérification post-récupération

• Assurez-vous que les alertes se résolvent : plus de HelmHookJobFailed ou HelmReleaseWorkloadUnavailable qui tirent.
• Confirmez desired = available replicas pour la release.
• Relancez helm status et helm history pour confirmer l'état stable.

Workflow de réponse aux incidents

Utilisez ceci comme runbook quand une alerte Helm tire.

1. Acquitter et cadrer

• Notez le namespace et app.kubernetes.io/instance dans l'alerte.
• Vérifiez si plusieurs alertes ciblent la même release ; groupez-les.

1. Confirmer l'état

   helm status <release> -n <ns>
   kubectl get jobs -n <ns> -l "helm.sh/hook"

1. Identifier le type de défaillance

• Échec hook : regardez les logs du job en premier.
• Disponibilité workload : inspectez le rollout et les événements pod.

     kubectl rollout status deploy -n <ns> -l app.kubernetes.io/instance=<release>
     kubectl get events -n <ns> --sort-by=.lastTimestamp | tail -n 50

1. Choisir une action sûre

• Fix-forward si le changement est petit et bien compris ; sinon rollback.

     helm rollback <release> <revision> -n <ns> --wait --timeout 10m

1. Vérifier et clôturer

• Assurez-vous que les alertes se nettoient et que les workloads sont sains pendant au moins un intervalle de bake-in (exemple : 15 minutes).
• Documentez la révision et la cause racine pour le suivi.

Signaux de logs à capturer

Si vous agrégez les logs Helm CLI et Kubernetes, cherchez ces motifs pour enrichir les alertes ou aider le triage :

• Helm CLI : "Error: INSTALLATION FAILED", "Error: UPGRADE FAILED", "failed pre-install", "failed post-upgrade", "render error", "parsing error\).
• Kubernetes : pods Job avec CrashLoopBackOff, ImagePullBackOff, OOMKilled autour du moment des hooks.
• Événements : FailedCreate, FailedMount, Unhealthy.

Liste de contrôle opérations

Quotidien

• Vérifiez Grafana pour toute release avec helm_release:deploy_unavailable_ratio > 0.
• Revoyez les alertes ouvertes groupées par namespace et app.kubernetes.io/instance ; assurez-vous que les propriétaires sont clairs.
• Scannez pour nouveaux ou inattendus jobs de hook dans les namespaces actifs.

Hebdomadaire

• Vérifiez une release au hasard : helm status, helm history, et un dry-run de rollout si disponible.
• Revoyez les alertes bruyantes ; ajustez seuils ou ajoutez labels manquants.
• Vérifiez que les nouveaux charts respectent les conventions de labeling.

Avant chaque upgrade

• Lancez helm lint localement et appliquez sur un namespace jetable.
• Confirmez que les images des jobs de hook existent et ont l'accès pull.
• Validez que les champs immuables sont inchangés ou qu'un plan de migration existe.

Hygiène rollback

• Gardez helm history taillé là où la politique l'exige, mais retenez assez de révisions pour rollback sûr.
• Après tout rollback, vérifiez alertes et dashboards pendant au moins un intervalle de bake-in.

Conclusion

Vous avez maintenant un chemin pratique, à faible risque, pour surveiller Helm avec des métriques concrètes, alertes et tableaux de bord qui se concentrent sur ce qu'Helm introduit de unique : les hooks et les rollouts par release. Commencez avec un pilote étroit, vérifiez que les alertes tirent et se résolvent prévisiblement, et utilisez des procédures de rollback claires pour garder les changements sûrs. En étendant la couverture au-delà du namespace pilote, gardez les labels cohérents, ajustez les seuils à vos SLOs, et affinez les runbooks pour que les ingénieurs on-call puissent diagnostiquer et récupérer rapidement. Cette approche garde les changements mesurables, réduit le retravail, et crée une fondation fiable pour les opérations Helm day-2.