Surveillance et alertes du serveur d'API Kubernetes : un guide pratique de mise en œuvre

Introduction

Le serveur d'API Kubernetes est le composant central du plan de contrôle qui traite toutes les requêtes REST du cluster. Il valide et configure les données des objets d'API tels que les pods, les services et les déploiements. Lorsque le serveur d'API se dégrade ou tombe en panne, toutes les automatisations, les tableaux de bord et les commandes utilisateur qui dépendent de Kubernetes sont affectés. Le surveiller efficacement signifie savoir quelles métriques sont importantes, comment les collecter, comment les transformer en tableaux de bord et alertes actionnables, et comment réagir en cas de problème.

Ce guide propose une approche pratique, étape par étape, pour la surveillance du serveur d'API Kubernetes. Il couvre l'inventaire et la vérification des versions, les modifications de configuration sécurisées, la vérification et le diagnostic, les modes de défaillance et la récupération, ainsi qu'une liste de contrôle des opérations. Chaque section comprend des commandes concrètes, les sorties attendues et les critères de décision. L'accent est mis sur la sécurité opérationnelle : observer avant de changer, limiter le rayon d'impact, utiliser des paramètres fictifs au lieu de secrets, vérifier les résultats et documenter les chemins de récupération.

Cet article s'adresse aux développeurs, consultants DevOps et équipes techniques de startups qui exploitent des clusters Kubernetes et doivent surveiller efficacement le serveur d'API. Il suppose une familiarité de base avec Kubernetes et la ligne de commande.

Inventaire de la version et de l'environnement

Avant d'apporter des modifications, vous devez comprendre la version, la topologie et l'état actuel du cluster. Cette section détaille les commandes d'inventaire essentielles et explique quelles informations capturer et pourquoi elles sont importantes.

Identifier la version de Kubernetes et la topologie de déploiement

Tout d'abord, déterminez la version de Kubernetes. Le comportement du serveur d'API, les métriques disponibles et les indicateurs de configuration varient selon la version. Exécutez :

kubectl version --short

Sortie attendue (exemple pour v1.28) :

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

Si la version du serveur n'est pas affichée, assurez-vous que votre kubeconfig pointe vers le bon cluster et que vous avez un accès réseau au point de terminaison du serveur d'API.

Ensuite, identifiez comment le serveur d'API est déployé. Dans les clusters gérés (par ex., EKS, GKE, AKS), le plan de contrôle est géré par le fournisseur cloud, et vous n'avez peut-être pas directement accès au processus du serveur d'API ni à son point de terminaison de métriques. Dans les clusters autogérés, le serveur d'API s'exécute généralement comme un pod statique sur les nœuds du plan de contrôle ou comme un service systemd.

Pour vérifier si le serveur d'API est un pod statique :

kubectl get pods -n kube-system -l component=kube-apiserver

Sortie attendue si pod statique :

NAME                    READY   STATUS    RESTARTS   AGE
kube-apiserver-node1   1/1     Running   0          10d

Si aucun pod n'est listé, vérifiez s'il existe un service systemd :

systemctl status kube-apiserver

Capturer l'état observable actuel (lecture seule)

Collectez des informations de base sans rien modifier. Utilisez les commandes suivantes pour obtenir des instantanés de santé et de configuration.

Points de terminaison de santé du serveur d'API (disponibles dans Kubernetes 1.26+) :

kubectl get --raw /readyz?verbose

Cela renvoie une liste de contrôles de santé et de leurs états. Exemple de sortie :

[+]ping ok
[+]log ok
[+]etcd ok
[+]poststarthook/start-kube-apiserver-admission-initializer ok
...
readyz check passed

Pour les versions plus anciennes, utilisez /healthz :

kubectl get --raw /healthz

Sortie attendue :

ok

Point de terminaison des métriques du serveur d'API (si accessible) :

curl -k https://<api-server-ip>:6443/metrics

Si vous utilisez un cluster géré, vous devrez peut-être faire un transfert de port ou utiliser l'intégration de surveillance du fournisseur cloud.

Enregistrez les éléments suivants dans votre inventaire :

