Comment créer un cluster Ku­ber­netes sur Proxmox ?

La création d’un cluster Ku­ber­netes sur Proxmox permet d’exploiter une pla­te­forme d’or­ches­tra­tion de con­te­neurs per­for­mante dans un en­vi­ron­ne­ment vir­tua­lisé et auto-hébergé. Cette approche convient par­ti­cu­liè­re­ment aux en­vi­ron­ne­ments de test, aux workflows de dé­ve­lop­pe­ment et de CI, ainsi qu’à des scénarios de pro­duc­tion de plus petite envergure. Dans ce guide, découvrez comment con­fi­gu­rer des machines vir­tuelles (VM) sur Proxmox et cons­truire, à partir de celles-ci, un cluster Ku­ber­netes Proxmox stable et fiable.

Étape 1 : vérifier les prérequis tech­niques

Avant de démarrer la mise en place du cluster Ku­ber­netes, vous devez vérifier que votre en­vi­ron­ne­ment répond à l’ensemble des prérequis tech­niques. Disposer d’une base propre dès le départ permet de gagner un temps précieux par la suite et de limiter les erreurs de con­fi­gu­ra­tion.

Vous avez tout d’abord besoin d’une ins­tal­la­tion Proxmox VE fonc­tion­nelle. Pour des raisons de per­for­mances, une ins­tal­la­tion bare metal de Proxmox est re­com­man­dée. L’accès Web via l’interface Proxmox ainsi que l’accès SSH à la ligne de commande doivent être dis­po­nibles. Grâce à SSH, vous pouvez exécuter des commandes, té­lé­ver­ser des images et au­to­ma­ti­ser certaines con­fi­gu­ra­tions.

Pour mettre en place un cluster Ku­ber­netes stable, plusieurs machines vir­tuelles sont également né­ces­saires. Les nœuds (nodes) Ku­ber­netes suivants sont re­com­man­dés :

• un nœud master de la control plane
• au moins deux nœuds worker

Cette con­fi­gu­ra­tion apporte une certaine re­don­dance et permet d’exploiter Ku­ber­netes dans des con­di­tions proches d’un en­vi­ron­ne­ment de pro­duc­tion. Pour des tests, une con­fi­gu­ra­tion plus réduite avec un nœud master et un nœud worker peut toutefois suffire.

Votre hôte Proxmox doit par ailleurs disposer d’une interface bridge fonc­tion­nelle, afin que les machines vir­tuelles puissent accéder au réseau local et, si né­ces­saire, à Internet. Cela est in­dis­pen­sable pour permettre aux VM de té­lé­char­ger des mises à jour et d’installer les com­po­sants Ku­ber­netes requis dans un en­vi­ron­ne­ment Ku­ber­netes Proxmox.

Étape 2 : té­lé­char­ger une image Cloud et créer un template Proxmox

Les ins­tal­la­tions Ku­ber­netes s’ef­fec­tuent le plus sim­ple­ment à l’aide d’images Cloud. Ces images de systèmes d’ex­ploi­ta­tion pré­con­fi­gu­rées, gé­né­ra­le­ment basées sur Ubuntu ou Debian, sont op­ti­mi­sées pour un démarrage au­to­ma­tisé avec cloud-init. Dans cet exemple, nous utilisons une image Cloud Ubuntu 22.04 LTS, car elle est stable, bien do­cu­men­tée et par­fai­te­ment adaptée à une uti­li­sa­tion avec Ku­ber­netes.

Commencez par té­lé­char­ger la version la plus récente de l’image Cloud Ubuntu di­rec­te­ment sur votre hôte Proxmox. Pour cela, connectez-vous à votre serveur Proxmox via SSH et accédez au ré­per­toire dans lequel Proxmox stocke les fichiers ISO et les images :

cd /var/lib/vz/template/iso

Té­lé­char­gez ensuite l’image Ubuntu avec la commande suivante :

wget -O ubuntu-22.04-server-cloudimg-amd64.img https://cloud-images.ubuntu.com/releases/22.04/release/ubuntu-22.04-server-cloudimg-amd64.img

