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.

Kubernetes- & Rancher-Integration

Stellen Sie Kubernetes-Cluster auf VergeOS mit dem Docker Machine Driver, Cloud Controller Manager, CSI Driver, der Rancher-UI-Erweiterung und Helm-Charts bereit und verwalten Sie sie.

Kubernetes auf VergeOS zu betreiben ist kein aufgesetztes Add-on — es ist eine erstklassige Integration aus vier speziell entwickelten Komponenten (Docker Machine Driver, Rancher UI Extension, Cloud Controller Manager und CSI Driver) sowie einem optionalen Cluster Autoscaler für von Rancher bereitgestellte Cluster aufgebaut, die Rancher (und jeder RKE2/K3s-Installation) vollständige Kenntnis über die Rechenleistung, den Speicher und das Netzwerk von VergeOS geben. Anstatt VergeOS als simplen VM-Host zu behandeln, ermöglichen diese Komponenten Kubernetes, Nodes bereitzustellen, persistenten Speicher anzubinden und Load Balancer über native VergeOS-APIs zu erstellen — dieselben APIs, die auch das Dashboard antreiben.

Voraussetzungen

Bevor Sie die Integration installieren, stellen Sie sicher, dass die Umgebung Folgendes bietet:

  • Ein Rancher Server Installation (v2.10+) mit kubectl und helm CLI-Tools

  • Ein Vorlagen-VM mit installiertem Ubuntu 24.04, cloud-init (und empfohlenem QEMU Guest Agent)

  • Ein VergeOS-API-Schlüssel erstellt unter Benutzereinstellungen

  • Ein Ziel-VergeOS-Netzwerk mit aktiviertem DHCP — der Treiber ermittelt die Node-IPs über den QEMU Guest Agent, und geklonte VMs erhalten ohne DHCP keine Adressen

  • Für persistenten blockbasierten Speicher: eine leere VergeOS-VM mit dem Namen k8spool zum Halten ungenutzter Blocklaufwerke (ihre VM-ID wird zur Installationszeit an das CSI-Helm-Chart übergeben; die VM muss niemals starten)

Stack-Übersicht

Die VergeOS-Kubernetes-Integration wird als vier separate Komponenten bereitgestellt — der Docker Machine Driver, die Rancher UI Extension, der Cloud Controller Manager und der CSI Driver — wobei jede für eine Ebene des Stacks verantwortlich ist; für von Rancher bereitgestellte Cluster ist außerdem ein optionaler Cluster Autoscaler verfügbar:

Docker Machine Driver

Stellt VergeOS-VMs als Kubernetes-Nodes bereit — klont Vorlagen, fügt SSH-Schlüssel ein, passt die Festplattengröße an und bindet Netzwerke an.

Rancher UI Extension

Zeigt VergeOS-spezifische Panels für Cloud Credentials und Machine Config direkt im Rancher-Dashboard an.

Cloud Controller Manager

Synchronisiert den Kubernetes-Node-Status mit dem VM-Lebenszyklus von VergeOS und stellt bei Bedarf Load-Balancer-Services bereit.

CSI Driver

Ordnet VergeOS vSAN/NAS-Blockspeicher Kubernetes PersistentVolumes für zustandsbehaftete Workloads zu.

Alle vier Komponenten (DMD, UI Extension, CCM, CSI Driver) werden über das verge-io Helm-Repositorybereitgestellt, was eine konsistente Versionierung und eine vereinfachte Installation sicherstellt. Ein optionaler Cluster Autoscaler ist für von Rancher bereitgestellte Cluster verfügbar.

Docker Machine Driver

Das docker-machine-driver-vergeos ist die Grundlage der Integration. Er bringt Docker Machine (und damit Rancher) bei, wie VMs auf VergeOS erstellt werden — und macht VergeOS damit zu einem erstklassigen Node-Bereitsteller für RKE2- und K3s-Cluster.

Funktionsweise

