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.

Rancher-Integration

VergeOS integriert sich über einen Docker-Machine-Node-Treiber und eine UI-Erweiterung mit Rancher und ermöglicht die Bereitstellung und Verwaltung von RKE2-/K3s-Clustern auf VergeOS über die Rancher-Oberfläche.

Übersicht

VergeOS integriert sich mit Rancher über einen Docker-Machine-Node-Driver und eine UI-Erweiterung. Zusammen ermöglichen diese Komponenten, dass wir RKE2/K3s-Cluster auf VergeOS-Infrastruktur direkt über die Rancher-Oberfläche bereitstellen und verwalten.

Komponente
Zweck

Docker-Machine-Treiber

Stellt VergeOS-VMs als Kubernetes-Knoten bereit

UI-Erweiterung

Fügt Rancher VergeOS-Cloud-Anmeldedaten und Maschinenkonfiguration hinzu

Sobald die Cluster laufen, die Kubernetes-Integration Komponenten (CSI-Treiber und Cloud Controller Manager) bieten persistenten Speicher und Knoten-Lebenszyklusverwaltung — diese funktionieren mit jedem Kubernetes-Cluster auf VergeOS, nicht nur mit von Rancher bereitgestellten.

Voraussetzungen

  • Eine VergeOS-Umgebung mit API-Zugriff

  • Eine Rancher-Server-Installation (v2.10+)

  • Eine Vorlagen-VM mit Ubuntu 24.04 und installiertem cloud-init

  • Ein VergeOS-API-Schlüssel (in den Benutzereinstellungen generiert)

  • kubectl und helm CLI-Tools

Docker-Machine-Treiber

Der Docker-Machine-Treiber ist die Grundlage der Rancher-Integration. Er verwaltet den vollständigen Lebenszyklus der VM über die VergeOS-API — klont Vorlagen-VMs, injiziert SSH-Schlüssel über cloud-init und erstellt Maschinen, wenn Cluster bereitgestellt werden. Wenn ein Cluster entfernt wird, löscht der Treiber automatisch die von ihm erstellten VMs.

So funktioniert es

  1. Klonen die Vorlagen-VM mit dem angeforderten Maschinennamen

  2. Konfiguriert CPU-Kerne, RAM und cloud-init (SSH-Schlüssel + Hostname + optionale Benutzerdaten)

  3. Größenänderung der primären Festplatte, wenn eine benutzerdefinierte Größe angegeben ist

  4. Bindet an die VM an das angegebene Netzwerk

  5. Schaltet ein und wartet auf eine IP-Adresse (QEMU Guest Agent bevorzugt, Fallback über NIC-DHCP)

Wenn ein Schritt fehlschlägt, bereinigt der Treiber die teilweise erstellte VM automatisch.

Vorbereitung der Vorlagen-VM

Vor der Bereitstellung von Clustern benötigen wir eine Vorlagen-VM in VergeOS mit Folgendem:

Erforderlich:

  • Ubuntu 24.04 (Noble Numbat) — derzeit das einzige unterstützte Vorlagen-Betriebssystem

  • cloud-init installiert und aktiviert — der Treiber injiziert SSH-Schlüssel und setzt den Hostnamen über eine mehrteilige MIME-cloud-init-Nutzlast

Empfohlen:

  • QEMU Guest Agent — ermöglicht eine genaue IP-Erkennung; ohne ihn greift der Treiber auf die IPs der NIC-DHCP-Leases zurück

Spezifika von Ubuntu 24.04

Der Treiber behandelt mehrere Besonderheiten von Ubuntu 24.04 automatisch über cloud-init:

  • Netplan-DHCP-Konfiguration — schreibt eine Netplan-Konfiguration, die zu en* Schnittstellen mit dhcp4: trueund behandelt Änderungen der PCI-Slot-Namen über Klone hinweg

  • Neu-Erzeugung der Machine-ID — erzeugt neu /etc/machine-id bei jedem Klon, damit jede VM eine eindeutige DHCP-Client-ID erhält

  • Bereinigung zwischengespeicherter DHCP-Leases — entfernt veraltete DHCP-Leases, die von der Vorlage übernommen wurden

Speicheranforderungen

Für den Einsatz mit Rancher mindestens 4 GB RAM pro Knoten zuweisen (8 GB empfohlen). Ein Single-Node-RKE2-Cluster mit Calico CNI wird mit 2 GB wegen Speichermangels (OOM) ausfallen.

Docker ist nicht auf der Vorlage erforderlich — Rancher installiert seine eigene Container-Laufzeitumgebung (containerd) über den System-Agenten. Die Vorlage benötigt nur cloud-init und den Guest Agent.

Netzwerkanforderungen

Das in --vergeos-network angegebene VergeOS-Netzwerk muss die folgenden Anforderungen erfüllen, damit von Rancher bereitgestellte Cluster funktionieren.

DHCP erforderlich

Im Netzwerk muss DHCP aktiviert sein. Der Treiber ermittelt die Knoten-IP-Adressen über den QEMU Guest Agent, und geklonte VMs erhalten ohne DHCP keine Adressen.

Rancher-Konnektivität

Die Knoten müssen den Rancher-Server erreichen können, und Rancher muss die Knoten erreichen können. Stellen Sie sicher, dass die folgenden Ports zwischen ihnen offen sind:

Für die vollständige Port-Matrix einschließlich Knoten-zu-Knoten-Anforderungen (die je nach CNI variieren) siehe die Rancher-RKE2-Portanforderungen .

Richtung
Port
Protokoll
Zweck

Knoten → Rancher

443

TCP

Registrierung und Kommunikation des System-Agenten

Rancher → Knoten

9345

TCP

