Intégration Rancher

VergeOS s’intègre à Rancher via un pilote de nœud Docker Machine et une extension d’interface utilisateur, permettant le provisionnement et la gestion de clusters RKE2/K3s sur VergeOS depuis l’interface Rancher.

Vue d’ensemble

VergeOS s'intègre avec Rancher via un pilote de nœud Docker Machine et une extension d'interface utilisateur. Ensemble, ces composants nous permettent de provisionner et de gérer des clusters RKE2/K3s sur l'infrastructure VergeOS directement depuis l'interface Rancher.

Composant	Objectif
Pilote Docker Machine	Provisionne les VM VergeOS en tant que nœuds Kubernetes
Extension d'interface utilisateur	Ajoute les identifiants cloud VergeOS et la configuration de machine à Rancher

Une fois les clusters en cours d'exécution, les Intégration Kubernetes composants (pilote CSI et Cloud Controller Manager) fournissent un stockage persistant et la gestion du cycle de vie des nœuds — ils fonctionnent avec n'importe quel cluster Kubernetes sur VergeOS, pas seulement ceux provisionnés par Rancher.

Prérequis

• Un environnement VergeOS avec accès à l'API

• Une installation de Rancher Server (v2.10+)

• Une VM modèle exécutant Ubuntu 24.04 avec cloud-init installé

• Une clé API VergeOS (générée dans les paramètres utilisateur)

• kubectl et helm Outils CLI

---

Pilote Docker Machine

Le pilote Docker Machine est la base de l'intégration Rancher. Il gère l'ensemble du cycle de vie des VM via l'API VergeOS — clonage des VM modèles, injection des clés SSH via cloud-init et création des machines lors du provisionnement des clusters. Lorsqu'un cluster est supprimé, le pilote supprime automatiquement les VM qu'il a créées.

Comment ça fonctionne

1. Clone la VM modèle avec le nom de machine demandé