• Version de Kubernetes (client et serveur)
• Méthode de déploiement du serveur d'API (pod statique, systemd, géré)
• Noms et adresses IP des nœuds du plan de contrôle
• Sortie du point de terminaison de santé
• Indicateurs de configuration pertinents (voir la section suivante pour savoir comment les récupérer)
• Horodatage de la collecte des données

Prérequis et rayon d'impact des modifications

Avant d'apporter toute modification de configuration, confirmez :

• Vous avez un accès kubectl avec des privilèges cluster-admin ou équivalents.
• Vous pouvez accéder aux nœuds du plan de contrôle (pour les clusters autogérés).
• Vous avez un plan de retour en arrière : pour les pods statiques, le kubelet redémarre le serveur d'API si le manifeste change ; pour les clusters gérés, les modifications de configuration passent généralement par l'API du fournisseur.
• Vous êtes conscient du rayon d'impact : modifier les indicateurs du serveur d'API affecte l'ensemble du cluster. Testez toujours dans un environnement de préproduction d'abord, si possible.

Exemple d'inventaire de version et d'environnement

Supposons que vous ayez un cluster autogéré en v1.28, avec un nœud de plan de contrôle. Vous exécutez les commandes d'inventaire et enregistrez :

• Version du serveur : v1.28.2
• Pod du serveur d'API : kube-apiserver-node1 dans kube-system
• La sortie de /readyz?verbose montre tous les contrôles réussis sauf etcd qui affiche un avertissement (latence supérieure au seuil).
• Les indicateurs du manifeste du pod statique incluent --etcd-servers=https://127.0.0.1:2379 et --audit-log-path=/var/log/kube-apiserver-audit.log.

Cette base de référence est essentielle avant tout réglage.

Chemin de configuration sécurisé

Cette section décrit comment examiner et ajuster en toute sécurité la configuration du serveur d'API, en se concentrant sur les indicateurs liés aux métriques et à la surveillance.

Examiner la configuration actuelle du serveur d'API

Pour afficher les indicateurs de ligne de commande du serveur d'API, inspectez le manifeste du pod statique (pour les clusters autogérés) :

sudo cat /etc/kubernetes/manifests/kube-apiserver.yaml

Recherchez les indicateurs liés à la surveillance et aux métriques. Les plus courants sont :

• --metrics-bind-address : adresse IP sur laquelle servir les métriques (par défaut 127.0.0.1).
• --metrics-port : port pour les métriques (par défaut 6443 ? En fait, les métriques sont servies sur le port sécurisé par défaut, mais il existe un --metrics-port distinct pour le point de terminaison de métriques non sécurisé dans les anciennes versions ; dans les versions plus récentes, les métriques sont disponibles à /metrics sur le port sécurisé).
• --audit-log-path et les indicateurs de politique d'audit : pour la journalisation d'audit, précieuse pour la surveillance de la sécurité.
• --profiling : active les points de terminaison de profilage, utiles pour le débogage mais pouvant exposer des informations sensibles s'ils ne sont pas sécurisés.

Pour les clusters gérés, utilisez la commande ou la console du fournisseur pour afficher la configuration équivalente.

Modifier l'exposition des métriques en toute sécurité

Si vous devez exposer les métriques à Prometheus ou à un autre collecteur, assurez-vous que les métriques du serveur d'API sont accessibles. Par défaut, dans de nombreux clusters, le serveur d'API sert les métriques sur le même port sécurisé (6443) à /metrics. Cependant, si vous devez changer l'adresse de liaison ou activer un point de terminaison de métriques non sécurisé distinct (non recommandé pour la sécurité), vous devez modifier le manifeste.

Exemple de scénario : vous voulez que Prometheus collecte les métriques sans utiliser de certificats client. Vous pourriez activer le point de terminaison de métriques non sécurisé sur un port spécifique (par ex., 8080) lié à localhost ou à une interface réseau. Cependant, c'est un risque de sécurité. Une meilleure approche consiste à configurer Prometheus avec une authentification et un TLS appropriés.

Exemple de modification sécurisée :