scp ubuntu-22.04-server-cloudimg-amd64.img root@<proxmox-ip>:/var/lib/vz/template/iso/

Une fois l’image présente sur l’hôte Proxmox, créez une nouvelle machine virtuelle à partir de celle-ci, qui servira ensuite de modèle (template). Pour cela, créez d’abord une VM vide avec un ID unique, par exemple 9000, et attribuez-lui des res­sources ma­té­rielles de base :

qm create 9000 --name ubuntu-template --memory 2048 --net0 virtio,bridge=vmbr0

Importez main­te­nant l’image Cloud té­lé­char­gée pré­cé­dem­ment comme disque dur virtuel dans le stockage souhaité (dans notre exemple local-lvm) :

qm importdisk 9000 /var/lib/vz/template/iso/ubuntu-22.04-server-cloudimg-amd64.img local-lvm

Rattachez ensuite le disque importé à la VM et con­fi­gu­rer le bon con­trô­leur. De cette manière, l’image est associée au con­trô­leur SCSI virtuel de la machine virtuelle :

qm set 9000 --scsihw virtio-scsi-pci --scsi0 local-lvm:vm-9000-disk-0

Pour pouvoir, plus tard, lors du clonage des VM, définir au­to­ma­ti­que­ment les adresses IP, les noms d’hôte et les clés SSH, vous avez besoin d’un lecteur Cloud-Init. Ce lecteur virtuel contient les données de con­fi­gu­ra­tion ap­pli­quées au­to­ma­ti­que­ment au démarrage de la VM. Ajoutez le lecteur Cloud-Init et dé­fi­nis­sez l’ordre de démarrage avec les commandes suivantes :

qm set 9000 --ide2 local-lvm:cloudinit
qm set 9000 --boot c --bootdisk scsi0

Activez en plus l’agent invité QEMU afin que Proxmox puisse ensuite lire les in­for­ma­tions d’état depuis la VM, et con­fi­gu­rez une console série pour disposer, en cas d’urgence, d’un accès direct à la console de la VM :

qm set 9000 --agent 1
qm set 9000 --serial0 socket --vga serial0

Une fois la con­fi­gu­ra­tion terminée, con­ver­tis­sez votre machine virtuelle en un modèle (template). Dans Proxmox, les templates servent de modèle, à partir duquel vous pouvez ensuite créer autant de clones que né­ces­saire. Ils cons­ti­tuent ainsi une base idéale pour déployer ra­pi­de­ment et de manière cohérente les nœuds d’un en­vi­ron­ne­ment Ku­ber­netes Proxmox.

qm template 9000

Après cette étape, le template Ubuntu est prêt et servira de base à vos nœuds Ku­ber­netes Proxmox.

Étape 3 : cloner les machines vir­tuelles pour les nœuds master et worker

Dans une troisième étape, vous créez, à partir du template créé pré­cé­dem­ment, les machines vir­tuelles qui serviront ensuite de nœuds master et worker de votre cluster Ku­ber­netes Proxmox. Chacune de ces VM reçoit sa propre adresse IP, un nom d’hôte unique ainsi qu’une clé SSH pour un accès sécurisé. Proxmox prend en charge au­to­ma­ti­que­ment la con­fi­gu­ra­tion de base via cloud-init, de sorte que vous n’avez plus besoin d’effectuer de con­fi­gu­ra­tion manuelle au sein des machines vir­tuelles.

Commencez par cloner le template créé préa­la­ble­ment (dans cet exemple avec l’ID 9000) et créez à partir de celui-ci trois machines vir­tuelles : une pour le nœud master et deux pour les nœuds worker cor­res­pon­dants. Adaptez également in­di­vi­duel­le­ment le CPU et la mémoire vive :

qm clone 9000 101 --name k8s-master-1 --full true
qm set 101 --cores 2 --memory 4096
qm clone 9000 102 --name k8s-worker-1 --full true
qm set 102 --cores 2 --memory 4096
qm clone 9000 103 --name k8s-worker-2 --full true
qm set 103 --cores 2 --memory 4096

