Surveillance et alertes avec kubectl : guide pratique avec exemples

Introduction

La surveillance et les alertes avec kubectl, illustrées par des exemples pratiques, doivent aider les opérateurs à passer d'un problème observé à un résultat vérifié. Ce guide se concentre sur la réalité quotidienne de l'exploitation de Kubernetes : vérifier la santé du cluster, diagnostiquer les charges de travail défaillantes, mettre en place des alertes légères et récupérer en toute sécurité lorsque quelque chose se casse.

Vous apprendrez un flux de travail reproductible : commencez par identifier la version installée, la topologie de déploiement, les prérequis et le composant exact inspecté. Ensuite, utilisez des commandes en lecture seule pour observer, effectuez le changement minimal justifié, vérifiez le résultat et documentez comment récupérer si l'état attendu n'est pas atteint.

L'article s'adresse aux développeurs, aux consultants DevOps et aux équipes techniques de startups qui utilisent kubectl comme interface principale avec Kubernetes. Il relie les alertes kubectl, les métriques, les tableaux de bord et la réponse aux incidents à des commandes concrètes, des sorties attendues, des signaux de défaillance et des décisions de récupération.

L'objectif est la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des espaces réservés plutôt que des secrets, vérifier le résultat et documenter comment récupérer si l'état attendu n'est pas atteint.

Inventaire des versions et de l'environnement

Avant de surveiller quoi que ce soit, sachez à quoi vous avez affaire. L'inventaire des versions et de l'environnement doit nommer le composant concerné, la plage de versions prise en charge, les prérequis, une observation en lecture seule, le changement minimal justifié et la commande ou le signal qui vérifie le résultat.

Dans l'inventaire des versions et de l'environnement, séparez l'observation de l'intervention. Capturez d'abord l'état actuel et les horodatages, protégez les informations d'identification et le matériel privé, puis ne modifiez qu'un seul élément délimité lorsque son rayon d'impact et son chemin de récupération sont compris.

Les concepts importants pour l'inventaire des versions et de l'environnement sont la surveillance kubectl, les alertes, les métriques, les tableaux de bord et la réponse aux incidents. Les domaines connexes tels que l'espace de noms, le pod et le déploiement ne doivent être inclus que lorsqu'ils affectent les prérequis, la compatibilité, la sécurité, l'observabilité ou la récupération pour ce sujet.

Vérification Kubernetes pratique pour l'inventaire des versions et de l'environnement : commencez par kubectl get pods -o wide, puis utilisez kubectl describe pod <nom> pour les détails de planification et d'événements, kubectl logs <nom> --previous pour les boucles de crash et kubectl rollout status deployment/<nom> avant de supposer qu'une version a réussi.

Pour l'inventaire des versions et de l'environnement, gardez le test local petit. Appliquez un seul manifeste, inspectez les ressources générées et vérifiez le trafic avec kubectl port-forward ou un type de service local avant de passer à un équilibreur de charge cloud ou à un contrôleur d'entrée.

Inventaire des versions étape par étape

1. Vérifiez les versions du client et du serveur :

    kubectl version --short

Exemple de sortie attendue :

    Client Version: v1.28.2
    Kustomize Version: v5.0.4-0.20230601165947-6ce0bf390ce3
    Server Version: v1.27.4

Si la version du serveur n'est pas affichée, votre kubeconfig n'a peut-être pas accès au cluster. Vérifiez kubectl config current-context pour confirmer avec quel cluster vous communiquez.

1. Vérifiez l'accès au cluster et les ressources de l'API :

    kubectl auth can-i list pods --all-namespaces

Attendu : yes ou no. Si no, vous savez immédiatement que certaines commandes de surveillance échoueront en raison du RBAC.

1. Listez les espaces de noms pour comprendre la topologie de l'environnement :

    kubectl get namespaces

Identifiez si vous êtes dans un espace de noms de développement, de préproduction ou de production. Par exemple, un espace de noms de production pourrait être nommé prod-eu-west, un espace de noms de préproduction staging et le développement dev-team1.

