> 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/automate-protect-and-extend/de/integrationen-und-apis/rancher-integration.md).

# Rancher-Integration

## Übersicht

VergeOS integriert sich mit [Rancher](https://www.rancher.com/) ü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](#docker-machine-driver) | Stellt VergeOS-VMs als Kubernetes-Knoten bereit                          |
| [UI-Erweiterung](#ui-extension)                  | Fügt Rancher VergeOS-Cloud-Anmeldedaten und Maschinenkonfiguration hinzu |

Sobald die Cluster laufen, die [Kubernetes-Integration](/automate-protect-and-extend/de/integrationen-und-apis/kubernetes-integration.md) 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.

```mermaid
graph TD
    subgraph rancher["Rancher-Server"]
        ui["UI-Erweiterung für VergeOS"]
        creds["Cloud-Anmeldedaten"] --> driver["Docker-Machine-Treiber"]
    end

    driver --> vms["VergeOS-VMs"]

    subgraph cluster["RKE2/K3s-Cluster (VergeOS-VMs)"]
        ccm["Cloud Controller Manager"]
        csi["CSI-Treiber"]
        ccm_features["Knotenmetadaten · Knoten-Lebenszyklus · Load Balancer"]
        csi_features["NAS ReadWriteMany · Block ReadWriteOnce"]
        ccm --- ccm_features
        csi --- csi_features
    end

    vms --> cluster
```

### 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

{% hint style="success" %}
**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: true`und 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
  {% endhint %}

{% hint style="warning" %}
**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.
{% endhint %}

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.

{% hint style="warning" %}
**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.
{% endhint %}

{% hint style="info" %}
**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](https://docs.rke2.io/install/requirements#networking) .
{% endhint %}

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

```bash
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}"
```

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.

{% hint style="info" %}
**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.
{% endhint %}

### Standalone-Verwendung

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

```bash
docker-machine create \\
  --driver vergeos \\
  --vergeos-host vergeos.example.com \\
  --vergeos-api-key your-api-key \\
  --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
```

{% hint style="info" %}
**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.
{% endhint %}

Die vollständige Liste der Treiber-Flags und Umgebungsvariablen finden Sie im Treiber-Repository unten in [Dokumentation und Ressourcen](#documentation-and-resources) unten.

{% hint style="info" %}
**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.
{% endhint %}

***

## 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

{% hint style="info" %}
**Kompatibilität**

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

{% hint style="info" %}
**Installation**

Die UI-Erweiterung wird automatisch als Teil des [kombinierten Helm-Charts](#installing-in-rancher)installiert. Es gibt keinen separaten Installationsschritt.
{% endhint %}

***

## 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](/automate-protect-and-extend/de/integrationen-und-apis/kubernetes-integration.md) 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](#installing-in-rancher) 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](/automate-protect-and-extend/de/integrationen-und-apis/kubernetes-integration.md) 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](https://github.com/verge-io/docker-machine-driver-vergeos) | Docker Machine / Rancher Node-Driver |
| [ui-extension-vergeos](https://github.com/verge-io/ui-extension-vergeos)                   | Rancher-UI-Erweiterung               |
| [helm-charts](https://github.com/verge-io/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>


---

# 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/automate-protect-and-extend/de/integrationen-und-apis/rancher-integration.md?ask=<question>&goal=<endgoal>
```

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