Polycrate 0.28.0¶

Veröffentlicht am: 2025-12-14

Highlights¶

Polycrate 0.28.0 ist ein umfangreiches Release mit zahlreichen neuen Features: Kubernetes Operator für Multi-Tenant-Management, Block Security Scanning mit SBOM-Generierung und IaC-Vulnerability-Detection (Checkov, Trivy, Syft/Grype), Verschlüsseltes Secret-Management, MCP-Server-Integration für AI-Assistenten, Kubernetes-Debugging, erweiterte Hub-Commands mit TUI, Workspace List mit API-Integration (Remote-Workspaces, UI-Browser-Öffnung), Git-Integration ohne externe Abhängigkeiten, Docker Native Mode, interaktive Dependency-Auflösung, TUI-Pager für Inspect-Commands, und vieles mehr.

Artefakte¶

Docker Images¶

# Multi-arch Image (linux/amd64, linux/arm64)
docker pull cargo.ayedo.cloud/library/polycrate:0.28.0
docker pull cargo.ayedo.cloud/library/polycrate:latest

CLI Downloads¶

Installation & Update¶

# Bestehende Installation aktualisieren
polycrate update 0.28.0

# Neuinstallation
curl -sSL https://hub.polycrate.io/get/polycrate/0.28.0/$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/' | sed 's/aarch64/arm64/')/polycrate_0.28.0_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/' | sed 's/aarch64/arm64/').tar.gz | sudo tar -xz -C /usr/local/bin/

→ Installationsanleitung | Update-Anleitung

Neue Features¶

Workspace Encryption & Secret Management¶

Polycrate bietet jetzt ein robustes Secret-Management-System mit age-Verschlüsselung:

Features:

• secrets.poly: Separate Datei für sensitive Block-Konfiguration mit Deep-Merge
• Artifact Secrets: Verschlüsselte Files in artifacts/secrets/ (workspace- und block-spezifisch)
• API-Integration: Automatischer Key-Abruf von der Polycrate API
• Keine Key-Datei im Workspace: Keys nur via API, Umgebungsvariable oder Prompt

Neue Commands:

# Workspace-Secrets verschlüsseln
polycrate workspace encrypt

# Workspace-Secrets entschlüsseln
polycrate workspace decrypt

# Encryption-Status anzeigen
polycrate workspace status

Verwendung in Ansible Playbooks:

Die entschlüsselten Secrets stehen in Ansible Playbooks über die workspace.secrets und block.secrets Dictionaries zur Verfügung:

# playbooks/deploy.yml
- name: Deploy to Kubernetes
  shell: kubectl --kubeconfig={{ workspace.secrets['kubeconfig.yml'] }} get pods

- name: Connect to Database
  shell: mysql -p{{ block.secrets['database_password'] }} -h localhost

→ Ausführliche Dokumentation

Kubernetes Operator¶

Polycrate enthält jetzt einen integrierten Kubernetes Operator, der automatisch Cluster-Ressourcen erkennt und mit der Polycrate API synchronisiert. Dies ermöglicht eine zentrale Übersicht über Endpoints, Zertifikate, Backups, Container-Images und deployten Anwendungen.

Hauptfunktionen:

• Resource Discovery: Automatische Erkennung von Ingresses, Certificates, Backups, Pods und Polycrate Blocks
• API-Synchronisation: Alle erkannten Ressourcen werden mit der Polycrate API synchronisiert
• Endpoint-Monitoring: Health-Checks für Endpoints im eigenen Cluster sowie global über die API
• Prometheus-Metriken: Export von Monitoring-Daten für VictoriaMetrics/Prometheus
• Change Detection: Hash-basierte Änderungserkennung verhindert unnötige API-Updates
• Finalizer-basiertes Cleanup: API-Objekte werden bei K8s-Deletion automatisch entfernt

Custom Resource Definitions (Discovery):

Neue CLI-Commands:

# CRDs ins Cluster installieren
polycrate operator install-crds