1. Vérifiez s'il manque des prérequis, comme metrics-server pour kubectl top :

    kubectl get deployment metrics-server -n kube-system

Si vous voyez NAME READY UP-TO-DATE AVAILABLE AGE, alors metrics-server est présent. Si vous voyez Error from server (NotFound): deployments.apps "metrics-server" not found, vous devez l'installer avant d'utiliser kubectl top.

1. Documentez la plage de versions prise en charge pour votre cluster. Par exemple, vous pourriez prendre en charge Kubernetes 1.24 à 1.28. Vérifiez toujours la politique officielle de décalage de version de Kubernetes : kubectl prend en charge une version mineure plus récente ou plus ancienne que le serveur API. Exemple : si votre cluster fonctionne en 1.27, utilisez kubectl 1.26, 1.27 ou 1.28.

Chemin de configuration sûr

La surveillance nécessite souvent des changements de configuration : mettre en place des alertes, des tableaux de bord ou de la journalisation. Le chemin de configuration sûr garantit que vous ne cassez pas un système en cours d'exécution pendant que vous le modifiez. Il doit nommer le composant concerné, la plage de versions prise en charge, les prérequis, une observation en lecture seule, le changement minimal justifié et la commande ou le signal qui vérifie le résultat.

Séparez l'observation de l'intervention. Capturez d'abord l'état actuel et les horodatages, protégez les informations d'identification et le matériel privé, puis ne modifiez qu'un seul élément délimité lorsque son rayon d'impact et son chemin de récupération sont compris.

Les concepts importants incluent la surveillance kubectl, les alertes, les métriques, les tableaux de bord et la réponse aux incidents. L'espace de noms, le pod et le déploiement apparaissent lorsqu'ils affectent les prérequis, la compatibilité, la sécurité, l'observabilité ou la récupération.

Vérification Kubernetes pratique : commencez par kubectl get pods -o wide, puis kubectl describe pod <nom>, kubectl logs <nom> --previous et kubectl rollout status deployment/<nom>.

Gardez le test local petit. Appliquez un seul manifeste, inspectez les ressources générées et vérifiez le trafic avec kubectl port-forward ou un type de service local avant de passer à un équilibreur de charge cloud ou à un contrôleur d'entrée.

Configurer une règle d'alerte Prometheus en toute sécurité

Supposons que vous vouliez ajouter une alerte Prometheus pour les pods bloqués dans CrashLoopBackOff. Le chemin sûr est :

1. Observez l'état actuel : Avant de modifier quoi que ce soit, voyez si un pod est déjà en train de planter :

    kubectl get pods --all-namespaces --field-selector=status.phase=Running

Filtrez pour les redémarrages :

    kubectl get pods --all-namespaces | awk '$4 > 0 {print $1, $2, $4}'

Cette commande liste les pods avec un nombre de redémarrages supérieur à zéro. Notez la sortie :

    kube-system   coredns-64897985d-4x2g2   1
    default       nginx-deployment-7c79c4bd97-9f8pk   3

Cela vous indique quels pods sont déjà dans une boucle de redémarrage.

1. Identifiez l'emplacement du fichier de règle d'alerte. Supposons que Prometheus soit déployé via le chart Helm kube-prometheus-stack. Les règles se trouvent dans une ConfigMap dans l'espace de noms de surveillance. Listez les ConfigMaps :

    kubectl get configmap -n monitoring | grep rules

Exemple de sortie :

    prometheus-kube-prometheus-alertmanager-rules   1      28d
    prometheus-kube-prometheus-prometheus-rulefiles-0   1      28d

1. Effectuez un changement minimal. Au lieu de modifier la ConfigMap en direct, créez un nouveau fichier de règles ou modifiez une copie de test. Par exemple, créez un fichier local crashloop-alert.yaml :

    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: custom-alert-rules
      namespace: monitoring
    data:
      crashloop.rules: |
        groups:
        - name: pod-crashloop
          rules:
          - alert: PodCrashLooping
            expr: increase(kube_pod_container_status_restarts_total[10m]) > 0
            for: 5m
            labels:
              severity: warning
            annotations:
              summary: "Pod {{ $labels.namespace }}/{{ $labels.pod }} est en boucle de crash"
              description: "Le conteneur {{ $labels.container }} a redémarré {{ $value }} fois au cours des 10 dernières minutes."