Wenn Rancher (oder ein eigenständiges Docker Machine) einen neuen Node anfordert, führt der Treiber diese Abfolge aus:

  1. Klonen der Vorlagen-VM — Eine vorgefertigte VergeOS-VM-Vorlage (z. B. Ubuntu 24.04 mit cloud-init) wird geklont, um den neuen Node zu erstellen

  2. Rechenressourcen konfigurieren — CPU-Kerne und RAM werden gemäß der Cluster-Spezifikation festgelegt

  3. SSH-Schlüssel über cloud-init einfügen — Der Treiber erzeugt ein SSH-Schlüsselpaar und fügt den öffentlichen Schlüssel über cloud-init für sicheren, passwortlosen Zugriff ein

  4. Primäre Festplatte vergrößern — Wenn der Cluster mehr Speicher benötigt, als die Vorlage bereitstellt, vergrößert der Treiber die Boot-Festplatte

  5. Mit dem Zielnetzwerk verbinden — Die VM wird mit dem angegebenen virtuellen VergeOS-Netzwerk verbunden

  6. Einschalten und auf IP warten — Der Treiber überwacht die Zuweisung einer IP-Adresse über den QEMU Guest Agent (bevorzugt) oder alternativ über einen DHCP-Lease-Fallback

Wenn ein Schritt fehlschlägt, bereinigt der Treiber automatisch teilweise erstellte VMs — es bleiben keine verwaisten Ressourcen zurück.

Authentifizierung

Der Treiber verwendet API-Schlüssel-Authentifizierung zur Kommunikation mit der VergeOS-REST-API. Erzeugen Sie einen API-Schlüssel in der VergeOS-UI unter Benutzereinstellungenund geben Sie ihn dann über das --vergeos-api-key Flag oder die VERGEOS_API_KEY Umgebungsvariable an.

Konfigurations-Flags

Schalter
Umgebungsvariable
Standard
Beschreibung

--vergeos-host

VERGEOS_HOST

(erforderlich)

VergeOS-Endpunkt-URL

--vergeos-api-key

VERGEOS_API_KEY

(erforderlich)

API-Schlüssel zur Authentifizierung

--vergeos-insecure

VERGEOS_INSECURE

false

TLS-Überprüfung überspringen

--vergeos-template-vm

VERGEOS_TEMPLATE_VM

(erforderlich)

Name der zu klonenden Vorlagen-VM

--vergeos-network

VERGEOS_NETWORK

(erforderlich)

Zielnetzwerk für die Anbindung

--vergeos-cpu-cores

VERGEOS_CPU_CORES

2

CPU-Kerne pro Node

--vergeos-ram

VERGEOS_RAM

2048

RAM in MB pro Node

--vergeos-disk-size

VERGEOS_DISK_SIZE

0 (Vorlagengröße)

Überschreibung der Festplattengröße in MB

--vergeos-ssh-user

VERGEOS_SSH_USER

root

SSH-Benutzername

--vergeos-ssh-port

VERGEOS_SSH_PORT

22

SSH-Port

--vergeos-cloudinit

—

—

Benutzerdefinierte cloud-init-Konfiguration (Datei oder Inline)

Vorlagenanforderungen

Ihre VM-Vorlage muss Folgendes enthalten:

  • Cloud-init installiert und aktiviert — erforderlich für die Einfügung von SSH-Schlüsseln und die Hostnamen-Konfiguration

  • QEMU Guest Agent (empfohlen) — ermöglicht eine zuverlässige Erkennung der IP-Adresse; fällt andernfalls auf den DHCP-Lease der NIC zurück

  • Docker (nur für eigenständige Nutzung) — Rancher-Bereitstellungen installieren die Container-Runtime automatisch

Unterstützung für Ubuntu 24.04

Der Treiber enthält eine automatische Behandlung der Besonderheiten von Ubuntu 24.04:

  • Netplan-DHCP-Konfiguration für dynamische en* Interface-Namensgebung

  • Neuerzeugung der Machine-ID um eindeutige DHCP-Kennungen pro Klon sicherzustellen

  • Bereinigung veralteter DHCP-Leases um IP-Konflikte durch Vererbung von Vorlagen zu verhindern