RKE2-Knotenregistrierung

Rancher → Knoten

6443

TCP

Kubernetes-API-Server

Knoten → Internet

443

TCP

Container-Images aus Registries abrufen

In Rancher installieren

Der Node-Driver und die UI-Erweiterung sind in einem einzigen Helm-Chart zusammengepackt. Dadurch werden das Docker-Machine-Driver-Binary installiert, die NodeDriver-Ressource registriert und die UI-Erweiterung bereitgestellt.

Per Helm-CLI:

Die vergeosHosts Der Wert ist eine Whitelist von VergeOS-Hostnamen, die der Proxy von Rancher erreichen darf. Ersetzen Sie vergeos.example.com durch den/die Hostnamen der VergeOS-Umgebung(en).

Über die Rancher-Oberfläche:

  1. Navigieren Sie zu Erweiterungen und klicken Sie auf das ⋮ Menü > Repositories verwalten

  2. Ein neues Repository mit der URL hinzufügen https://verge-io.github.io/helm-charts

  3. Zurück zu Erweiterungen und installieren Sie die VergeOS Node Driver Erweiterung

Nach der Installation, VergeOS wird beim Erstellen von Clustern als Node-Driver-Option angezeigt.

Selbstsignierte Zertifikate

Wenn die VergeOS-Umgebung ein selbstsigniertes Zertifikat verwendet, setzen Sie insecure auf true beim Erstellen der Cloud-Anmeldedaten in Rancher. Dadurch wird dem Treiber mitgeteilt, die TLS-Verifizierung bei der Kommunikation mit der VergeOS-API zu überspringen.

Standalone-Verwendung

Der Treiber funktioniert auch außerhalb von Rancher direkt mit Docker Machine:

Docker für die Standalone-Verwendung erforderlich

Wenn er als eigenständiger Docker Machine Driver (nicht über Rancher) verwendet wird, muss Docker auch auf der Vorlagen-VM installiert sein, oder wir können --vergeos-cloudinit verwenden, um es beim ersten Start zu installieren.

Die vollständige Liste der Treiber-Flags und Umgebungsvariablen finden Sie im Treiber-Repository unten in Dokumentation und Ressourcen unten.

Standard-SSH-Benutzer

Der Treiber verwendet standardmäßig root als SSH-Benutzer, aber die Rancher-UI-Erweiterung verwendet standardmäßig ubuntu. Wenn Sie die CLI direkt verwenden, setzen Sie --vergeos-ssh-user ubuntu für Ubuntu-Vorlagen.

UI-Erweiterung

Die UI-Erweiterung fügt der Rancher-Oberfläche VergeOS-spezifische Komponenten hinzu und bietet eine native Erfahrung beim Erstellen von Cloud-Anmeldedaten und Konfigurieren von Maschinen.

Was sie hinzufügt

Formular für Cloud-Anmeldedaten — fragt nach:

  • VergeOS-Host-URL

  • API-Schlüssel (als Rancher-Secret gespeichert)

  • Umschalter für TLS-Verifizierung

Formular für Maschinenkonfiguration — bietet:

  • Name der Vorlagen-VM (Name der zu klonenden VergeOS-VM)

  • Netzwerkname (VergeOS-VNet, an das angehängt wird)

  • Eingaben für CPU-Kerne, RAM und Festplattengröße

  • cloud-init-Benutzerdatenfeld

  • Konfiguration von SSH-Benutzer und Port

Kompatibilität

Die UI-Erweiterung erfordert Rancher v2.10+ und das Rancher-Extensions-Framework v3.x.

Installation

Die UI-Erweiterung wird automatisch als Teil des kombinierten Helm-Chartsinstalliert. Es gibt keinen separaten Installationsschritt.

Zusammenfassung

Die Rancher-Integration besteht aus zwei Komponenten, die in einem einzigen Helm-Chart verpackt sind:

  • Docker-Machine-Treiber — klont VergeOS-Vorlagen-VMs und verwaltet deren Lebenszyklus für die Cluster-Bereitstellung

  • UI-Erweiterung — fügt der Rancher-Oberfläche Formulare für VergeOS-Cloud-Anmeldedaten und Maschinenkonfiguration hinzu

Zusammen ermöglichen sie uns, RKE2/K3s-Cluster auf VergeOS-Infrastruktur direkt über die Rancher-UI bereitzustellen. Sobald die Cluster laufen, die Kubernetes-Integration Komponenten kümmern sich um persistenten Speicher und den Lebenszyklus der Knoten.

Nächste Schritte

  • Bereiten Sie eine Vorlagen-VM (Ubuntu 24.04 + cloud-init + QEMU Guest Agent) in VergeOS vor

  • Installieren Sie den VergeOS Node Driver Helm-Chart im Rancher-Cluster

  • Stellen Sie einen Downstream-Cluster bereit mit VergeOS als Node-Driver

  • Installieren Sie den CSI-Treiber und Cloud Controller Manager auf dem Downstream-Cluster für persistenten Speicher und Load Balancer

Dokumentation und Ressourcen

Für detaillierte Konfiguration, Treiber-Flags, Chart-Werte und Release Notes siehe die GitHub-Repositories:

Repository
Beschreibung

docker-machine-driver-vergeos

Docker Machine / Rancher Node-Driver

ui-extension-vergeos

Rancher-UI-Erweiterung

helm-charts

Helm-Chart-Repository

Support

Wenn Sie auf Probleme stoßen oder Funktionswünsche haben, eröffnen Sie bitte ein Issue im entsprechenden GitHub-Repository:

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

VorherigeVergeOS Python SDK (pyvergeos)
NächsteStorware-Integration mit VergeOS

Zuletzt aktualisiert

War das hilfreich?