Liste de contrôle des opérations de production Kube-Proxy : exemples pratiques pour des clusters fiables

Introduction

Kube-proxy est le cheval de trait qui implémente les services Kubernetes sur chaque nœud. Lorsqu'il est mal configuré ou en mauvaise santé, les pods peuvent continuer à fonctionner, mais le trafic cesse de circuler au bon endroit. Cet article fournit une liste de contrôle axée sur la production pour exploiter kube-proxy en toute sécurité : de l'inventaire des versions et de la topologie, en passant par la configuration, la vérification, les diagnostics et la récupération. Chaque section comprend des commandes concrètes, les résultats attendus et les signaux de défaillance, afin que vous puissiez passer d'un symptôme observé à une correction vérifiée.

Ce guide est destiné aux ingénieurs de plateforme, aux consultants DevOps et aux fondateurs techniques qui doivent maintenir kube-proxy en production sans approximation. Il met l'accent sur la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des espaces réservés au lieu de secrets, vérifier les résultats et documenter les chemins de récupération.

Vous apprendrez à :

• Identifier la version et le mode installés de kube-proxy (iptables, IPVS, etc.)
• Inspecter et modifier la configuration en toute sécurité sur les nœuds en direct
• Vérifier que kube-proxy programme correctement les règles du plan de données
• Diagnostiquer les modes de défaillance courants tels que des endpoints manquants ou des règles obsolètes
• Utiliser une liste de contrôle de type runbook pour réduire le temps moyen de récupération

Tous les exemples supposent un cluster Kubernetes exécutant la version 1.28 ou ultérieure, avec accès kubectl et autorisation d'afficher les ressources au niveau des nœuds. Remplacez les espaces réservés comme <nom-du-nœud> et <nom-du-service> par vos valeurs réelles.

Inventaire des versions et de l'environnement

Avant de modifier quoi que ce soit, vous devez avoir une vision claire de ce qui s'exécute. Kube-proxy peut être déployé en tant que DaemonSet (courant) ou en tant que pod statique dans certaines distributions. Son comportement diffère considérablement selon la version et le mode.

1. Identifier la topologie de déploiement de kube-proxy

Tout d'abord, vérifiez si kube-proxy est géré par un DaemonSet :

kubectl get daemonset -n kube-system | grep kube-proxy

Sortie attendue sur un cluster par défaut :

kube-proxy           1         1         1       1            1           kubernetes.io/os=linux   5m2s

Si vous ne voyez aucune sortie, recherchez un pod statique :

ls /etc/kubernetes/manifests/

Recherchez un fichier nommé kube-proxy.yaml. Sur les services gérés (EKS, GKE, AKS), kube-proxy est souvent masqué à l'utilisateur ; consultez la documentation de votre fournisseur.

2. Déterminer la version et l'image de kube-proxy

Exécutez :

kubectl get daemonset kube-proxy -n kube-system -o jsonpath='{.spec.template.spec.containers[0].image}'

Exemple de sortie attendue :

registry.k8s.io/kube-proxy:v1.28.2

Vérifiez que la version est compatible avec votre plan de contrôle. Kubernetes autorise un écart de deux versions mineures pour kube-proxy. Si votre serveur API est en v1.28, kube-proxy v1.26 est la version la plus ancienne prise en charge. L'utilisation d'une version plus ancienne peut entraîner des changements d'indicateurs ou des fonctionnalités manquantes.

3. Confirmer le mode d'exécution de kube-proxy

Kube-proxy utilise l'un des trois modes principaux : iptables, ipvs ou userspace (rare). Le mode est généralement défini via l'indicateur --proxy-mode. Sur un nœud, examinez les journaux de kube-proxy :

kubectl logs -n kube-system daemonset/kube-proxy | head -20

Recherchez une ligne comme :

I0101 12:00:00.000000       1 server.go:567] "Using iptables Proxier"

Si vous voyez "Using ipvs Proxier", le mode est IPVS. Si userspace, mettez à niveau immédiatement car il est obsolète et plus lent.

Pour inspecter sans journaux, vérifiez le point de terminaison des métriques s'il est activé :