Supposons que le serveur d'API n'ait actuellement aucun --metrics-bind-address explicite. Pour rendre les métriques disponibles uniquement sur l'adresse IP interne d'un nœud de plan de contrôle spécifique pour Prometheus, ajoutez l'indicateur au manifeste :

spec:
  containers:
  - command:
    - kube-apiserver
    - --metrics-bind-address=192.168.1.10
    # autres indicateurs

Ensuite, le kubelet redémarre automatiquement le pod. Vérifiez toujours la modification en contrôlant l'état du pod et le point de terminaison des métriques.

Prérequis :

• Accès au nœud du plan de contrôle.
• Sauvegarde du fichier manifeste existant.

Rayon d'impact :

• Si l'adresse IP est inaccessible ou incorrecte, la collecte des métriques échoue (mais le serveur d'API continue de traiter les requêtes API normales).
• Si l'adresse de liaison est changée pour une interface publique sans règles de pare-feu, les métriques pourraient être exposées.

Vérification :

Vérifiez l'état du pod :

kubectl get pods -n kube-system -l component=kube-apiserver

Assurez-vous que le pod redémarre et est en cours d'exécution. Testez ensuite le point de terminaison :

curl -k https://192.168.1.10:6443/metrics | head -n 5

La sortie attendue comprend des lignes telles que :

# HELP apiserver_request_total Counter of apiserver requests broken out for each verb, dry run value, group, version, resource, scope, component, and HTTP response code.
# TYPE apiserver_request_total counter

Récupération :

Si le pod ne démarre pas, revenez à la modification du manifeste et restaurez la sauvegarde. Consultez les journaux :

kubectl logs -n kube-system <apiserver-pod-name>

Recherchez les erreurs indiquant une valeur d'indicateur invalide ou une adresse déjà utilisée.

Activer et configurer la journalisation d'audit (optionnel mais important)

Les journaux d'audit fournissent un enregistrement détaillé des requêtes API, précieux pour la surveillance et les enquêtes sur les incidents. Pour activer la journalisation d'audit, vous devez définir les indicateurs de politique d'audit et de chemin de journalisation.

Exemple d'ajout au manifeste du serveur d'API :

- --audit-log-path=/var/log/kube-apiserver-audit.log
- --audit-policy-file=/etc/kubernetes/audit-policy.yaml
- --audit-log-maxage=30
- --audit-log-maxbackup=10
- --audit-log-maxsize=100

Vous devez également créer le fichier de politique d'audit. Une politique minimale qui journalise les métadonnées de toutes les requêtes au niveau Metadata :

apiVersion: audit.k8s.io/v1
kind: Policy
rules:
- level: Metadata

Placez ce fichier sur le nœud du plan de contrôle à /etc/kubernetes/audit-policy.yaml et assurez-vous que le pod du serveur d'API peut le lire (souvent en montant un volume hostPath).

Vérification :

Après le redémarrage du pod, vérifiez que le fichier journal est créé et reçoit des entrées :

sudo tail -f /var/log/kube-apiserver-audit.log

Vous devriez voir des lignes JSON avec les détails des requêtes.

Récupération :

Si le serveur d'API ne démarre pas, examinez les journaux pour des erreurs telles qu'une politique d'audit invalide ou des problèmes de permissions. Corrigez ou supprimez les indicateurs.

Vérification et diagnostic

Maintenant que le serveur d'API fonctionne et que les métriques sont exposées, vous devez vérifier que la surveillance fonctionne et être capable de diagnostiquer les problèmes.

Vérifier la collecte des métriques

Si vous utilisez Prometheus, vérifiez que votre configuration de collecte inclut le serveur d'API. Tâche Prometheus typique pour le serveur d'API Kubernetes :

- job_name: 'kubernetes-apiservers'
  kubernetes_sd_configs:
  - role: endpoints
  scheme: https
  tls_config:
    ca_file: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
  bearer_token_file: /var/run/secrets/kubernetes.io/serviceaccount/token
  relabel_configs:
  - source_labels: [__meta_kubernetes_namespace, __meta_kubernetes_service_name, __meta_kubernetes_endpoint_port_name]
    action: keep
    regex: default;kubernetes;https