1. Appliquez et vérifiez la ConfigMap sans perturber les règles existantes :

    kubectl apply -f crashloop-alert.yaml

Vérifiez :

    kubectl get configmap custom-alert-rules -n monitoring -o yaml

Confirmez que le fichier de règles apparaît sous data.

1. Vérifiez que Prometheus prend en compte la règle. Si vous utilisez l'opérateur Prometheus, il recharge automatiquement les règles à partir des ConfigMaps correctement étiquetées. Vous pouvez vérifier l'interface utilisateur ou l'API de Prometheus :

    kubectl port-forward -n monitoring svc/prometheus-kube-prometheus-prometheus 9090:9090

Ouvrez ensuite http://localhost:9090/alerts dans un navigateur. Votre nouvelle alerte devrait apparaître dans la liste, initialement inactive.

1. Déclenchez une alerte de test. Pour vérifier que l'alerte fonctionne, déployez un pod qui plante dans un espace de noms de test :

    kubectl create namespace test-alert
    kubectl run crashpod --image=busybox --restart=Never --command -- sh -c 'exit 1'

Attendez quelques minutes et vérifiez la page des alertes de Prometheus ou interrogez l'état de l'alerte via l'API :

    curl -s http://localhost:9090/api/v1/alerts | jq '.data.alerts[] | select(.labels.alertname=="PodCrashLooping")'

Vous devriez voir l'alerte passer à pending puis à firing.

1. Nettoyez : Supprimez le pod de test et l'espace de noms après vérification.

    kubectl delete namespace test-alert

Vérification et diagnostic

La vérification et le diagnostic sont au cœur de la surveillance kubectl. Vous devez savoir si un symptôme observé est réel, ce qui l'a causé et si une correction a fonctionné.

Pour la surveillance kubectl, la vérification et le diagnostic doivent nommer le composant concerné, la plage de versions prise en charge, les prérequis, une observation en lecture seule, le changement minimal justifié et la commande ou le signal qui vérifie le résultat.

Séparez l'observation de l'intervention. Capturez d'abord l'état actuel et les horodatages, protégez les informations d'identification et le matériel privé, puis ne modifiez qu'un seul élément délimité lorsque son rayon d'impact et son chemin de récupération sont compris.

Les concepts importants incluent la surveillance kubectl, les alertes, les métriques, les tableaux de bord et la réponse aux incidents. Les domaines connexes tels que l'espace de noms, le pod et le déploiement sont inclus lorsqu'ils affectent les prérequis, la compatibilité, la sécurité, l'observabilité ou la récupération.

Vérification pratique : commencez par kubectl get pods -o wide, puis kubectl describe pod <nom>, kubectl logs <nom> --previous et kubectl rollout status deployment/<nom>.

Gardez les tests locaux petits. Appliquez un seul manifeste, inspectez les ressources, vérifiez le trafic avec kubectl port-forward ou un service local avant de passer aux équilibreurs de charge cloud ou aux contrôleurs d'entrée.

Diagnostiquer un déploiement échoué

Parcourons un scénario réaliste : votre déploiement web-app dans l'espace de noms production ne devient pas prêt.

1. Obtenez un aperçu rapide :

    kubectl get pods -n production -l app=web-app

La sortie montre un pod en CrashLoopBackOff :

    NAME                        READY   STATUS             RESTARTS   AGE
    web-app-7c9f8b6d4-abcde    0/1     CrashLoopBackOff   6          5m
    web-app-7c9f8b6d4-fghij    1/1     Running            0          5m

1. Décrivez le pod qui plante pour voir les événements et l'état du conteneur :

    kubectl describe pod web-app-7c9f8b6d4-abcde -n production

