kubeone

KubeOne installieren: Ihr erster Cluster in 15 Minuten

Abubakar Siddiq Ango
Abubakar Siddiq Ango Senior Developer Advocate
17. März 2026 10 Min. Lesezeit Anfänger
Erste Schritte Automatisierung

Voraussetzungen

  • Ein Server oder eine VM mit Ubuntu 22.04+ (mindestens 2 vCPU, 4 GB RAM)
  • Zugriff auf den Server über SSH-Schlüssel
  • kubectl ist auf Ihrem lokalen Rechner installiert
  • Grundlegendes Verständnis von KubeOne – siehe „Was ist KubeOne?“

Einführung

In diesem Tutorial installieren Sie KubeOne und nutzen es, um einen Kubernetes-Cluster mit einem einzigen Knoten auf einem beliebigen Server einzurichten, auf den Sie per SSH zugreifen können. Dies ist der schnellste Weg, um mit KubeOne einen funktionsfähigen Cluster zu erhalten – kein Konto bei einem Cloud-Anbieter erforderlich, kein Terraform, keine Einrichtung eines Load Balancers. Sie benötigen lediglich einen Server, einen SSH-Schlüssel und eine YAML-Datei.

In Produktionsumgebungen werden drei Control-Plane-Knoten für hohe Verfügbarkeit verwendet. Wenn Sie mit einem Knoten beginnen, können Sie sich ohne zusätzlichen Infrastrukturaufwand mit dem Arbeitsablauf vertraut machen. Sobald Sie die Funktionsweise von KubeOne verstanden haben, ist die Skalierung auf einen vollständigen HA-Cluster lediglich eine Frage des Hinzufügens weiterer Hosts zum Manifest.

Am Ende dieses Tutorials verfügen Sie über einen laufenden Kubernetes-Cluster, eine bereitgestellte Test-Workload und ein solides Verständnis des auf „apply“ basierenden Workflows von KubeOne.

Schritt 1: KubeOne installieren

KubeOne wird als einzelne statische Binärdatei ohne externe Abhängigkeiten bereitgestellt. Am schnellsten lässt es sich mit dem offiziellen Installationsskript installieren:

curl -sfL https://get.kubeone.io | sh

Dadurch wird die neueste stabile Version heruntergeladen und die kubeone Binärdatei /usr/local/bin. Überprüfen Sie die Installation:

kubeone-Version

Es sollte eine Ausgabe angezeigt werden, die die KubeOne-Version, die Go-Version, mit der das Programm kompiliert wurde, sowie Ihr Betriebssystem angibt. Für dieses Tutorial ist jede neuere Version (1.7+) geeignet.

Wenn Sie lieber eine bestimmte Version installieren möchten, laden Sie diese direkt von der GitHub-Release-Seite herunter. Jedes Release enthält Binärdateien für Linux (amd64, arm64), macOS und Windows.

Tipp: KubeOne ist eine einzelne statische Binärdatei ohne Abhängigkeiten. Es läuft unter Linux, macOS und Windows (WSL). Sie benötigen weder Docker noch Helm oder andere lokal installierte Tools – lediglich KubeOne und kubectl.

Schritt 2: Bereiten Sie Ihren Server vor

Sie benötigen einen Server, der diese Anforderungen erfüllt:

  • Betriebssystem: Ubuntu 22.04 oder neuer (Debian, CentOS und andere Distributionen funktionieren ebenfalls, in dieser Anleitung wird jedoch Ubuntu verwendet)
  • Systemanforderungen: Mindestens 2 vCPU und 4 GB RAM
  • Netzwerk: Eine öffentliche IP-Adresse, die von Ihrem lokalen Rechner aus erreichbar ist
  • Zugriff: SSH-Schlüssel-basierte Authentifizierung für einen Benutzer mit Sudo-Rechten konfiguriert

Dies kann eine Cloud-VM eines beliebigen Anbieters sein – DigitalOcean, Hetzner, AWS EC2, Google Compute Engine, Azure – oder eine lokale VM, die mit Multipass, Vagrant oder VirtualBox erstellt wurde. Die einzige Voraussetzung ist, dass Sie über SSH darauf zugreifen können.

Überprüfen Sie, ob Ihre SSH-Verbindung funktioniert:

ssh -i ~/.ssh/dein-Schlüssel ubuntu@DEINE_SERVER-IP "hostname"

Ersetzen ~/.ssh/Ihr-Schlüssel mit dem Pfad zu Ihrem privaten SSH-Schlüssel, Ubuntu als SSH-Benutzer auf Ihrem Server und DEINE_SERVER-IP mit der tatsächlichen IP-Adresse. Wenn dieser Befehl den Hostnamen des Servers ausgibt, können Sie fortfahren.

Warnung: KubeOne erfordert eine passwortlose SSH-Schlüsselauthentifizierung. Passwortbasiertes SSH funktioniert nicht. Wenn Sie einen Cloud-Anbieter nutzen, richten die meisten standardmäßig VMs mit SSH-Schlüsselzugriff ein. Für lokale VMs generieren Sie ein Schlüsselpaar mit ssh-keygen und kopieren Sie den öffentlichen Schlüssel mit ssh-copy-id.

Stellen Sie sicher, dass die folgenden Ports in der Firewall oder Sicherheitsgruppe des Servers geöffnet sind:

HafenProtokollZweck
22TCPSSH-Zugriff für KubeOne
6443TCPKubernetes-API-Server
30000–32767TCPNodePort-Dienste (zu Testzwecken)

Wenn sich Ihr Server hinter einer Cloud-Sicherheitsgruppe befindet, fügen Sie Regeln hinzu, um eingehenden Datenverkehr über diese Ports von Ihrer lokalen IP-Adresse zuzulassen.

Schritt 3: Erstellen Sie das KubeOneCluster-Manifest

Das KubeOneCluster-Manifest ist eine YAML-Datei, die den gewünschten Zustand Ihres Clusters beschreibt. KubeOne liest diese Datei und kümmert sich um alles Notwendige, damit der Cluster genau den von Ihnen festgelegten Anforderungen entspricht.

Erstellen Sie eine Datei mit dem Namen kubeone.yaml in einem neuen Verzeichnis auf Ihrem lokalen Rechner:

mkdir mein-erster-Cluster && cd mein-erster-Cluster

Erstellen Sie anschließend das Manifest:

apiVersion: kubeone.k8c.io/v1beta2
kind: KubeOneCluster
name: my-first-cluster

versions:
  kubernetes: "v1.30.2"

cloudProvider:
  none: {}

controlPlane:
  hosts:
    - publicAddress: "YOUR_SERVER_IP"
      privateAddress: "YOUR_SERVER_IP"
      sshUser: "ubuntu"
      sshPrivateKeyFile: "~/.ssh/your-key"

Ersetzen DEINE_SERVER-IP durch die tatsächliche IP-Adresse Ihres Servers, Ubuntu mit Ihrem SSH-Benutzer und ~/.ssh/Ihr-Schlüssel mit dem Pfad zu Ihrem privaten SSH-Schlüssel.

Hier ist die Funktion der einzelnen Felder:

  • versions.kubernetes: Die genaue Kubernetes-Version, die installiert werden soll. KubeOne unterstützt alle aktiv gepflegten Kubernetes-Versionen. Überprüfen Sie die Kompatibilitätsmatrix die vollständige Liste.
  • cloudProvider.none: Teilt KubeOne mit, dass keine Integration mit einem Cloud-Anbieter vorhanden ist. Dies ist die richtige Wahl, wenn Sie mit Bare-Metal-Servern, lokalen VMs oder einer beliebigen Infrastruktur arbeiten, bei der Sie keine cloudspezifischen Funktionen wie automatische Lastverteiler oder die Bereitstellung persistenter Volumes benötigen.
  • controlPlane.hosts: Die Liste der Server, auf denen die Kubernetes-Steuerungsebene ausgeführt wird. In diesem Tutorial gibt es einen Host. Der öffentliche Adresse ist die IP-Adresse, mit der sich KubeOne über SSH verbindet. Die privateAddress ist die IP-Adresse, über die Kubernetes-Komponenten miteinander kommunizieren. Auf einem einzelnen Server mit einer Netzwerkkarte handelt es sich dabei um dieselbe IP-Adresse.

Dieses Manifest ist Ihre zentrale Informationsquelle für den Cluster. Verwalten Sie es zusammen mit Ihren anderen Infrastrukturdateien unter Versionskontrolle.