# CRD-Definitionen ausgeben
polycrate operator crds

# Operator starten
polycrate operator run --kubeconfig ~/.kube/config

# Status aller Ressourcen anzeigen
polycrate operator status

# Health-Check
polycrate operator health

Discovery-Funktionalität:

Der Operator erkennt automatisch Kubernetes-Ressourcen und erstellt entsprechende Custom Resources, die mit der Polycrate API synchronisiert werden:

Alle Discovery-Controller erstellen Custom Resources mit Owner-Reference für automatisches Cleanup. Finalizer stellen sicher, dass API-Objekte bei K8s-Deletion automatisch entfernt werden.

Prometheus-Metriken:

Der Operator exportiert Monitoring-Metriken im Prometheus-Format. Diese können von VictoriaMetrics Agent oder Prometheus selbst aufgesammelt werden:

# Metriken-Endpoint
curl http://localhost:8080/metrics

→ Ausführliche Dokumentation

Certificate Discovery (cert-manager Integration)¶

Der Operator erkennt automatisch TLS-Zertifikate von cert-manager und synchronisiert sie mit der API:

Erkannte Felder aus cert-manager Certificate:

Certificate CRD Status:

status:
  phase: "Synced"  # Ready, Issuing, Failed
  api_id: "uuid-..."
  issuer_ready: true
  certificate_ready: true
  not_after: "2026-03-15T00:00:00Z"
  renewal_time: "2026-02-13T00:00:00Z"
  conditions:
    - type: Ready
      status: "True"
      reason: "Issued"

Beispiel: Erkanntes Zertifikat

$ kubectl get certificates -A
NAMESPACE   NAME              SECRET            ISSUER          READY   AGE
prod        api-example-com   api-tls           letsencrypt     True    30d
prod        web-example-com   web-tls           letsencrypt     True    15d

K8sApp Discovery (Deployed Blocks)¶

Der Operator erkennt automatisch deployte Polycrate Blocks anhand der Meta-Secrets (*.poly):

K8sApp CRD Features:

• Block-Metadaten: Name, Version, App-Version, Source, Type, Flavor
• Helm-Chart-Informationen: Chart-Name, Version, Repo-URL
• Workspace-Kontext: Workspace-Name und Organization
• Installation-Status: Ableitung aus Action-Name/Status
• Artifact-Verknüpfung: Liste der verwendeten Container-Images

Beispiel: K8sApp anzeigen

$ kubectl get k8sapps -A
NAMESPACE   NAME             BLOCK            VERSION   ARTIFACTS   PHASE    AGE
prod        nginx-ingress    nginx-ingress    1.2.0     3           Synced   7d
prod        redis            redis            7.2.0     1           Synced   14d
staging     authentik        authentik        2024.8    5           Synced   3d

$ kubectl describe k8sapp nginx-ingress -n prod
Name:         nginx-ingress
Namespace:    prod
Spec:
  Block:
    Name:           nginx-ingress
    Display Name:   NGINX Ingress Controller
    Version:        1.2.0
    App Version:    1.9.6
    From:           cargo.ayedo.cloud/ayedo/k8s/nginx-ingress
    Type:           ingress-controller
  Workspace:
    Name:           production
    Organization:   acme-corp
Status:
  Phase:         Synced
  Installed:     true
  Artifacts:
    - Name:   cargo-ayedo-cloud-library-nginx-1-25-3
      Image:  cargo.ayedo.cloud/library/nginx:1.25.3
      Pod Count: 3

Artifact Discovery (Container Images)¶

Der Operator trackt automatisch alle Container-Images im Cluster:

Features:

• Cluster-weit: Artifacts sind cluster-scoped (nicht namespace-gebunden)
• Image-Parsing: Vollständige Auflösung von Registry, Repository, Tag/Digest
• Namespace-Tracking: Welche Namespaces nutzen welches Image?
• K8sApp-Verknüpfung: Bidirektionale Referenz zwischen K8sApp und Artifacts