Ensuite, vous dé­fi­nis­sez via cloud-init les pa­ra­mètres réseau de base, le nom d’hôte et la clé SSH. Vous pouvez attribuer des adresses IP fixes ou utiliser le DHCP. Dans cet exemple, des adresses statiques sont utilisées :

# Configurer le nœud master
qm set 101 --ipconfig0 ip=192.168.1.10/24,gw=192.168.1.1
qm set 101 --sshkey "$(cat ~/.ssh/id_rsa.pub)"
qm set 101 --ciuser ubuntu
qm set 101 --nameserver 192.168.1.1
qm set 101 --description "K8s Control Plane 1"
# Configurer les nœuds worker
qm set 102 --ipconfig0 ip=192.168.1.11/24,gw=192.168.1.1
qm set 102 --sshkey "$(cat ~/.ssh/id_rsa.pub)"
qm set 102 --ciuser ubuntu
qm set 103 --ipconfig0 ip=192.168.1.12/24,gw=192.168.1.1
qm set 103 --sshkey "$(cat ~/.ssh/id_rsa.pub)"
qm set 103 --ciuser ubuntu

Pour finir, démarrez les trois machines avec les commandes de terminal ci-dessous :

qm start 101
qm start 102
qm start 103

Attendez un moment, le temps que les systèmes aient com­plè­te­ment démarré, puis testez la connexion via SSH. Si tout fonc­tionne, vous pouvez par exemple vous connecter au nœud master avec la commande suivante :

ssh ubuntu@192.168.1.10

Étape 4 : appliquer la con­fi­gu­ra­tion système de base sur toutes les VM

Avant d’installer Ku­ber­netes sur les VM, certains réglages au niveau du système sont in­dis­pen­sables pour garantir un fonc­tion­ne­ment stable. Cela comprend la dé­sac­ti­va­tion du swap, l’ajus­te­ment des pa­ra­mètres du noyau pour le réseau et l’IP for­war­ding, ainsi que la syn­chro­ni­sa­tion de l’heure système. Ces mesures assurent que Ku­ber­netes fonc­tionne cor­rec­te­ment et que les mé­ca­nismes réseau au sein des con­te­neurs restent fiables.

Commencez par dé­sac­ti­ver le swap sur l’ensemble des nœuds, car Ku­ber­netes l’exige pour le bon fonc­tion­ne­ment du scheduler. Supprimez également l’entrée cor­res­pon­dante dans /etc/fstab, afin d’éviter toute réac­ti­va­tion du swap après un re­dé­mar­rage :

sudo swapoff -a
sudo sed -i '/ swap / s/^/#/' /etc/fstab

Ensuite, con­fi­gu­rez les pa­ra­mètres du noyau afin de vous assurer que les paquets réseau peuvent être traités cor­rec­te­ment entre les con­te­neurs et les nœuds :

cat <<'EOF' | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables = 1
net.ipv4.ip_forward = 1
net.bridge.bridge-nf-call-ip6tables = 1
EOF
# Appliquer les modifications
sudo sysctl --system

Une autre étape im­por­tante consiste à syn­chro­ni­ser l’heure système, afin que les cer­ti­fi­cats et les com­po­sants du cluster ne ren­contrent pas de problèmes dus à des écarts d’horloge. Pour cela, installez et démarrez chrony :

sudo apt update && sudo apt install -y chrony
sudo systemctl enable --now chrony

Enfin, il est re­com­mandé d’installer quelques outils de base, utiles pour les étapes suivantes :

sudo apt install -y curl apt-transport-https ca-certificates gnupg lsb-release

Après ces étapes, tous les nœuds sont préparés de manière uniforme, le swap est désactivé, les pa­ra­mètres réseau sont cor­rec­te­ment définis et l’heure est syn­chro­ni­sée. Vos VM sont désormais prêtes pour l’ins­tal­la­tion de Ku­ber­netes et la mise en place de votre cluster.

