Surveiller Helm et déclencher des alertes : guide pratique avec exemples

Intro

Cette version française explique Helm monitoring and alerts with practical examples avec le même objectif pratique que l article source : aider le lecteur à comprendre le contexte, les décisions à prendre et les points à vérifier avant de passer à l action.

Helm orchestre les cycles de vie applicatifs sur Kubernetes, mais ses modes de défaillance ne sont pas toujours visibles via les métriques génériques du cluster. Des hooks peuvent échouer avant qu'un Deployment n'existe. Des rollouts peuvent s'arrêter en dessous du nombre de réplicas désiré. Une release peut rester en état "failed" après une application partielle. Ce guide propose des étapes concrètes pour surveiller et alerter sur des signaux spécifiques à Helm, avec du PromQL, des tactiques sûres de déploiement et de rollback, et une checklist d'exploitation compacte utilisable au quotidien.

Objectif : mettre en place un périmètre de monitoring fiable qui détecte 1) les échecs de jobs de hook, 2) l'indisponibilité des workloads par release, et 3) des redémarrages bruyants regroupés par release Helm. Nous commençons petit, vérifions localement, puis nous élargissons. Ce guide couvre aussi Helm monitoring, Helm alerts, Helm metrics, un Helm dashboard minimal et un runbook de Helm incident response.

Inventaire des versions et de l'environnement

Avant d'ajouter des règles ou des dashboards, capturez un instantané de l'environnement. Cela évite les hypothèses erronées sur les labels, la présence des métriques et les versions.

Prérequis (exemples construits) :

Helm v3.12+ et kubectl v1.25+.
Accès API Kubernetes aux namespaces ciblés.
Prometheus scrappant kube-state-metrics et les métriques kubelet/cAdvisor.
Optionnel : Alertmanager pour router les alertes ; Grafana pour les dashboards.

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'usage des labels dans vos charts. Pour un PromQL pérenne, vous voulez :

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

Extrait d'un périmètre pilote (exemple) :

Namespace : staging
Release : webapp
Charts : webapp, worker

Pourquoi c'est critique : tout ce qui suit regroupe par app.kubernetes.io/instance pour attribuer les signaux à une release Helm.

Chemin de configuration sûr

Définir un pilote étroit

Choisissez un namespace et une ou deux releases. Le pilote initial doit être mesurable et inspectable localement avant déploiement.
Critères de succès (exemple) : une alerte se déclenche quand un job de hook Helm échoue en staging, et une autre quand les réplicas disponibles pour la release webapp passent sous le désiré pendant 10 minutes.

Valider labels et hooks

Assurez-vous que vos charts posent les labels sur Deployments, StatefulSets, DaemonSets, Jobs et CronJobs.
Pour les hooks Helm, confirmez que vos Jobs de hook incluent l'annotation et le label pour l'attribution :
annotation : "helm.sh/hook: pre-install, post-upgrade"
label : helm.sh/hook: "pre-install" (kube-state-metrics l'expose en label_helm_sh_hook)

Les modèles PromQL ci-dessous reposent sur kube-state-metrics et les métriques kubelet. Remplacez namespaces et releases par les vôtres. Seuils et requêtes sont des exemples à ajuster.

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

3.1) Indisponibilité des workloads par release Helm

But : détecter quand la somme des réplicas disponibles est inférieure au désiré pour tout Deployment de la release.
Règle d'enregistrement (optionnelle, rend les alertes moins coûteuses) :

# Enregistrer désiré et disponible 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 (déclenche si au moins 20 % indisponible pendant 10 min) :

- alert: HelmReleaseWorkloadUnavailable
  expr: helm_release: deploy_unavailable_ratio > 0.2
  for: 10m
  labels:
    severity: warning
  annotations:
    summary: "Helm release has unavailable replicas"
    description: "{{ $labels.namespace }}/{{ $labels.label_app_kubernetes_io_instance }} is below availability SLO"

3.2) Échecs ou blocages de jobs de hook Helm

Détecter tout job de hook en échec :

