>
E-NO
EN FR
Commencer
Kube Controller Manager a... 8 min de lecture

Concepts avancés du Kube Controller Manager expliqués avec des exemples pratiques

calendar_today Publié : 2026-08-29
update Dernière mise à jour : 2026-08-29
analytics Efficacité SEO : 100%
Illustration du guide technique pour « Concepts avancés du Kube Controller Manager expliqués avec des exemples pratiques ».

Introduction

Le Kube Controller Manager est le composant du plan de contrôle Kubernetes qui exécute les boucles de contrôle principales. Il observe l'état du cluster via le serveur d'API et apporte des modifications afin de rapprocher l'état actuel de l'état souhaité. Pour les opérateurs et développeurs travaillant sur des clusters en production, comprendre ses concepts avancés est essentiel pour assurer un fonctionnement fiable, un dépannage efficace et un réglage des performances.

Cet article explique les concepts avancés du kube-controller-manager avec des exemples pratiques. Nous couvrons son architecture, le fonctionnement interne des contrôleurs, les options de configuration clés, la surveillance et le diagnostic, les modes de défaillance courants et les procédures de récupération. Chaque section inclut des commandes, des sorties attendues et des bonnes pratiques directement applicables.

Nous supposons que vous disposez d'un cluster Kubernetes en cours d'exécution et d'un accès kubectl. Tous les exemples sont indépendants de la version, mais nous signalons les changements de comportement. L'objectif est 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 le résultat et documenter la procédure de reprise si l'état attendu n'est pas atteint.

Inventaire de la version et de l'environnement

Avant de procéder à des modifications ou de déboguer des problèmes, vous devez disposer d'une vision claire de votre environnement, notamment de la version de Kubernetes, du déploiement du plan de contrôle et de l'état actuel du processus kube-controller-manager.

Vérifier la version de Kubernetes

Exécutez :

kubectl version --short

Sortie attendue (exemple, peut varier) :

Client Version: v1.27.3
Kustomize Version: v5.0.1
Server Version: v1.27.3

Notez la version du serveur, car certains comportements et options des contrôleurs changent d'une version à l'autre. Par exemple, l'option --use-service-account-credentials a été dépréciée en v1.24 et supprimée en v1.26.

Identifier la topologie de déploiement du plan de contrôle

Le kube-controller-manager s'exécute en tant que pod statique sur les nœuds du plan de contrôle dans les clusters installés avec kubeadm, ou en tant que service systemd dans certains clusters autogérés.

Pour vérifier s'il s'agit d'un pod statique, exécutez :

kubectl get pods -n kube-system | grep controller-manager

Sortie attendue (exemple) :

kube-controller-manager-controlplane01            1/1     Running   0          5d3h

Si vous voyez un tel pod, il est géré par le kubelet sur ce nœud via des manifests de pod statique. Le manifest se trouve généralement dans /etc/kubernetes/manifests/kube-controller-manager.yaml.

Pour inspecter les options passées au gestionnaire de contrôleurs, décrivez le pod :

kubectl describe pod -n kube-system kube-controller-manager-controlplane01

Recherchez la section Command dans la sortie. Par exemple :

Command:
  kube-controller-manager
  --allocate-node-cidrs=true
  --authentication-kubeconfig=/etc/kubernetes/controller-manager.conf
  --authorization-kubeconfig=/etc/kubernetes/controller-manager.conf
  --bind-address=127.0.0.1
  --client-ca-file=/etc/kubernetes/pki/ca.crt
  --cluster-cidr=10.244.0.0/16
  --cluster-name=kubernetes
  --cluster-signing-cert-file=/etc/kubernetes/pki/ca.crt
  --cluster-signing-key-file=/etc/kubernetes/pki/ca.key
  --controllers=*,bootstrapsigner,tokencleaner
  --kubeconfig=/etc/kubernetes/controller-manager.conf
  --leader-elect=true
  --node-cidr-mask-size=24
  --root-ca-file=/etc/kubernetes/pki/ca.crt
  --service-account-private-key-file=/etc/kubernetes/pki/sa.key
  --use-service-account-credentials=true

Cette sortie révèle des détails de configuration importants. Par exemple, --leader-elect=true signifie que le gestionnaire de contrôleurs fonctionne en mode haute disponibilité avec élection de leader.

Vérifier l'état de santé du gestionnaire de contrôleurs

