SSH-Sessions und kubectl-Debugging: Polycrate als Operations-Werkzeug | Blog

TL;DR

Polycrate ist nicht nur ein Deployment-Tool: Mit polycrate ssh und Block-Actions für kubectl wird es zum zentralen Operations-Werkzeug für Linux-, Windows- und Kubernetes-Umgebungen.
SSH-Sessions laufen direkt aus dem Workspace – mit Inventory-basierter Hostauswahl, Tab-Completion und ohne „Wo liegt das Passwort?“-Fragen. Über die Polycrate API werden alle Sessions revisionssicher geloggt.
Kubernetes-Debugging wird zum wiederholbaren Prozess: polycrate run myapp debug startet Ansible-Playbooks mit kubernetes.core.k8s_log und k8s_info im Container – immer mit der richtigen Kubeconfig aus dem Workspace.
Das löst gleich mehrere Probleme klassischer Setups: kein lokales Ansible, kein kubectl-Chaos, keine herumgeschickten Kubeconfigs, klare Audit-Trails für SSH-Zugriffe und K8s-Operationen.
ayedo unterstützt Sie mit Polycrate, maßgeschneidertem Platform Engineering und Beratungsleistungen dabei, Operations und Compliance gemeinsam zu denken – von der ersten Demo bis zum produktiven Betrieb.

Polycrate als Operations-Werkzeug, nicht nur als Deployment-Helfer

Viele Teams nutzen Ansible und kubectl primär für Provisionierung und Deployments. Der Alltag in Operations sieht aber anders aus:

„Wer kann sich schnell auf web-03 einloggen?“
„Welche Kubeconfig brauche ich für den payments-Cluster?“
„Wer hat gestern Abend noch auf dem Prod-Node debuggt?“
„Warum crasht der Pod, obwohl das letzte Deployment grün war?“

Genau hier setzt Polycrate an. Polycrate kapselt nicht nur Ihre Automatisierung in Blöcken, es bringt:

Eine konsistente, containerisierte Toolchain (Ansible, Python, kubectl, Helm …) für alle, ohne lokales Setup-Chaos.
Struktur durch das Block-Modell, das auch Debugging- und Betriebs-Tasks als Actions abbildet – nicht nur Deployments.
SSH- und API-Funktionen, die Operations-Aktivitäten auditierbar machen.

Die folgenden Abschnitte zeigen konkret, wie Sie SSH-Zugriffe und Kubernetes-Debugging mit Polycrate abbilden – inklusive vollständiger workspace.poly, block.poly und Ansible-Playbooks.

SSH direkt aus dem Workspace: `polycrate ssh`

Inventory als Single Source of Truth

Im Polycrate-Workspace liegt das Inventory immer als inventory.yml im Workspace-Root. Polycrate setzt die Umgebung für Ansible und polycrate ssh automatisch.

Ein minimales Inventory für unseren Beispiel-Workspace acme-corp-automation:

# inventory.yml
all:
  hosts:
    web-01.acme-corp.com:
      ansible_user: ubuntu
    web-02.acme-corp.com:
      ansible_user: ubuntu
    k8s-node-01.acme-corp.com:
      ansible_user: ubuntu

Keine INI-Dateien, kein -i-Parameter, kein Rätselraten. Polycrate liest dieses Inventory bei jeder Action und auch bei polycrate ssh.

Workspace-Definition mit SSH-fähigem Block

Unser Workspace:

# workspace.poly
name: acme-corp-automation
organization: acme

blocks:
  - name: k8s-debug
    from: registry.acme-corp.com/acme/ops/k8s-debug:0.1.0
    config:
      namespace: "payments"
      app_label: "app=payments-api"

Wichtig:

Der Block kommt per from: aus einer OCI-Registry (hier fiktiv registry.acme-corp.com/...; öffentlich z. B. cargo.ayedo.cloud oder PolyHub). Die Version ist im from: gepinnt (:0.1.0).
Kein kubeconfig_path in workspace.poly oder block.poly: Polycrate setzt im Action-Container KUBECONFIG und K8S_AUTH_KUBECONFIG auf die Workspace-Kubeconfig (artifacts/secrets/kubeconfig.yml bzw. die konfigurierte Quelle). kubernetes.core.k8s* und kubectl nutzen das automatisch.
Die Kubeconfig liegt typischerweise unter artifacts/secrets/kubeconfig.yml; Polycrate entschlüsselt sie bei Bedarf transparent (Details: Workspace-Verschlüsselung).
Für SSH wird dasselbe Secret-Handling genutzt (z.B. private SSH-Keys), ohne dass Sie externe Tools wie Vault integrieren müssen.

`polycrate ssh`: Hostauswahl mit Tab-Completion

Mit dieser Basis reicht:

polycrate ssh

Polycrate liest das Inventory, zeigt Ihnen die bekannten Hosts an und Sie können:

interaktiv einen Host auswählen oder
einfach polycrate ssh web-0<TAB> tippen, um per Tab-Completion zu web-01.acme-corp.com zu springen.

Kein Copy-Paste von IP-Adressen, keine Key-Suche, keine individuellen ~/.ssh/config-Varianten im Team.

Vergleich ohne Polycrate

Ohne Polycrate sieht das oft so aus:

lokal unterschiedliche SSH-Clients und Configs
Ketten von Nachrichten à la „Kannst du mir den SSH-Key für Prod schicken?“
manuelle ssh ubuntu@web-01.acme-corp.com-Befehle ohne einheitliches Logging

Mit Polycrate bringt das Inventory Struktur und polycrate ssh eine einheitliche UX – unabhängig davon, ob Sie Linux-Server, Windows-Hosts (über WinRM) oder Edge-Nodes verwalten. Die Details zur SSH-Integration finden Sie in der Polycrate SSH-Dokumentation.

SSH-Audit mit Polycrate API: Wer war wann auf welchem Host?

Aus Compliance-Sicht (z.B. ISO 27001 oder DSGVO, die am 25.05.2018 in Kraft getreten ist) reicht es nicht, „irgendwie“ auf Server zu kommen. Sie müssen nachweisen können:

Wer hat wann eine SSH-Session gestartet?
Auf welchen Host?
Wie lange lief die Session?
Wie endete sie (Exit-Code)?

Polycrate protokolliert jede polycrate ssh-Session und stellt diese Daten über die Polycrate API bereit:

Session-Start-Zeitpunkt
Session-Ende
Dauer
Benutzer (z.B. via SSO-Integration)
Zielhost
Exit-Code

Damit wird aus „Admin war auf dem Server“ ein sauberer Audit-Trail.

Abfragen über die Polycrate API

Die Details zur API sind in der Polycrate API-Dokumentation beschrieben. Typische Use-Cases:

Täglicher Export aller Prod-SSH-Sessions ins SIEM
Ad-hoc-Analyse: „Wer war zwischen 02:00 und 03:00 Uhr auf k8s-node-01?“
Nachvollziehbarkeit bei Security-Incidents

Statt verstreuter SSH-Logins aus individuellen Terminals werden SSH-Zugriffe zu einem zentral steuerbaren und auswertbaren Prozess – ohne zusätzliche Bastelarbeit. Für Compliance-Verantwortliche ist das Gold wert, für Platform-Teams ein wichtiger Baustein einer modernen Platform Engineering-Strategie.

Interaktiv im Cluster: `polycrate k8s debug`

Neben wiederholbaren Block-Actions gibt es für ad-hoc-Arbeit direkt im Cluster den CLI-Befehl polycrate k8s debug. Er startet einen temporären Pod mit dem Polycrate-Image, verbindet Sie automatisch mit einer Shell im Pod und räumt danach wieder auf.

Laut Dokumentation passiert dabei im Wesentlichen:

ServiceAccount polycrate-admin im Ziel-Namespace (falls nicht vorhanden)
ClusterRoleBinding mit cluster-admin-Rechten für diesen ServiceAccount
Pod mit dem Polycrate-Image; anschließend Attach zur interaktiven Shell
Nach exit wird der Pod gelöscht

Die Kubeconfig kommt wie bei allen Kubernetes-Funktionen aus dem Workspace (typisch artifacts/secrets/kubeconfig.yml). Im Pod stehen dieselben Tools wie im lokalen Polycrate-Container zur Verfügung (kubectl, helm, ansible, …); Details: Debug-Pod und CLI-Referenz polycrate k8s debug.

# Standard-Namespace kube-system (per -n anpassbar)
polycrate k8s debug

polycrate k8s debug -n default

Sicherheit (laut Dokumentation): Der Debug-Pod arbeitet mit cluster-admin. Nur in vertrauenswürdigen Umgebungen nutzen; Details im Sicherheitshinweis unter Debug-Pod.

Abgrenzung: polycrate k8s debug ist die schnelle interaktive Session im Cluster. Die folgenden Block-Actions sind der wiederholbare, versionierte Weg für Logs, Events und strukturierte Checks im Team.

Kubernetes-Debugging als Block: `kubectl` und Ansible-Playbooks

SSH löst die Zugriffsseite. Für Kubernetes-Debugging braucht es zusätzlich:

konsistentes kubectl mit der richtigen Kubeconfig
wiederholbare Debug-Schritte, statt „kubectl-Befehle aus dem Gedächtnis“
Logs, Events und Status in strukturierter Form

Polycrate bündelt das im Block-Modell: derselbe Block, der deployt, kann auch Debugging-Actions enthalten.

Der Debug-Block: `blocks/registry.acme-corp.com/acme/ops/k8s-debug/block.poly`

Ein einfacher generischer Block (nach Push in eure Registry; name = vollständiger Registry-Pfad ohne Tag):

# blocks/registry.acme-corp.com/acme/ops/k8s-debug/block.poly
name: registry.acme-corp.com/acme/ops/k8s-debug
version: 0.1.0
kind: generic

config:
  namespace: "default"
  app_label: "app=myapp"

actions:
  - name: kubectl
    command: |
      kubectl -n "{{ block.config.namespace }}" {{ action.args | default('get pods') }}

  - name: debug
    playbook: debug.yml

Wesentliche Punkte:

Die Toolchain (kubectl, Python, Ansible) läuft im Polycrate-Container – kein lokales Setup nötig.
kubectl nutzt dieselbe Umgebung wie Ansible: KUBECONFIG zeigt auf die Workspace-Kubeconfig – kein --kubeconfig in der Action nötig.
Action kubectl erlaubt schnelle Abfragen (polycrate run k8s-debug kubectl -- get pods).
Action debug startet ein Ansible-Playbook, das Logs, Events und Pod-Status einsammelt.

Konkrete Werte wie namespace und app_label setzen Sie pro Workspace im config-Block der Block-Instanz (siehe workspace.poly oben), nicht nur in der block.poly des Blocks.

Best Practices zur Block-Struktur finden Sie in den Polycrate Best Practices und in der Übersicht zu Blöcken.

Debug-Playbook mit `kubernetes.core.k8s_log` und `k8s_info`

Das Ansible-Playbook debug.yml liegt im selben Verzeichnis wie die block.poly:

# blocks/registry.acme-corp.com/acme/ops/k8s-debug/debug.yml
- name: Kubernetes Debugging für eine Anwendung
  hosts: localhost
  connection: local
  gather_facts: false

  vars:
    namespace: "{{ block.config.namespace }}"
    app_label: "{{ block.config.app_label }}"

  tasks:
    - name: Pods zur Anwendung ermitteln
      kubernetes.core.k8s_info:
        api_version: v1
        kind: Pod
        namespace: "{{ namespace }}"
        label_selectors:
          - "{{ app_label }}"
      register: pod_info

    - name: Gefundene Pods anzeigen
      ansible.builtin.debug:
        var: pod_info.resources

    - name: Logs des ersten Pods ausgeben
      when: pod_info.resources | length > 0
      kubernetes.core.k8s_log:
        namespace: "{{ namespace }}"
        name: "{{ pod_info.resources[0].metadata.name }}"
      register: pod_logs

    - name: Pod-Logs anzeigen
      when: pod_info.resources | length > 0
      ansible.builtin.debug:
        var: pod_logs.logs

    - name: Events im Namespace abrufen
      kubernetes.core.k8s_info:
        api_version: v1
        kind: Event
        namespace: "{{ namespace }}"
      register: ns_events

    - name: Relevante Events (nur Warning) filtern
      ansible.builtin.set_fact:
        warning_events: >-
          {{ ns_events.resources
             | selectattr('type', 'defined')
             | selectattr('type', 'equalto', 'Warning')
             | list }}

    - name: Warning-Events anzeigen
      ansible.builtin.debug:
        var: warning_events

Wichtig:
hosts: localhost ist hier korrekt, weil das Playbook nicht auf einem Remote-Host arbeitet, sondern über das Kubernetes-API gegen den Cluster spricht. Es läuft im Polycrate-Container, der kubectl- und Ansible-Umgebung bereitstellt. Details zur Anbindung von Ansible an Polycrate finden Sie in der Ansible-Integration.

Debug-Szenario 1: Pod crasht immer wieder

Typische Situation: Das Deployment ist durch, aber der Pod geht sofort in CrashLoopBackOff.

Mit Polycrate:

# Überblick über Pods im Namespace
polycrate run k8s-debug kubectl -- get pods -o wide

# Standard-Debug-Playbook ausführen
polycrate run k8s-debug debug

Ergebnis:

k8s_info listet alle Pods mit Label app=payments-api
k8s_log holt die Logs des ersten Pods
k8s_info zieht alle Events im Namespace, gefiltert auf Warning

Mit einem Befehl erhalten Sie Logs und Events in strukturierter Form – wiederholbar, versioniert im Block und mit der Sicherheit, dass immer die richtige Kubeconfig genutzt wird.

Debug-Szenario 2: Service nicht erreichbar

Der Service payments-api ist in Kubernetes als ClusterIP verfügbar, aber die Anwendung wirkt „down“.

Mögliche Workflow-Schritte, alle als Actions im Block abbildbar:

# Pods checken
polycrate run k8s-debug kubectl -- get pods -l app=payments-api -o wide

# Events checken
polycrate run k8s-debug debug

# Service und Endpoints checken
polycrate run k8s-debug kubectl -- get svc,ep -l app=payments-api

Weil das Ganze in einem Block steckt, können Sie diesen Debug-Block in eine OCI-Registry pushen (z. B. fiktiv registry.acme-corp.com, öffentlich cargo.ayedo.cloud) und über PolyHub mit anderen Teams teilen. Sharable Automation gilt nicht nur für Deployments, sondern auch für Operations-Workflows.

Lifecycle-Argument: Vom Install bis zum Debug – alles auditierbar

Viele Toolchains unterscheiden zwischen „Deployment“ und „Operations“. Das führt oft zu:

anderen Tools
anderen Log-Pfaden
fehlenden Audit-Trails bei manuellen Eingriffen

Polycrate zieht diese Phasen zusammen:

Installation / Provisionierung – klassische Ansible-Playbooks in Blöcken, die via polycrate run ausgeführt werden.
Änderungen / Deployments – ebenfalls als Actions oder Workflows im Workspace definiert.
Live-Debugging / Incident Response – polycrate ssh und Debug-Actions im selben Workspace, mit denselben Inventories, Secrets und Audit-Funktionen.

Weil alle Aktionen in einem containerisierten Kontext laufen, entfällt das lokale Dependency-Chaos:

Kein „Auf meinem Laptop ist Ansible 2.9, bei dir 2.15“
Keine unterschiedlichen kubectl-Versionen und Kontexte
Geringere Supply-Chain-Risiken, da die Toolchain im Container definiert ist (über Dockerfile.poly oder ein Setup-Script)