Rancher-Node-Größe

Rancher-Bereitstellungen erfordern mindestens 4 GB RAM pro Node. Für Produktionsstabilität werden 8 GB RAM pro Node empfohlen.

Eigenständige Nutzung

Sie können den Treiber außerhalb von Rancher für die spontane Docker-Machine-Bereitstellung verwenden:

Standardwert für den SSH-Benutzer

Der Treiber verwendet standardmäßig root für SSH, aber Ubuntu-Cloud-Images erlauben kein Root-SSH-Login. Wenn Sie die CLI direkt gegen eine Ubuntu-Vorlage verwenden, setzen Sie --vergeos-ssh-user ubuntu (die Rancher-UI-Erweiterung verwendet bereits standardmäßig ubuntu).

Rancher UI Extension

Das ui-extension-vergeos fügt dem Rancher-DashboardVergeOS-spezifische Panels hinzu und bietet so eine native Benutzererfahrung für die Verwaltung von auf VergeOS basierenden Kubernetes-Clustern, ohne die Rancher-UI zu verlassen.

Cloud Credential Panel

Beim Erstellen neuer Cloud Credentials in Rancher fügt die Erweiterung eine VergeOS Anbieteroption hinzu. Geben Sie die URL Ihres VergeOS-Hosts, den API-Schlüssel und die TLS-Einstellungen ein — Rancher speichert diese sicher und verwendet sie für alle nachfolgenden Node-Bereitstellungsoperationen.

Machine Config Panel

Beim Definieren von Node-Pools für einen neuen Cluster zeigt die Erweiterung VergeOS-spezifische Konfigurationsfelder an:

  • Vorlagen-VM — Wählen Sie aus den verfügbaren VergeOS-VM-Vorlagen

  • Netzwerk — Wählen Sie das Ziel-virtuelle Netzwerk

  • CPU / RAM / Festplatte — Legen Sie die Rechenressourcen pro Node fest

  • Cloud-init — Geben Sie benutzerdefinierte Initialisierungsskripte an

Die Erweiterung wird als Teil des vergeos-node-driver Helm-Charts bereitgestellt, das sowohl den Docker Machine Driver als auch die UI Extension zusammen bündelt.

Cloud Controller Manager

Das vergeos-cloud-controller-manager (CCM) verbindet Kubernetes-Cluster-Operationen mit der VergeOS-Control-Plane und implementiert die standardmäßige Kubernetes-Cloud-Provider-Schnittstelle.

Synchronisierung des Node-Lebenszyklus

Der CCM überwacht fortlaufend die Kubernetes-Node-Liste und synchronisiert sie mit dem VM-Status von VergeOS:

  • Node-Registrierung — Wenn ein neuer Node dem Cluster beitritt, versieht ihn der CCM mit VergeOS-spezifischen Metadaten (VM-ID, Netzwerk, Zone)

  • Node-Entfernung — Wenn eine VergeOS-VM gelöscht oder ausgeschaltet wird, markiert der CCM den entsprechenden Kubernetes-Node als nicht verfügbar und löst ein erneutes Planen der Pods aus

  • Überwachung des Gesundheitszustands — Regelmäßige Prüfungen stellen sicher, dass der Status der Kubernetes-Nodes den tatsächlichen VM-Zustand widerspiegelt

Load-Balancer-Bereitstellung

Wenn ein Kubernetes-Service vom Typ LoadBalancer erstellt wird, stellt der CCM über die VergeOS-Netzwerkschicht einen Load Balancer bereit:

  • Weist eine virtuelle IP aus dem konfigurierten Adresspool zu

  • Konfiguriert die Verteilung des Datenverkehrs über die Backend-Node-Ports

  • Aktualisiert den status.loadBalancer.ingress des Services mit der zugewiesenen IP