kubectl exec -n kube-system daemonset/kube-proxy -- curl -s localhost:10249/metrics | grep proxy_mode

Sortie attendue montrant le mode comme étiquette :

kubeproxy_sync_proxy_rules_duration_seconds_count{mode="iptables"} 42

4. Observation en lecture seule : vérifier la ConfigMap

La configuration de kube-proxy est souvent stockée dans une ConfigMap nommée kube-proxy dans kube-system :

kubectl get configmap kube-proxy -n kube-system -o yaml

Recherchez des champs comme mode, clusterCIDR, iptables.syncPeriod, etc. Utilisez kubectl describe pour un résumé :

kubectl describe configmap kube-proxy -n kube-system

Exemple de sortie :

Name:         kube-proxy
Namespace:    kube-system
Labels:       app=kube-proxy
Annotations:  kubeadm.kubernetes.io/component-config.hash: sha256:...

Data
====
config.conf:
----
apiVersion: kubeproxy.config.k8s.io/v1alpha1
kind: KubeProxyConfiguration
clientConnection:
  kubeconfig: /var/lib/kube-proxy/kubeconfig.conf
clusterCIDR: 10.244.0.0/16
mode: iptables

Capturez l'annotation de hachage car les modifications de la ConfigMap doivent y être reflétées.

5. Rayon d'impact et prérequis

Avant de modifier quoi que ce soit, comprenez que kube-proxy exécute un pod par nœud. La modification de sa ConfigMap ou de la spécification du DaemonSet déclenche un redémarrage progressif sur tous les nœuds, ce qui peut perturber le trafic des services pendant quelques secondes. Pour une modification sur un seul nœud, vous pouvez d'abord le cordonner et le drainer, mais pour les changements de configuration, un impact plus large est attendu. En production, planifiez les modifications pendant une fenêtre de faible trafic.

Prérequis pour un inventaire sûr : un accès au cluster avec RBAC en lecture seule est suffisant. Vous n'avez pas besoin d'autorisations d'écriture pour collecter ces informations.

Chemin de configuration sûr

Les modifications de configuration doivent suivre un processus strict : inspecter, sauvegarder, modifier un élément, vérifier et être prêt à revenir en arrière.

1. Inspecter la ConfigMap et le DaemonSet actuels

Avant de modifier, enregistrez une sauvegarde des deux ressources :

kubectl get configmap kube-proxy -n kube-system -o yaml > kube-proxy-cm-backup-$(date +%Y%m%d).yaml
kubectl get daemonset kube-proxy -n kube-system -o yaml > kube-proxy-ds-backup-$(date +%Y%m%d).yaml

Ces fichiers sont vos artefacts de restauration.

2. Identifier la modification nécessaire

Modifications sûres courantes :

• Ajuster iptables.syncPeriod de 30s à 60s pour réduire le CPU sur les nœuds avec de nombreux services (nécessite un redémarrage).
• Activer metricsBindAddress s'il est actuellement désactivé (permet le scraping Prometheus).
• Passer de iptables à ipvs pour de meilleures performances à grande échelle (nécessite des modules noyau sur le nœud et des tests minutieux).
• Mettre à jour clusterCIDR si le réseau de pods a changé.

Ne modifiez jamais plusieurs paramètres à la fois en production. Choisissez-en un seul.

3. Modifier la ConfigMap via kubectl edit ou patch

Exemple : augmenter la période de synchronisation. La ConfigMap actuelle peut contenir :

apiVersion: v1
data:
  config.conf: |-
    apiVersion: kubeproxy.config.k8s.io/v1alpha1
    kind: KubeProxyConfiguration
    iptables:
      syncPeriod: 30s
    mode: iptables
kind: ConfigMap
metadata:
  name: kube-proxy
  namespace: kube-system

Utilisez kubectl patch pour une modification ciblée :

kubectl patch configmap kube-proxy -n kube-system --type merge -p '{"data":{"config.conf":"apiVersion: kubeproxy.config.k8s.io/v1alpha1\nkind: KubeProxyConfiguration\niptables:\n  syncPeriod: 60s\nmode: iptables\n"}}'

