Aller au contenu
English
Compte : non connecté, synchronisation possible Mon apprentissage
Selectionner le thème
English

Joindre un worker à un cluster kubeadm

Par mis à jour le

Améliorer cette page

Pour joindre un worker à un cluster kubeadm, vous préparez la machine, vous demandez au plan de contrôle une commande de jonction, puis vous la lancez en root sur le worker. La préparation compte autant que la commande : un swap encore actif fait échouer la jonction, ou la fait réussir jusqu'au prochain redémarrage. Un pilote de cgroup mal choisi (la façon dont containerd range les processus des conteneurs) rend le nœud instable. Cette leçon s'adresse à qui a déjà un plan de contrôle initialisé avec son réseau de Pods, comme celui de la leçon Installer un cluster Kubernetes avec kubeadm.

  • Préparer un worker pour Kubernetes 1.37 : swap coupé sans retour possible, containerd sur le pilote de cgroup systemd, paquets figés.
  • Produire une commande de jonction avec kubeadm token create --print-join-command et savoir combien de temps son jeton reste valable.
  • Lancer kubeadm join et vérifier que le nœud est Ready avec la bonne version de kubelet.
  • Prouver que le nœud accueille des charges en y forçant un Pod avec nodeName.
  • Diagnostiquer une jonction qui échoue avec la sortie de kubeadm join et le journal du kubelet.

Vous avez un plan de contrôle initialisé, dont le nœud est Ready : la leçon Installer un cluster Kubernetes avec kubeadm y mène. Le worker est une machine Linux joignable en SSH, avec sudo, et kubeadm, kubelet et kubectl en 1.37 installés dessus de la même façon que sur le plan de contrôle. Le worker suit pour cela les étapes 1 à 6 de la section Installation des prérequis sur tous les nœuds : modules noyau overlay et br_netfilter, routage IP (ip_forward), swap coupé, installation et configuration de containerd (le fichier /etc/containerd/config.toml doit exister), puis installation de kubeadm, kubelet et kubectl. Les commandes ci-dessous visent Ubuntu 24.04.

Que se passe-t-il quand un worker rejoint le cluster ?

Section intitulée « Que se passe-t-il quand un worker rejoint le cluster ? »

