Concepts avancés des baux Kubernetes expliqués avec des exemples pratiques

Introduction

Les baux Kubernetes (Leases) sont une primitive de coordination fondamentale qui passe souvent inaperçue jusqu'à ce qu'un problème survienne. Ils alimentent l'élection de leader pour des composants critiques du plan de contrôle comme kube-controller-manager et kube-scheduler, et offrent un moyen léger aux applications de coordonner un accès exclusif. Mais qu'est-ce qu'un bail exactement, comment fonctionne-t-il en interne et comment le dépanner en cas de problème ?

Cet article explore en profondeur les concepts avancés des baux Kubernetes, destiné aux développeurs, consultants DevOps et équipes techniques de startups qui doivent aller au-delà des bases. Nous examinerons l'API Lease, son architecture et ses rouages internes, puis nous mettrons en pratique des exemples concrets avec de vraies commandes et les sorties attendues. À la fin, vous serez capable d'observer, de vérifier et de résoudre les problèmes liés aux baux en toute confiance.

Nous mettrons l'accent sur la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des valeurs de remplacement plutôt que des secrets, vérifier les résultats et documenter les procédures de récupération. Commençons.

Inventaire des versions et de l'environnement

Avant de toucher à un objet Lease, vous devez avoir une vision claire de votre environnement. Cette section couvre les composants concernés, les versions prises en charge, les prérequis, une étape d'observation en lecture seule, la plus petite modification justifiée et la vérification.

Périmètre des composants

Les baux Kubernetes font partie du groupe d'API coordination.k8s.io. Le type Lease a été introduit dans Kubernetes 1.14 et est stable (v1) depuis. Il est utilisé par les composants de base pour l'élection de leader, et il est disponible pour toute application souhaitant l'utiliser.

Composants clés qui interagissent avec les baux :

• kube-controller-manager : utilise un bail nommé kube-controller-manager dans l'espace de noms kube-system pour élire l'instance active du gestionnaire de contrôleurs. Seul le leader exécute les contrôleurs ; les instances en attente patientent.
• kube-scheduler : utilise un bail nommé kube-scheduler dans kube-system pour l'élection de leader parmi plusieurs réplicas du planificateur.
• Contrôleurs et opérateurs personnalisés : beaucoup, construits avec client-go ou controller-runtime, utilisent les baux pour l'élection de leader, souvent avec des noms dérivés du nom du composant et de l'espace de noms.
• kubelet : dans certaines configurations, le kubelet utilise un bail pour le battement de cœur du nœud (remplaçant l'ancien mécanisme de mise à jour du NodeStatus).

Prérequis

• Un cluster Kubernetes (version 1.14 ou ultérieure) avec kubectl configuré pour y accéder.
• L'API coordination.k8s.io/v1 doit être activée (elle l'est par défaut dans toutes les distributions actuelles).
• Pour l'élection de leader, vous avez besoin d'au moins deux réplicas du composant (pour les composants du plan de contrôle, cela signifie une configuration multi-maîtres ou un déploiement avec plusieurs réplicas).
• Des permissions RBAC suffisantes pour obtenir, lister et décrire les baux dans l'espace de noms concerné.

Observation en lecture seule

Commencez par l'observation. Exécutez les commandes suivantes pour voir l'état actuel des baux dans votre cluster :

# Lister tous les baux dans kube-system (où vivent les composants du plan de contrôle)
kubectl get leases -n kube-system

Exemple de sortie :

NAME                    HOLDER                            AGE
kube-controller-manager master-node-1_1a2b3c4d-5e6f-...   10d
kube-scheduler          master-node-1_9a8b7c6d-5e4f-...   10d

