Verbinden mit kubectl

Sobald dein gehosteter Cluster läuft, verbindest du dich mit ihm über eine kubeconfig, die du aus dem Dashboard herunterlädst (öffne den Cluster, dann den Tab Kubeconfig). kubehz bietet zwei Varianten, und die Standardvariante ist die, die du möchtest.

Hosted

Diese Seite beschreibt, wie der Zugriff auf einen gehosteten Cluster funktioniert; bei einem Self-Hosted-Cluster hältst du deine eigene kubeconfig bereits selbst.

Die OIDC-kubeconfig (Standard)

Der Standard-Download ist eine OIDC-kubeconfig. Sie trägt kein langlebiges Zugangsgeheimnis: Stattdessen weist sie kubectl an, dich über kubehz anzumelden (dieselbe Anmeldung, die du für das Dashboard verwendest) und diese Identität zu nutzen. Dein Zugriff auf den Cluster folgt deiner Team-Mitgliedschaft und deiner Rolle: Was kubectl tun kann, ist genau das, was deine Rolle erlaubt.

Dies ist der empfohlene Weg zum Verbinden: Nichts Geheimes liegt in der Datei, der Zugriff folgt deiner aktiven Anmeldung, und wenn du das Team verlässt, endet dein Zugriff mit ihr.

Einmalige Einrichtung: kubelogin installieren

Die OIDC-kubeconfig nutzt das kubelogin-Plugin (kubectl oidc-login), um die Browser-Anmeldung abzuwickeln. Installiere es einmalig:

# krew (any platform)
kubectl krew install oidc-login

# or Homebrew (macOS / Linux)
brew install int128/kubelogin/kubelogin

Verbinden

1. Öffne im Dashboard deinen Cluster und den Tab Kubeconfig.

2. Lade die OIDC-kubeconfig (die Standardvariante) herunter und speichere sie, z. B. unter ~/.kube/kubehz-<cluster>.yaml.

3. Richte kubectl darauf aus und führe einen beliebigen Befehl aus:

   export KUBECONFIG="$HOME/.kube/kubehz-<cluster>.yaml"
   kubectl get nodes
   
   # Mit einem Worker-Pool:
   # NAME       STATUS   ROLES    AGE   VERSION
   # worker-1   Ready    <none>   4m    v1.31.4
   
   # Cluster nur mit Control Plane, noch kein Pool — das ist ERFOLG:
   # No resources found

   Eine leere Liste ist keine fehlgeschlagene Verbindung. Eine gehostete Control Plane hat keine eigenen Nodes: No resources found heißt, dass kubectl deinen API-Server erreicht hat und dieser geantwortet hat. Kapazität fügst du unter Worker-Pools hinzu.

   Der erste Befehl öffnet deinen Browser zur Anmeldung bei kubehz. Danach wird das Token zwischengespeichert und kubectl arbeitet normal, bis es abläuft. Dann bittet es dich einfach erneut um Anmeldung.

Wenn ein Befehl Forbidden zurückgibt, gewährt deine Rolle diese Aktion nicht; siehe Zugriff & Rollen.

Die Admin-kubeconfig (fortgeschritten, nicht empfohlen)

Eine Admin-kubeconfig ist ebenfalls unter einer Erweitert-Option verfügbar, aber wir raten davon ab:

• sie bettet ein langlebiges Client-Zertifikat ein, das nicht an deine Identität gebunden ist;
• sie kann nicht widerrufen werden, außer durch Rotation der CA des Clusters;
• sie gewährt immer vollen cluster-admin und ignoriert deine Rolle.

Greife nur als Break-Glass-Notlösung darauf zurück (zum Beispiel, wenn der OIDC-Weg nicht verfügbar ist). Da sie sensibel ist, ist sie doppelt abgesichert:

1. Aktiviere sie zuerst in den Einstellungen des Clusters: Dies erfordert eine frische Zwei-Faktor-Anmeldung und ein ausdrückliches Zustimmungs-Häkchen. Bis du das tust, ist der Admin-Download nicht verfügbar.
2. Herunterladen: Der Download selbst erfordert eine weitere frische Zwei-Faktor-Anmeldung.

Jedes Aktivieren, Deaktivieren und Herunterladen wird im Audit-Log deines Kontos festgehalten. Schalte die Option in den Einstellungen wieder aus, wenn du sie nicht mehr brauchst.

Nächste Schritte

• Zugriff & Rollen: was jedes Mitglied tun kann und benutzerdefinierte Rollen, die auf Namespaces beschränkt sind.
• Identität & Anmeldung: wie deine Anmeldung auf den Cluster-Zugriff abgebildet wird.
• Add-ons: der Cluster-Viewer im Dashboard und weitere gehostete Add-ons.

---

Doku-Status

Aspekt	Detail
Zustand	Live: OIDC-kubeconfig ist der Standard; die Admin-kubeconfig ist doppelt abgesichert
Zuletzt geprüft	2026-07-14