> 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/de/modul-8-entwicklung-and-devops/07-kubernetes-rancher.md). # Kubernetes- und Rancher-Integration 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: ```mermaid graph TB subgraph "Rancher Dashboard" UI["UI Extension
(vergeos panels)"] RC["Cloud Credentials &
Machine Config"] end subgraph "Node-Bereitstellung" DMD["Docker Machine Driver
(docker-machine-driver-vergeos)"] end subgraph "Kubernetes-Cluster" CCM["Cloud Controller Manager
(vergeos-cloud-controller-manager)"] CSI["CSI Driver
(csi-vergeos)"] end subgraph "VergeOS-Plattform" API["VergeOS-REST-API"] VM["VMs & Vorlagen"] VSAN["vSAN / NAS-Speicher"] NET["Virtuelle Netzwerke"] end UI --> RC RC --> DMD DMD -->|"Vorlage klonen,
SSH-Schlüssel einfügen"| API API --> VM CCM -->|"Node-Lebenszyklus,
Load Balancer"| API API --> NET CSI -->|"Persistente Volumes"| API API --> VSAN ``` ### 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-Repository**bereitgestellt, 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 **Benutzereinstellungen**und 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 {% hint style="success" %} **Rancher-Node-Größe** Rancher-Bereitstellungen erfordern mindestens **4 GB RAM** pro Node. Für Produktionsstabilität werden **8 GB RAM** pro Node empfohlen. {% endhint %} ### Eigenständige Nutzung Sie können den Treiber außerhalb von Rancher für die spontane Docker-Machine-Bereitstellung verwenden: ```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" %} **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`). {% endhint %} ## Rancher UI Extension Das `ui-extension-vergeos` fügt dem **Rancher-Dashboard**VergeOS-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. {% hint style="info" %} **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. {% endhint %} {% hint style="info" %} **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. {% endhint %} ## 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 ```yaml apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: vergeos-block provisioner: csi.vergeos.com parameters: type: block reclaimPolicy: Delete volumeBindingMode: WaitForFirstConsumer ``` 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: ```bash # VergeOS-Helm-Repository hinzufügen helm repo add verge-io https://verge-io.github.io/helm-charts helm repo update # Verfügbare Charts durchsuchen helm search repo verge-io # Den Cloud Controller Manager installieren helm install vergeos-ccm verge-io/vergeos-cloud-controller-manager \\ --namespace kube-system # Den CSI Driver installieren helm install vergeos-csi verge-io/vergeos-csi \\ --namespace kube-system # Node Driver + UI Extension installieren (für Rancher) helm install vergeos-node-driver verge-io/vergeos-node-driver \\ --namespace cattle-system \\ --set "vergeosHosts={vergeos.example.com}" ``` 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: ```mermaid flowchart LR A["1. VM-Vorlage
vorbereiten"] --> B["2. Node Driver
registrieren"] B --> C["3. Cloud
Credential erstellen"] C --> D["4. Cluster
bereitstellen"] D --> E["5. CCM + CSI
bereitstellen"] E --> F["6. Workloads
ausführen"] 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 ``` ### 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 `kubectl`auf 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`: ```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" ``` 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. --- # 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/de/modul-8-entwicklung-and-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.