Le gestionnaire de contrôleurs expose un point de terminaison de santé à /healthz sur son adresse de service (par défaut 127.0.0.1:10257). Sur un nœud du plan de contrôle, vous pouvez l'interroger localement :

curl -k https://127.0.0.1:10257/healthz

Sortie attendue :

ok

Si vous obtenez une erreur, le gestionnaire de contrôleurs est peut-être défaillant. Consultez les journaux (voir la section Vérification et diagnostic).

Prérequis pour les modifications

Avant de modifier la configuration du kube-controller-manager, assurez-vous de :

  • Disposer d'une sauvegarde du fichier de configuration ou du manifest actuel.
  • Connaître l'impact de chaque option modifiée.
  • Avoir un plan de retour en arrière.
  • Pour une configuration en pod statique, vous pouvez modifier le fichier manifest sur le nœud ; le kubelet redémarrera automatiquement le pod.
  • Pour un service systemd, modifiez le fichier de service puis redémarrez.
  • Ne jamais inclure de véritables identifiants ou jetons dans la documentation ; utilisez des espaces réservés.

Question rapide 1 sur 2

Quel est le rôle principal d'un contrôleur dans Kubernetes ?

Un contrôleur est une boucle de contrôle qui surveille l'état partagé du cluster via l'apiserver et apporte des modifications tentant de faire évoluer l'état actuel vers l'état souhaité.

Chemin de configuration sûr

Modifier les paramètres du kube-controller-manager peut perturber le fonctionnement du cluster si cela est mal fait. Suivez un chemin de configuration sûr : observez l'état actuel, effectuez une modification minimale, vérifiez et prévoyez un plan de récupération.

Modifications de configuration courantes

1. Ajuster la concurrence des contrôleurs

Chaque contrôleur du kube-controller-manager exécute un certain nombre de workers simultanés. Vous pouvez régler la concurrence par contrôleur via des options, mais la plupart des contrôleurs utilisent des valeurs par défaut sûres pour la production. Par exemple, pour augmenter la concurrence du contrôleur de déploiement, il faudrait modifier l'option --concurrent-deployment-syncs (par défaut 5). Toutefois, tous les contrôleurs ne disposent pas de telles options ; seule une partie d'entre eux les possèdent. Consultez la documentation officielle correspondant à votre version de Kubernetes.

Exemple d'option à ajouter au manifest :

--concurrent-deployment-syncs=10

Rayon d'impact : affecte uniquement la vitesse de synchronisation du contrôleur de déploiement ; augmente l'utilisation du processeur et de la mémoire.

Vérification : après le redémarrage, vérifiez les journaux du gestionnaire de contrôleurs pour l'option ou utilisez les métriques (voir la section Surveillance).

2. Modifier les seuils d'éviction des nœuds

Le contrôleur de cycle de vie des nœuds (anciennement partie de kube-controller-manager) évince les pods des nœuds défaillants en fonction de seuils. Vous pouvez ajuster --node-monitor-grace-period (par défaut 40 s) et --node-monitor-period (par défaut 5 s).

Exemple :

--node-monitor-grace-period=60s
--node-monitor-period=10s

Ces options indiquent au contrôleur combien de temps attendre avant de considérer un nœud comme défaillant. Augmenter la période de grâce peut réduire les faux positifs sur les réseaux instables, mais retarde l'éviction des pods.

Rayon d'impact : affecte tous les nœuds et toutes les charges de travail ; peut retarder la récupération après une défaillance de nœud.

Vérification : simulez une défaillance de nœud (par exemple, arrêtez le kubelet sur un nœud) et observez le délai d'éviction.

3. Configurer l'élection de leader

Par défaut, le kube-controller-manager utilise l'élection de leader pour garantir qu'une seule instance est active. Vous pouvez ajuster --leader-elect-lease-duration (par défaut 15 s), --leader-elect-renew-deadline (par défaut 10 s) et --leader-elect-retry-period (par défaut 2 s). Ces valeurs conviennent généralement à la production, mais dans certains environnements à forte latence réseau, il peut être nécessaire de les augmenter.

Exemple :

--leader-elect-lease-duration=30s
--leader-elect-renew-deadline=20s
--leader-elect-retry-period=5s

Rayon d'impact : affecte le temps de basculement en cas de défaillance de l'instance active.