Schritt 4: Cluster bereitstellen

Wenn das Manifest fertig ist, führen Sie folgenden Befehl aus:

kubeone apply --manifest kubeone.yaml

KubeOne fordert Sie auf, den Vorgang zu bestätigen. Geben Sie ein ja um fortzufahren. Und so geht es weiter:

  1. SSH-Verbindung – KubeOne stellt über die in Ihrem Manifest angegebenen Anmeldedaten eine Verbindung zum Server her.
  2. Container-Laufzeitumgebung – Hiermit wird „containerd“ als Container-Laufzeitumgebung installiert und konfiguriert.
  3. Kubernetes-Komponenten – Es installiert kubeadm, kubelet und kubectl auf dem Server.
  4. Cluster-Bootstrap — Es läuft kubeadm init um die Kubernetes-Steuerungsebene zu initialisieren, einschließlich etcd, des API-Servers, des Controller-Managers und des Schedulers.
  5. CNI-Installation – Hier wird Canal (Calico + Flannel) als Container Network Interface-Plugin eingesetzt, das die Netzwerkkommunikation zwischen den Pods übernimmt.
  6. Maschinensteuerung – Hier wird die Kubermatic-Maschinensteuerung eingesetzt, die die Worker-Knoten verwaltet. Bei dieser Ein-Knoten-Konfiguration werden Sie diese nicht verwenden, sie steht jedoch für zukünftige Erweiterungen zur Verfügung.
  7. Erstellung einer Kubeconfig-Datei — Es wird eine Kubeconfig-Datei erstellt, mit der Sie von Ihrem lokalen Rechner aus auf den Cluster zugreifen können.

Der gesamte Vorgang dauert 3 bis 5 Minuten, abhängig von der Internetgeschwindigkeit und den Ressourcen Ihres Servers. KubeOne gibt bei jedem Schritt detaillierte Informationen aus, sodass Sie den Vorgang verfolgen und genau sehen können, was gerade passiert.

Sobald der Vorgang abgeschlossen ist, erstellt KubeOne eine Datei mit dem Namen meine-erste-Cluster-Kubeconfig in Ihrem aktuellen Verzeichnis. Diese Datei enthält die Anmeldedaten und Endpunktinformationen, die für die Verbindung zu Ihrem Cluster erforderlich sind.

Schritt 5: Auf Ihren Cluster zugreifen

Stellen Sie die KUBECONFIG Umgebungsvariable, die auf die generierte Kubeconfig verweist:

export KUBECONFIG=$(pwd)/my-first-cluster-kubeconfig

Überprüfen Sie nun, ob Sie den Cluster erreichen können:

kubectl get nodes

Die Ausgabe sollte in etwa so aussehen:

NAME              STATUS   ROLLEN           ALTER   VERSION
Ihr-Server       Bereit    Control-Plane   2m    v1.30.2

Die Bereit Dieser Status bedeutet, dass der Knoten betriebsbereit ist und Arbeitslasten annimmt. Der Steuerungsebene Die Rolle bestätigt, dass es sich um den Knoten der Steuerungsebene handelt.

Überprüfen Sie, ob alle Systemkomponenten laufen:

kubectl get pods -A

Du solltest Kapseln in der Laufen Geben Sie für diese Komponenten Folgendes an:

  • coredns – Cluster-DNS
  • Canal (oder Kaliko/Flanell) — Pod-Netzwerk
  • kube-proxy – Netzwerkkonfiguration für Dienste
  • kube-apiserver – die Kubernetes-API
  • kube-controller-manager – Abgleichschleifen
  • kube-scheduler – Pod-Planung
  • etcd – storage für den Cluster-Status

Falls ein Pod nicht in Laufen Wenn der Status nicht angezeigt wird, warte einen Moment und überprüfe es erneut. Bei einigen Komponenten dauert es einen Moment, bis ihre Container-Images geladen sind und sie hochgefahren sind.

Schritt 6: Eine Test-Workload bereitstellen

Starten Sie den Cluster und stellen Sie einen einfachen Nginx-Webserver bereit, um zu überprüfen, ob alles durchgängig funktioniert:

kubectl create deployment nginx--image=nginx:latest--replicas=2

Dadurch wird ein Deployment mit zwei Nginx-Pods erstellt. Überprüfen Sie, ob die Pods laufen:

kubectl get pods

Beide Kapseln sollten Laufen Status innerhalb von 30 Sekunden. In einem Cluster mit einem einzigen Knoten laufen beide Pods auf demselben Knoten – dies ist beabsichtigt.

Stellen Sie die Bereitstellung als NodePort-Dienst bereit, damit Sie von außerhalb des Clusters darauf zugreifen können:

kubectl expose deployment nginx--port=80--type=NodePort

Finden Sie den zugewiesenen NodePort:

kubectl get svc nginx

Die Ausgabe zeigt eine Portzuordnung wie folgt: 80:31234/TCP. Die Zahl nach dem Doppelpunkt (in diesem Beispiel 31234) ist der NodePort. Rufen Sie die nginx-Startseite über die IP-Adresse Ihres Servers und diesen Port auf:

NODE_PORT=$(kubectl get svc nginx -o jsonpath='{.spec.ports[0].nodePort}')
curl http://YOUR_SERVER_IP:${NODE_PORT}

Sie sollten nun die Standard-HTML-Willkommensseite von Nginx sehen. Dies bestätigt, dass der Cluster läuft, das Pod-Netzwerk funktioniert und die Dienste den Datenverkehr korrekt vom Knoten zu den Pods weiterleiten.

Tipp: In einer Produktionsumgebung würden Sie zur Gewährleistung der Hochverfügbarkeit drei Control-Plane-Knoten einsetzen. Ein einzelner Control-Plane-Knoten reicht für Entwicklungs- und Schulungszwecke aus, doch ein Ausfall dieses Knotens führt dazu, dass der gesamte Cluster nicht mehr verfügbar ist. Informationen zu einer vollständigen HA-Konfiguration finden Sie unter „Bereitstellung von Bare-Metal-Kubernetes mit KubeOne und Terraform “.

Schritt 7: Den KubeOne-Workflow verstehen

Nachdem Sie nun über einen laufenden Cluster verfügen, lohnt es sich zu verstehen, wie KubeOne diesen künftig verwaltet. Genau darin unterscheidet sich KubeOne von Tools, die lediglich die Erstinstallation übernehmen.

Idempotente Anwendung

KubeOne verwendet eine Idempotentes Anwendungsmodell. Sie können kubeone apply so oft Sie möchten, und er wird sich dem in Ihrem Manifest beschriebenen Sollzustand annähern. Wenn der Cluster bereits mit dem Manifest übereinstimmt, führt KubeOne keine Aktion durch. Sollte es Abweichungen geben – eine andere Kubernetes-Version, eine fehlende Komponente, eine fehlerhafte Konfiguration –, behebt KubeOne diese.

Das bedeutet, dass Ihr Manifest stets die maßgebliche Quelle ist. Ändern Sie das Manifest, führen Sie „apply“ aus, und KubeOne ermittelt, was zu tun ist.

Kubernetes aktualisieren

Um Ihren Cluster auf eine neuere Kubernetes-Version zu aktualisieren, bearbeiten Sie kubeone.yaml und die Version ändern:

Versionen:
  Kubernetes: "v1.31.0"

Führen Sie dann Folgendes aus:

kubeone apply --manifest kubeone.yaml

KubeOne übernimmt den Upgrade-Prozess: Es entlastet den Knoten, aktualisiert die Komponenten der Steuerungsebene, aktualisiert das Kubelet und hebt die Isolierung des Knotens auf. Bei Clustern mit mehreren Knoten erfolgt dies als rollierendes Upgrade – Knoten für Knoten –, um die Verfügbarkeit aufrechtzuerhalten.

Cluster-Status prüfen

So können Sie den aktuellen Status Ihres Clusters einsehen, ohne Änderungen vorzunehmen:

kubeone status --manifest kubeone.yaml

Hier werden die auf jedem Knoten ausgeführte Kubernetes-Version, der Zustand der Knoten sowie die Übereinstimmung des Clusters mit dem Manifest angezeigt.

Den Cluster abbauen

Wenn Sie den Cluster vollständig entfernen möchten:

kubeone reset --manifest kubeone.yaml