Alternativement, utilisez kubectl edit configmap kube-proxy -n kube-system et modifiez la valeur.

4. Déclencher le déploiement et observer

Si la ConfigMap est montée dans le pod kube-proxy en tant que fichier, kube-proxy peut ne pas recharger automatiquement. Vous devez redémarrer les pods :

kubectl rollout restart daemonset kube-proxy -n kube-system

Surveillez le déploiement :

kubectl rollout status daemonset kube-proxy -n kube-system

Sortie attendue :

Waiting for daemon set "kube-proxy" rollout to finish: 0 out of 3 new pods have been updated...
Successfully rolled out!

Si vous voyez error: daemonset "kube-proxy" has timed out, examinez les journaux des pods.

5. Vérifier que la modification a pris effet

Sur un nœud, inspectez les journaux de kube-proxy après le redémarrage :

kubectl logs -n kube-system daemonset/kube-proxy --tail=30

Recherchez :

I0101 12:30:00.000000       1 config.go:315] "Using iptables Proxier"
I0101 12:30:00.000000       1 server.go:661] "Successfully set iptables sync period without needing a full resync" syncPeriod="60s"

Pour une vérification basée sur les métriques :

kubectl exec -n kube-system daemonset/kube-proxy -- curl -s localhost:10249/metrics | grep iptables_sync_period_seconds

Attendu :

# HELP kubeproxy_sync_proxy_rules_duration_seconds...

Si la période de synchronisation n'a pas changé, vérifiez l'indentation YAML de la ConfigMap et que le pod a redémarré avec le volume mis à jour.

6. Chemin de restauration

Si la modification cause des problèmes, restaurez la ConfigMap de sauvegarde et redémarrez à nouveau :

kubectl apply -f kube-proxy-cm-backup-YYYYMMDD.yaml
kubectl rollout restart daemonset kube-proxy -n kube-system

Comme vous avez sauvegardé à la fois la ConfigMap et le DaemonSet, vous pouvez également restaurer le DaemonSet si le modèle de pod a été modifié.

Vérification et diagnostics

Un kube-proxy sain signifie que le plan de données (règles iptables, tables IPVS) correspond aux services et endpoints souhaités. Cette section fournit une routine de vérification reproductible.

1. Vérifier la santé et la disponibilité des pods kube-proxy

Tous les pods doivent être en cours d'exécution et prêts :

kubectl get pods -n kube-system -l k8s-app=kube-proxy -o wide

Sortie attendue :

NAME               READY   STATUS    RESTARTS   AGE   IP           NODE
kube-proxy-abcde   1/1     Running   0          10m   10.0.0.10    node-1
kube-proxy-fghij   1/1     Running   0          10m   10.0.0.11    node-2
kube-proxy-klmno   1/1     Running   0          10m   10.0.0.12    node-3

Si un pod n'est pas prêt, vérifiez ses journaux :

kubectl logs -n kube-system kube-proxy-abcde --tail=50

Recherchez des erreurs fatales comme :

E0101 12:00:00.000000       1 server.go:321] "Failed to run proxier" err="can't set ipset"

2. Vérifier les règles iptables pour un service

Choisissez un service de test (par exemple, default/my-service). Sur un nœud où kube-proxy s'exécute, listez la chaîne iptables pertinente :

sudo iptables-save | grep -A 10 'KUBE-SVC-'

La sortie attendue comprend une chaîne pour votre service avec une IP virtuelle (ClusterIP) et des règles sautant vers les chaînes KUBE-SEP-* pour chaque endpoint.

Exemple pour un service avec ClusterIP 10.96.0.10 et deux endpoints :

-A KUBE-SERVICES -d 10.96.0.10/32 -p tcp -m comment --comment "default/my-service:http cluster IP" -m tcp --dport 80 -j KUBE-SVC-XXXXXXXXXXXXXXXX
-A KUBE-SVC-XXXXXXXXXXXXXXXX -m comment --comment "default/my-service:http" -m statistic --mode random --probability 0.50000000000 -j KUBE-SEP-YYYYYYYYYYYYYYYY
-A KUBE-SVC-XXXXXXXXXXXXXXXX -m comment --comment "default/my-service:http" -j KUBE-SEP-ZZZZZZZZZZZZZZZZ