Vérification : vérifiez l'état de l'élection de leader dans les journaux ou les métriques.

Procédure de modification sûre

  1. Sauvegardez le manifest actuel :
   sudo cp /etc/kubernetes/manifests/kube-controller-manager.yaml /etc/kubernetes/manifests/kube-controller-manager.yaml.bak
  1. Modifiez le manifest avec vos changements. Pour les pods statiques, le kubelet détectera la modification et redémarrera automatiquement le pod.
  1. Surveillez l'apparition du nouveau pod :
   kubectl get pods -n kube-system -w | grep controller-manager
  1. Si le pod ne démarre pas, consultez les journaux :
   kubectl logs -n kube-system kube-controller-manager-controlplane01
  1. Si nécessaire, revenez en arrière en restaurant la sauvegarde :
   sudo cp /etc/kubernetes/manifests/kube-controller-manager.yaml.bak /etc/kubernetes/manifests/kube-controller-manager.yaml

Vérifiez toujours que le gestionnaire de contrôleurs devient prêt avant de considérer la modification comme réussie.

Vérification et diagnostic

Après avoir modifié la configuration ou lors d'un dépannage, vous devez vérifier que le gestionnaire de contrôleurs fonctionne correctement et diagnostiquer tout problème.

Consulter les journaux

La principale source de diagnostic est constituée par les journaux du gestionnaire de contrôleurs. Accédez-y via kubectl :

kubectl logs -n kube-system kube-controller-manager-controlplane01

Recherchez les erreurs, les avertissements ou les messages concernant l'élection de leader, les échecs de synchronisation des contrôleurs, etc.

Exemple d'extrait de journal normal :

I0712 10:00:00.123456       1 controllermanager.go:246] "Starting" version="v1.27.3"
I0712 10:00:00.123789       1 leaderelection.go:248] attempting to acquire leader lease kube-system/kube-controller-manager...
I0712 10:00:00.234567       1 leaderelection.go:258] successfully acquired lease kube-system/kube-controller-manager
I0712 10:00:00.234999       1 controllermanager.go:256] "Started"

Si le gestionnaire de contrôleurs est bloqué dans l'élection de leader, vous verrez des messages répétés « attempting to acquire » sans succès. Cela peut indiquer un problème avec le serveur d'API ou etcd.

Métriques et points de terminaison de santé

Le kube-controller-manager expose des métriques et des points de terminaison de santé. Par défaut, ils écoutent sur 127.0.0.1:10257 pour le service sécurisé et 127.0.0.1:10252 pour le service non sécurisé (déprécié). Pour accéder aux métriques, vous devrez peut-être effectuer un transfert de port :

kubectl port-forward -n kube-system kube-controller-manager-controlplane01 10257:10257

Puis dans un autre terminal :

curl -k https://127.0.0.1:10257/metrics