Das Block-Modell fungiert nebenbei als Guardrail: statt wild verstreuter Playbooks und Shell-Skripte haben Sie klar definierte Actions („deploy“, „patch“, „debug“, „logs“), die auch von weniger tief technischen Kolleg:innen sicher ausgeführt werden können.

Häufige Fragen

Wie unterscheidet sich `polycrate ssh` von einem normalen `ssh`?

polycrate ssh nutzt das im Workspace definierte Inventory (inventory.yml) und die darin gepflegten Verbindungsparameter (z.B. ansible_user) und Secrets. Sie müssen keine Hostnamen oder IPs manuell tippen, keine individuellen SSH-Configs pflegen und keine Zugänge per Chat teilen.
Zusätzlich werden alle Sessions über die Polycrate API protokolliert – mit Benutzer, Host, Start-/Endzeit, Dauer und Exit-Code. Das ist mit einem reinen ssh-Befehl so nicht abbildbar, ohne zusätzliche Eigenentwicklung.

Kann ich meine bestehenden kubectl- und Ansible-Skripte weiterverwenden?

Ja. Polycrate verpackt bestehende Playbooks und Skripte in Blöcke und Actions. Sie definieren, welche Playbooks oder Commands unter welchem Action-Namen laufen. Das Deployment-Playbook bleibt das gleiche, Sie gewinnen aber:

eine konsistente, containerisierte Umgebung (kein lokales Setup nötig)
einheitliche Ausführung über polycrate run BLOCK ACTION
die Möglichkeit, dieselben Blöcke über Registries mit anderen Teams zu teilen

Bestehende kubectl-One-Liner können Sie z.B. als command-Actions im Block unterbringen.

Wie passt das zu meiner bestehenden Platform- oder DevOps-Strategie?

Polycrate ergänzt etablierte CI/CD- und Plattform-Ansätze, statt sie zu ersetzen. Die Stärke liegt darin, dass Deployments, Betriebsaufgaben und Debugging:

dieselben Workspaces, Inventories und Secrets nutzen
durch das Block-Modell strukturiert und versioniert sind
über die Polycrate API auswertbar und automatisierbar werden

Gerade im Kontext von Platform Engineering hilft Polycrate dabei, standardisierte, aber flexible Runbooks bereitzustellen – inklusive klarer Guardrails und Audit-Trails.

Weitere Fragen? Siehe unsere FAQ

Von der Theorie zur Umsetzung

In diesem Beitrag haben Sie gesehen, wie Polycrate als Operations-Werkzeug funktioniert:

polycrate ssh macht Zugriffe auf Server und Nodes reproduzierbar und auditierbar, ohne dass Sie lokale SSH-Configs und Credentials manuell verwalten müssen.
polycrate k8s debug startet bei Bedarf einen interaktiven Debug-Pod mit dem Polycrate-Image für schnelle Arbeit direkt im Cluster.
Kubernetes-Debugging wird durch Blöcke, Actions und Ansible-Playbooks mit kubernetes.core.k8s_log und k8s_info zu einem klar definierten Prozess, der im Team geteilt und weiterentwickelt werden kann.
Die containerisierte Toolchain und das Block-Modell sorgen dafür, dass Deployments, Debugging und Compliance-Nachweise auf derselben Grundlage aufsetzen – ohne lokales Versions-Chaos.

Wenn Sie diese Konzepte in Ihrer eigenen Umgebung umsetzen möchten, begleiten wir Sie dabei: von der ersten Polycrate-Evaluierung über das Design Ihrer Workspaces und Blöcke bis hin zu einer integrierten Platform Engineering-Lösung, die Operations und Compliance zusammendenkt.

Der nächste Schritt ist einfach: Vereinbaren Sie eine persönliche Session, in der wir Ihre aktuelle Landschaft anschauen und gemeinsam ein passendes Setup skizzieren.
Workshops