Cherchez la section Events en bas. Exemple d'événement qui indique un problème de tirage d'image :

    Warning  Failed     5m    kubelet            Failed to pull image "myrepo/web-app:latest": rpc error: code = NotFound desc = failed to pull and unpack image

Ou une mise à mort OOM :

    Warning  BackOff    4m    kubelet            Back-off restarting failed container
    Normal   Killing    4m    kubelet            Container web-app failed liveness probe, will be restarted

1. Vérifiez les journaux précédents si le conteneur a redémarré avant que vous puissiez capturer sa sortie :

    kubectl logs web-app-7c9f8b6d4-abcde -n production --previous

Exemple de ligne de journal indiquant une variable d'environnement manquante :

    ERROR: DATABASE_URL environment variable is not set

1. Vérifiez le statut du déploiement :

    kubectl rollout status deployment/web-app -n production

Si le déploiement est bloqué, vous pouvez voir :

    Waiting for deployment "web-app" rollout to finish: 1 out of 2 new replicas have been updated...

Utilisez kubectl rollout history deployment/web-app -n production pour voir les révisions précédentes.

1. Vérifiez l'utilisation des ressources si metrics-server est disponible :

    kubectl top pods -n production -l app=web-app

La sortie peut montrer une utilisation mémoire élevée :

    NAME                        CPU(cores)   MEMORY(bytes)
    web-app-7c9f8b6d4-abcde    10m          350Mi
    web-app-7c9f8b6d4-fghij    5m           120Mi

Si la limite mémoire du pod est de 300Mi, le premier pod est proche de sa limite. Vérifiez les limites :

    kubectl get pod web-app-7c9f8b6d4-abcde -n production -o jsonpath='{.spec.containers[*].resources}'

Exemple de sortie :

    {"limits":{"cpu":"500m","memory":"300Mi"},"requests":{"cpu":"100m","memory":"150Mi"}}

1. Confirmez le diagnostic : Le pod plante parce que la variable d'environnement de l'URL de la base de données est manquante (d'après les journaux) et/ou la limite mémoire est trop basse (d'après top). Vérifiez en examinant l'environnement du déploiement :

    kubectl get deployment web-app -n production -o yaml | grep -A5 env:

Vous pouvez constater qu'il n'y a pas d'entrée DATABASE_URL. Ou vérifiez la ConfigMap/Secret référencée. C'est une vérification en lecture seule qui isole la cause racine avant de faire des changements.

Modes de défaillance et récupération

Même avec une surveillance attentive, des défaillances surviennent. Les modes de défaillance et la récupération doivent nommer le composant concerné, la plage de versions prise en charge, les prérequis, une observation en lecture seule, le changement minimal justifié et la commande ou le signal qui vérifie le résultat.

Séparez l'observation de l'intervention. Capturez d'abord l'état actuel et les horodatages, protégez les informations d'identification et le matériel privé, puis ne modifiez qu'un seul élément délimité lorsque son rayon d'impact et son chemin de récupération sont compris.

Les concepts importants incluent la surveillance kubectl, les alertes, les métriques, les tableaux de bord et la réponse aux incidents. L'espace de noms, le pod et le déploiement sont inclus lorsqu'ils affectent les prérequis, la compatibilité, la sécurité, l'observabilité ou la récupération.

Vérification pratique : commencez par kubectl get pods -o wide, puis kubectl describe pod <nom>, kubectl logs <nom> --previous et kubectl rollout status deployment/<nom>.

Gardez les tests locaux petits. Appliquez un seul manifeste, inspectez les ressources, vérifiez le trafic avec kubectl port-forward ou un service local avant de passer aux équilibreurs de charge cloud ou aux contrôleurs d'entrée.

Modes de défaillance courants et étapes de récupération

Exemple de récupération : corriger un CrashLoopBackOff

En reprenant le diagnostic précédent, supposons que le pod web-app-7c9f8b6d4-abcde soit en boucle de crash parce que DATABASE_URL est manquante. Étapes de récupération :