VergeOS übernimmt die Bereitstellung von Load Balancern nativ über den CCM.

Kommen Sie von VMware?

Auf VergeOS kombiniert der CCM die Verwaltung des Node-Lebenszyklus und LoadBalancer die Service-Bereitstellung in einer einzigen per Helm installierten Komponente — keine separaten Add-ons für Cloud Provider, CSI/CPI und Load Balancer, die zusammengesetzt werden müssen.

Kommen Sie von Nutanix?

VergeOS arbeitet mit jeder RKE2/K3s-Toolchain über Rancher zusammen, anstatt eine proprietäre Kubernetes-Distribution bereitzustellen — Sie wählen die Upstream-Kubernetes-Variante, und der CCM liefert die native Cloud-Provider-Integration darüber hinaus.

CSI Driver

Das csi-vergeos (Container Storage Interface) Driver stellt VergeOS-Speicher Kubernetes-Workloads über die standardmäßige CSI-Spezifikation bereit.

Speicher-Backends

Der CSI-Driver unterstützt zwei Backends, die beide von einem einzigen Go-Binary bereitgestellt werden:

Backend
Zugriffsmodus
Beschreibung

NAS

ReadWriteMany

EXT4-Volumes auf VergeOS-NAS-Diensten, bereitgestellt über NFS

Block

ReadWriteOnce

VM-Laufwerke, die per Hotplug an VergeOS-VMs über das vSAN angehängt werden

Funktionsweise

  1. Ein Entwickler erstellt eine PersistentVolumeClaim (PVC) in Kubernetes

  2. Der CSI-Driver kommuniziert mit der VergeOS-API, um den angeforderten Speicher bereitzustellen

  3. Der Speicher wird an den Node angehängt, auf dem der Pod läuft, und unter dem angegebenen Pfad eingehängt

  4. Beim Löschen des Pods übernimmt der CSI-Driver das Aushängen und optional das Löschen gemäß der Reclaim-Policy

Beispiel für eine StorageClass

Kubernetes-Administratoren definieren StorageClass Ressourcen, die auf VergeOS-Speicher-Backends abgebildet werden. Entwickler verweisen dann in ihren PVCs auf diese Klassen, ohne die zugrunde liegende Infrastruktur verstehen zu müssen.

Helm-Charts

Das helm-charts Repository packt alle VergeOS-Kubernetes-Komponenten für eine optimierte Bereitstellung zusammen. Es sind drei Charts verfügbar:

Verfügbare Charts

Chart
Komponenten
Zweck

vergeos-node-driver

Docker Machine Driver + UI Extension

Node-Bereitstellung und Integration ins Rancher-Dashboard

vergeos-cloud-controller-manager

CCM

Synchronisierung des Node-Lebenszyklus und Bereitstellung von Load Balancern

vergeos-csi

CSI Driver

Persistenter Speicher (NAS + Block)

Installation

Fügen Sie das VergeOS-Helm-Repository hinzu und installieren Sie die Charts:

Das vergeosHosts Wert ist eine erforderliche Whitelist von VergeOS-Hostnamen, die der Proxy von Rancher erreichen darf. Ersetzen Sie vergeos.example.com durch die Hostnamen Ihrer VergeOS-Umgebung(en); ohne ihn kann der Treiber die VergeOS-API nicht erreichen.

End-to-End-Bereitstellungs-Workflow

Wenn alle vier Komponenten zusammengebracht werden, sieht der vollständige Ablauf zur Bereitstellung eines Kubernetes-Clusters auf VergeOS mit Rancher wie folgt aus:

Schritt 1: Eine VM-Vorlage vorbereiten

Erstellen Sie eine VergeOS-VM mit Ubuntu 24.04 (Noble Numbat) — derzeit das einzige unterstützte Vorlagen-Betriebssystem — installieren Sie cloud-init und den QEMU Guest Agent und speichern Sie sie dann als Vorlage. Diese Vorlage wird für jeden Kubernetes-Node geklont.

