Erste Schritte mit kcp

Einführung

kcp ist eine Kubernetes-ähnliche Steuerungsebene, die Ihnen die API-Funktionen von Kubernetes – CRDs, RBAC, Zulassungskontrolle, Ressourcenverwaltung – ohne Pods, Nodes oder Container-Orchestrierung zur Verfügung stellt. Es handelt sich um ein CNCF-Sandbox-Projekt, das für den Aufbau mandantenfähiger Plattformen konzipiert ist, bei denen jedes Team einen isolierten API-Bereich erhält, der sich wie ein eigener Cluster anfühlt.

Wenn Sie bereits den Artikel „Was ist kcp?“ gelesen haben, sind Ihnen die Konzepte bereits bekannt. In diesem Tutorial werden diese Konzepte in die Praxis umgesetzt. Sie werden kcp installieren, einen Server starten, Arbeitsbereiche erstellen, eine benutzerdefinierte API mithilfe eines CRD definieren, Ressourcen für diese API erstellen und nachweisen, dass Arbeitsbereiche eine echte Isolation bieten – und das alles auf Ihrem lokalen Rechner in etwa zwanzig Minuten.

Am Ende dieser Anleitung werden Sie ein klares Verständnis davon haben, wie KCP-Arbeitsbereiche, benutzerdefinierte APIs und Ressourcenisolierung zusammenwirken. Alles läuft hier lokal. Es sind weder ein Cloud-Konto noch ein bestehender Kubernetes-Cluster noch eine spezielle Infrastruktur erforderlich.

Was Sie lernen werden:

• So installieren und starten Sie einen KCP-Server
• So erstellen Sie Arbeitsbereiche und navigieren darin
• Wie sich kcp auf API-Ebene von einem herkömmlichen Kubernetes-Cluster unterscheidet
• So definieren Sie eine benutzerdefinierte Ressource (CRD) innerhalb eines Arbeitsbereichs
• Wie die Isolierung von Arbeitsbereichen verhindert, dass CRDs und Ressourcen über Grenzen hinweg verloren gehen

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie Folgendes zur Hand haben:

• Go 1.21 oder höher — erkundigen Sie sich bei go version. Go installieren falls erforderlich.
• kubectl — erkundigen Sie sich bei kubectl version --client. kubectl installieren falls erforderlich.
• Ein Terminal — Alle Befehle werden in einer Standard-Shell (bash oder zsh) ausgeführt.
• Grundkenntnisse in Kubernetes — Sie sollten mit Konzepten wie CRDs, Namespaces und kubectl apply.

Geschätzte Dauer: 20 Minuten

In diesem Tutorial verwendete Umgebung:

• Betriebssystem: macOS oder Linux (die Befehle funktionieren auf beiden Systemen)
• kcp: Neueste Version
• kubectl: 1.28+

Schritt 1: Installieren Sie kcp

Laden Sie die neueste vorgefertigte Binärdatei von GitHub herunter. Das ist der schnellste Weg, um loszulegen:

# Detect the latest release version
KCP_VERSION=$(curl -s https://api.github.com/repos/kcp-dev/kcp/releases/latest | grep tag_name | cut -d '"' -f 4)

# Download the binary (adjust the platform suffix for your OS)
# Linux: linux_amd64 | macOS Intel: darwin_amd64 | macOS Apple Silicon: darwin_arm64
curl -L -o kcp.tar.gz "https://github.com/kcp-dev/kcp/releases/download/${KCP_VERSION}/kcp_${KCP_VERSION}_linux_amd64.tar.gz"

# Extract and install
tar xzf kcp.tar.gz
sudo mv bin/kcp /usr/local/bin/
sudo mv bin/kubectl-kcp /usr/local/bin/

Das Archiv enthält sowohl die kcp Server-Binärdatei und die kubectl-kcp Plugin, das kubectl um Befehle zur Verwaltung von Arbeitsbereichen erweitert.

Überprüfen Sie, ob beide installiert sind:

kcp --version
kubectl kcp --help

Beim ersten Befehl sollte eine Versionsnummer angezeigt werden, beim zweiten eine Liste der Unterbefehle.

Tipp: Informationen zu alternativen Installationsmethoden – einschließlich der Kompilierung aus dem Quellcode – finden Sie in der ausführlichen Anleitung: „kcp installieren und Ihren ersten Arbeitsbereich erstellen“.

Schritt 2: Starten Sie den kcp-Server

Erstellen Sie ein Arbeitsverzeichnis für dieses Tutorial und starten Sie den Server:

mkdir -p ~/kcp-tutorial && cd ~/kcp-tutorial
kcp start

kcp startet eine eingebettete etcd-Instanz, richtet die API-Funktionen ein und wartet auf eingehende Verbindungen. Während der Initialisierung werden Log-Meldungen angezeigt. Sobald Zeilen erscheinen, die darauf hinweisen, dass der Server bereit ist, nimmt er Anfragen entgegen.

kcp schreibt eine Admin-Kubeconfig-Datei in .kcp/admin.kubeconfig im aktuellen Verzeichnis. Diese Datei verwenden Sie, um eine Verbindung mit kubectl herzustellen.

Lassen Sie dieses Terminal geöffnet. Öffnen Sie für die folgenden Schritte ein neues Terminal.

Stellen Sie im neuen Terminal die Umgebungsvariable KUBECONFIG ein:

export KUBECONFIG=~/kcp-tutorial/.kcp/admin.kubeconfig

Warnung: Jede neue Terminalsitzung benötigt dies KUBECONFIG export. Wenn kubectl-Befehle Verbindungsfehler zurückgeben, liegt die Ursache höchstwahrscheinlich in einem fehlenden oder falschen KUBECONFIG-Pfad.

Schritt 3: Erstellen Sie Ihren ersten Arbeitsbereich

Wenn kcp gestartet wird, befinden Sie sich im Stammarbeitsbereich – der obersten Ebene der Hierarchie. Überprüfen Sie dies:

kubectl kcp workspace .

Erwartetes Ergebnis:

Der aktuelle Arbeitsbereich ist „root“.

Erstellen Sie nun einen Arbeitsbereich mit dem Namen Team-Frontend und geben Sie es ein:

kubectl kcp workspace create team-frontend --type universal --enter

Erwartetes Ergebnis:

Arbeitsbereich „team-frontend“ (Typ root:universal) wurde erstellt. Es wird darauf gewartet, dass er bereit ist...
Der Arbeitsbereich „team-frontend“ (Typ root:universal) ist einsatzbereit.
Der aktuelle Arbeitsbereich ist „root:team-frontend“.

Die --Typ: Universal flag erstellt einen Arbeitsbereich mit dem Standardsatz an kcp-APIs. Das --Eingabe Mit diesem Flag wird Ihr kubectl-Kontext automatisch auf den neuen Arbeitsbereich umgestellt.

Schritt 4: Entdecken Sie den Arbeitsbereich

Sie befinden sich jetzt im Inneren Team-Frontend. Dieser Arbeitsbereich verhält sich wie ein Kubernetes-API-Server. Führen Sie einen bekannten Befehl aus:

kubectl api-resources

Sie werden Ressourcen wie ConfigMaps, Secrets, ServiceAccounts, Namespaces und CustomResourceDefinitions sehen. Dies sind die APIs zur Zustandsverwaltung von Kubernetes.

Was Sie nicht sehen werden: Pods, Deployments, ReplicaSets, Services, Nodes. Diese gehören zur Rechenschicht und werden von kcp nicht berücksichtigt. Das ist der grundlegende Unterschied – Sie arbeiten mit einem API-Server, der den Zustand und das Schema verwaltet, nicht mit Containern.

Überprüfe die Namespaces:

kubectl namespaces abrufen

Erwartetes Ergebnis:

NAME      STATUS   ALTER
Standard   Aktiv   30er

Genau wie bei einem neuen Kubernetes-Cluster erhalten Sie einen Standard Namensraum. Der Arbeitsbereich ist ein unbeschriebenes Blatt, bereit für Ihre Ressourcen und APIs.

Tipp: Aus Entwicklersicht unterscheidet sich die Interaktion mit einem kcp-Workspace nicht von der Interaktion mit einem Kubernetes-Cluster. Ihre bestehenden kubectl-Befehle, YAML-Manifeste und Tools funktionieren alle ohne Änderungen.

Schritt 5: Definieren einer benutzerdefinierten API (CRD)

Eine der Stärken von kcp besteht darin, dass jeder Arbeitsbereich über einen eigenen CRD-Bereich verfügt. Sie können in einem Arbeitsbereich benutzerdefinierte APIs definieren, ohne dass dies Auswirkungen auf andere Arbeitsbereiche hat.

Erstellen Sie eine Datei mit dem Namen environment-crd.yaml das eine einfache Umwelt Quelle:

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: environments.platform.example.com
spec:
  group: platform.example.com
  names:
    plural: environments
    singular: environment
    kind: Environment
    shortNames:
      - env
  scope: Namespaced
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              required:
                - tier
                - region
              properties:
                tier:
                  type: string
                  enum: ["development", "staging", "production"]
                region:
                  type: string
                replicas:
                  type: integer
                  minimum: 1
                  maximum: 10
            status:
              type: object
              properties:
                phase:
                  type: string
      subresources:
        status: {}

Tragen Sie das CRD im Inneren des Team-Frontend Arbeitsbereich:

kubectl apply -f environment-crd.yaml

Erwartetes Ergebnis:

customresourcedefinition.apiextensions.k8s.io/environments.platform.example.com wurde erstellt

Überprüfen Sie, ob das CRD registriert ist:

kubectl get crds

Das solltest du dir ansehen environments.platform.example.com aufgeführt. Die Umwelt Die API ist jetzt verfügbar – allerdings nur in diesem Arbeitsbereich.

Schritt 6: Ressourcen mithilfe der benutzerdefinierten API erstellen

Verwenden Sie nun die benutzerdefinierte API, um Umgebungsressourcen zu erstellen. Erstellen Sie eine Datei mit dem Namen staging-env.yaml:

apiVersion: platform.example.com/v1
Art: Umgebung
Metadaten:
  Name: staging-eu
  Namespace: default
spec:
  Ebene: Staging
  Region: eu-west-1
  Replikate: 2

Anwenden:

kubectl apply -f staging-env.yaml

Erstellen Sie inline eine zweite Umgebung:

kubectl apply -f - <<EOF
apiVersion: platform.example.com/v1
kind: Environment
metadata:
  name: prod-us
  namespace: default
spec:
  tier: production
  region: us-east-1
  replicas: 5
EOF

Nenne die Umgebungen:

kubectl get environments

Erwartetes Ergebnis:

NAME         ALTER
staging-eu   15s
prod-us      5s

Sehen Sie sich eines davon an:

kubectl get environment staging-eu -o yaml

Sie sehen die vollständige Ressource mit den von Ihnen definierten Spezifikationen. Die CRD-Validierung wird durchgesetzt – wenn Sie versuchen, Ebene auf einen Wert außerhalb der Enumeration, lehnt kcp diesen ab, genau wie es Kubernetes tun würde.

Tipp: Verwende den Kurznamen env für schnellere Befehle: kubectl get env funktioniert, weil du Kurzbezeichnungen: ["env"] im CRD.

Schritt 7: Erstellen Sie einen zweiten Arbeitsbereich und überprüfen Sie die Isolierung

Hier wird das Isolationsmodell von kcp konkret. Navigieren Sie zurück zum Stamm-Workspace:

kubectl kcp workspace ..

Erstellen Sie einen zweiten Arbeitsbereich und wechseln Sie dorthin:

kubectl kcp workspace create team-backend --type universal --enter

Versuchen Sie nun, Umgebungen in Team-Backend:

kubectl get environments

Erwartetes Ergebnis:

Fehler: Der Server verfügt nicht über den Ressourcentyp „Umgebungen“

Die Umwelt CRD existiert nicht in Team-Backend. Es wurde nur in Team-Frontend. Im regulären Kubernetes gelten CRDs für den gesamten Cluster – sie sind in jedem Namespace sichtbar. In kcp bildet jeder Workspace einen eigenen API-Bereich. CRDs, die in einem Workspace definiert wurden, sind für alle anderen Workspaces unsichtbar.

Stellen Sie sicher, dass sich überhaupt keine CRDs in Team-Backend:

kubectl get crds

Erwartetes Ergebnis:

Es wurden keine Ergebnisse gefunden

Das ist echte Isolation. Das Backend-Team kann die benutzerdefinierten APIs des Frontend-Teams weder einsehen noch nutzen oder beeinflussen. Jedes Team hat die volle Kontrolle über seine eigene API-Oberfläche.

Sie können eine völlig andere Umwelt CRD in Team-Backend mit anderen Feldern, anderen Validierungsregeln, sogar einer anderen API-Gruppe – und es wird keinen Konflikt mit der in Team-Frontend.

Flussdiagramm TB
    Root["root workspace"]

    Teilgraph FE["root:team-frontend"]
        CRD1[CRD: environments.platform.example.com]
        R1[Environment/staging-eu]
        R2[Environment/prod-us]
        CRD1 --> R1
        CRD1 --> R2
    Ende

    Teilgraph BE["root:team-backend"]
        Leer["(keine CRDs)
(keine benutzerdefinierten Ressourcen)"]
    Ende

    Root --> FE
    Root --> BE

    FE -. isoliert .-x BE

Warnung: Durch die Isolierung der Arbeitsbereiche werden APIs standardmäßig nicht gemeinsam genutzt. Wenn Sie möchten, dass das Team-Backend das Team-Frontend nutzt, Umwelt API: Um diese explizit freizugeben, müssen Sie die Mechanismen „APIExport“ und „APIBinding“ von kcp verwenden. Dies ist ein separates Thema, das in der kcp-Reihe behandelt wird.

Schritt 8: Aufräumen

Beenden Sie den kcp-Server, indem Sie Strg+C in dem Terminal, in dem es ausgeführt wird.

Entfernen Sie das Arbeitsverzeichnis und alle generierten Dateien:

rm -rf ~/kcp-tutorial

Dadurch werden die eingebetteten etcd-Daten, die generierte kubeconfig-Datei und der gesamte Workspace-Status entfernt. Da alles lokal ausgeführt wird, ist die Bereinigung unkompliziert – in der Cloud muss nichts abgebaut werden.

Fehlerbehebung

Port 6443 wird bereits verwendet

Symptom: kcp lässt sich nicht starten und gibt die Fehlermeldung „Adresse bereits in Gebrauch“ aus.

Ursache: Ein anderer Prozess – beispielsweise minikube, kind, das in Docker Desktop integrierte Kubernetes oder eine frühere kcp-Instanz – hört bereits auf Port 6443.

Lösung:

# kcp auf einem anderen Port starten
kcp start--secure-port=6444

Wenn Sie den Port ändern, wird die generierte kubeconfig-Datei unter .kcp/admin.kubeconfig wird automatisch auf den neuen Port verweisen.

KUBECONFIG nicht festgelegt

Symptom: kubectl-Befehle geben die Meldung „Die Verbindung zum Server localhost:8080 wurde abgelehnt“ oder ähnliche Verbindungsfehler zurück.

Ursache: Die Umgebungsvariable KUBECONFIG ist nicht gesetzt oder verweist auf die falsche Datei.

Lösung:

# Setze KUBECONFIG auf die kcp-Admin-Kubeconfig
export KUBECONFIG=~/kcp-tutorial/.kcp/admin.kubeconfig

# Überprüfen Sie die Verbindung
kubectl cluster-info

Beachten Sie, dass dieser Export nur für die aktuelle Terminalsitzung gilt. Für jedes neue Terminal muss der Export erneut durchgeführt werden.

Arbeitsbereich nicht gefunden

Symptom: kubectl kcp workspace use <name> gibt eine Fehlermeldung aus, dass der Arbeitsbereich nicht existiert.

Ursache: Sie befinden sich im falschen übergeordneten Arbeitsbereich. Arbeitsbereiche sind hierarchisch aufgebaut – Sie können nur auf direkte Unterelemente Ihres aktuellen Arbeitsbereichs zugreifen.

Lösung:

# Wechseln Sie zunächst in den Stamm-Workspace
kubectl kcp workspace ..

# Verfügbare untergeordnete Arbeitsbereiche auflisten
kubectl get workspaces

# Wechseln Sie dann zum Ziel-Workspace
kubectl kcp workspace use team-frontend

kubectl kcp: Befehl nicht gefunden

Symptom: Laufen kubectl kcp gibt „unbekannter Befehl“ oder „Befehl nicht gefunden“ zurück.

Grund: Die kubectl-kcp Die Plugin-Binärdatei ist nicht installiert oder befindet sich nicht in Ihrem PATH.

Lösung:

# Prüfen, ob die Binärdatei vorhanden ist
welches kubectl-kcp

# Falls nicht gefunden, installiere sie aus dem kcp-Release-Archiv
sudo mv bin/kubectl-kcp /usr/local/bin/

Unstimmigkeit bei der Go-Version (Kompilierung aus dem Quellcode)

Symptom: make build schlägt mit Fehlern bezüglich der Go-Version fehl.

Grund: kcp erfordert Go 1.21 oder höher.

Lösung:

go version
# Falls Version unter 1.21, aktualisieren:
# macOS: brew upgrade go
# Linux: Download unter https://go.dev/dl/

Nächste Schritte

Nachdem Sie nun kcp in Aktion gesehen haben, finden Sie hier die empfohlenen nächsten Tutorials:

• kcp installieren und Ihren ersten Arbeitsbereich erstellen — behandelt die Installationsoptionen ausführlicher, einschließlich der Kompilierung aus dem Quellcode, und führt Sie Schritt für Schritt durch die Navigation im Arbeitsbereich und die CRD-Isolierung.
• kcp-Workspaces vs. Namespaces vs. vcluster – ein Vergleich der drei wichtigsten Multi-Tenancy-Ansätze im Kubernetes-Ökosystem, damit Sie beurteilen können, wo kcp für Ihren Anwendungsfall geeignet ist.
• Was ist kcp? Kubernetes ohne Pods – falls Sie direkt zu dieser praktischen Anleitung gesprungen sind: Der konzeptionelle Artikel erläutert die Architektur, Anwendungsfälle und Designentscheidungen hinter kcp.

Zusammenfassung

In diesem Tutorial haben Sie kcp installiert, einen lokalen Server gestartet und einen kompletten praktischen Arbeitsablauf durchgearbeitet. Sie haben zwei Arbeitsbereiche erstellt (Team-Frontend und Team-Backend), definierte eine benutzerdefinierte Umwelt Ich habe eine API verwendet, die eine CRD in einem Arbeitsbereich nutzt, Ressourcen für diese API erstellt und überprüft, dass die CRD und ihre Ressourcen vom anderen Arbeitsbereich aus vollständig unsichtbar sind.

Die wichtigsten Erkenntnisse:

• kcp stellt die Kubernetes-API-Funktionalität ohne die Rechenebene bereit. Sie erhalten CRDs, RBAC, Namespaces und Ressourcenverwaltung, jedoch keine Pods, Nodes oder Scheduler.
• Arbeitsbereiche sind echte Isolationsgrenzen. Jeder Arbeitsbereich verfügt über einen eigenen CRD-Bereich, eigene Ressourcen und eine eigene API-Oberfläche. Im Gegensatz zu Kubernetes-Namespaces isolieren Arbeitsbereiche clusterweite Ressourcen wie CRDs.
• Die Entwicklerumgebung ist vertraut. Man nutzt kubectl, schreibt Standard-YAML und interagiert mit den Standard-Kubernetes-APIs. Der einzige Unterschied besteht darin, was diese APIs verwalten.

Dieses Isolationsmodell macht kcp zu einer soliden Grundlage für mandantenfähige Plattformen. Jedes Team oder jeder Mandant erhält einen Arbeitsbereich, der wie ein dedizierter Cluster aussieht und sich auch so anfühlt, während im Hintergrund eine einzige kcp-Instanz läuft.