Cela suppose que le serveur d'API est exposé via le service kubernetes dans l'espace de noms default. Vérifiez que Prometheus le collecte :

curl -s 'http://prometheus:9090/api/v1/targets' | jq '.data.activeTargets[] | select(.labels.job=="kubernetes-apiservers") | {health, lastError, scrapeUrl}'

Sortie attendue (sain) :

{
  "health": "up",
  "lastError": "",
  "scrapeUrl": "https://10.96.0.1:443/metrics"
}

Si l'état est « down », vérifiez la connectivité réseau, les certificats TLS et les permissions du jeton de compte de service.

Métriques clés pour le diagnostic

Voici les métriques critiques du serveur d'API à surveiller et ce qu'elles indiquent :

Commandes de diagnostic et sorties attendues

Utilisez les commandes suivantes pour interroger ces métriques directement depuis le serveur d'API (si vous y avez accès) ou via Prometheus.

Vérifier les requêtes en cours :

curl -k -s https://<api-server-ip>:6443/metrics | grep apiserver_current_inflight_requests

Sortie attendue :

# HELP apiserver_current_inflight_requests Maximal number of currently used inflight request limit of this apiserver per request kind in last second.
# TYPE apiserver_current_inflight_requests gauge
apiserver_current_inflight_requests{requestKind="mutating"} 2
apiserver_current_inflight_requests{requestKind="readOnly"} 5

Si le nombre de requêtes de mutation est proche de la limite (200 par défaut), le serveur d'API peut être soumis à une forte charge d'écriture.

Vérifier les percentiles de latence des requêtes :

Via Prometheus :

histogram_quantile(0.99, sum(rate(apiserver_request_duration_seconds_bucket{job="kubernetes-apiservers"}[5m])) by (le, resource, verb))

Cela renvoie la latence au 99e percentile par ressource et verbe. Si le p99 dépasse votre SLO (par ex., 1 seconde), enquêtez.

Vérifier la latence d'etcd :

histogram_quantile(0.99, sum(rate(etcd_request_duration_seconds_bucket[5m])) by (le, operation))

Si la latence p99 d'etcd est élevée, le serveur d'API sera lent.

Dépannage des problèmes courants

• Latence élevée du serveur d'API : Vérifiez la santé et la latence d'etcd, le taux de requêtes du serveur d'API et l'utilisation des ressources du nœud (CPU, mémoire). Vérifiez également si le serveur d'API est configuré avec --max-requests-inflight trop élevé.
• Utilisation de la mémoire du serveur d'API en croissance : Pourrait être une fuite de mémoire ou trop de flux de surveillance. Vérifiez apiserver_longrunning_gauge et apiserver_registered_watchers.
• Réponses 5xx fréquentes : Vérifiez les journaux du serveur d'API et les métriques comme apiserver_request_total{code="500"}. Vérifiez également la disponibilité d'etcd.

Modes de défaillance et récupération

Cette section couvre les scénarios de défaillance courants du serveur d'API Kubernetes et comment s'en remettre.

Mode de défaillance : CrashLoopBackOff du pod du serveur d'API

Symptômes :

• kubectl get pods -n kube-system montre le pod du serveur d'API redémarrant à plusieurs reprises.
• L'état du pod est CrashLoopBackOff.
• kubectl get --raw /readyz échoue.

Diagnostic :

Consultez les journaux du pod :

kubectl logs -n kube-system <apiserver-pod> --previous

Causes courantes :