1. Ajoutez la variable d'environnement au déploiement. Utilisez kubectl edit deployment web-app -n production ou appliquez un correctif :

    kubectl set env deployment/web-app -n production DATABASE_URL=postgres://user:[email protected]:5432/webdb

Ou si la valeur est dans un secret :

    kubectl set env deployment/web-app -n production --from=secret/db-secret --keys=DATABASE_URL

Remarque : Ne mettez jamais de secrets en texte brut dans la ligne de commande si vous pouvez l'éviter. Utilisez une référence de secret.

1. Vérifiez que le déploiement déclenche de nouveaux pods :

    kubectl rollout status deployment/web-app -n production

Attendez le message de succès :

    deployment "web-app" successfully rolled out

1. Vérifiez que le nouveau pod fonctionne et ne redémarre pas :

    kubectl get pods -n production -l app=web-app

La sortie doit montrer tous les pods avec RESTARTS restant à 0 ou n'augmentant pas :

    NAME                        READY   STATUS    RESTARTS   AGE
    web-app-7c9f8b6d4-abcde    1/1     Running   0          2m
    web-app-7c9f8b6d4-fghij    1/1     Running   0          26m

1. Vérifiez les journaux pour confirmer que l'application a démarré correctement :

    kubectl logs web-app-7c9f8b6d4-abcde -n production | tail -20

Cherchez des messages de démarrage réussis, par exemple Connected to database, Server started on port 8080.

1. Vérifiez les points de terminaison du service si applicable :

    kubectl get endpoints web-app-service -n production

Devrait lister les IP des pods et le port.

1. Documentez la récupération dans votre journal d'incident : ce qui a été observé, ce qui a changé, comment vérifié, et tout suivi (par exemple, ajouter une alerte pour les boucles de crash).

Liste de contrôle opérationnelle

Une liste de contrôle garantit une surveillance et une récupération cohérentes sans dépendre de la mémoire. Pour les opérations, vous devez nommer le composant concerné, la plage de versions prise en charge, les prérequis, une observation en lecture seule, le changement minimal justifié et la commande ou le signal qui vérifie le résultat.

Séparez l'observation de l'intervention. Capturez d'abord l'état actuel et les horodatages, protégez les informations d'identification et le matériel privé, puis ne modifiez qu'un seul élément délimité lorsque son rayon d'impact et son chemin de récupération sont compris.

Les concepts importants incluent la surveillance kubectl, les alertes, les métriques, les tableaux de bord et la réponse aux incidents. L'espace de noms, le pod et le déploiement sont inclus lorsqu'ils affectent les prérequis, la compatibilité, la sécurité, l'observabilité ou la récupération.

Vérification pratique : commencez par kubectl get pods -o wide, puis kubectl describe pod <nom>, kubectl logs <nom> --previous et kubectl rollout status deployment/<nom>.

Gardez les tests locaux petits. Appliquez un seul manifeste, inspectez les ressources, vérifiez le trafic avec kubectl port-forward ou un service local avant de passer aux équilibreurs de charge cloud ou aux contrôleurs d'entrée.

Liste de contrôle quotidienne de surveillance

Exécutez ces commandes au début d'un quart de surveillance ou après tout changement de cluster. Remplacez les espaces réservés par vos noms réels d'espace de noms et de déploiement.

1. Aperçu de la santé du cluster :

    kubectl get nodes

Vérifiez que tous les nœuds sont Ready. Si un nœud est NotReady, exécutez :

    kubectl describe node <nom-du-nœud>

Cherchez les conditions et événements, par exemple Kubelet stopped posting node status.

1. Statut des pods dans tous les espaces de noms :

    kubectl get pods --all-namespaces --field-selector=status.phase!=Running,status.phase!=Succeeded

Cela montre les pods qui ne sont pas dans un état sain (Pending, Failed, Unknown). Enquêtez sur toute sortie.

1. Statut du déploiement pour les applications critiques :

    kubectl rollout status deployment/<nom> -n <espace-de-noms>

