> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/learn-the-platform/fr/module-8-developpeur-et-devops/07-kubernetes-rancher.md). # Intégration Kubernetes et Rancher Exécuter Kubernetes sur VergeOS n'est pas un ajout greffé — c'est une **intégration de premier ordre** conçue à partir de quatre composants spécialement développés (Docker Machine Driver, Rancher UI Extension, Cloud Controller Manager et CSI Driver), plus un Cluster Autoscaler optionnel pour les clusters provisionnés par Rancher, qui donnent à Rancher (et à tout déploiement RKE2/K3s) une connaissance complète du calcul, du stockage et du réseau VergeOS. Au lieu de traiter VergeOS comme un simple hôte de VM, ces composants permettent à Kubernetes de provisionner des nœuds, d'attacher un stockage persistant et de créer des équilibreurs de charge via les API natives de VergeOS — les mêmes API qui alimentent le tableau de bord. ## Prérequis Avant d'installer l'intégration, assurez-vous que l'environnement fournit : * Un **Rancher Server** installation (v2.10+) avec `kubectl` et `helm` outils CLI * Un **VM modèle** exécutant Ubuntu 24.04 avec cloud-init installé (et l'agent invité QEMU recommandé) * Un **clé API VergeOS** générée dans **Paramètres utilisateur** * Un réseau VergeOS cible avec **DHCP activé** — le pilote détecte les adresses IP des nœuds via l'agent invité QEMU et les VM clonées n'obtiendront pas d'adresse sans DHCP * Pour le stockage persistant sur bloc : une VM VergeOS vide nommée **`k8spool`** pour héberger des disques bloc inactifs (son ID de VM est transmis au chart Helm CSI au moment de l'installation ; la VM n'a jamais besoin de démarrer) ## Vue d'ensemble de la pile L'intégration Kubernetes de VergeOS est fournie sous la forme de quatre composants distincts — Docker Machine Driver, Rancher UI Extension, Cloud Controller Manager et CSI Driver — chacun responsable d'une couche de la pile, avec un Cluster Autoscaler optionnel disponible pour les clusters provisionnés par Rancher : ```mermaid graph TB subgraph "Tableau de bord Rancher" UI["Extension UI
(panneaux VergeOS)"] RC["Identifiant cloud &
Configuration de machine"] end subgraph "Provisionnement des nœuds" DMD["Pilote Docker Machine
(docker-machine-driver-vergeos)"] end subgraph "Cluster Kubernetes" CCM["Gestionnaire du contrôleur cloud
(vergeos-cloud-controller-manager)"] CSI["Pilote CSI
(csi-vergeos)"] end subgraph "Plateforme VergeOS" API["API REST VergeOS"] VM["VM et modèles"] VSAN["Stockage vSAN / NAS"] NET["Réseaux virtuels"] end UI --> RC RC --> DMD DMD -->|"Cloner le modèle,
injecter les clés SSH"| API API --> VM CCM -->|"Cycle de vie des nœuds,
équilibreurs de charge"| API API --> NET CSI -->|"Volumes persistants"| API API --> VSAN ``` ### Pilote Docker Machine Provisionne des VM VergeOS comme nœuds Kubernetes — clone les modèles, injecte les clés SSH, redimensionne les disques et attache les réseaux. ### Extension UI de Rancher Expose directement dans le tableau de bord Rancher les panneaux de Cloud Credential et de Machine Config spécifiques à VergeOS. ### Gestionnaire du contrôleur cloud Synchronise l'état des nœuds Kubernetes avec le cycle de vie des VM VergeOS et provisionne les services d'équilibrage de charge à la demande. ### Pilote CSI Associe le stockage vSAN/NAS/bloc de VergeOS aux PersistentVolumes Kubernetes pour les charges de travail avec état. Les quatre composants (DMD, UI Extension, CCM, CSI driver) sont distribués via le **dépôt Helm verge-io**, garantissant une gestion cohérente des versions et une installation simplifiée. Un **Cluster Autoscaler** est disponible pour les clusters provisionnés par Rancher. ## Pilote Docker Machine Le `docker-machine-driver-vergeos` est le socle de l'intégration. Il apprend à Docker Machine (et, par extension, à Rancher) à créer des VM sur VergeOS — faisant de VergeOS un provisionneur de nœuds de premier ordre pour les clusters RKE2 et K3s. ### Fonctionnement Lorsque Rancher (ou Docker Machine autonome) demande un nouveau nœud, le pilote exécute la séquence suivante : 1. **Clone la VM modèle** — Un modèle de VM VergeOS préconstruit (par ex. Ubuntu 24.04 avec cloud-init) est cloné pour créer le nouveau nœud 2. **Configure les ressources de calcul** — Les cœurs CPU et la RAM sont définis selon la spécification du cluster 3. **Injecte les clés SSH via cloud-init** — Le pilote génère une paire de clés SSH et injecte la clé publique via cloud-init pour un accès sécurisé sans mot de passe 4. **Redimensionne le disque principal** — Si le cluster nécessite plus de stockage que celui fourni par le modèle, le pilote redimensionne le disque de démarrage 5. **Se connecte au réseau cible** — La VM est connectée au réseau virtuel VergeOS spécifié 6. **Démarre et attend l'adresse IP** — Le pilote surveille l'obtention d'une adresse IP via l'agent invité QEMU (méthode privilégiée) ou, à défaut, le bail DHCP Si une étape échoue, le pilote nettoie automatiquement les VM partiellement créées — aucune ressource orpheline n'est laissée derrière. ### Authentification Le pilote utilise **l'authentification par clé API** pour communiquer avec l'API REST VergeOS. Générez une clé API depuis l'interface VergeOS dans **Paramètres utilisateur** , puis fournissez-la via le `--vergeos-api-key` indicateur ou la `VERGEOS_API_KEY` variable d'environnement. ### Options de configuration | Option | Variable d'environnement | Valeur par défaut | Description | | ----------------------- | ------------------------ | ---------------------- | ------------------------------------------------------------ | | `--vergeos-host` | `VERGEOS_HOST` | *(obligatoire)* | URL du point de terminaison VergeOS | | `--vergeos-api-key` | `VERGEOS_API_KEY` | *(obligatoire)* | Clé API pour l'authentification | | `--vergeos-insecure` | `VERGEOS_INSECURE` | `false` | Ignorer la vérification TLS | | `--vergeos-template-vm` | `VERGEOS_TEMPLATE_VM` | *(obligatoire)* | Nom de la VM modèle à cloner | | `--vergeos-network` | `VERGEOS_NETWORK` | *(obligatoire)* | Réseau cible pour la connexion | | `--vergeos-cpu-cores` | `VERGEOS_CPU_CORES` | `2` | Cœurs CPU par nœud | | `--vergeos-ram` | `VERGEOS_RAM` | `2048` | RAM en Mo par nœud | | `--vergeos-disk-size` | `VERGEOS_DISK_SIZE` | `0` (taille du modèle) | Remplacement de la taille du disque en Mo | | `--vergeos-ssh-user` | `VERGEOS_SSH_USER` | `root` | Nom d'utilisateur SSH | | `--vergeos-ssh-port` | `VERGEOS_SSH_PORT` | `22` | Port SSH | | `--vergeos-cloudinit` | — | — | Configuration cloud-init personnalisée (fichier ou en ligne) | ### Exigences du modèle Votre modèle de VM doit inclure : * **Cloud-init** installé et activé — requis pour l'injection des clés SSH et la configuration du nom d'hôte * **QEMU guest agent** (recommandé) — fournit une détection fiable de l'adresse IP ; utilise à défaut le bail DHCP de la carte réseau si indisponible * **Docker** (utilisation autonome uniquement) — les déploiements Rancher installent automatiquement le runtime de conteneurs ### Prise en charge d'Ubuntu 24.04 Le pilote inclut une prise en charge automatique des particularités d'Ubuntu 24.04 : * **Configuration DHCP Netplan** pour le `en*` nommage dynamique des interfaces * **Régénération du Machine-ID** pour garantir des identifiants DHCP uniques par clone * **Nettoyage des baux DHCP obsolètes** pour éviter les conflits d'adresses IP dus à l'héritage du modèle {% hint style="success" %} **Dimensionnement des nœuds Rancher** Les déploiements Rancher nécessitent un **minimum de 4 Go de RAM** par nœud. Pour une stabilité en production, **8 Go de RAM** par nœud est recommandé. {% endhint %} ### Utilisation autonome Vous pouvez utiliser le pilote en dehors de Rancher pour un provisionnement ponctuel avec Docker Machine : ```bash docker-machine create --driver vergeos \\ --vergeos-host vergeos.example.com \\ --vergeos-api-key your-api-key \\ --vergeos-template-vm ubuntu-2404 \\ --vergeos-network my-k8s-network \\ --vergeos-ssh-user ubuntu \\ --vergeos-cpu-cores 4 \\ --vergeos-ram 8192 \\ k8s-worker-01 ``` {% hint style="info" %} **Utilisateur SSH par défaut** Le pilote utilise par défaut `root` pour SSH, mais les images cloud Ubuntu n'autorisent pas la connexion SSH en root. Lorsque vous utilisez directement la CLI avec un modèle Ubuntu, définissez `--vergeos-ssh-user ubuntu` (l'extension UI Rancher utilise déjà par défaut `ubuntu`). {% endhint %} ## Extension UI de Rancher Le `ui-extension-vergeos` ajoute des panneaux spécifiques à VergeOS au **tableau de bord Rancher**, offrant une expérience utilisateur native pour gérer les clusters Kubernetes adossés à VergeOS sans quitter l'interface Rancher. ### Panneau des identifiants cloud Lors de la création d'un nouvel identifiant cloud dans Rancher, l'extension ajoute une **VergeOS** option de fournisseur. Saisissez l'URL d'hôte VergeOS, la clé API et les paramètres TLS — Rancher les stocke de manière sécurisée et les utilise pour toutes les opérations ultérieures de provisionnement des nœuds. ### Panneau de configuration de machine Lors de la définition des pools de nœuds pour un nouveau cluster, l'extension expose des champs de configuration spécifiques à VergeOS : * **VM modèle** — Sélectionnez parmi les modèles de VM VergeOS disponibles * **Réseau** — Choisissez le réseau virtuel cible * **CPU / RAM / Disque** — Définissez les ressources de calcul par nœud * **Cloud-init** — Fournissez des scripts d'initialisation personnalisés L'extension est déployée dans le cadre du `vergeos-node-driver` chart Helm, qui regroupe à la fois le Docker Machine Driver et l'UI Extension. ## Gestionnaire du contrôleur cloud Le `vergeos-cloud-controller-manager` (CCM) fait le pont entre les opérations du cluster Kubernetes et le plan de contrôle VergeOS, en implémentant l'interface standard de fournisseur cloud Kubernetes. ### Synchronisation du cycle de vie des nœuds Le CCM surveille en continu la liste des nœuds Kubernetes et la synchronise avec l'état des VM VergeOS : * **Enregistrement du nœud** — Lorsqu'un nouveau nœud rejoint le cluster, le CCM lui ajoute des métadonnées spécifiques à VergeOS (ID de VM, réseau, zone) * **Suppression du nœud** — Lorsqu'une VM VergeOS est supprimée ou arrêtée, le CCM marque le nœud Kubernetes correspondant comme indisponible et déclenche la replanification des pods * **Surveillance de l'état** — Des vérifications périodiques garantissent que l'état du nœud Kubernetes reflète l'état réel de la VM ### Provisionnement de l'équilibreur de charge Lorsqu'un Service Kubernetes de type `LoadBalancer` est créé, le CCM provisionne un équilibreur de charge via la couche réseau VergeOS : * Alloue une IP virtuelle depuis le pool d'adresses configuré * Configure la distribution du trafic sur les ports des nœuds de backend * Met à jour le Service `status.loadBalancer.ingress` avec l'IP allouée VergeOS gère nativement le provisionnement de l'équilibreur de charge via le CCM. {% hint style="info" %} **Vous venez de VMware ?** Sur VergeOS, le CCM combine la gestion du cycle de vie des nœuds et `LoadBalancer` le provisionnement des Services dans un seul composant installé via Helm — pas besoin d'assembler des modules cloud-provider, CSI/CPI et load-balancer séparés. {% endhint %} {% hint style="info" %} **Vous venez de Nutanix ?** VergeOS fonctionne avec n'importe quelle chaîne d'outils RKE2/K3s via Rancher plutôt que de fournir une distribution Kubernetes propriétaire — vous choisissez la variante Kubernetes amont, et le CCM fournit par-dessus l'intégration native du fournisseur cloud. {% endhint %} ## Pilote CSI Le `csi-vergeos` (pilote Container Storage Interface) expose le stockage VergeOS aux charges de travail Kubernetes via la spécification CSI standard. ### Backends de stockage Le pilote CSI prend en charge deux backends, tous deux servis par un seul binaire Go : | Backend | Mode d'accès | Description | | -------- | ------------- | ------------------------------------------------------------- | | **NAS** | ReadWriteMany | Volumes EXT4 sur les services NAS VergeOS, exposés via NFS | | **Bloc** | ReadWriteOnce | Disques de VM branchés à chaud sur des VM VergeOS via le vSAN | ### Fonctionnement 1. Un développeur crée un `PersistentVolumeClaim` (PVC) dans Kubernetes 2. Le pilote CSI communique avec l'API VergeOS pour provisionner le stockage demandé 3. Le stockage est attaché au nœud exécutant le pod et monté au chemin spécifié 4. Lors de la suppression du pod, le pilote CSI gère le démontage et, éventuellement, la suppression selon la politique de récupération ### Exemple de StorageClass ```yaml apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: vergeos-block provisioner: csi.vergeos.com parameters: type: block reclaimPolicy: Delete volumeBindingMode: WaitForFirstConsumer ``` Les administrateurs Kubernetes définissent des `StorageClass` ressources qui correspondent aux backends de stockage VergeOS. Les développeurs référencent ensuite ces classes dans leurs PVC sans avoir à comprendre l'infrastructure sous-jacente. ## Charts Helm Le `helm-charts` Le dépôt regroupe tous les composants Kubernetes VergeOS pour un déploiement simplifié. Trois charts sont disponibles : ### Charts disponibles | Chart | Composants | Objectif | | ---------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------- | | `vergeos-node-driver` | Docker Machine Driver + UI Extension | Provisionnement des nœuds et intégration au tableau de bord Rancher | | `vergeos-cloud-controller-manager` | CCM | Synchronisation du cycle de vie des nœuds et provisionnement de l'équilibreur de charge | | `vergeos-csi` | Pilote CSI | Stockage persistant (NAS + bloc) | ### Installation Ajoutez le dépôt Helm VergeOS et installez les charts : ```bash # Ajouter le dépôt Helm VergeOS helm repo add verge-io https://verge-io.github.io/helm-charts helm repo update # Rechercher les charts disponibles helm search repo verge-io # Installer le Cloud Controller Manager helm install vergeos-ccm verge-io/vergeos-cloud-controller-manager \\ --namespace kube-system # Installer le pilote CSI helm install vergeos-csi verge-io/vergeos-csi \\ --namespace kube-system # Installer le pilote de nœud + l'extension UI (pour Rancher) helm install vergeos-node-driver verge-io/vergeos-node-driver \\ --namespace cattle-system \\ --set "vergeosHosts={vergeos.example.com}" ``` Le `vergeosHosts` la valeur est une liste blanche obligatoire de noms d'hôte VergeOS que le proxy de Rancher est autorisé à atteindre. Remplacez `vergeos.example.com` par le ou les noms d'hôte de votre ou vos environnements VergeOS ; sans cela, le pilote ne peut pas atteindre l'API VergeOS. ## Flux de déploiement de bout en bout En réunissant les quatre composants, voici le workflow complet pour déployer un cluster Kubernetes sur VergeOS avec Rancher : ```mermaid flowchart LR A["1. Préparer
le modèle de VM"] --> B["2. Enregistrer
le pilote de nœud"] B --> C["3. Créer un
identifiant cloud"] C --> D["4. Provisionner
le cluster"] D --> E["5. Déployer
CCM + CSI"] E --> F["6. Exécuter
les charges de travail"] style A fill:#2563eb,color:#fff style B fill:#2563eb,color:#fff style C fill:#2563eb,color:#fff style D fill:#2563eb,color:#fff style E fill:#2563eb,color:#fff style F fill:#16a34a,color:#fff ``` ### Étape 1 : Préparer un modèle de VM Créez une VM VergeOS avec Ubuntu 24.04 (Noble Numbat) — actuellement le seul système d'exploitation de modèle pris en charge — installez cloud-init et l'agent invité QEMU, puis enregistrez-la comme modèle. Ce modèle sera cloné pour chaque nœud Kubernetes. ### Étape 2 : Enregistrer le pilote de nœud Appliquez le manifeste NodeDriver VergeOS à votre cluster de gestion Rancher à l'aide de `kubectl`. Cela informe Rancher du Docker Machine Driver VergeOS et l'active comme option de provisionnement. Redémarrez Rancher après l'enregistrement pour activer le schéma du pilote. ### Étape 3 : Créer un identifiant cloud Dans l'interface Rancher, créez un nouvel **identifiant cloud** en utilisant le fournisseur VergeOS (ajouté par l’extension d’interface utilisateur). Saisissez l’URL de votre hôte VergeOS et votre clé API. ### Étape 4 : provisionner le cluster Créez un nouveau cluster RKE2 ou K3s dans Rancher, en sélectionnant VergeOS comme fournisseur d’infrastructure. Définissez vos pools de nœuds (plan de contrôle, etcd, travailleurs) avec les ressources de calcul souhaitées. Rancher utilise le Docker Machine Driver pour cloner des VM, injecter des clés SSH et amorcer le cluster Kubernetes. ### Étape 5 : déployer le CCM et le CSI Installez le Cloud Controller Manager et le pilote CSI via Helm dans le nouveau cluster. Le CCM commence immédiatement à synchroniser l’état des nœuds avec VergeOS, et le pilote CSI rend le stockage VergeOS disponible pour les PersistentVolumeClaims. ### Étape 6 : exécuter des charges de travail Déployez vos applications avec des manifestes Kubernetes standard. Les services de type `LoadBalancer` sont gérés par le CCM, et les PersistentVolumeClaims sont satisfaites par le pilote CSI — le tout sur l’infrastructure VergeOS. ## Enregistrement du pilote de nœud dans Rancher Le Docker Machine Driver doit être enregistré en tant que ressource Rancher NodeDriver. Appliquez le manifeste suivant avec `kubectl`: ```yaml apiVersion: management.cattle.io/v3 kind: NodeDriver metadata: name: vergeos annotations: privateCredentialFields: "apiKey" publicCredentialFields: "host,insecure" spec: active: true builtin: false displayName: vergeos uiUrl: "" url: "https://github.com/verge-io/docker-machine-driver-vergeos/releases/download/v0.1.0/docker-machine-driver-vergeos-linux-amd64.tar.gz" ``` Après l’application, redémarrez Rancher pour charger le nouveau schéma du pilote. L’option VergeOS apparaîtra alors dans l’assistant de création de cluster. ## Résumé L’intégration Kubernetes VergeOS transforme VergeOS d’une plateforme de VM en un **fournisseur cloud Kubernetes complet**. En mettant en œuvre les interfaces Docker Machine, Cloud Controller Manager et CSI, VergeOS fournit à Kubernetes les mêmes primitives que celles disponibles chez les fournisseurs de cloud public — provisionnement automatisé des nœuds, gestion du cycle de vie, équilibrage de charge et stockage persistant — le tout exécuté sur votre propre infrastructure avec les performances et l’efficacité du vSAN et du réseau virtuel de VergeOS. ### Provisionnement automatisé des nœuds Le Docker Machine Driver clone des VM à partir de modèles avec cloud-init, des clés SSH et l’attachement au réseau — entièrement automatisé via Rancher. ### Fournisseur cloud natif Le CCM et le pilote CSI implémentent les interfaces Kubernetes standard, de sorte que les charges de travail utilisent `LoadBalancer` des services et `des PersistentVolumeClaims` sans modification. ### Déploiement géré par Helm Tous les composants sont fournis sous forme de charts Helm pour une installation cohérente et versionnée à travers les clusters. ### Expérience native de Rancher L’extension d’interface utilisateur intègre la configuration VergeOS directement dans le tableau de bord Rancher — aucun changement de contexte nécessaire. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.verge.io/learn-the-platform/fr/module-8-developpeur-et-devops/07-kubernetes-rancher.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.