• Indicateur de configuration invalide (par ex., URL etcd incorrecte, nom de plugin d'admission erroné).
• Certificat expiré ou manquant.
• Permissions insuffisantes sur les fichiers montés (par ex., chemin du journal d'audit non accessible en écriture).
• Contraintes de ressources (limite de mémoire trop basse).

Récupération :

Pour les pods statiques, vérifiez le fichier manifeste sur le nœud du plan de contrôle. Assurez-vous que la syntaxe et les valeurs sont correctes. Si vous avez récemment modifié un indicateur, revenez en arrière. Si les certificats sont expirés, renouvelez-les avec kubeadm certs renew (si vous utilisez kubeadm) ou la méthode appropriée.

Exemple : revenir sur un mauvais indicateur en éditant /etc/kubernetes/manifests/kube-apiserver.yaml et en supprimant ou corrigeant l'indicateur. Le kubelet redémarre le pod. Vérifiez ensuite que le pod est en cours d'exécution et que les points de terminaison de santé fonctionnent.

Mode de défaillance : Serveur d'API inaccessible (pas de redémarrage du pod)

Symptômes :

• Le pod du serveur d'API fonctionne, mais les requêtes API expirent.
• Le point de terminaison de santé peut ou non répondre.

Diagnostic :

Vérifiez l'utilisation du CPU et de la mémoire du processus du serveur d'API sur le nœud :

top -p <pid>

Consultez les journaux système pour les tueries OOM ou autres événements :

journalctl -u kubelet | grep -i apiserver

Vérifiez la disponibilité d'etcd :

ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2379 --cacert=/etc/kubernetes/pki/etcd/ca.crt --cert=/etc/kubernetes/pki/etcd/server.crt --key=/etc/kubernetes/pki/etcd/server.key endpoint health

Récupération :

Si le serveur d'API est surchargé, augmentez les limites de ressources dans le manifeste du pod (après confirmation de la capacité du nœud). Si etcd est en panne, restaurez etcd à partir d'une sauvegarde ou résolvez les problèmes de quorum etcd.

Mode de défaillance : Point de terminaison des métriques ne fonctionne pas

Symptômes :

• Prometheus ne peut pas collecter les métriques.
• curl vers /metrics renvoie 404 ou connexion refusée.

Diagnostic :

Vérifiez si le chemin des métriques est activé et correct. Dans les versions plus récentes, les métriques sont toujours disponibles à /metrics sur le port sécurisé. Si vous avez précédemment modifié --metrics-bind-address ou le port, vérifiez la valeur de l'indicateur.

Vérifiez la connectivité réseau du serveur Prometheus au serveur d'API.

Récupération :

• Si vous utilisez un port de métriques distinct, assurez-vous que le port est ouvert dans les règles de pare-feu.
• Si vous utilisez TLS, assurez-vous que les certificats sont valides.
• Ajustez la configuration de collecte Prometheus si le point de terminaison a changé.

Mode de défaillance : Le journal d'audit remplit le disque

Symptômes :

• Le pod du serveur d'API peut être expulsé ou le nœud subit une pression de disque.
• La taille du fichier journal d'audit dépasse la limite.

Diagnostic :

Vérifiez l'utilisation du disque :

df -h /var/log

Vérifiez la taille du journal d'audit :

ls -lh /var/log/kube-apiserver-audit.log

Récupération :

• Faites pivoter le journal manuellement : sudo logrotate -f /etc/logrotate.d/kube-apiserver-audit (si configuré).
• Augmentez --audit-log-maxsize et --audit-log-maxbackup si nécessaire.
• Envisagez d'expédier les journaux vers un système externe pour éviter de remplir le disque.

Liste de contrôle des opérations

Cette liste de contrôle résume les principales tâches de surveillance et d'alerte pour le serveur d'API Kubernetes. Elle inclut les responsables et les fréquences de révision.

Contrôles quotidiens (automatisés via des alertes)

• Disponibilité du serveur d'API : Surveillez le point de terminaison /readyz. Alertez s'il ne répond pas pendant plus de 2 minutes.
• Responsable : SRE de garde (rotation).
• Révision : Revue d'incident après déclenchement de l'alerte.
• Taux d'erreur du serveur d'API : Alertez sur sum(rate(apiserver_request_total{code=~"5.."}[5m])) / sum(rate(apiserver_request_total[5m])) > 0.01 (taux d'erreur de 1 % sur 5 minutes).
• Responsable : Responsable de l'équipe plateforme (Priya Shah).
• Révision : Revue hebdomadaire des métriques.
• Latence du serveur d'API : Alertez sur une latence p99 > 1 seconde pendant 10 minutes.
• Responsable : Ingénieur plateforme API (Carlos Mendes).
• Révision : Revue mensuelle des SLO.
• Latence etcd : Alertez sur une durée de requête etcd p99 > 500 ms pendant 5 minutes.
• Responsable : Ingénieure fiabilité des bases de données (Aisha Khan).
• Révision : Hebdomadaire.
• Requêtes en vol proches de la limite : Alertez lorsque apiserver_current_inflight_requests > 80 % de la limite pendant 5 minutes.
• Responsable : Administrateur de cluster (David Lee).
• Révision : Revue de capacité hebdomadaire.

Contrôles hebdomadaires

• Examinez les tendances des métriques du serveur d'API : taux de requêtes, latence, taux d'erreur, nombre de surveillances.
• Assurez-vous que les journaux d'audit sont générés et archivés correctement.
• Vérifiez que les cibles de collecte Prometheus sont saines.
• Vérifiez s'il y a eu des redémarrages de pod du serveur d'API au cours des 7 derniers jours.

Contrôles mensuels

• Révisez les seuils d'alerte et ajustez-les en fonction des modèles de trafic réels.
• Testez la reprise après sinistre : simulez une défaillance du serveur d'API dans un cluster de préproduction et pratiquez les procédures de récupération.
• Faites tourner les certificats s'ils approchent de l'expiration (vérifiez avec kubeadm certs check-expiration).
• Révisez les permissions RBAC pour les outils de surveillance et les utilisateurs.

Pièges courants et comment les éviter

1. Ignorer la surveillance d'etcd : Le serveur d'API dépend fortement d'etcd. Si etcd est lent, le serveur d'API est lent. Surveillez toujours etcd en même temps que le serveur d'API.

• Éviter : Mettez en place des tableaux de bord et des alertes etcd.

1. Fatigue des alertes due à des seuils trop sensibles : Définir des alertes de latence trop basses (par ex., p99 à 100 ms) peut déclencher des faux positifs. Basez les seuils sur les SLO réels et les mesures de référence.

• Éviter : Mesurez la référence pendant 2 à 4 semaines avant de finaliser les seuils d'alerte.

1. Ne pas sécuriser les points de terminaison des métriques : Exposer les métriques sans authentification ni restrictions réseau peut divulguer des données sensibles (par ex., les URI des requêtes). Utilisez toujours TLS et l'authentification pour les points de terminaison de métriques.

• Éviter : Utilisez RBAC Kubernetes et les politiques réseau.

1. Négliger les journaux d'audit : Les journaux d'audit sont essentiels pour les enquêtes de sécurité. Ne pas les activer laisse un angle mort. Activez au moins la journalisation au niveau Metadata.

• Éviter : Commencez par une politique d'audit minimale et affinez en fonction des besoins de conformité.

1. Ne pas avoir de plan de retour en arrière pour les modifications de configuration : Modifier le manifeste du serveur d'API sans sauvegarde peut entraîner un temps d'arrêt prolongé si la modification casse le serveur.

• Éviter : Sauvegardez toujours les manifestes avant de les modifier et testez les changements en préproduction.

Conclusion

La surveillance du serveur d'API Kubernetes est une pratique fondamentale pour la fiabilité du cluster. En inventoriant systématiquement votre environnement, en configurant en toute sécurité les métriques et la journalisation d'audit, en vérifiant la collecte de données et en vous préparant aux modes de défaillance, vous pouvez détecter et résoudre les problèmes avant qu'ils n'affectent les utilisateurs.

Commencez par les bases : vérifiez les points de terminaison de santé de votre serveur d'API, assurez-vous que les métriques sont collectées et configurez quelques alertes à forte valeur ajoutée. Ensuite, développez des tableaux de bord et des diagnostics avancés si nécessaire. N'oubliez pas de documenter vos configurations, de tester vos procédures de récupération et d'affiner continuellement votre surveillance en fonction des incidents réels.

Un flux de travail technique fiable rend les défaillances visibles, protège les valeurs sensibles, limite les modifications à la ressource prévue et définit la vérification de la récupération avant qu'un incident ne force la décision. Appliquez ces principes à la surveillance de votre serveur d'API Kubernetes et vous disposerez d'un plan de contrôle robuste et observable.