Beispiel: Artifacts anzeigen

$ kubectl get artifacts
NAME                                      IMAGE                                      PODS   PHASE
cargo-ayedo-cloud-library-nginx-1-25-3    cargo.ayedo.cloud/library/nginx:1.25.3    5      Discovered
docker-io-library-redis-7-2               redis:7.2                                  2      Discovered
ghcr-io-cert-manager-controller-v1-14     ghcr.io/cert-manager/controller:v1.14     1      Discovered

OperatorConfig für Artifact Discovery:

spec:
  artifact_discovery:
    enabled: true
    ignore_namespaces:
      - kube-system
      - kube-public
    exclude_registries:
      - registry.k8s.io  # System-Images ignorieren
    cleanup:
      enabled: true
      stale_threshold_hours: 1  # Nach 1h ohne Pods löschen

→ Ausführliche Dokumentation | CLI-Referenz

MCP Server Integration¶

Die CLI enthält jetzt einen integrierten MCP-Server (Model Context Protocol), der AI-Assistenten direkten Zugriff auf den Polycrate Hub und die Dokumentation ermöglicht.

Use Cases:

• Workspace-Entwicklung mit AI: Beim Entwickeln neuer Workspaces kann der AI-Assistent das Hub nach passenden Blöcken durchsuchen. Frage einfach: "Welche Blöcke gibt es für Kubernetes-Deployments?" oder "Zeige mir Blöcke für Authentifizierung"
• Block-Discovery: Der Assistent kann verfügbare Blöcke, deren Versionen und Dokumentation abrufen, ohne dass du das Hub manuell durchsuchen musst
• Schema-Spezifikationen: AI-Assistenten können die Schemas für workspace.poly, block.poly, secrets.poly und CHANGELOG.poly abrufen um korrekte Konfigurationen zu generieren
• Dokumentationsabfragen: Der Assistent kann die offizielle Polycrate-Dokumentation von docs.ayedo.de abrufen und kontextbezogen zitieren

Verfügbare Tools:

Beispiel-Interaktion mit AI:

Du: "Ich brauche einen Block für PostgreSQL-Deployments auf Kubernetes"

AI: [nutzt hub_list_blocks mit Filter "postgres"]
    "Im Hub gibt es den Block 'cargo.ayedo.cloud/ayedo/k8s-apps/postgres' 
     in Version 1.2.0. Er unterstützt..."
    [nutzt hub_inspect_block für Details]

Cursor-Konfiguration (~/.cursor/mcp.json):

{
  "mcpServers": {
    "polycrate": {
      "command": "polycrate",
      "args": ["mcp"]
    }
  }
}

Claude Desktop-Konfiguration (~/Library/Application Support/Claude/claude_desktop_config.json auf macOS):

{
  "mcpServers": {
    "polycrate": {
      "command": "polycrate",
      "args": ["mcp"]
    }
  }
}

Auf Linux liegt die Datei unter ~/.config/Claude/claude_desktop_config.json.

GitHub Copilot-Konfiguration (.vscode/mcp.json im Workspace):

{
  "servers": {
    "polycrate": {
      "command": "polycrate",
      "args": ["mcp"]
    }
  }
}

→ Ausführliche Dokumentation

Hub Commands¶

Neue Commands zum Arbeiten mit dem Polycrate Hub:

# Alle verfügbaren Blöcke anzeigen
polycrate hub list

# Nach Name filtern
polycrate hub list --filter authentik

# Nach Kind filtern
polycrate hub list --kind k8sapp

# Block-Details anzeigen
polycrate hub inspect ayedo/k8s/authentik

# Block-Versionen anzeigen
polycrate hub versions ayedo/k8s/authentik

→ Ausführliche Dokumentation | CLI-Referenz

Kubernetes Debug Command¶

Starte einen temporären Debug-Pod mit Polycrate-Image und cluster-admin Rechten:

# Standard: kube-system Namespace
polycrate k8s debug -w my-workspace

# Custom Namespace
polycrate k8s debug -w my-workspace --namespace monitoring

# Mit PVC-Mounts
polycrate k8s debug -w my-workspace -m data-pvc:/data -m logs-pvc:/var/log

Features:

• Automatisches ServiceAccount-Setup mit cluster-admin Rechten
• PVC-Mount-Support für Datenzugriff
• Automatisches Cleanup bei Exit
• TTY-Session mit sofortigem Shell-Prompt

→ Ausführliche Dokumentation | CLI-Referenz

SSH Passphrase Support¶

Unterstützung für SSH-Keys mit Passphrase über ssh-agent:

# SSH-Passphrase-Support beim Init aktivieren
polycrate --ssh-use-passphrase workspace init

# Für bestehende Workspaces
polycrate --ssh-use-passphrase action run deploy

Passphrase-Quellen (Priorität):

1. Keyfile: $WORKSPACE_ROOT/ssh-passphrase.poly
2. User-Prompt: Interaktive Eingabe

Der ssh-agent wird automatisch gestartet und der Socket in Docker-Container gemountet.

→ Ausführliche Dokumentation

Workspace List Command¶

Interaktive TUI zum Browsen und Verwalten von Workspaces – jetzt mit API-Integration:

# API-Workspaces (Standard, oder Fallback auf lokal)
polycrate workspace list

# Explizit lokale Workspaces
polycrate workspace list --local

# Mit Vorfilter
polycrate workspace list --filter production

# Tabellenausgabe ohne TUI
polycrate workspace list --no-pager

# Detaillierte Tabellenausgabe (lokal)
polycrate workspace list --local --no-pager -v

Modus-Entscheidung:

TUI-Navigation:

Action-Menü (Remote/API):

• open – Workspace in der Polycrate UI öffnen (Browser)
• gitlab – GitLab-Repository im Browser öffnen
• clone – Repository lokal klonen

Action-Menü (Lokal):

• open – Workspace-Details und Pfad anzeigen
• status – Workspace-Status abrufen
• git-sync – Git-Änderungen synchronisieren

Angezeigte Informationen (Lokal):

• Name und Organization
• Encryption-Status (🔒)
• Git-Branch, Commit, Status (clean/dirty)
• Letzter Autor und letzte Änderung

Angezeigte Informationen (Remote):

• Name und Organization
• State (READY, DEGRADED, DOWN)
• UI-URL zur Polycrate Weboberfläche

→ Ausführliche Dokumentation | CLI-Referenz

Git Commands¶

Vereinfachte Git-Integration ohne externe Git-Installation (basiert auf go-git):

# Repository-Status
polycrate git status

# Dateien stagen
polycrate git add file.txt
polycrate git add --all

# Committen
polycrate git commit --message "feat: add feature"

# Push/Pull
polycrate git push
polycrate git pull

# Automatischer Sync-Workflow
polycrate git sync

Features:

• Farbige Status-Ausgabe
• Conflict-Erkennung VOR dem Pull
• Auto-Stage und Auto-Commit
• Spinner während Push/Pull

→ Ausführliche Dokumentation | CLI-Referenz

Workspace Git-Aliase¶

Alle Git-Commands sind nun auch als polycrate workspace * Aliase verfügbar:

# Äquivalente Commands:
polycrate workspace pull    # = polycrate git pull
polycrate workspace push    # = polycrate git push
polycrate workspace sync    # = polycrate git sync
polycrate workspace add     # = polycrate git add
polycrate workspace commit  # = polycrate git commit

Diese Aliase ermöglichen eine intuitivere UX, bei der alle Workspace-bezogenen Operationen unter polycrate workspace verfügbar sind.

→ CLI-Referenz

CLI Instance Tracking¶

Polycrate trackt jetzt automatisch alle CLI-Installationen pro User:

Features:

• Automatische Registrierung: Bei jedem ActionRun wird die CLI-Installation automatisch erfasst
• Machine-Identifikation: Hostname, OS, Architektur, Git- und Docker-Version
• Version-Tracking: Aktuelle und vorherige CLI-Version mit Update-History
• User Interface: Neuer Tab "CLI Installations" in den Account-Einstellungen

Tracking-Daten:

Unique Key: Jede Kombination aus (user, hostname, os, arch) wird als separate Installation getrackt.

→ Ausführliche Dokumentation

ActionRun API Submission¶

Action-Run-Ergebnisse werden automatisch an die Polycrate API übermittelt:

# Aktiviert über Konfiguration
polycrate run block action  # Results werden automatisch submitted

# Deaktivieren
polycrate --no-api-submit-action-runs run block action

Features:

• Fail-Safe Design: API-Fehler blockieren niemals erfolgreiche Actions
• Retry-Logic mit exponential Backoff
• Detailliertes Metadata (CLI-Version, Host, OS, Duration)

→ Ausführliche Dokumentation

Endpoint Path Support¶

HTTP-Endpoint-Checks unterstützen jetzt spezifische Pfade für Health-Checks:

Ingress-Annotation:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-api
  annotations:
    # Health-Check auf spezifischen Pfad
    endpoints.polycrate.io/path: "/api/health"
spec:
  rules:
    - host: api.example.com
      # ...

Features:

• Pfad wird bei jedem Reconciliation-Zyklus dynamisch gelesen
• Änderungen an der Annotation werden automatisch übernommen
• Default: / wenn keine Annotation gesetzt

Beispiele:

→ Ausführliche Dokumentation

Operator API-Authentifizierung¶

Der Kubernetes Operator kommuniziert mit der Polycrate API über den Workspace Agent Token:

Konfiguration:

apiVersion: polycrate.io/v1alpha1
kind: OperatorConfig
metadata:
  name: default
  namespace: polycrate
spec:
  api_sync:
    enabled: true
    api_url: "https://api.polycrate.io"
    credentials_ref:
      secret_name: polycrate-api-creds
      token_key: token  # Agent Token aus diesem Secret

Vorteile:

• Workspace-Isolation: Agent Token hat nur Zugriff auf den zugeordneten Workspace
• Keine User-Credentials: Kein persönlicher API-Key erforderlich
• Automatisches Scoping: Alle API-Operationen sind auf den Workspace beschränkt

Der Agent Token wird im Polycrate UI unter Workspace → Settings → Tokens generiert.

→ Ausführliche Dokumentation

Changelog Commands¶

Neue interaktive Commands zum Browsen von Changelogs:

# Workspace Changelog
polycrate workspace changelog

# Block Changelog
polycrate block changelog <block-name>

# Changelog-Format anzeigen
polycrate workspace changelog --spec

→ CLI-Referenz

Block Security Scanning¶

Polycrate enthält jetzt integriertes Security-Scanning für Blöcke mit SBOM-Generierung und Vulnerability-Detection:

Verfügbare Scanner:

Neue Commands:

# Block analysieren (Checkov für IaC-Security, Standard)
polycrate block analyze my-block

# Mit Trivy analysieren (Dependencies, Container)
polycrate block analyze my-block --tool trivy

# Mit Syft + Grype analysieren (Production)
polycrate block analyze my-block --tool syft

# Ergebnisse anzeigen
polycrate block sbom inspect my-block
polycrate block vulnerabilities inspect my-block
polycrate block vulns inspect my-block  # Alias

Output-Dateien:

TUI-Features:

• Interaktive Liste mit Filter-Suche
• YAML-Syntax-Highlighting
• vim-style Navigation (j/k, g/G)
• --no-pager für CI/CD-Pipelines

Beispiel: Ansible-Block scannen

$ polycrate block analyze hardening
◰ Analyzing block 'hardening'...
◰ Running checkov analysis...
✓ Analysis complete:
◰   Components: 0
◰   Vulnerabilities: 3 (1 HIGH, 2 MEDIUM)