Étape 5 : choisir la dis­tri­bu­tion Ku­ber­netes adaptée

Avant de commencer l’ins­tal­la­tion pro­pre­ment dite de Ku­ber­netes, vous devez choisir une dis­tri­bu­tion adaptée. Selon vos besoins, optez pour l’une des deux variantes re­com­man­dées :

• RKE2 (Rancher Ku­ber­netes Engine 2) : RKE2 est une dis­tri­bu­tion Ku­ber­netes stable et prête pour la pro­duc­tion, dé­ve­lop­pée par Rancher. Elle convient par­ti­cu­liè­re­ment si vous prévoyez d’utiliser par la suite une interface d’ad­mi­nis­tra­tion graphique via Rancher ou de mettre en place un cluster avec plusieurs nœuds de la control plane.
• k3s : k3s est une dis­tri­bu­tion Ku­ber­netes légère, bien adaptée aux en­vi­ron­ne­ments de test, aux Home Labs ou aux systèmes disposant de res­sources limitées. Elle se distingue par une ins­tal­la­tion simple et une con­som­ma­tion réduite de mémoire et de CPU.

Pour la mise en place d’un cluster Ku­ber­netes Proxmox robuste, pouvant également être utilisé dans un contexte proche de la pro­duc­tion, RKE2 est re­com­mandé. Si vous souhaitez en revanche déployer ra­pi­de­ment un petit cluster de test ou de dé­ve­lop­pe­ment, k3s constitue une al­ter­na­tive par­ti­cu­liè­re­ment pratique. Dans la suite de ce guide, RKE2 est utilisé.

Étape 6 : installer RKE2 sur le nœud master

Une fois la con­fi­gu­ra­tion de base de vos machines vir­tuelles terminée, commencez l’ins­tal­la­tion de RKE2 sur le nœud master. Pour cela, connectez-vous au nœud master via SSH :

ssh ubuntu@192.168.1.10

Té­lé­char­gez main­te­nant le script d’ins­tal­la­tion de RKE2 et exécutez-le. Vous pouvez, en option, indiquer un canal cor­res­pon­dant à la version souhaitée :

curl -sfL https://get.rke2.io | sudo INSTALL_RKE2_CHANNEL=v1.28 bash -

Après l’ins­tal­la­tion, activez le service serveur RKE2 et démarrez-le im­mé­dia­te­ment :

sudo systemctl enable --now rke2-server.service

Vérifiez avec la commande suivante si le serveur RKE2 fonc­tionne cor­rec­te­ment :

sudo systemctl status rke2-server

Pour pouvoir gérer le cluster Ku­ber­netes depuis votre machine locale, copiez le fichier kubeconfig :

sudo chmod 644 /etc/rancher/rke2/rke2.yaml
scp ubuntu@192.168.1.10:/etc/rancher/rke2/rke2.yaml ~/rke2-kubeconfig

Ensuite, adaptez l’IP du master dans le fichier afin que kubectl accède cor­rec­te­ment au serveur :

sed -i 's/127.0.0.1:6443/192.168.1.10:6443/' ~/rke2-kubeconfig
export KUBECONFIG=~/rke2-kubeconfig

Avec cette commande, vérifiez main­te­nant si le nœud master est joignable :

kubectl get nodes

Si le master s’affiche, l’ins­tal­la­tion est terminée avec succès ! Vous pouvez passer à l’étape suivante, c’est-à-dire ajouter les nœuds worker.

Étape 7 : joindre les nœuds worker au cluster avec RKE2

Une fois le nœud master configuré avec succès, intégrez les nœuds worker à votre cluster. Pour cela, installez l’agent RKE2 sur chaque worker et connectez-le au master.

Sur le nœud master, vous avez d’abord besoin du node token, qui est né­ces­saire à l’au­then­ti­fi­ca­tion des workers auprès du cluster :

sudo cat /var/lib/rancher/rke2/server/node-token