La colonne HOLDER indique quelle instance détient actuellement le bail (c'est-à-dire est le leader). Dans cet exemple, les deux baux sont détenus par master-node-1, ce qui signifie que ce nœud héberge le leader pour les deux composants.

Pour voir les détails complets du bail :

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

Cela affichera la spécification du bail : holderIdentity, leaseDurationSeconds, acquireTime, renewTime, leaseTransitions. Nous expliquerons ces champs plus tard.

Plus petite modification justifiée

Après observation, si une modification est nécessaire (par exemple, forcer une élection de leader), la plus petite modification est souvent de supprimer l'objet Lease. Cela entraîne la perte du bail par le leader actuel et la compétition des autres réplicas pour le leadership. Mais c'est une action perturbatrice ; ne le faites que de manière contrôlée pendant une fenêtre de maintenance si vous devez déplacer le leadership.

Une approche plus sûre consiste à réduire à zéro le déploiement du composant, puis à le remonter, ou à déclencher manuellement une élection de leader si le composant dispose d'un point de terminaison pour cela (la plupart n'en ont pas).

Vérification

Après toute modification, vérifiez le nouvel état :

kubectl get leases -n kube-system
kubectl describe lease kube-controller-manager -n kube-system

Vérifiez que le détenteur a changé pour une autre instance (si c'était l'intention) et que les pods du composant sont en cours d'exécution. Par exemple :

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

La sortie attendue montre le nouveau pod leader s'exécutant sur un nœud différent.

Chemin de configuration sûr

La configuration des baux implique de comprendre leurs paramètres et leur incidence sur le comportement de l'élection de leader. La voie sûre consiste à éviter de modifier directement les baux système et à configurer correctement vos propres composants.

Définition de la ressource Lease

Un objet Lease est défini comme suit (exemple) :

apiVersion: coordination.k8s.io/v1
kind: Lease
metadata:
  name: my-app-leader
  namespace: default
spec:
  holderIdentity: my-app-pod-0
  leaseDurationSeconds: 15
  acquireTime: "2023-01-01T00:00:00Z"
  renewTime: "2023-01-01T00:00:10Z"
  leaseTransitions: 2

Champs clés :

• holderIdentity : l'identité du détenteur actuel du bail (souvent le nom du pod ou un identifiant unique).
• leaseDurationSeconds : la durée pendant laquelle un bail est valide sans renouvellement. Si le détenteur ne renouvelle pas avant l'expiration de cette durée, le bail est considéré comme perdu et d'autres concurrents peuvent l'acquérir.
• acquireTime : horodatage de l'acquisition du bail.
• renewTime : horodatage du dernier renouvellement.
• leaseTransitions : nombre de fois où le bail a changé de mains.

Algorithme d'élection de leader

Kubernetes utilise un algorithme simple pour l'élection de leader basé sur les baux :

1. Chaque candidat tente de créer un objet Lease avec sa propre identité comme détenteur. Le premier à le créer gagne.
2. Le leader renouvelle périodiquement le bail en mettant à jour renewTime (généralement toutes les leaseDurationSeconds / 3 environ).
3. Si le leader ne renouvelle pas, les autres candidats remarquent que renewTime est plus ancien que leaseDurationSeconds et tentent d'acquérir le bail en mettant à jour holderIdentity et renewTime.
4. Le processus se répète.

Ceci est implémenté dans le paquet leaderelection de client-go pour les contrôleurs personnalisés ; les composants du plan de contrôle utilisent un mécanisme intégré similaire.

Configuration des paramètres du bail

Pour vos propres applications, définissez leaseDurationSeconds en fonction de vos exigences de fiabilité. Une durée plus courte signifie un basculement plus rapide mais des renouvellements plus fréquents (plus d'appels API). Une durée plus longue réduit la charge API mais augmente le temps de détection d'un leader défaillant.

Un schéma courant :

• leaseDurationSeconds = 15 (ou 30)
• renewDeadline = 10 (le leader doit renouveler dans ce délai)
• retryPeriod = 2 (fréquence à laquelle le leader tente de renouveler)

Ces valeurs sont généralement définies dans la configuration de l'élection de leader du composant, et non directement sur l'objet Lease (le contrôleur gère le bail automatiquement).

Exemple : configuration d'un contrôleur personnalisé avec élection de leader

Supposons que vous utilisiez controller-runtime (Go). Vous configureriez les options d'élection de leader comme suit :

mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
    LeaderElection: true,
    LeaderElectionID: "my-app-leader",
    LeaseDuration: &leaseDuration,
    RenewDeadline: &renewDeadline,
    RetryPeriod: &retryPeriod,
})