Si aucune règle KUBE-SERVICES n'existe pour ce ClusterIP, kube-proxy ne synchronise pas correctement. Vérifiez les tranches d'endpoints :

kubectl get endpointslice -l kubernetes.io/service-name=my-service -n default

Si les EndpointSlices sont vides, le service n'a pas de pods prêts, ce qui n'est pas une faute de kube-proxy.

3. Vérifier les règles IPVS si en mode IPVS

Sur le nœud, exécutez :

sudo ipvsadm -Ln

La sortie attendue comprend une entrée de service virtuel :

TCP  10.96.0.10:80 rr
  -> 10.244.1.5:8080              Masq    1      0          0
  -> 10.244.2.6:8080              Masq    1      0          0

Si le service virtuel est manquant ou n'a pas de serveurs réels, kube-proxy n'a pas réussi à programmer IPVS.

4. Vérifier le point de terminaison des métriques

Si metricsBindAddress est défini (par exemple, 0.0.0.0:10249), interrogez-le depuis un pod ou via le proxy du nœud :

kubectl exec -n kube-system daemonset/kube-proxy -- curl -s http://localhost:10249/healthz

Sortie attendue : ok

Pour compter les erreurs de synchronisation :

kubectl exec -n kube-system daemonset/kube-proxy -- curl -s http://localhost:10249/metrics | grep sync_proxy_rules_last_timestamp_seconds

Recherchez un horodatage récent ; si l'horodatage est ancien, la synchronisation est bloquée.

5. Valider la connectivité de bout en bout

Depuis un pod dans le cluster, testez un nom DNS de service et un port :

kubectl run test-pod --rm -it --image=busybox --restart=Never -- sh -c 'wget -qO- http://my-service.default.svc.cluster.local'

Sortie attendue si le service renvoie une page Web : contenu HTML. Si la connexion se bloque, vérifiez kube-proxy et la disponibilité des endpoints.

Modes de défaillance et récupération

Les défaillances de kube-proxy se manifestent par des délais de connexion, des connexions refusées ou des anomalies aléatoires d'équilibrage de charge. Voici les modes de défaillance courants avec les étapes de récupération.

1. Pod kube-proxy en boucle de crash

Symptômes : kubectl get pods -n kube-system affiche CrashLoopBackOff pour les pods kube-proxy.

Diagnostic : Vérifiez les journaux :

kubectl logs -n kube-system kube-proxy-abcde --previous

Causes courantes :

• Syntaxe de ConfigMap invalide entraînant une erreur d'analyse.
• Fichier kubeconfig manquant en raison de la suppression d'un secret.
• Mémoire ou CPU insuffisants sur le nœud.
• Indicateurs incompatibles si exécution d'une version non prise en charge.

Récupération : Revenez à la dernière bonne ConfigMap de sauvegarde, puis redémarrez :

kubectl apply -f kube-proxy-cm-backup.yaml
kubectl rollout restart daemonset kube-proxy -n kube-system

Si le problème vient des ressources du nœud, cordonnez le nœud et examinez la pression mémoire :

kubectl cordon node-1
kubectl drain node-1 --ignore-daemonsets

2. ClusterIP de service inaccessible mais pods sains

Symptômes : Les journaux d'application montrent des délais de connexion vers l'IP du service, mais curl vers les IP individuelles des pods fonctionne.

Diagnostic : Vérifiez si kube-proxy s'exécute sur le nœud où le pod client s'exécute :

kubectl get pod -n kube-system -l k8s-app=kube-proxy -o wide

Si aucun kube-proxy sur ce nœud (par exemple, après un remplacement de nœud et un problème de planification du DaemonSet), cela explique la défaillance.

Récupération : Assurez-vous que le DaemonSet a les tolérances et le sélecteur de nœud corrects, puis décordez ou ajoutez le nœud :

kubectl describe daemonset kube-proxy -n kube-system | grep -A5 Tolerations

S'il manque une tolérance pour un nœud avec des teintes, ajoutez-la :