Warnung: kubeone zurücksetzen löscht den Cluster und entfernt alle Kubernetes-Komponenten vom Server. Alle Workloads, Daten und Konfigurationen gehen dabei verloren. Der Server selbst wird nicht gelöscht – lediglich die Kubernetes-Installation wird entfernt. Gehen Sie bei dieser Aktion mit Vorsicht vor.

Fehlerbehebung bei häufigen Problemen

Zeitüberschreitung bei der SSH-Verbindung

Stellen Sie sicher, dass die Firewall des Servers eingehenden SSH-Verkehr auf Port 22 zulässt. Überprüfen Sie noch einmal, ob der Pfad zum SSH-Schlüssel in Ihrem Manifest mit einem autorisierten Schlüssel auf dem Server übereinstimmt. Führen Sie den SSH-Befehl aus Schritt 2 manuell aus, um das Problem einzugrenzen.

Die Cluster-Bereitstellung schlägt während der Container-Laufzeit fehl

KubeOne muss während der Bereitstellung Container-Images aus dem Internet abrufen. Befindet sich Ihr Server hinter einem Unternehmensproxy oder ist der ausgehende Datenverkehr eingeschränkt, konfigurieren Sie die Proxy-Einstellungen im KubeOneCluster-Manifest unter dem Stellvertreter Abschnitt:

Proxy:
  http: „http://proxy.example.com:8080“
  https: „http://proxy.example.com:8080“
  noProxy: „localhost,127.0.0.1,10.0.0.0/8“

kubectl kann nach der Bereitstellung keine Verbindung herstellen

Stellen Sie sicher, dass die Firewall des Servers eingehenden Datenverkehr auf Port 6443 zulässt, dem Port des Kubernetes-API-Servers. Wenn Sie einen Cloud-Anbieter nutzen, überprüfen Sie die Sicherheitsgruppe oder die Firewall-Regeln der virtuellen Maschine. Vergewissern Sie sich außerdem, dass die öffentliche Adresse in Ihrem Manifest ist die richtige IP-Adresse angegeben.

Pods, die im Status „Ausstehend“ hängen geblieben sind

In einer Ein-Knoten-Konfiguration muss der Knoten der Steuerungsebene auch reguläre Workloads ausführen. KubeOne hebt die standardmäßige Taint-Markierung der Steuerungsebene für Ein-Knoten-Cluster auf. Sollten Pods jedoch im Status „Pending“ verbleiben, überprüfen Sie den Knoten auf mögliche Probleme:

kubectl describe node

Achten Sie auf Anzeichen wie Scheibendruck, Speicherdruckoder PID-Druck. Dies deutet darauf hin, dass der Server nicht über genügend Ressourcen verfügt. Für einen Cluster mit einem Knoten, auf dem Test-Workloads ausgeführt werden, sind 2 vCPU und 4 GB RAM das Minimum – mehr ist besser.

Aufräumen

Wenn Sie mit dem Experimentieren fertig sind und aufräumen möchten:

kubeone reset --manifest kubeone.yaml

Dadurch wird Kubernetes vom Server entfernt. Falls Sie speziell für dieses Tutorial eine Cloud-VM erstellt haben, löschen Sie diese über die Konsole oder die CLI Ihres Cloud-Anbieters, um weitere Kosten zu vermeiden.

Nächste Schritte

Sie verfügen nun über die Grundlagen für die Arbeit mit KubeOne. So geht es nun weiter:

Zusammenfassung

Sie haben KubeOne installiert, ein KubeOneCluster-Manifest für einen einzelnen Server erstellt und innerhalb weniger Minuten einen funktionsfähigen Kubernetes-Cluster bereitgestellt. KubeOne hat die Installation der Container-Laufzeitumgebung, das Kubeadm-Bootstrapping, die CNI-Konfiguration und die Erstellung der Kubeconfig-Datei übernommen – alles mit einem einzigen Befehl.

Das Wichtigste ist der Workflow von KubeOne: Beschreiben Sie den gewünschten Zustand in einem YAML-Manifest, führen Sie kubeone apply– und KubeOne macht es möglich. Ein und derselbe Befehl übernimmt die Erstinstallation, Konfigurationsänderungen und Kubernetes-Versions-Upgrades. Dieses Verfahren wenden Sie an, ganz gleich, ob Sie einen einzelnen Knoten für die Entwicklung verwalten oder fünfzig Knoten über mehrere Rechenzentren hinweg.