Cela crée un bail nommé my-app-leader dans l'espace de noms où le contrôleur s'exécute. Le contrôleur gère automatiquement le renouvellement et le basculement.

Vérification

Après avoir déployé votre contrôleur, vérifiez que le bail a été créé et qu'il est renouvelé :

kubectl get lease my-app-leader -n my-namespace -o yaml

Recherchez renewTime qui se met à jour toutes les quelques secondes. Vous pouvez le surveiller avec :

kubectl get lease my-app-leader -n my-namespace -w

Vérification et diagnostics

Lorsque quelque chose ne va pas avec l'élection de leader ou la coordination basée sur les baux, vous devez diagnostiquer le problème systématiquement. Cette section décrit les étapes et les commandes pour vérifier un comportement sain et identifier les défaillances.

Vérification de l'élection de leader pour les composants du plan de contrôle

Exécutez la commande suivante pour vérifier le leader actuel et l'activité récente du bail :

kubectl get lease -n kube-system -o custom-columns=NAME:.metadata.name,HOLDER:.spec.holderIdentity,AGE:.metadata.creationTimestamp,RENEW:.spec.renewTime

Cela donne une vue concise de qui est leader et de la dernière fois qu'il a renouvelé. Si RENEW n'est pas récent (plus ancien que leaseDurationSeconds), le leader peut être en panne ou incapable de renouveler.

Inspection des détails du bail

Utilisez kubectl describe pour voir l'état complet :

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

La sortie inclut les événements (le cas échéant) et les champs de spécification. Remarque : les baux ne génèrent pas d'événements par défaut, mais vous pouvez voir le détenteur actuel et l'heure de renouvellement.

Scénarios de diagnostic

Scénario 1 : Aucun leader élu

Si plusieurs réplicas sont en cours d'exécution mais que personne ne détient le bail, vérifiez les journaux du composant pour les erreurs. Pour kube-controller-manager :

kubectl logs -n kube-system kube-controller-manager-<node-name> | grep -i leader

Recherchez des messages comme « attempting to acquire leader lease... » ou des erreurs liées à l'accès API ou aux mises à jour du bail. Causes courantes :

• Permissions RBAC insuffisantes pour mettre à jour le bail.
• Partition réseau entre les nœuds du plan de contrôle.
• Drapeau --leader-elect mal configuré (doit être vrai pour plusieurs réplicas).

Scénario 2 : Changements fréquents de leader (basculement)

Si leaseTransitions s'incrémente rapidement, il peut y avoir un problème de renouvellement. Vérifiez les journaux pour les échecs de renouvellement. Vérifiez également le décalage d'horloge entre les nœuds ; le timing du bail est basé sur l'heure de l'horloge murale, et un décalage important peut provoquer une expiration prématurée du bail.

# Vérifiez l'état de synchronisation de l'horloge sur chaque nœud (en utilisant timedatectl ou ntpq)

Scénario 3 : Bail non renouvelé

Si le renewTime du détenteur est obsolète, le leader peut être bloqué ou manquer de ressources. Vérifiez l'utilisation des ressources du pod :

kubectl top pod -n kube-system kube-controller-manager-<node-name>

Une pression élevée sur le CPU ou la mémoire pourrait empêcher des renouvellements opportuns.

Utilisation des événements

Bien que les baux eux-mêmes n'émettent pas d'événements, le composant utilisant le bail peut consigner des événements. Vous pouvez vérifier les événements dans l'espace de noms :

kubectl get events -n kube-system --sort-by=.lastTimestamp

Recherchez des avertissements liés à l'élection de leader.