Le worker présente un jeton temporaire au plan de contrôle, vérifie qu'il parle bien au bon cluster grâce à l'empreinte de sa CA (l'autorité qui signe les certificats du cluster), puis reçoit son propre certificat et s'enregistre. Le schéma suit les échanges dans l'ordre : regardez que la commande de jonction contient les deux informations dont le worker a besoin, le jeton et l'empreinte.

Sur le plan de contrôle, l'administrateur lance kubeadm token create --print-join-command et reçoit une commande qui porte un jeton et l'empreinte de la CA. Il la lance sur le worker. Le worker lit les informations publiques du cluster avec le jeton et compare l'empreinte de la CA. Son kubelet demande ensuite un certificat avec le jeton, reçoit un certificat signé, et le nœud s'enregistre. Il apparaît dans kubectl get nodes, Ready une fois son réseau démarré.Worker,kubeadm joinPlan decontrôleAdministrateu-rcomparel'empreintede la CA àcelle de lacommandekubeadm token create--print-join-commandcommande dejonction (jeton,empreinte de la CA)lance la commande en root sur le workerlit les informationspubliques du clusteravec le jetonle kubelet demandeun certificat avec lejetoncertificat signé,kubelet.conf écritle nœud s'enregistrekubectl get nodesle worker est listé,Ready quand sonréseau tourne
Source · SVG
Échap pour fermer, + et − pour zoomer, défilement pour se déplacer. 100 %

Le jeton prouve que le worker a le droit de demander à rejoindre le cluster. L'empreinte prouve à l'inverse que le plan de contrôle est le bon : sans elle, un faux serveur pourrait se faire passer pour votre API server. Les deux sont donc obligatoires dans la commande.

Que faut-il préparer sur le worker avant de le joindre ?

Section intitulée « Que faut-il préparer sur le worker avant de le joindre ? »

Trois réglages doivent être en place et durables : le swap coupé, containerd sur le pilote de cgroup systemd, et les paquets Kubernetes figés. Un réglage fait à chaud disparaît au redémarrage si rien ne l'écrit sur le disque, et un worker joint à la hâte retombe alors au premier reboot. Les commandes de cette section se lancent sur le worker.

Par défaut, le kubelet refuse de démarrer tant que du swap est actif : kubeadm join échoue donc sur une machine qui en a. Deux gestes sont nécessaires, et le premier ne suffit pas seul. swapoff -a coupe le swap tout de suite, mais la ligne swap de /etc/fstab le rallume au démarrage suivant. Le kubelet refuse alors de redémarrer et le nœud passe NotReady : il faut donc aussi retirer cette ligne.

Fenêtre de terminal
# Couper le swap immédiatement
sudo swapoff -a
# Retirer la ligne swap de fstab, pour que le swap ne revienne pas au démarrage
sudo sed -i '/swap/d' /etc/fstab

Cette commande supprime toute ligne qui contient le mot swap. Si votre /etc/fstab en contient d'autres que la ligne du swap, relisez-les d'abord avec grep swap /etc/fstab. Vérifiez ensuite les deux états : le swap actif et le swap déclaré.

Fenêtre de terminal
# Le swap actif : aucune sortie attendue
swapon --show
# Le swap déclaré dans fstab : aucune ligne active attendue
grep -v '^#' /etc/fstab | grep swap

Les deux commandes ne doivent rien afficher. La première liste ce qui est actif maintenant, la seconde ce qui se rallumerait au prochain démarrage.

Comment accorder containerd et le kubelet sur le pilote de cgroup ?

Section intitulée « Comment accorder containerd et le kubelet sur le pilote de cgroup ? »

Le kubelet et containerd doivent utiliser le même pilote de cgroup. Sur une distribution avec systemd, la documentation de Kubernetes recommande le pilote systemd. Deux cas se présentent.

Avec containerd 2.x, le kubelet 1.37 demande lui-même le pilote à containerd. Mais un containerd laissé sur cgroupfs ajoute un second gestionnaire de cgroups à celui de systemd, et le nœud devient instable quand les ressources manquent. Avec containerd 1.x, le kubelet garde le pilote de sa propre configuration, systemd avec kubeadm, et un désaccord entre les deux provoque des erreurs.

Le réglage s'appelle SystemdCgroup et se trouve dans /etc/containerd/config.toml. containerd ne relit ce fichier qu'à son redémarrage.

Fenêtre de terminal
# Passer le pilote à systemd dans la configuration
sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/' /etc/containerd/config.toml
# containerd ne lit sa configuration qu'au démarrage
sudo systemctl restart containerd

Pour vérifier, ne vous contentez pas de lire le fichier : demandez à containerd la valeur qu'il a chargée.

Fenêtre de terminal
# La valeur que containerd utilise réellement
sudo crictl info | grep SystemdCgroup

La ligne doit afficher true. Si le fichier dit true et que crictl info dit false, containerd n'a pas été redémarré depuis la modification.

Comment éviter qu'une mise à jour automatique déplace le worker de version ?

Section intitulée « Comment éviter qu'une mise à jour automatique déplace le worker de version ? »

Les trois paquets se figent avec apt-mark hold, comme sur le plan de contrôle. Sans cela, une mise à jour automatique d'Ubuntu peut éloigner le kubelet du worker de la version du cluster.

Fenêtre de terminal
sudo apt-mark hold kubeadm kubelet kubectl
apt-mark showhold

apt-mark showhold doit lister kubeadm, kubelet et kubectl. Le gel a une conséquence que vous retrouverez à la montée de version : il faut apt-mark unhold avant d'installer une autre version, voir la leçon Mettre à jour un cluster Kubernetes sans interruption.

La commande de jonction se fabrique sur le plan de contrôle avec kubeadm token create --print-join-command. Elle crée un jeton et affiche la commande kubeadm join complète, empreinte de la CA comprise. Un jeton est valable 24 heures par défaut, d'après la documentation de kubeadm token ; l'option --ttl change cette durée.

Fenêtre de terminal
# Sur le plan de contrôle
kubeadm token create --print-join-command

La sortie est une ligne de la forme kubeadm join <adresse>:6443 --token <jeton> --discovery-token-ca-cert-hash sha256:<empreinte>. Copiez-la telle quelle. Traitez cette ligne comme un secret : tant que le jeton est valable, quiconque la possède peut présenter une machine au cluster.

Vous pouvez aussi reprendre la commande affichée à la fin de kubeadm init, tant que son jeton n'a pas expiré. Passé 24 heures, kubeadm token list ne montre plus ce jeton et il faut en créer un nouveau avec la commande ci-dessus.

La jonction se lance sur le worker, en root, avec la ligne copiée. L'exemple ci-dessous reprend les adresses de la leçon d'installation : remplacez l'adresse, le jeton et l'empreinte par les vôtres.

Fenêtre de terminal
sudo kubeadm join 192.168.122.10:6443 \
--token abcdef.0123456789abcdef \
--discovery-token-ca-cert-hash sha256:...

Le worker contrôle d'abord sa propre préparation, puis suit les échanges du schéma. Quand la commande réussit, sa sortie se termine par This node has joined the cluster:, suivi de deux lignes qui résument la demande de certificat et l'information donnée au kubelet. La vérification se fait ensuite depuis le plan de contrôle. Si la commande échoue, ne la relancez pas à l'aveugle : lisez le message, puis passez à la section sur le diagnostic.

Comment vérifier que le worker est Ready avec le bon kubelet ?

Section intitulée « Comment vérifier que le worker est Ready avec le bon kubelet ? »

Vérifiez depuis le plan de contrôle que le nœud est listé, qu'il est Ready et que son kubelet annonce la version du cluster.

Fenêtre de terminal
kubectl get nodes -o wide
Sortie (kubeadm 1.37.2, cluster de lab à deux nœuds)
NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME
k8s-cp.lab Ready control-plane 91s v1.37.2 10.10.50.11 <none> Ubuntu 24.04.5 LTS 6.8.0-149-generic (amd64) containerd://2.2.1
k8s-w1.lab Ready <none> 4s v1.37.2 10.10.50.12 <none> Ubuntu 24.04.5 LTS 6.8.0-149-generic (amd64) containerd://2.2.1

Cette sortie vient du cluster du catalogue de labs, qui compte un plan de contrôle et un seul worker. Regardez la colonne STATUS (le worker est Ready) et la colonne VERSION (la même sur les deux nœuds). Le worker peut rester NotReady un court moment, le temps que le réseau de Pods démarre sur lui.

La colonne VERSION reprend la version que le kubelet du nœud annonce, le champ status.nodeInfo.kubeletVersion. Vous pouvez le lire seul, et le comparer à la ligne Server Version de kubectl version.

Fenêtre de terminal
kubectl get node k8s-w1.lab -o jsonpath='{.status.nodeInfo.kubeletVersion}'
kubectl version

Les deux versions doivent concorder. Un kubelet qui diffère de l'API server vient en général d'un paquet installé à la mauvaise version : la règle de décalage autorisé est détaillée dans la leçon de montée de version.

Comment prouver que le worker accueille des Pods ?

Section intitulée « Comment prouver que le worker accueille des Pods ? »

Un nœud Ready ne prouve pas qu'il exécute des Pods : le seul moyen de le voir est d'y faire tourner un. Le champ nodeName de la spec d'un Pod le place sur un nœud précis et court-circuite le scheduler, ce qui évite de dépendre de son choix. Créez un namespace, puis un Pod forcé sur le worker.

Fenêtre de terminal
kubectl create namespace jonction
pod-sur-w1.yaml
apiVersion: v1
kind: Pod
metadata:
name: pod-sur-w1
namespace: jonction
spec:
nodeName: k8s-w1.lab
containers:
- name: attente
image: busybox:1.38.0@sha256:a46257e06c82ad85242d0d38077d0a52d9896389ca60a1a59d3463db586e5fa4
command: ["sleep", "3600"]
Fenêtre de terminal
kubectl apply -f pod-sur-w1.yaml
kubectl -n jonction get pod pod-sur-w1 -o wide

Dans la sortie de get pod -o wide, lisez deux colonnes : STATUS doit valoir Running et NODE doit valoir k8s-w1.lab. Si le Pod reste Pending ou ContainerCreating, le worker n'a pas fini de démarrer son réseau ou ne peut pas télécharger l'image : kubectl -n jonction describe pod pod-sur-w1 donne les événements. Quand la preuve est faite, supprimez le namespace avec kubectl delete namespace jonction.

Une jonction échoue presque toujours pour l'une de quatre raisons : le jeton, le swap, le pilote de cgroup ou le réseau. Commencez par lire les dernières lignes de la sortie de kubeadm join, puis, si elles ne suffisent pas, le journal du kubelet sur le worker.

Fenêtre de terminal
# Sur le worker : le journal du kubelet, ouvert sur ses dernières lignes
sudo journalctl -u kubelet -xe

Le tableau relie chaque symptôme à sa cause et à la correction. La ligne sur le swap et celle sur le pilote de cgroup décrivent les deux pannes que le lab de cette leçon met en place.

SymptômeCauseComment le voirCorrection
kubeadm join refuse le jeton ou n'obtient pas de réponse du clusterJeton expiré ou perdu (24 heures par défaut)Sur le plan de contrôle, kubeadm token list ne montre plus le jetonkubeadm token create --print-join-command, puis relancer la jonction
kubeadm join échoue, le nœud n'apparaît jamaisSwap actif : le kubelet refuse de démarrerswapon --show liste du swap, et journalctl -u kubelet le ditCouper le swap et retirer sa ligne de /etc/fstab
Des Pods du nœud échouent ou le nœud devient instable sous chargecontainerd sur cgroupfs alors que systemd gère le reste du nœud, ou, avec containerd 1.x, un pilote différent de celui du kubeletsudo crictl info | grep SystemdCgroup affiche falseSystemdCgroup = true, puis sudo systemctl restart containerd et sudo systemctl restart kubelet (le kubelet lit le pilote du runtime à son démarrage)
kubeadm join n'atteint pas le plan de contrôleRéseau ou port ferméping puis nc -zv <adresse> 6443 depuis le workerOuvrir le port 6443 ou corriger la route

Après un échec dû au swap ou au pilote de cgroup, la jonction a déjà écrit des fichiers sur le worker. Défaites-la avant de recommencer, puis relancez la commande de jonction avec un jeton encore valable.

Fenêtre de terminal
# Sur le worker : défaire une jonction partielle
sudo kubeadm reset -f

La commande kubeadm reset ne supprime ni les règles iptables, nftables ou IPVS du nœud, ni la configuration du réseau de Pods dans /etc/cni/net.d. Une jonction ratée avant le démarrage du réseau n'en laisse pas, mais un nœud qui a déjà tourné dans un cluster demande de nettoyer ces deux points avant d'être réutilisé ailleurs.

Deux cas restent hors de cette leçon. Joindre un nœud de plan de contrôle plutôt qu'un worker demande une procédure différente, décrite dans Haute disponibilité du control plane. Ce que fait le kubelet une fois le nœud joint est expliqué dans Fonctionnement des Worker Nodes Kubernetes.

Le lab part d'un worker k8s-w1.lab retiré du cluster et remis à zéro : son swap est actif et déclaré dans /etc/fstab, containerd est revenu sur cgroupfs et les paquets ne sont plus figés. Vous le préparez, vous le joignez avec la commande que fabrique le plan de contrôle, puis vous y placez un Pod.

La validation lit six états. Le nœud k8s-w1.lab est joint et Ready. Son kubelet annonce la même version que l'API server. Le swap est coupé, et aucune ligne active de /etc/fstab ne le rallumera. containerd tourne avec le pilote systemd, d'après la valeur qu'il a chargée : une configuration modifiée sans redémarrage échoue. kubeadm, kubelet et kubectl sont figés. Enfin un Pod du namespace jonction tourne sur k8s-w1.lab, prêt.

  • Un worker se joint avec la commande que fabrique kubeadm token create --print-join-command sur le plan de contrôle, lancée en root sur le worker.
  • La commande porte un jeton, valable 24 heures par défaut, et l'empreinte de la CA : le jeton ouvre l'accès, l'empreinte prouve que le cluster est le bon.
  • Le swap se coupe avec swapoff -a et se retire de /etc/fstab, sinon il revient au redémarrage et le kubelet refuse de démarrer.
  • containerd doit tourner avec SystemdCgroup = true, et il faut le redémarrer pour qu'il relise sa configuration ; crictl info donne la valeur chargée.
  • apt-mark hold fige kubeadm, kubelet et kubectl à la version du cluster.
  • Ready et la colonne VERSION se lisent avec kubectl get nodes -o wide ; un Pod avec nodeName prouve que le nœud exécute des charges.
  • En cas d'échec, lisez la sortie de kubeadm join, puis journalctl -u kubelet, et défaites une jonction partielle avec kubeadm reset -f.

Cinq questions sur la durée de vie du jeton, la préparation durable du worker, la lecture de l'état d'un nœud et le diagnostic d'une jonction qui échoue.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

5 questions
5 min.
70% requis

Informations

  • Le chronomètre démarre au clic sur Démarrer
  • Questions à choix multiples, vrai/faux et réponses courtes
  • Vous pouvez naviguer entre les questions
  • Les résultats détaillés sont affichés à la fin

Lance le quiz et démarre le chronomètre