Zum Inhalt

Kubernetes

Polycrate bietet native Kubernetes-Integration für die Verwaltung von Clustern und das Debugging.

Kubeconfig

Polycrate ist in Kubernetes integriert und kann sich über eine Kubeconfig-Datei mit einem Cluster verbinden.

Kubeconfig-Suchpfade

Polycrate sucht nach einer Kubeconfig in folgender Reihenfolge:

  1. Workspace Secrets: artifacts/secrets/kubeconfig.yml (empfohlen für verschlüsselte Workspaces)
  2. Workspace-Konfiguration: In workspace.poly definierter Pfad (kubeconfig.filename)
  3. Workspace-Root: kubeconfig.yml im Workspace-Verzeichnis
  4. Block-Artifacts: artifacts/blocks/k8s/kubeconfig.yml (Legacy)
  5. Globale Kubeconfig: ~/.kube/config (Fallback)

Kubeconfig in workspace.poly

Die Kubeconfig kann in der workspace.poly konfiguriert werden:

# workspace.poly
name: my-workspace

kubeconfig:
  filename: kubeconfig.yml  # Pfad relativ zum Workspace

Kubeconfig von anderem Block erben

In der workspace.poly kann ein Block die Kubeconfig von einem anderen Block erben:

# workspace.poly
name: my-workspace

blocks:
  # Der k8s-Block generiert die Kubeconfig
  - name: k8s
    from: registry.my-org.com/blocks/k8s/cluster:1.0.0
    config:
      # ...

  # Der my-app Block erbt die Kubeconfig vom k8s-Block
  - name: my-app
    from: registry.my-org.com/blocks/k8s/my-app:1.0.0
    kubeconfig:
      from: k8s  # Erbt Kubeconfig von Block "k8s"

Dies fügt automatisch eine Umgebungsvariable (KUBECONFIG=pfad/zur/kubeconfig/von/k8s) zum Container hinzu, sodass kubectl, helm und andere Tools die richtige Kubeconfig verwenden.

Konfiguration in workspace.poly

Die kubeconfig.from Konfiguration wird immer in der workspace.poly bei der Block-Instanz definiert, nicht in der block.poly des Blocks selbst.

Empfohlene Struktur

Für verschlüsselte Workspaces empfehlen wir:

my-workspace/
├── workspace.poly              # kubeconfig.from wird hier pro Block-Instanz definiert
├── artifacts/
│   └── secrets/
│       └── kubeconfig.yml      # Wird verschlüsselt als kubeconfig.yml.age
└── blocks/
    └── my-app/
        └── block.poly          # Block-Definition (keine kubeconfig.from hier)

Verschlüsselung

Speichern Sie die Kubeconfig in artifacts/secrets/ und verschlüsseln Sie den Workspace mit polycrate workspace encrypt. Siehe Workspace-Verschlüsselung.

Debug-Pod

Mit polycrate k8s debug können Sie einen temporären Debug-Pod im Cluster starten, um direkt im Cluster-Kontext zu arbeiten.

Verwendung

polycrate k8s debug

Was passiert?

  1. ServiceAccount erstellen: Ein ServiceAccount polycrate-admin wird im Ziel-Namespace erstellt (falls nicht vorhanden)
  2. ClusterRoleBinding: Der ServiceAccount erhält cluster-admin Rechte
  3. Pod starten: Ein Pod mit dem Polycrate-Image wird gestartet
  4. Attach: Polycrate verbindet sich automatisch mit der Shell im Pod
  5. Cleanup: Nach Beenden der Session wird der Pod automatisch gelöscht

Optionen

Flag Standard Beschreibung
-n, --namespace kube-system Namespace für den Debug-Pod

Beispiele

# Debug-Pod im Standard-Namespace (kube-system)
polycrate k8s debug

# Debug-Pod in einem anderen Namespace
polycrate k8s debug -n default

# Mit explizitem Workspace-Pfad
polycrate k8s debug -w /path/to/workspace

Beispiel-Session

$ polycrate k8s debug
INFO Starting debug pod polycrate-debug-1701234567 in namespace kube-system
INFO Creating service account polycrate-admin in namespace kube-system
INFO Creating cluster role binding polycrate-admin-cluster-admin
INFO Pod created, waiting for it to be ready...
INFO Pod is running, attaching...

# Jetzt im Pod:
bash-5.1# kubectl get nodes
NAME           STATUS   ROLES           AGE   VERSION
master-1       Ready    control-plane   30d   v1.28.2
worker-1       Ready    <none>          30d   v1.28.2
worker-2       Ready    <none>          30d   v1.28.2

bash-5.1# helm list -A
NAME            NAMESPACE       REVISION    STATUS      CHART
ingress-nginx   ingress         1           deployed    ingress-nginx-4.8.0
cert-manager    cert-manager    1           deployed    cert-manager-1.13.0

bash-5.1# exit

INFO Debug session ended
INFO Cleaning up debug pod polycrate-debug-1701234567...
INFO Debug pod deleted

Use Cases

Szenario Beschreibung
Cluster-Debugging Direkt im Cluster mit allen Polycrate-Tools arbeiten
Netzwerk-Tests Service-Konnektivität innerhalb des Clusters testen
Helm-Operationen Helm-Charts installieren, upgraden oder debuggen
Log-Analyse Pod-Logs und Events analysieren
Secret-Inspection Secrets und ConfigMaps einsehen