Notez le token. Vous aurez besoin de cette valeur juste après sur les nœuds worker.

Connectez-vous via SSH sur chaque nœud worker :

ssh ubuntu@192.168.1.11

Té­lé­char­gez le script d’ins­tal­la­tion de RKE2 et installez l’agent avec la commande suivante :

curl -sfL https://get.rke2.io | sudo INSTALL_RKE2_CHANNEL=v1.28 sh -

Créez ensuite le fichier de con­fi­gu­ra­tion de l’agent et ren­seig­nez-y l’IP du master ainsi que le token du nœud :

sudo mkdir -p /etc/rancher/rke2
cat <<EOF | sudo tee /etc/rancher/rke2/config.yaml
server: https://192.168.1.10
token: <INSÉRER_LE_TOKEN_ICI>
EOF

Pour finir, activez et démarrez le service de l’agent RKE2 :

sudo systemctl enable --now rke2-agent.service

Répétez cette opération pour tous les nœuds worker du cluster. Après quelques minutes, vérifiez sur le master si les nœuds worker sont cor­rec­te­ment connectés :

kubectl get nodes

Vous devriez main­te­nant voir tous les nœuds, le master ainsi que les workers nou­vel­le­ment ajoutés. Votre cluster est ainsi complet et prêt pour l’ins­tal­la­tion de plugins réseau, de load balancers et d’autres com­po­sants Ku­ber­netes.

Étape 8 : con­fi­gu­rer le réseau du cluster avec un CNI et un Load Balancer

Une fois les nœuds de la control plane et les nœuds worker con­fi­gu­rés avec succès, vous devez mettre en place une Container Network Interface (CNI) afin de permettre la com­mu­ni­ca­tion entre les pods au sein du cluster, ainsi qu’un Load Balancer pour rendre les services ac­ces­sibles sur le réseau. Dans ce guide, nous utilisons Calico comme CNI et MetalLB pour assurer la fonc­tion­na­lité de load balancing en couche 2.

Calico établit les con­nexions réseau entre les pods, gère l’at­tri­bu­tion des adresses IP et permet, en option, la dé­fi­ni­tion de po­li­tiques réseau. Son ins­tal­la­tion s’effectue sim­ple­ment à l’aide d’une commande dans le terminal :

kubectl apply -f https://docs.projectcalico.org/manifests/calico.yaml

Vérifiez ensuite si tous les pods Calico ont bien démarré :

kubectl get pods -n kube-system

Tous les pods doivent afficher le statut Running ou Completed. Si certains pods affichent encore Pending, patientez quelques minutes, car Calico a besoin d’un certain temps pour dis­tri­buer la con­fi­gu­ra­tion réseau sur tous les nœuds.

Ku­ber­netes prend en charge par défaut le type de Service Load Balancer, qui nécessite des IP externes. Dans un cluster auto-hébergé comme sur Proxmox, MetalLB est utilisé à cet effet. Installez d’abord MetalLB :

kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.13.10/config/manifests/metallb-native.yaml

Créez ensuite un pool d’IP à partir duquel MetalLB peut attribuer des adresses IP aux services. Adaptez la plage d’IP à votre réseau local :

cat <<EOF | kubectl apply -f
apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
name: my-ip-pool
namespace: metallb-system
spec:
addresses:
- 192.168.1.200-192.168.1.210
---
apiVersion: metallb.io/v1beta1
kind: L2Advertisement
metadata:
name: l2adv
namespace: metallb-system
spec: {}
EOF

Vérifiez également ici que les pods MetalLB fonc­tion­nent cor­rec­te­ment :

kubectl get pods -n metallb-system

Dès que tous les pods ont le statut Running, votre réseau est configuré. Vous pouvez désormais utiliser des types de services Load­Ba­lan­cer pour rendre des ap­pli­ca­tions ac­ces­sibles sur le LAN. Votre cluster Ku­ber­netes Proxmox est ainsi en­tiè­re­ment configuré et prêt à déployer des ap­pli­ca­tions et à gérer les res­sources réseau.