Modes de défaillance et récupération

Comprendre ce qui peut mal tourner avec les baux et comment récupérer est essentiel pour maintenir des clusters hautement disponibles. Cette section couvre les modes de défaillance courants et les procédures de récupération étape par étape.

Mode de défaillance 1 : Le pod leader plante

Symptôme : Le pod détenteur n'est pas en cours d'exécution, mais le bail n'a pas été libéré (le détenteur indique toujours le pod mort).

Cause : Le pod a planté et n'a pas eu la possibilité de libérer le bail.

Récupération : Le bail expirera après leaseDurationSeconds (15 s par défaut pour les composants du plan de contrôle). Les réplicas en attente entreront alors en compétition pour le leadership. Généralement, aucune intervention manuelle n'est nécessaire ; attendez simplement l'expiration du bail et l'émergence d'un nouveau leader.

Vérifiez la récupération :

kubectl get lease kube-controller-manager -n kube-system -w

Surveillez le changement de détenteur du pod mort vers un pod vivant en 20 à 30 secondes environ.

Mode de défaillance 2 : Le bail expire mais aucun nouveau leader

Symptôme : Le détenteur du bail est vide, tous les pods sont en cours d'exécution, mais aucun leader n'est élu.

Cause : Problèmes possibles : mauvaise configuration RBAC empêchant les mises à jour du bail, partition réseau entre les nœuds, ou tous les candidats échouent à acquérir en raison d'erreurs API.

Étapes de récupération :

1. Vérifiez les journaux des pods candidats pour les erreurs :

   kubectl logs -n kube-system kube-controller-manager-<node1> | grep -i "leader\|lease"
   kubectl logs -n kube-system kube-controller-manager-<node2> | grep -i "leader\|lease"

1. Vérifiez les permissions RBAC pour le compte de service du composant. Pour les composants du plan de contrôle, les rôles de cluster system:kube-controller-manager ou system:kube-scheduler doivent avoir des permissions sur les baux. Vous pouvez vérifier avec :

   kubectl auth can-i update leases -n kube-system --as=system:serviceaccount:kube-system:kube-controller-manager

Sortie attendue : yes