Vous verrez un grand nombre de métriques. Les métriques clés à surveiller comprennent :

  • workqueue_depth pour chaque contrôleur (indique l'arriéré).
  • workqueue_adds_total et workqueue_retries_total.
  • leader_election_master_status (1 si cette instance est leader).
  • rest_client_requests_total pour les interactions avec le serveur d'API.

Exemple de récupération d'une métrique spécifique :

curl -k https://127.0.0.1:10257/metrics | grep workqueue_depth

Extrait de sortie :

# HELP workqueue_depth Current depth of workqueue
# TYPE workqueue_depth gauge
workqueue_depth{name="deployment"} 0
workqueue_depth{name="replicaset"} 0
workqueue_depth{name="statefulset"} 0

Si une profondeur de file d'attente reste élevée en continu, le contrôleur a du mal à suivre.

Utiliser kubectl pour l'état des composants

Les anciennes versions de Kubernetes disposaient de kubectl get componentstatuses (ou cs), mais cette commande est dépréciée et supprimée depuis la v1.19. Ne vous y fiez pas. Vérifiez plutôt l'état du pod et les journaux.

Scénario de diagnostic : un ReplicaSet ne crée pas de pods

Supposons que vous créiez un déploiement, mais que le ReplicaSet ne crée pas de pods. Le problème peut provenir du contrôleur de replicaset. Vérifiez les journaux du gestionnaire de contrôleurs pour les erreurs liées au replicaset :

kubectl logs -n kube-system kube-controller-manager-controlplane01 | grep -i replicaset

Recherchez des messages d'erreur tels que des autorisations manquantes, une spécification invalide, etc. Si vous voyez des erreurs RBAC, vérifiez les autorisations du compte de service du gestionnaire de contrôleurs.

Question rapide 2 sur 2

Quel est le port sécurisé par défaut pour les métriques et les endpoints de santé de kube-controller-manager ?

Par défaut, kube-controller-manager expose les métriques et les endpoints de santé sur 127.0.0.1:10257 pour le service sécurisé.

Modes de défaillance et récupération

Comprendre les modes de défaillance courants du kube-controller-manager et savoir comment récupérer est essentiel pour maintenir la santé du cluster.

1. Élection de leader bloquée

Symptôme : Les journaux du gestionnaire de contrôleurs affichent des messages répétés « attempting to acquire leader lease » sans jamais aboutir. L'instance active est peut-être morte, mais le bail n'est pas libéré, ou il y a une partition réseau.

Diagnostic : Vérifiez l'objet de bail :

kubectl get lease -n kube-system kube-controller-manager -o yaml

Regardez spec.holderIdentity et spec.renewTime. Si le détenteur est un pod qui n'existe plus, le bail devrait expirer, mais parfois le nettoyage est retardé.

Récupération : Vous pouvez supprimer le bail pour forcer une nouvelle élection :

kubectl delete lease -n kube-system kube-controller-manager

Surveillez ensuite les journaux pour voir un nouveau leader élu. Cette opération est sûre car le bail est recréé automatiquement.

2. CrashLoopBackOff du gestionnaire de contrôleurs

Symptôme : Le pod du gestionnaire de contrôleurs est en état CrashLoopBackOff.

Vérification : Décrivez le pod :

kubectl describe pod -n kube-system kube-controller-manager-controlplane01

Recherchez les événements et la dernière raison de terminaison. Causes courantes :

  • Option invalide : le pod échoue immédiatement avec un message d'erreur.
  • Fichiers manquants : par exemple, les fichiers kubeconfig ou de certificat ne sont pas montés.
  • Ressources insuffisantes : impossible de démarrer en raison d'un manque de mémoire (OOM).

Exemple d'erreur :

Error: failed to create listener: failed to listen on 127.0.0.1:10257: listen tcp 127.0.0.1:10257: bind: address already in use

Cela indique qu'un autre processus utilise le port. Vous devrez peut-être tuer ce processus ou changer de port.

Récupération : Corrigez le problème sous-jacent, puis redémarrez le pod. Pour les pods statiques, le kubelet redémarrera automatiquement après correction du manifest.

3. Utilisation élevée du processeur ou de la mémoire

Symptôme : Le gestionnaire de contrôleurs consomme trop de processeur ou de mémoire, ce qui peut dégrader d'autres composants.

Diagnostic : Utilisez la surveillance des ressources (Prometheus, metrics-server) ou kubectl top si disponible :

kubectl top pod -n kube-system kube-controller-manager-controlplane01

Sortie :

NAME                                            CPU(cores)   MEMORY(bytes)
kube-controller-manager-controlplane01          500m         300Mi

Si l'utilisation est beaucoup plus élevée que la normale, identifiez quel contrôleur est occupé. Consultez les métriques de profondeur de file d'attente et le taux d'éléments traités. Une charge élevée peut être due à un grand nombre d'objets en constante évolution, ou à un bug dans un contrôleur particulier.

Atténuation : Vous pouvez réduire la concurrence des contrôleurs les plus actifs en ajustant les options (si disponibles) ou en recherchant la charge de travail sous-jacente à l'origine du renouvellement. Par exemple, un contrôleur défaillant qui crée et supprime des pods en boucle entraînera une utilisation élevée du processeur.

4. Le gestionnaire de contrôleurs ne démarre pas en raison de problèmes de certificats

Symptôme : Le pod échoue avec des erreurs TLS.

Exemple de journal :

E0712 10:00:00.123456       1 run.go:74] "command failed" err="failed to load config: open /etc/kubernetes/controller-manager.conf: no such file or directory"

Récupération : Assurez-vous que le fichier kubeconfig existe et est valide. Vous devrez peut-être régénérer les certificats avec kubeadm :

kubeadm init phase certs all

Redémarrez ensuite le gestionnaire de contrôleurs.

Liste de contrôle opérationnelle