$ polycrate block vulns inspect hardening
# Interaktive TUI mit allen Findings

→ Ausführliche Dokumentation | Integrationen

Docker Native Mode¶

Polycrate kann nun optional das Docker Go SDK direkt verwenden statt die Docker CLI aufzurufen:

# Via Flag
polycrate --docker-native run myblock install
polycrate -N run myblock install

# Via Umgebungsvariable
export POLYCRATE_DOCKER_NATIVE=true

# Via Konfigurationsdatei (~/.polycrate/config.yml)
# docker:
#   native: true

Vorteile:

• Keine Docker CLI Installation erforderlich
• Bessere Performance (keine Shell-Spawning)
• Typisierte Fehlerbehandlung statt Text-Parsing
• Podman-Kompatibilität über Docker API Socket

→ Ausführliche Dokumentation

Container Debug Command¶

Neues polycrate debug Command für interaktive Debug-Sessions im Container:

# Debug-Container starten
polycrate debug

# Mit zusätzlichen Mounts
polycrate debug -m /local:/container

# Mit Environment-Variablen
polycrate debug -e DEBUG=true

Startet den Polycrate-Container mit allen Mounts und Environment-Variablen wie bei einem Action Run, aber mit interaktiver Bash-Shell statt Action-Ausführung.

→ Ausführliche Dokumentation | CLI-Referenz

Interaktive Dependency-Auflösung¶

Beim Laden eines Workspaces mit fehlenden oder veralteten Block-Dependencies zeigt Polycrate einen interaktiven Prompt:

• [MISSING] - Block fehlt
• [UPGRADE] - Installierte Version älter als angefordert
• [DOWNGRADE] - Installierte Version neuer (mit Warnung)

Optionen im Prompt:

1. Install/Update all - Alle Abhängigkeiten automatisch auflösen
2. Solve manually - Zeigt benötigte Befehle

In CI/CD-Umgebungen wird automatisch eine detaillierte Fehlermeldung ausgegeben.

→ Ausführliche Dokumentation

TUI-Pager für Inspect-Commands¶

Inspect-Commands nutzen nun einen interaktiven TUI-Pager mit Scroll- und Suchfunktionen:

polycrate workspace inspect
polycrate block inspect <block>
polycrate action inspect <block>.<action>

Navigation:

Features:

• YAML-Syntax-Highlighting
• Such-Highlighting mit Match-Counter
• Back-Navigation mit Backspace
• Automatischer Fallback bei CI/Pipe

Deaktivieren mit --no-pager für direkten Output.

Neue Globale Flags¶

CI/CD-Erkennung¶

Polycrate erkennt automatisch CI/CD-Umgebungen und deaktiviert interaktive Features:

Erkannte Systeme:

• GitHub Actions, GitLab CI, Jenkins
• CircleCI, Travis CI, Drone CI
• Buildkite, TeamCity, Azure DevOps
• Bitbucket Pipelines

Verbesserungen¶

Build-Spinner für Custom Images¶

Beim Bauen von Custom-Images (via Dockerfile.poly) wird ein animierter Spinner angezeigt. Mit --loglevel 2 wird der vollständige Build-Output gestreamt.

Verbesserte git status Ausgabe¶

Farbige Status-Indikatoren ohne Emojis:

• new: (grün)
• modified: (gelb)
• deleted: (rot)
• renamed:/copied: (cyan)

Technische Details¶

age CLI Kompatibilität¶

Alle verschlüsselten Dateien nutzen das Standard age-Format und sind mit der age CLI kompatibel:

# Manuelle Entschlüsselung
echo "$KEY" | age --decrypt -i - secrets.poly.age > secrets.poly

Migration¶

Keine Änderungen erforderlich. Alle neuen Features sind optional und rückwärtskompatibel.

Bekannte Einschränkungen¶

• Workspace Encryption erfordert API-Zugang oder manuelles Key-Management