1. Si les permissions sont manquantes, appliquez le ClusterRole et le ClusterRoleBinding appropriés (généralement inclus dans l'installation de Kubernetes, donc une mauvaise configuration peut indiquer une configuration de cluster cassée).
2. Si tout le reste échoue, vous pouvez supprimer manuellement l'objet Lease ; le prochain candidat le recréera :

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

Cela devrait déclencher une élection de leader immédiate.

Mode de défaillance 3 : Split brain dû au décalage d'horloge

Symptôme : Deux composants pensent être leaders simultanément.

Cause : Un décalage d'horloge important entre les nœuds peut amener le non-leader à penser que le bail a expiré et à l'acquérir, tandis que l'ancien leader continue de fonctionner.

Récupération : Corrigez la synchronisation de l'horloge (par exemple, assurez-vous que NTP fonctionne sur tous les nœuds). Ensuite, si nécessaire, forcez une nouvelle élection en supprimant le bail (comme ci-dessus). À l'avenir, assurez-vous que tous les nœuds ont des horloges synchronisées.

Mode de défaillance 4 : Objet Lease supprimé accidentellement

Symptôme : L'élection de leader échoue ou un nouveau leader est élu de manière inattendue.

Cause : Quelqu'un a supprimé l'objet Lease.

Récupération : Les candidats le recréeront automatiquement. Aucune action manuelle n'est nécessaire sauf si le composant n'est pas conçu pour réessayer la création (rare). Si nécessaire, redémarrez les pods du composant.

Vérification générale de la récupération

Après toute action de récupération, vérifiez que le cluster fonctionne normalement :

• Vérifiez l'état des composants : kubectl get componentstatuses (si disponible) ou kubectl get pods -n kube-system.
• Vérifiez l'élection de leader : kubectl get leases -n kube-system.
• Assurez-vous que les charges de travail sont planifiées : kubectl get pods --all-namespaces et recherchez les pods en attente.

Liste de contrôle opérationnelle

Utilisez cette liste de contrôle pour vous assurer d'avoir couvert tous les aspects de la gestion et du dépannage des baux. Chaque élément est concret et actionnable.

Liste de contrôle avant modification

• [ ] Vérifiez la version du cluster : kubectl version (assurez-vous >=1.14).
• [ ] Listez les baux actuels : kubectl get leases --all-namespaces.
• [ ] Notez les détenteurs actuels des composants critiques (kube-controller-manager, kube-scheduler) dans un bloc-notes sécurisé.
• [ ] Confirmez que vous avez l'accès kubectl et les permissions.
• [ ] Identifiez le rayon d'impact de toute modification potentielle (par exemple, la suppression d'un bail affecte l'élection de leader pour ce composant).
• [ ] Configurez une surveillance du bail (dans un terminal séparé) : kubectl get lease <name> -n <namespace> -w.

Pendant la modification

• [ ] Si vous supprimez un bail pour forcer l'élection, utilisez :

  kubectl delete lease <name> -n <namespace>

Surveillez immédiatement la sortie de la commande de surveillance.

• [ ] Pour les modifications de configuration de composants personnalisés (par exemple, durée du bail), mettez à jour la spécification de déploiement ou les drapeaux d'élection de leader, puis appliquez :

  kubectl apply -f <updated-manifest.yaml>

• [ ] Surveillez les journaux du composant pour voir les messages d'élection de leader :

  kubectl logs -f deployment/<component> -n <namespace>

Vérification après modification

• [ ] Vérifiez le nouveau détenteur : kubectl get lease <name> -n <namespace> -o yaml et vérifiez holderIdentity.
• [ ] Vérifiez que renewTime est mis à jour (exécutez watch -n 5 kubectl get lease <name> -n <namespace> -o yaml et observez le changement de renewTime).
• [ ] Vérifiez l'état du pod du composant : kubectl get pods -n <namespace> | grep <component>.
• [ ] Testez la fonctionnalité : pour kube-scheduler, essayez de planifier un pod de test ; pour les contrôleurs, déclenchez une réconciliation.
• [ ] Documentez toute modification dans votre journal des opérations.

Référence rapide de dépannage

Conclusion

Les baux Kubernetes sont un mécanisme puissant mais sous-estimé pour la coordination et l'élection de leader. En comprenant leurs rouages internes (les champs de spécification, le processus de renouvellement et les modes de défaillance), vous pouvez exploiter votre cluster et vos contrôleurs personnalisés avec une plus grande fiabilité.

Cet article a passé en revue l'inventaire des versions et de l'environnement, les pratiques de configuration sûres, la vérification et les diagnostics, les modes de défaillance et une liste de contrôle opérationnelle. Les points clés à retenir sont :

• Observez toujours avant de modifier : utilisez kubectl get leases et kubectl describe lease pour comprendre l'état actuel.
• L'élection de leader repose sur des renouvellements opportuns ; surveillez renewTime pour garantir la santé.
• Les défaillances courantes incluent les leaders qui plantent, le décalage d'horloge et les problèmes RBAC ; chacune a un chemin de récupération clair.
• Utilisez la liste de contrôle opérationnelle pour gérer systématiquement les modifications liées aux baux.

Comme prochaine étape, appliquez ces concepts à un scénario à faible risque : créez un bail de test en utilisant le manifeste d'exemple, observez son comportement et simulez une défaillance en supprimant le pod détenteur (si vous utilisez un contrôleur personnalisé) ou en mettant à jour manuellement le bail. Enregistrez les résultats et comparez-les au comportement attendu décrit ici.

N'oubliez pas qu'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 récupération avant qu'un incident ne force la décision. Avec ces concepts avancés sur les baux, vous êtes mieux équipé pour maintenir votre environnement Kubernetes stable et hautement disponible.