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.

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)

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¶

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¶

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.

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

Kubeconfig-Synchronisation¶

polycrate k8s sync-kubeconfigs lädt alle Kubernetes-Cluster aus der Polycrate API und schreibt ihre Kubeconfigs in die lokale Kubeconfig-Datei (Standard: ~/.kube/config). Vorhandene Einträge mit demselben Cluster-Namen werden überschrieben — der Befehl ist idempotent.

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

# Workspace-Namen als Kontext verwenden (kein Argument)
polycrate k8s set-context -w /pfad/zum/workspace

# 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

Loopback-Kubeconfig-Sync¶

Bei Workspaces mit einem K8sCluster vom Typ loopback rotiert die Kubeconfig serverseitig über die Polycrate API (Loopback-Integration). Die lokale Datei im Workspace — typischerweise artifacts/secrets/kubeconfig.yml — wird nicht automatisch aktualisiert, wenn die API eine neuere Version bereitstellt.

Ab CLI 0.46.0 prüft die CLI vor jedem Action-Run (polycrate run, polycrate blocks run), ob eine neuere Kubeconfig verfügbar ist, und bietet interaktiv einen Download an.

Voraussetzungen¶

• API konfiguriert (api.enabled: true, api.api_key) → API-Integration
• Workspace nutzt eine workspace-lokale Kubeconfig (nicht den globalen Fallback ~/.kube/config)
• Ein Loopback-K8sCluster ist dem Workspace in der API zugeordnet
• Interaktive Session (in CI wird der Check übersprungen)

Ablauf¶

1. Workspace und lokale Kubeconfig laden (wie bei jedem Run)
2. Loopback-Cluster für diesen Workspace in der API suchen
3. Credential-Kubeconfig mit lokalem Dateiinhalt vergleichen
4. Bei Unterschied: Prompt — „A newer kubeconfig for loopback cluster '…' is available — download and overwrite?"
5. Bei Bestätigung: Datei mit Modus 0600 überschreiben; der Action-Run läuft danach normal weiter

Bei Ablehnung oder API-Fehler wird der Run nicht abgebrochen (im Gegensatz zu Wartungsfenster- oder Git-Stale-Checks).

Konfiguration¶

# Einmalig deaktivieren
polycrate run my-block install --sync-loopback-kubeconfig=false

→ Konfiguration — Update- und Prüf-Checks

→ Loopback-Integration (API)

Siehe also¶

• CLI-Referenz - Vollständige Command-Referenz
• Der Polycrate Container - Verfügbare Tools im Container
• API-Integration - Polycrate API konfigurieren