Welcome to the new VergeOS docs! The legacy docs remain available until they're retired later this year.
Legacy VergeOS Docs
Ctrlk
Verge.ioGitHub repoSupport
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Intégration Kubernetes et Rancher

Déployez et gérez des clusters Kubernetes sur VergeOS avec le Docker Machine Driver, le Cloud Controller Manager, le pilote CSI, l’extension de l’interface Rancher et les Helm Charts.

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 :

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

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é.

Utilisation autonome

Vous pouvez utiliser le pilote en dehors de Rancher pour un provisionnement ponctuel avec Docker Machine :

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).

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.

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.

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.

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

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 :

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 :

É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:

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.

PrécédentTask Engine et webhooks
SuivantAperçu

Mis à jour

Ce contenu vous a-t-il été utile ?