- 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: "Helm hook job failed"
    description: "{{ $labels.namespace }}/{{ $labels.job }} ({{ $labels.label_helm_sh_hook }}) failed"

Détecter un job de hook trop long (potentiel blocage) :

- 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: "Helm hook job running too long"
    description: "{{ $labels.namespace }}/{{ $labels.job }} has been running > 10m"

3.3) Redémarrages regroupés par release Helm

Utile pour repérer un état instable après 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: "High restart rate in release"
    description: "{{ $labels.namespace }}/{{ $labels.label_app_kubernetes_io_instance }} restarting > 0.1/s"

Astuce de routage (optionnelle) : dans Alertmanager, groupez par namespace et label_app_kubernetes_io_instance pour présenter un incident cohérent par release à l'astreinte.

Garder le changement sûr et réversible

Appliquez d'abord en staging. Utilisez un fichier de règles dédié pour revenir en arrière sans toucher l'existant.
Préfixez clairement (ex. : helm_release: pour enregistrement, Helm pour alertes).
Chemin de rollback : en cas de bruit, désactivez uniquement les nouvelles règles.

Vérification et diagnostics

Après application, vérifiez les métriques et alertes sans impacter la production.

Exécutez ces requêtes dans l'UI Prometheus :

Les métriques attendues existent

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 la requête retourne vide, vérifiez kube-state-metrics, la définition des hooks en Jobs et la présence des labels.

Tests fonctionnels en environnement non prod (exemple)

Provoquez un échec bénin en référencant une image inexistante dans un hook pre-install d'un chart de test.
Observez HelmHookJobFailed en 1-2 minutes.
Corrigez l'image, relancez et vérifiez la résolution.

Contrôles Helm CLI et Kubernetes

Inspecter une release :

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

Inspecter les pods/Logs des jobs de hook :

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

Vérifier 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 :

Release saine : réplicas disponibles = réplicas désirés.
Hooks en échec ou bloqués : Jobs avec échecs non nuls ou durée anormalement longue.

Dashboard Grafana minimal (mise en page construite)

Panneau A : helm_release: deploy_unavailable_ratio par namespace/instance (barres empilées ou tableau), lignes à 0.1 et 0.2.
Panneau B : helm_release: pod_container_restarts: rate5m top 10 par instance (série temporelle).
Panneau C : Hooks 24h : sum by (label_helm_sh_hook, namespace, job) (kube_job_status_succeeded) et sum by (...) (kube_job_status_failed).

Que surveiller pour Helm (référence rapide)

Disponibilité des workloads par release : kube_deployment_spec_replicas, kube_deployment_status_replicas_available. Détecte les rollouts partiels ou bloqués. Identifiant : app.kubernetes.io/instance.
Échecs de jobs de hook : kube_job_status_failed, kube_job_status_start_time. Capture précocement les échecs pre/post install/upgrade. Identifiant : label_helm_sh_hook sur les Jobs.
Hooks bloqués : time() - kube_job_status_start_time pour prévenir les blocages de release.
Tempêtes de redémarrages par release : kube_pod_container_status_restarts_total pour remonter une instabilité post-upgrade.
Labels Helm manquants : kubectl ... --show-labels pour garantir un regroupement fiable.

Exemples de règles d'alerte (aperçu)

HelmReleaseWorkloadUnavailable : (helm_release: deploy_unavailable_ratio > 0.2) pendant 10m, severity : warning.
HelmHookJobFailed : max by (...) (kube_job_status_failed{label_helm_sh_hook!=""}) > 0 pendant 1m, severity : critical.
HelmHookJobStalled : (time() - kube_job_status_start_time{label_helm_sh_hook!=""}) > 600 et kube_job_status_succeeded == 0 pendant 5m, severity : warning.
HelmReleaseHighRestartRate : helm_release: pod_container_restarts: rate5m > 0.1 pendant 15m, severity : warning.

Modes de panne et reprise

Symptômes : release en échec ; Jobs de hook en Failed. Remédiation :

Échec de hook pre-install ou pre-upgrade