kubectl patch daemonset kube-proxy -n kube-system -p '{"spec":{"template":{"spec":{"tolerations":[{"key":"node-role.kubernetes.io/master","operator":"Exists","effect":"NoSchedule"}]}}}}'

3. Règles iptables obsolètes provoquant un mauvais routage

Symptômes : Le trafic vers un service est envoyé à un pod qui n'existe plus, ou vers le mauvais port, après une réduction d'échelle.

Diagnostic : Inspectez iptables pour la chaîne du service :

sudo iptables-save | grep KUBE-SVC-XXXXXXXXXXXXXXXX

Si vous voyez des règles KUBE-SEP-* pointant vers des IP de pods terminés, la synchronisation n'a pas eu lieu.

Récupération : Forcez une synchronisation complète en redémarrant kube-proxy :

kubectl delete pod -n kube-system -l k8s-app=kube-proxy

Cela recrée toutes les règles iptables à partir de zéro. Vérifiez après le redémarrage.

4. Mode IPVS ne fonctionnant pas en raison de modules noyau manquants

Symptômes : Les journaux du pod kube-proxy montrent des erreurs comme "can't create ipvs" ou "failed to load kernel module".

Diagnostic : Sur le nœud, vérifiez les modules noyau :

sudo lsmod | grep ip_vs

Si la sortie est vide, les modules requis sont manquants.

Récupération : Chargez les modules (temporaire) :

sudo modprobe ip_vs
sudo modprobe ip_vs_rr
sudo modprobe ip_vs_wrr
sudo modprobe ip_vs_sh

Pour la persistance, consultez la documentation de votre système d'exploitation de nœud. Alternativement, repassez temporairement en mode iptables en modifiant la ConfigMap et en redémarrant.

5. Point de terminaison des métriques inaccessible

Symptômes : Prometheus ne peut pas collecter les métriques de kube-proxy.

Diagnostic : Vérifiez si metricsBindAddress est défini :

kubectl get configmap kube-proxy -n kube-system -o yaml | grep metricsBindAddress

S'il est manquant, les métriques sont désactivées par défaut dans les versions récentes.

Récupération : Ajoutez metricsBindAddress: 0.0.0.0:10249 sous metricsBindAddress dans la ConfigMap, puis redémarrez. Remarque : exposer les métriques sur toutes les interfaces peut être un risque de sécurité ; restreignez via une politique réseau si possible.

Liste de contrôle des opérations

Utilisez ce tableau comme audit pré-vol et périodique pour kube-proxy en production. Remplacez les noms d'espace réservé par les valeurs de votre cluster.

Exécutez cette liste de contrôle mensuellement et après toute mise à niveau du plugin réseau, mise à niveau de Kubernetes ou événement de mise à l'échelle significatif.

Conclusion

Exploiter kube-proxy en production exige une observation disciplinée, une intervention minimale et une vérification fiable. Cette liste de contrôle vous donne un chemin reproductible du symptôme à la résolution : connaître votre version et votre topologie, inspecter la configuration en toute sécurité, vérifier la programmation du plan de données, diagnostiquer les défaillances courantes et récupérer avec des sauvegardes.

Points clés à retenir :

• Enregistrez toujours l'état actuel avant de modifier quoi que ce soit.
• Effectuez une modification de configuration à la fois et vérifiez son effet.
• Utilisez des commandes en lecture seule (kubectl get, logs, iptables-save, ipvsadm) pour observer.
• Conservez des sauvegardes de la ConfigMap et du DaemonSet comme points de restauration.
• Comprenez le rayon d'impact : les redémarrages de kube-proxy affectent tous les services sur un nœud.

Comme prochaine étape, choisissez une vérification à faible risque de la liste de contrôle des opérations (par exemple, vérifier le hachage de la ConfigMap ou l'horodatage de synchronisation) et exécutez-la sur votre cluster. Documentez la sortie, comparez au résultat attendu et corrigez toute divergence. Au fil du temps, construisez un runbook spécifique à votre environnement, en incorporant ces modèles et vos propres étapes de récupération.

Un flux de travail opérationnel fiable pour kube-proxy 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.