2. Configure les cœurs CPU, la RAM et cloud-init (clés SSH + nom d'hôte + user-data facultatif)

3. Redimensionne le disque principal si une taille personnalisée est spécifiée

4. Attache la VM au réseau spécifié

5. Met sous tension et attend une adresse IP (agent invité QEMU préféré, repli sur le bail DHCP de la carte réseau)

Si une étape échoue, le pilote nettoie automatiquement la VM partiellement créée.

Préparation de la VM modèle

Avant de provisionner des clusters, nous avons besoin dans VergeOS d'une VM modèle avec les éléments suivants :

Requis :

• Ubuntu 24.04 (Noble Numbat) — le seul système d'exploitation modèle pris en charge pour le moment

• cloud-init installé et activé — le pilote injecte les clés SSH et définit le nom d'hôte via une charge utile cloud-init MIME multipartite

Recommandé :

• agent invité QEMU — permet une découverte précise de l'adresse IP ; sans lui, le pilote se rabat sur les adresses IP des baux DHCP de la carte réseau

Spécificités d'Ubuntu 24.04

Le pilote gère automatiquement plusieurs spécificités d'Ubuntu 24.04 via cloud-init :

• Configuration DHCP de Netplan — écrit une configuration Netplan correspondant à en* interfaces avec dhcp4: true, en gérant les changements de nom d'emplacement PCI entre les clones

• Régénération de l'ID machine — régénère /etc/machine-id à chaque clone afin que chaque VM obtienne un identifiant client DHCP unique

• Nettoyage du cache des baux DHCP — supprime les anciens baux DHCP hérités du modèle

Exigences mémoire

Pour une utilisation avec Rancher, allouez au moins 4 Go de RAM par nœud (8 Go recommandés). Un cluster RKE2 monoposte avec Calico CNI manquera de mémoire avec 2 Go.

Docker est pas requis sur la VM modèle — Rancher installe son propre runtime de conteneurs (containerd) via l'agent système. La VM modèle n'a besoin que de cloud-init et de l'agent invité.

Exigences réseau

Le réseau VergeOS spécifié dans --vergeos-network doit respecter les exigences suivantes pour que les clusters provisionnés par Rancher fonctionnent.

DHCP requis

Le réseau doit avoir DHCP activé. Le pilote découvre les adresses IP des nœuds via l'agent invité QEMU, et les VM clonées ne recevront pas d'adresse sans DHCP.

Connectivité Rancher

Les nœuds doivent pouvoir joindre le serveur Rancher, et Rancher doit pouvoir joindre les nœuds. Assurez-vous que les ports suivants sont ouverts entre eux :

Pour la matrice complète des ports, y compris les exigences de nœud à nœud (qui varient selon le CNI), consultez les exigences de ports Rancher RKE2 .

Direction	Port	Protocole	Objectif
Nœud → Rancher	443	TCP	Enregistrement et communication de l'agent système
Rancher → Nœud	9345	TCP	Enregistrement du nœud RKE2
Rancher → Nœud	6443	TCP	Serveur API Kubernetes
Nœud → Internet	443	TCP	Télécharger les images de conteneurs depuis les registres

Installation dans Rancher

Le pilote de nœud et l'extension UI sont empaquetés ensemble dans un seul chart Helm. Cela installe le binaire du pilote Docker Machine, enregistre la ressource NodeDriver et déploie l'extension UI.

Via l'interface CLI Helm :

helm repo add verge-io https://verge-io.github.io/helm-charts
helm repo update

helm install vergeos-node-driver verge-io/vergeos-node-driver \
  -n cattle-system \
  --set "vergeosHosts={vergeos.example.com}"

Le vergeosHosts la valeur est une liste blanche des noms d'hôte VergeOS que le proxy de Rancher est autorisé à joindre. Remplacez vergeos.example.com par le ou les noms d'hôte de l'environnement VergeOS.

Via l'interface Rancher :

1. Accédez à Extensions et cliquez sur le ⋮ menu > Gérer les dépôts

2. Ajoutez un nouveau dépôt avec l'URL https://verge-io.github.io/helm-charts

3. Revenez à Extensions et installez l' VergeOS Node Driver extension

Une fois installé, VergeOS apparaîtra comme une option de pilote de nœud lors de la création de clusters.

Certificats auto-signés

Si l'environnement VergeOS utilise un certificat auto-signé, définissez insecure à true lors de la création de l'identifiant cloud dans Rancher. Cela indique au pilote d'ignorer la vérification TLS lors de la communication avec l'API VergeOS.

Utilisation autonome

Le pilote fonctionne également en dehors de Rancher, directement avec Docker Machine :

docker-machine create \
  --driver vergeos \
  --vergeos-host vergeos.example.com \
  --vergeos-api-key votre-clé-api \
  --vergeos-insecure \
  --vergeos-template-vm ubuntu-2404 \
  --vergeos-network your-network-name \
  --vergeos-ssh-user ubuntu \
  --vergeos-cpu-cores 2 \
  --vergeos-ram 4096 \
  --vergeos-disk-size 30 \
  my-docker-host

Docker requis pour une utilisation autonome

Lorsqu'il est utilisé comme pilote Docker Machine autonome (et non via Rancher), la VM modèle doit également avoir Docker installé, ou nous pouvons utiliser --vergeos-cloudinit pour l'installer au premier démarrage.

Pour la liste complète des indicateurs du pilote et des variables d'environnement, consultez le dépôt du pilote dans Documentation et ressources ci-dessous.

Utilisateur SSH par défaut

Le pilote utilise par défaut root pour l'utilisateur SSH, mais l'extension UI Rancher utilise par défaut ubuntu. Lorsque vous utilisez directement la CLI, définissez --vergeos-ssh-user ubuntu pour les modèles Ubuntu.

---

Extension d'interface utilisateur

L'extension UI ajoute à l'interface Rancher des composants spécifiques à VergeOS, offrant une expérience native lors de la création d'identifiants cloud et de la configuration des machines.

Ce qu'elle ajoute

Formulaire d'identifiants cloud — demande :

• URL de l'hôte VergeOS

• Clé API (stockée comme secret Rancher)

• Bascule de vérification TLS

Formulaire de configuration de machine — fournit :

• Nom de la VM modèle (nom de la VM VergeOS à cloner)

• Nom du réseau (VNet VergeOS à joindre)

• Champs pour les cœurs CPU, la RAM et la taille du disque

• Champ user-data de cloud-init

• Configuration de l'utilisateur SSH et du port

Compatibilité

L'extension UI nécessite Rancher v2.10+ et le framework Rancher Extensions v3.x.

Installation

L'extension UI est installée automatiquement dans le cadre du chart Helm combiné. Il n'y a aucune étape d'installation séparée.

---

Résumé

L'intégration Rancher se compose de deux composants empaquetés dans un seul chart Helm :

• Pilote Docker Machine — clone les VM modèles VergeOS et gère leur cycle de vie pour le provisionnement des clusters

• Extension d'interface utilisateur — ajoute à l'interface Rancher des formulaires d'identifiants cloud et de configuration de machine VergeOS

Ensemble, ils nous permettent de provisionner des clusters RKE2/K3s sur l'infrastructure VergeOS directement depuis l'interface Rancher. Une fois les clusters en cours d'exécution, les Intégration Kubernetes composants gèrent le stockage persistant et le cycle de vie des nœuds.

Étapes suivantes

• Préparez une VM modèle (Ubuntu 24.04 + cloud-init + agent invité QEMU) dans VergeOS

• Installez le VergeOS Node Driver chart Helm dans le cluster Rancher

• Provisionnez un cluster en aval en utilisant VergeOS comme pilote de nœud

• Installez le Pilote CSI et Cloud Controller Manager sur le cluster en aval pour le stockage persistant et les équilibreurs de charge

Documentation et ressources

Pour la configuration détaillée, les options du pilote, les valeurs du chart et les notes de version, consultez les dépôts GitHub :

Dépôt	Description
docker-machine-driver-vergeos	Pilote de nœud Docker Machine / Rancher
ui-extension-vergeos	Extension UI Rancher
helm-charts	Dépôt du chart Helm

Support

Si vous rencontrez des problèmes ou avez des demandes de fonctionnalités, veuillez ouvrir une issue sur le dépôt GitHub concerné :

https://github.com/verge-io/docker-machine-driver-vergeos/issues