kubectl logs job/<failed-hook-job> -n <ns>
helm upgrade --install <release> <chart> -n <ns> --wait --timeout 10m --atomic
helm history <release> -n <ns>
helm rollback <release> <revision> -n <ns> --wait --timeout 10m

Symptômes : erreur d'upgrade sur champs immuables. Remédiation :

Modification d'un champ immuable (ex. ClusterIP, selector)

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

Conservez des sélecteurs stables dans les charts.

Symptômes : changements de CRD non appliqués, ressources dépendantes en échec. Remédiation :

Mises à niveau de CRD partielles

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

Symptômes : helm upgrade dépasse le délai tandis que les workloads progressent lentement. Remédiation :

Timeouts et rollouts lents

helm upgrade <release> <chart> -n <ns> --wait --timeout 20m
kubectl rollout status deploy -n <ns> -l app.kubernetes.io/instance=<release>

Ajustez probes et stratégie (canary/surge) dans le chart si nécessaire.

Symptômes : helm uninstall ne termine pas, ressources en Terminating. Remédiation :

Uninstall bloqué par des finalizers

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

Retirez avec précaution les finalizers sûrs au cas par cas, puis réessayez l'uninstall.

Vérifications post-récupération

Les alertes se résolvent : plus de HelmHookJobFailed ni de HelmReleaseWorkloadUnavailable.
Désiré = disponible pour la release.
helm status et helm history indiquent un état stable.

Workflow d'incident (exemple)

Accuser réception et cadrer

Notez namespace et app.kubernetes.io/instance dans l'alerte.
Regroupez si plusieurs alertes ciblent la même release.

Confirmer l'état

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

Identifier le type de défaillance

Hook en échec : consulter d'abord les logs du job.
Indisponibilité des workloads : inspecter le rollout et les événements.

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

Choisir une action sûre

Corriger en avant si le changement est compris ; sinon rollback.

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

Vérifier et clôturer

S'assurer que les alertes disparaissent et que les workloads restent sains sur un intervalle d'observation (ex. 15 min).
Documenter la révision et la cause racine pour suivi.

Signaux de logs à capter

Helm CLI : « Error: INSTALLATION FAILED », « Error: UPGRADE FAILED », « failed pre-install », « failed post-upgrade », « render error », « parsing error ».
Kubernetes : pods de Job en CrashLoopBackOff, ImagePullBackOff, OOMKilled autour des fenêtres de hooks.
Événements : FailedCreate, FailedMount, Unhealthy.

Checklist d'exploitation

Quotidien (exemple) :

Vérifier dans Grafana les releases avec helm_release: deploy_unavailable_ratio > 0.
Passer en revue les alertes ouvertes regroupées par namespace et app.kubernetes.io/instance ; vérifier la prise en charge.
Rechercher des jobs de hooks nouveaux ou inattendus.

Hebdomadaire (exemple) :

Contrôler une release : helm status, helm history, et si possible un dry-run de rollout.
Réduire le bruit : ajuster les seuils et ajouter les labels manquants.
Valider la conformité des nouveaux charts aux conventions de labels.

Avant chaque upgrade (exemple) :

Exécuter helm lint en local et déployer sur un namespace jetable.
Confirmer que les images des hooks existent et sont accessibles.
Vérifier l'absence de modifications de champs immuables ou prévoir une migration.

Hygiène de rollback (exemple) :

Conserver l'historique Helm selon la politique tout en gardant assez de révisions pour un rollback sûr.
Après rollback, surveiller alertes et dashboard sur un intervalle d'observation.

Conclusion

Vous disposez maintenant d'un chemin pragmatique et à faible risque pour surveiller Helm avec des métriques, alertes et dashboards centrés sur ses spécificités : hooks et rollouts par release. Commencez par un pilote étroit, validez que les alertes se déclenchent et se résolvent de façon prédictible, et utilisez des procédures claires de rollback pour rester en sécurité. En étendant au-delà du namespace pilote, gardez des labels cohérents, calibrez les seuils à vos SLO et affinez les runbooks pour que l'astreinte diagnostique et répare rapidement. Cette approche maintient les changements mesurables, réduit le rework et crée une base fiable pour les opérations Helm au quotidien.