# Comment créer un cluster Kubernetes sur Proxmox ? La création d’un cluster Kubernetes sur Proxmox permet d’exploiter une plateforme d’orchestration de conteneurs performante dans un environnement virtualisé et auto-hébergé. Cette approche convient particulièrement aux environnements de test, aux workflows de développement et de CI, ainsi qu’à des scénarios de production de plus petite envergure. Dans ce guide, découvrez comment configurer des machines virtuelles (VM) sur Proxmox et construire, à partir de celles-ci, un cluster Kubernetes Proxmox stable et fiable. ## Étape 1 : vérifier les prérequis techniques Avant de démarrer la mise en place du cluster Kubernetes, vous devez vérifier que votre environnement répond à l’ensemble des prérequis techniques. 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 configuration. Vous avez tout d’abord besoin d’une installation [Proxmox](https://www.ionos.fr/digitalguide/serveur/know-how/proxmox/) VE fonctionnelle. Pour des raisons de performances, une [installation bare metal de Proxmox](https://www.ionos.fr/digitalguide/serveur/configuration/installation-proxmox-sur-bare-metal/) est recommandée. L’**accès Web** via l’interface Proxmox ainsi que l’**accès SSH** à la ligne de commande doivent être disponibles. Grâce à [SSH](https://www.ionos.fr/digitalguide/serveur/outils/protocole-ssh/), vous pouvez exécuter des commandes, téléverser des images et automatiser certaines configurations. Pour mettre en place un [cluster Kubernetes](https://www.ionos.fr/digitalguide/serveur/know-how/cluster-kubernetes/) stable, plusieurs [machines virtuelles](https://www.ionos.fr/digitalguide/serveur/know-how/machine-virtuelle/) sont également nécessaires. Les [nœuds (nodes) Kubernetes](https://www.ionos.fr/digitalguide/serveur/configuration/nodes-kubernetes/) suivants sont recommandés : - un nœud master de la control plane - au moins deux nœuds worker Cette configuration apporte une certaine redondance et permet d’exploiter [Kubernetes](https://www.ionos.fr/digitalguide/serveur/know-how/kubernetes/) dans des conditions proches d’un environnement de production. Pour des tests, une configuration 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 fonctionnelle**, afin que les machines virtuelles puissent accéder au réseau local et, si nécessaire, à Internet. Cela est indispensable pour permettre aux VM de télécharger des mises à jour et d’installer les composants Kubernetes requis dans un environnement Kubernetes Proxmox. Conseil Pour les environnements de production, il est également recommandé de configurer des sauvegardes régulières des machines virtuelles via un [serveur de sauvegarde Proxmox](https://www.ionos.fr/digitalguide/serveur/configuration/proxmox-backup-server/). Vous pouvez ainsi restaurer rapidement vos nœuds Kubernetes en cas de besoin et réduire les temps d’arrêt. ## Étape 2 : télécharger une image Cloud et créer un template Proxmox Les installations Kubernetes s’effectuent le plus simplement à l’aide d’**images Cloud**. Ces images de systèmes d’exploitation préconfigurées, généralement basées sur Ubuntu ou Debian, sont optimisées pour un démarrage automatisé avec `cloud-init`. Dans cet exemple, nous utilisons une image Cloud Ubuntu 22.04 LTS, car elle est stable, bien documentée et parfaitement adaptée à une utilisation avec Kubernetes. Commencez par télécharger la version la plus récente de l’image Cloud Ubuntu directement sur votre hôte Proxmox. Pour cela, connectez-vous à votre serveur Proxmox via SSH et accédez au répertoire dans lequel Proxmox stocke les fichiers ISO et les images : ```bash cd /var/lib/vz/template/iso ``` Téléchargez ensuite l’image Ubuntu avec la commande suivante : ```bash 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 ``` Note Vous pouvez aussi télécharger d’abord l’image sur votre machine locale, puis la transférer vers l’hôte Proxmox via `scp` (Secure Copy) : ```bash scp ubuntu-22.04-server-cloudimg-amd64.img root@:/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 ressources matérielles de base : ```bash qm create 9000 --name ubuntu-template --memory 2048 --net0 virtio,bridge=vmbr0 ``` Importez maintenant l’image Cloud téléchargée précédemment **comme disque dur virtuel dans le stockage souhaité** (dans notre exemple `local-lvm`) : ```bash qm importdisk 9000 /var/lib/vz/template/iso/ubuntu-22.04-server-cloudimg-amd64.img local-lvm ``` Conseil Si votre cluster Proxmox dispose d’un stockage distribué, vous pouvez également enregistrer l’image dans le stockage Ceph. L’intégration de [Ceph sur Proxmox](https://www.ionos.fr/digitalguide/serveur/configuration/ceph-sur-proxmox/) fournit une solution de stockage hautement disponible et évolutive, particulièrement adaptée aux VM d’un environnement Kubernetes Proxmox. Rattachez ensuite le disque importé à la VM et configurer le bon contrôleur. De cette manière, l’image est associée au contrôleur SCSI virtuel de la machine virtuelle : ```bash 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 automatiquement les [adresses IP](https://www.ionos.fr/digitalguide/serveur/know-how/quest-ce-quune-adresse-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 configuration appliquées automatiquement au démarrage de la VM. Ajoutez le lecteur Cloud-Init et définissez l’ordre de démarrage avec les commandes suivantes : ```bash qm set 9000 --ide2 local-lvm:cloudinit qm set 9000 --boot c --bootdisk scsi0 ``` Activez en plus l’agent invité [QEMU](https://www.ionos.fr/digitalguide/serveur/configuration/qemu/) afin que Proxmox puisse ensuite **lire les informations d’état depuis la VM**, et configurez une console série pour disposer, en cas d’urgence, d’un accès direct à la console de la VM : ```bash qm set 9000 --agent 1 qm set 9000 --serial0 socket --vga serial0 ``` Une fois la configuration terminée, convertissez 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écessaire. Ils constituent ainsi une base idéale pour déployer rapidement et de manière cohérente les nœuds d’un environnement Kubernetes Proxmox. ```bash qm template 9000 ``` Après cette étape, le template Ubuntu est prêt et servira de base à vos nœuds Kubernetes Proxmox. ## Étape 3 : cloner les machines virtuelles pour les nœuds master et worker Dans une troisième étape, vous créez, à partir du template créé précédemment, les machines virtuelles qui serviront ensuite de **nœuds master et worker de votre cluster Kubernetes 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 automatiquement la configuration de base via `cloud-init`, de sorte que vous n’avez plus besoin d’effectuer de configuration manuelle au sein des machines virtuelles. Commencez par cloner le template créé préalablement (dans cet exemple avec l’ID 9000) et créez à partir de celui-ci **trois machines virtuelles** : une pour le nœud master et deux pour les nœuds worker correspondants. Adaptez également individuellement le [CPU](https://www.ionos.fr/digitalguide/serveur/know-how/cpu/) et la [mémoire vive](https://www.ionos.fr/digitalguide/serveur/know-how/quest-ce-quune-memoire-vive/) : ```bash 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éfinissez via `cloud-init` les paramè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](https://www.ionos.fr/digitalguide/serveur/configuration/dhcp-le-protocole-reseau-client-serveur/). Dans cet exemple, des adresses statiques sont utilisées : ```bash # 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 ``` Note Adaptez les adresses IP d’exemple utilisées ici à la configuration de votre propre réseau. Veillez à sélectionner des adresses issues de la plage IP de votre routeur et à attribuer à chaque VM une adresse unique, qui n’est pas déjà utilisée. Pour finir, démarrez les trois machines avec les commandes de terminal ci-dessous : ```bash qm start 101 qm start 102 qm start 103 ``` Attendez un moment, le temps que les systèmes aient complètement démarré, puis **testez la connexion via SSH**. Si tout fonctionne, vous pouvez par exemple vous connecter au nœud master avec la commande suivante : ```none ssh ubuntu@192.168.1.10 ``` ## Étape 4 : appliquer la configuration système de base sur toutes les VM Avant d’installer Kubernetes sur les VM, certains réglages au niveau du système sont indispensables pour garantir un fonctionnement stable. Cela comprend la désactivation du swap, l’ajustement des paramètres du [noyau](https://www.ionos.fr/digitalguide/serveur/know-how/quest-ce-quun-noyau-de-systeme-dexploitation/) pour le réseau et l’IP forwarding, ainsi que la synchronisation de l’heure système. Ces mesures assurent que Kubernetes fonctionne correctement et que les mécanismes réseau au sein des conteneurs restent fiables. Commencez par désactiver le swap sur l’ensemble des nœuds, car Kubernetes l’**exige pour le bon fonctionnement du scheduler**. Supprimez également l’entrée correspondante dans `/etc/fstab`, afin d’éviter toute réactivation du swap après un redémarrage : ```bash sudo swapoff -a sudo sed -i '/ swap / s/^/#/' /etc/fstab ``` Ensuite, configurez les paramètres du noyau afin de vous assurer que les paquets réseau peuvent être traités correctement entre les conteneurs et les nœuds : ```bash 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 importante consiste à synchroniser l’heure système, afin que les certificats et les composants du cluster ne rencontrent pas de problèmes dus à des écarts d’horloge. Pour cela, installez et démarrez `chrony` : ```bash sudo apt update && sudo apt install -y chrony sudo systemctl enable --now chrony ``` Enfin, il est recommandé d’installer quelques **outils de base**, utiles pour les étapes suivantes : ```bash 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 paramètres réseau sont correctement définis et l’heure est synchronisée. Vos VM sont désormais prêtes pour l’installation de Kubernetes et la mise en place de votre cluster. ## Étape 5 : choisir la distribution Kubernetes adaptée Avant de commencer l’installation proprement dite de Kubernetes, vous devez choisir une **distribution adaptée**. Selon vos besoins, optez pour l’une des deux variantes recommandées : - **RKE2 (Rancher Kubernetes Engine 2) :** RKE2 est une distribution Kubernetes stable et prête pour la production, développée par Rancher. Elle convient particulièrement si vous prévoyez d’utiliser par la suite une interface d’administration graphique via Rancher ou de mettre en place un cluster avec plusieurs nœuds de la control plane. - **k3s :** [k3s](https://www.ionos.fr/digitalguide/serveur/know-how/quest-ce-que-k3s/) est une distribution Kubernetes légère, bien adaptée aux environnements de test, aux Home Labs ou aux systèmes disposant de ressources limitées. Elle se distingue par une installation simple et une consommation réduite de mémoire et de CPU. Pour la mise en place d’un **cluster Kubernetes Proxmox** robuste, pouvant également être utilisé dans un contexte proche de la production, **RKE2 est recommandé**. Si vous souhaitez en revanche déployer rapidement un petit cluster de test ou de développement, k3s constitue une alternative particulièrement pratique. Dans la suite de ce guide, RKE2 est utilisé. ## Étape 6 : installer RKE2 sur le nœud master Une fois la configuration de base de vos machines virtuelles terminée, commencez l’**installation de RKE2 sur le nœud master**. Pour cela, connectez-vous au nœud master via SSH : ```bash ssh ubuntu@192.168.1.10 ``` Téléchargez maintenant le script d’installation de RKE2 et exécutez-le. Vous pouvez, en option, indiquer un canal correspondant à la version souhaitée : ```bash curl -sfL https://get.rke2.io | sudo INSTALL_RKE2_CHANNEL=v1.28 bash - ``` Après l’installation, activez le service serveur RKE2 et démarrez-le immédiatement : ```bash sudo systemctl enable --now rke2-server.service ``` Vérifiez avec la commande suivante si le serveur RKE2 fonctionne correctement : ```bash sudo systemctl status rke2-server ``` Pour pouvoir gérer le cluster Kubernetes depuis votre machine locale, copiez le fichier `kubeconfig` : ```bash 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 correctement au serveur : ```bash sed -i 's/127.0.0.1:6443/192.168.1.10:6443/' ~/rke2-kubeconfig export KUBECONFIG=~/rke2-kubeconfig ``` Avec cette commande, vérifiez maintenant si le nœud master est joignable : ```bash kubectl get nodes ``` Si le master s’affiche, l’installation 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écessaire à l’authentification des workers auprès du cluster : ```bash 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 : ```bash ssh ubuntu@192.168.1.11 ``` Téléchargez le script d’installation de RKE2 et installez l’agent avec la commande suivante : ```bash curl -sfL https://get.rke2.io | sudo INSTALL_RKE2_CHANNEL=v1.28 sh - ``` Créez ensuite le fichier de configuration de l’agent et renseignez-y l’IP du master ainsi que le token du nœud : ```bash sudo mkdir -p /etc/rancher/rke2 cat < EOF ``` Pour finir, activez et démarrez le service de l’agent RKE2 : ```bash 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 correctement connectés : ```bash kubectl get nodes ``` Vous devriez maintenant voir tous les nœuds, le master ainsi que les workers nouvellement ajoutés. Votre cluster est ainsi complet et prêt pour l’installation de plugins réseau, de load balancers et d’autres composants Kubernetes. ## Étape 8 : configurer 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 configurés avec succès, vous devez mettre en place une **Container Network Interface (CNI)** afin de permettre la communication entre les pods au sein du cluster, ainsi qu’un **Load Balancer** pour rendre les services accessibles sur le réseau. Dans ce guide, nous utilisons Calico comme CNI et MetalLB pour assurer la fonctionnalité de [load balancing](https://www.ionos.fr/digitalguide/serveur/know-how/load-balancer-repartition-de-charge-sur-un-serveur/) en couche 2. **Calico établit les connexions réseau entre les pods**, gère l’attribution des adresses IP et permet, en option, la définition de politiques réseau. Son installation s’effectue simplement à l’aide d’une commande dans le terminal : ```bash kubectl apply -f https://docs.projectcalico.org/manifests/calico.yaml ``` Vérifiez ensuite si tous les pods Calico ont bien démarré : ```bash 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 distribuer la configuration réseau sur tous les nœuds. Kubernetes 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 : ```bash 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 : ```bash cat <