Schritt 2: Den Node Driver registrieren

Wenden Sie das VergeOS-NodeDriver-Manifest mit kubectlauf Ihren Rancher-Management-Cluster an. Dadurch wird Rancher über den VergeOS Docker Machine Driver informiert und er als Bereitstellungsoption aktiviert. Starten Sie Rancher nach der Registrierung neu, um das Treiberschema zu aktivieren.

Schritt 3: Ein Cloud Credential erstellen

Erstellen Sie in der Rancher-UI ein neues Cloud Credential unter Verwendung des VergeOS-Anbieters (hinzugefügt durch die UI Extension). Geben Sie die URL Ihres VergeOS-Hosts und den API-Schlüssel ein.

Schritt 4: Den Cluster bereitstellen

Erstellen Sie in Rancher einen neuen RKE2- oder K3s-Cluster und wählen Sie VergeOS als Infrastruktur-Anbieter. Definieren Sie Ihre Node-Pools (Control Plane, etcd, Worker) mit den gewünschten Rechenressourcen. Rancher verwendet den Docker Machine Driver, um VMs zu klonen, SSH-Schlüssel einzufügen und den Kubernetes-Cluster zu bootstrappen.

Schritt 5: CCM und CSI bereitstellen

Installieren Sie den Cloud Controller Manager und den CSI Driver per Helm in den neuen Cluster. Der CCM beginnt sofort mit der Synchronisierung des Node-Status mit VergeOS, und der CSI-Driver stellt VergeOS-Speicher für PersistentVolumeClaims bereit.

Schritt 6: Workloads ausführen

Stellen Sie Ihre Anwendungen mit standardmäßigen Kubernetes-Manifests bereit. Services vom Typ LoadBalancer werden vom CCM behandelt, und PersistentVolumeClaims werden vom CSI-Driver erfüllt — alles gestützt durch die VergeOS-Infrastruktur.

Den Node Driver in Rancher registrieren

Der Docker Machine Driver muss als Rancher-NodeDriver-Ressource registriert werden. Wenden Sie das folgende Manifest mit kubectl:

Starten Sie Rancher nach dem Anwenden neu, um das neue Treiberschema zu laden. Die VergeOS-Option wird dann im Assistenten zur Cluster-Erstellung angezeigt.

Zusammenfassung

Die Kubernetes-Integration von VergeOS verwandelt VergeOS von einer VM-Plattform in einen vollwertigen Kubernetes-Cloud-Anbieter. Durch die Implementierung der Docker-Machine-, Cloud-Controller-Manager- und CSI-Schnittstellen stellt VergeOS Kubernetes dieselben Grundbausteine bereit, die auch von öffentlichen Cloud-Anbietern verfügbar sind — automatisierte Knotenbereitstellung, Lifecycle-Management, Lastverteilung und persistenten Speicher — alles läuft auf Ihrer eigenen Infrastruktur mit der Leistung und Effizienz von VergeOS vSAN und virtueller Vernetzung.

Automatisierte Knotenbereitstellung

Der Docker-Machine-Driver klont VMs aus Vorlagen mit cloud-init, SSH-Schlüsseln und Netzwerkanbindung — vollständig automatisiert über Rancher.

Nativer Cloud-Anbieter

Der CCM- und CSI-Treiber implementiert standardmäßige Kubernetes-Schnittstellen, sodass Workloads LoadBalancer Dienste und PersistentVolumeClaims ohne Anpassungen verwenden.

Mit Helm verwaltete Bereitstellung

Alle Komponenten werden als Helm-Charts paketiert, um eine konsistente, versionskontrollierte Installation über Cluster hinweg zu gewährleisten.

Rancher-native Erfahrung

Die UI-Erweiterung bringt die Konfiguration von VergeOS direkt ins Rancher-Dashboard — kein Kontextwechsel erforderlich.

VorherigeTask Engine & Webhooks
NächsteÜberblick

Zuletzt aktualisiert

War das hilfreich?