Utilisez cette liste de contrôle pour les opérations de routine et la réponse aux incidents impliquant le kube-controller-manager.

Contrôle de santé de routine

  • [ ] Vérifiez que le pod du gestionnaire de contrôleurs est en cours d'exécution et prêt : kubectl get pods -n kube-system | grep controller-manager
  • [ ] Vérifiez l'état de l'élection de leader : dans les journaux ou les métriques (leader_election_master_status doit être à 1 sur une instance).
  • [ ] Passez en revue les journaux récents pour les erreurs : kubectl logs -n kube-system kube-controller-manager-controlplane01 --tail=100
  • [ ] Surveillez les métriques clés : profondeur de la file d'attente, latence des requêtes API, goroutines.
  • [ ] Assurez-vous qu'il n'y a pas de boucles de crash : kubectl get pods -n kube-system | grep controller-manager affiche un nombre de redémarrages stable.

Avant une modification de configuration

  • [ ] Sauvegardez le manifest actuel : cp /etc/kubernetes/manifests/kube-controller-manager.yaml /tmp/kcm-backup-$(date +%Y%m%d).yaml
  • [ ] Consultez la documentation des options pour votre version de Kubernetes.
  • [ ] Estimez le rayon d'impact : quels contrôleurs sont affectés ? Cela pourrait-il avoir un impact sur toutes les charges de travail ?
  • [ ] Préparez le retour en arrière : sachez comment restaurer rapidement la sauvegarde.
  • [ ] Informez l'équipe si la modification risque d'entraîner une brève interruption du plan de contrôle.

Après une modification de configuration

  • [ ] Surveillez le démarrage du pod : kubectl get pods -n kube-system -w | grep controller-manager
  • [ ] Vérifiez que les journaux indiquent un démarrage réussi et une élection de leader.
  • [ ] Testez une charge de travail représentative : créez un déploiement de test et assurez-vous qu'il évolue correctement.
  • [ ] Vérifiez les métriques pour détecter des anomalies.
  • [ ] Documentez la modification et ses effets.

Réponse aux incidents : gestionnaire de contrôleurs en panne

  • [ ] Vérifiez l'état du pod : kubectl get pods -n kube-system
  • [ ] En cas de CrashLoopBackOff, inspectez les journaux et décrivez le pod.
  • [ ] Si l'élection de leader est bloquée, envisagez de supprimer le bail.
  • [ ] Sur un cluster autogéré, vérifiez l'état du service systemd : systemctl status kube-controller-manager
  • [ ] Si le serveur d'API est également en panne, concentrez-vous d'abord sur la récupération d'etcd et du serveur d'API, car le gestionnaire de contrôleurs en dépend.
  • [ ] Une fois rétabli, validez le fonctionnement des contrôleurs en vérifiant que les ressources existantes sont réconciliées (par exemple, les déploiements ont le bon nombre de réplicas).

Conclusion

Le kube-controller-manager est un composant essentiel qui garantit le maintien de l'état souhaité des ressources Kubernetes. Comprendre ses concepts avancés — architecture, boucles de contrôle, configuration, surveillance et dépannage — est indispensable pour faire fonctionner un cluster sain.

Nous avons vu comment inventorier votre environnement, modifier la configuration en toute sécurité, diagnostiquer les problèmes et récupérer des défaillances courantes. Suivez toujours les bonnes pratiques opérationnelles : observer d'abord, modifier de manière minimale, vérifier et disposer d'un plan de retour en arrière.

En appliquant les exemples pratiques et les listes de contrôle de cet article, vous pourrez gérer en toute confiance le kube-controller-manager en production et résoudre les problèmes avant qu'ils n'affectent vos applications.

Prochaines étapes : choisissez une vérification à faible risque de cet article, comme vérifier le point de terminaison de santé ou consulter les métriques, et exécutez-la dans votre cluster. Enregistrez l'état actuel, comparez-le aux signaux attendus et passez en revue les dépendances telles que Kube API Server, ReplicaSet et Deployment. Cela vous permettra de mettre en place un flux de travail fiable qui rend les défaillances visibles et les décisions de récupération claires.

Recherches connexes

Score de qualité de l’article

Utilité pour le lecteur 100%
  • check_circle Guide prêt à lire
  • check_circle Exemples pratiques inclus
  • check_circle URL d’article optimisée pour le SEO