Im Pod verfügbare Tools

Der Debug-Pod enthält alle Tools aus dem Polycrate-Image:

Kubernetes & Container:

  • kubectl - Kubernetes CLI
  • helm - Helm Package Manager (+ helm-diff Plugin)
  • kustomize - Kubernetes Konfiguration
  • cilium - Cilium CNI CLI
  • argocd - Argo CD CLI
  • velero - Kubernetes Backup Tool
  • docker - Docker CLI
  • skopeo - Container Image Management

Backup & Encryption:

  • restic - Backup Tool
  • kopia - Backup Tool
  • age - Moderne Verschlüsselung

Utilities:

  • ansible - Configuration Management
  • git, curl, wget, rsync
  • jq, yq - JSON/YAML Processing
  • psql, mysql - Datenbank-Clients
  • dig, nslookup, telnet - Netzwerk-Tools

Siehe Der Polycrate Container für die vollständige Tool-Liste.

Sicherheitshinweis

Der Debug-Pod hat cluster-admin Rechte. Verwenden Sie diesen Befehl nur in vertrauenswürdigen Umgebungen und löschen Sie den ServiceAccount nach dem Debugging falls nötig:

kubectl delete serviceaccount polycrate-admin -n kube-system
kubectl delete clusterrolebinding polycrate-admin-cluster-admin

Kubeconfig-Synchronisation

Das CLI-Feature ist polycrate k8s sync-kubeconfigs: alle K8sCluster der Polycrate API (jedes kind), deren Credential eine Kubeconfig enthält. Nicht Loopback-spezifisch, nicht Teil der Kubernetes Distro.

polycrate k8s sync-kubeconfigs schreibt die Kontexte in die lokale Kubeconfig-Datei (Standard: ~/.kube/config). Vorhandene Einträge mit demselben Cluster-Namen werden überschrieben — der Befehl ist idempotent.

Voraussetzung: Polycrate API

Der Befehl benötigt eine konfigurierte API-Verbindung (~/.polycrate/polycrate.yml mit api.enabled: true und api.api_key). Cluster ohne hinterlegte Credential werden übersprungen. → API-Integration

Verwendung

polycrate k8s sync-kubeconfigs

Was passiert?

  1. Cluster abrufen: Alle K8sCluster-Objekte werden von der Polycrate API geladen.
  2. Credential laden: Für jeden Cluster wird die zugehörige Credential (inkl. Kubeconfig-Inhalt) abgerufen.
  3. Mergen: Cluster, AuthInfo und Context aus der jeweiligen Kubeconfig werden unter dem Cluster-Namen (cluster.name) in die lokale Kubeconfig eingetragen.
  4. Schreiben: Die aktualisierte Kubeconfig wird in ~/.kube/config gespeichert (Verzeichnis wird ggf. angelegt).

Cluster ohne Credential oder mit leerem Kubeconfig-Inhalt werden übersprungen und protokolliert.

Beispiel

$ polycrate k8s sync-kubeconfigs
● Fetching K8s clusters from API...
● Found 3 cluster(s)
✓ archenemy
✓ laser24
● skipped: tank-3 (no credential)
● Wrote 2 context(s) to /home/user/.kube/config (1 skipped)

Nach der Synchronisation können die Kontexte direkt mit kubectl genutzt werden:

kubectl config get-contexts
kubectl config use-context archenemy
kubectl get nodes

Kontext wechseln

Mit polycrate k8s set-context wird der aktive Kontext in ~/.kube/config gesetzt:

# Kontext explizit angeben
polycrate k8s set-context archenemy

# Ohne Argument: interaktive TUI zur Kontext-Auswahl (ab CLI 0.44.2)
polycrate k8s set-context

# Nur textuell listen (kein TUI)
polycrate k8s set-context --no-tui

Workflow: sync + set-context

# Einmalig synchronisieren
polycrate k8s sync-kubeconfigs

# Danach schnell zwischen Clustern wechseln
polycrate k8s set-context archenemy
kubectl get nodes

Ziel-Kubeconfig anpassen

Standardmäßig wird ~/.kube/config verwendet. Das Ziel kann in ~/.polycrate/polycrate.yml geändert werden:

# ~/.polycrate/polycrate.yml
kubeconfig: /pfad/zur/kubeconfig.yml

Workspace-Datei vor Action-Runs

sync-kubeconfigs schreibt nach ~/.kube/config (bzw. kubeconfig: in polycrate.yml). Actions im Container nutzen oft eine workspace-lokale Datei (artifacts/secrets/kubeconfig.yml).

Vor einem interaktiven polycrate run kann die CLI diese Datei mit dem Credential des dem Workspace zugeordneten API-Clusters abgleichen und einen Download anbieten. Der Flag heißt historisch --sync-loopback-kubeconfig / sync_loopback_kubeconfig (Default true): die Implementierung matcht derzeit nur Cluster mit API-kind=loopback — weil deren Kubeconfig in der API rotiert wird, nicht weil Loopback eine Distro-Variante wäre.

polycrate run my-block install --sync-loopback-kubeconfig=false

Kein Abort-Gate; in CI übersprungen; nie den globalen ~/.kube/config-Fallback. Für alle Cluster-Arten: polycrate k8s sync-kubeconfigs.

API-seitig bleibt die Loopback-Integration (Typisierung, Zertifikats-Alerts, Metadaten) — unabhängig von der Distro.

Siehe also