Remplacez par vos noms de déploiement réels, par exemple kubectl rollout status deployment/web-app -n production.

1. Vérifiez les événements pour les avertissements récents :

    kubectl get events --all-namespaces --sort-by='.lastTimestamp' | tail -20

Ou filtrez pour les avertissements :

    kubectl get events --all-namespaces --field-selector type=Warning --sort-by='.lastTimestamp'

1. Utilisation des ressources (si metrics-server est installé) :

    kubectl top nodes
    kubectl top pods --all-namespaces --sort-by=memory

Cherchez les nœuds ou les pods dépassant 80 % de la capacité.

1. Statut des alertes dans Prometheus (si configuré) :

    kubectl port-forward -n monitoring svc/prometheus-kube-prometheus-prometheus 9090:9090
    # puis interrogez http://localhost:9090/api/v1/alerts

Ou utilisez curl :

    curl -s http://localhost:9090/api/v1/alerts | jq '.data.alerts[] | select(.state=="firing")'

Liste de contrôle de réponse aux incidents

Lorsqu'une alerte se déclenche ou qu'un utilisateur signale un problème, suivez cette liste ordonnée.

1. Accusez réception et enregistrez l'heure dans votre outil de gestion des incidents. Exemple d'entrée : 2025-08-01T14:23:00Z - Received alert PodCrashLooping for namespace=production, pod=web-app-abcde.

1. Isolez le rayon d'impact : Quel espace de noms, quel service, combien d'utilisateurs affectés ? Exemple de commande :

    kubectl get pods -n production -o wide

Déterminez s'il s'agit d'un seul pod ou de toutes les répliques.

1. Collectez des preuves (en lecture seule) avant de modifier quoi que ce soit :

    kubectl describe pod <nom-du-pod> -n production > incident-<horodatage>-describe.txt
    kubectl logs <nom-du-pod> -n production --previous > incident-<horodatage>-logs.txt
    kubectl get events -n production --sort-by='.lastTimestamp' > incident-<horodatage>-events.txt

1. Formez une hypothèse basée sur les preuves. Par exemple : « Le pod est en boucle de crash en raison de la variable d'environnement DATABASE_URL manquante, comme le montrent les journaux. »

1. Appliquez la plus petite correction (avec approbation si nécessaire). Exemple :

    kubectl set env deployment/web-app -n production --from=secret/db-secret --keys=DATABASE_URL

1. Vérifiez la récupération :

    kubectl rollout status deployment/web-app -n production
    kubectl get pods -n production -l app=web-app

Assurez-vous que les pods sont Running et que les redémarrages n'augmentent pas.

1. Documentez la cause racine et la prévention. Exemple : « Cause racine : variable d'environnement manquante dans la spécification du déploiement. Prévention : ajouter une vérification CI pour valider les variables d'environnement du déploiement par rapport à la liste requise. Ajouter une alerte pour les boucles de crash comme fait dans le chemin de configuration sûr. »

Conclusion

La surveillance et les alertes avec kubectl, illustrées par des exemples pratiques, ne sont utiles que si chaque recommandation est limitée à une version, observable et réversible là où la technologie le permet. Copier une commande sans vérifier les prérequis et la sortie attendue n'est pas une procédure d'exploitation.

Comme prochaine étape, choisissez une vérification à faible risque pour la surveillance kubectl, enregistrez l'état actuel, exécutez le contrôle documenté, comparez le résultat avec le signal attendu et examinez les dépendances telles que l'espace de noms, le pod et le déploiement.

Un flux de travail technique fiable rend les défaillances visibles, protège les valeurs sensibles, limite les changements à la ressource prévue et définit la vérification de récupération avant qu'un incident ne force la décision.

Mettez en œuvre la liste de contrôle quotidienne de surveillance et le chemin de configuration sûr pour les règles d'alerte. Testez votre réponse aux incidents avec un pod de crash simulé. Ensuite, étendez-vous aux métriques personnalisées et aux tableaux de bord à mesure que votre confiance grandit.