Zum Inhalt

API-Integration

Polycrate unterstützt die Integration mit dem PolyHub über eine HTTP-API. Diese Integration ermöglicht es, Action-Ergebnisse zu übermitteln, Workspace-Daten zu synchronisieren und weitere Cloud-Features zu nutzen.

API-Konfiguration

Die API-Integration kann über Flags oder die Workspace-Konfiguration aktiviert werden.

Globale API-Flags

# API aktivieren
polycrate run my-block install --api-enabled

# API-URL festlegen
polycrate run my-block install --api-url https://hub.polycrate.io

# API-Key für Authentifizierung
polycrate run my-block install --api-api-key <your-api-key>

# Action-Ergebnisse übermitteln (Standard: true)
polycrate run my-block install --api-submit-action-runs

Workspace-Konfiguration

Sie können die API-Integration auch in Ihrer workspace.poly konfigurieren:

name: my-workspace

api:
  enabled: true
  url: https://hub.polycrate.io
  api_key: ${API_KEY}  # Aus Umgebungsvariable
  submit_action_runs: true
  validate_workspace_on_load: false

API-Features

Action-Ergebnisse übermitteln

Wenn --api-submit-action-runs aktiviert ist (Standard), werden die Ergebnisse jeder Action-Ausführung an die API übermittelt. Dies ermöglicht:

  • Zentrale Überwachung von Action-Ausführungen
  • Historie und Audit-Trail
  • Fehleranalyse und Reporting

Workspace Encryption Key Management

Die API verwaltet zentral die Encryption Keys für verschlüsselte Workspaces. Dies ist die empfohlene Lösung für Teams.

Funktionsweise:

  1. Automatischer Key-Abruf: Die CLI fragt den Workspace Encryption Key automatisch von der API ab
  2. Höchste Priorität: API-Keys überschreiben lokale Umgebungsvariablen
  3. Workspace-spezifisch: Jeder Workspace erhält seinen eigenen Encryption Key
  4. Team-Sharing: Alle Teammitglieder mit API-Zugang können den Workspace entschlüsseln

Credential-Typen:

Die API speichert Encryption Keys als Workspace Credentials mit folgenden Eigenschaften:

  • Kind: workspace-encryption
  • Private Key (ssh_private_key): age Secret Key für Ver-/Entschlüsselung
  • Public Key (ssh_public_key): age Public Key (automatisch abgeleitet)
  • State: READY, PENDING oder ERROR

Beispiel-Workflow:

# 1. API konfigurieren
cat > ~/.polycrate/polycrate.yml << EOF
api:
  enabled: true
  url: https://hub.polycrate.io
  api_key: your-api-key
EOF

# 2. Workspace verschlüsseln (Key wird von API geholt)
polycrate workspace encrypt

# 3. Teammitglied klont Repository
git clone <repo>
cd workspace

# 4. Workspace entschlüsseln (Key wird automatisch von API geholt)
polycrate workspace decrypt

Vorteile:

  • ✅ Kein manuelles Key-Sharing erforderlich
  • ✅ Zentrale Key-Rotation möglich
  • ✅ Audit-Logging aller Key-Zugriffe
  • ✅ Automatisches State-Tracking

Für Details siehe Workspace-Verschlüsselung.

Workspace-Validierung

Mit --api-validate-workspace-on-load wird der Workspace beim Laden gegen die API validiert:

polycrate run my-block install --api-validate-workspace-on-load

Dies prüft:

  • Ob alle Blocks in der API registriert sind
  • Ob die verwendeten Versionen kompatibel sind
  • Ob Sicherheitsupdates verfügbar sind

API-Informationen anzeigen

polycrate api

Zeigt aktuelle API-Konfiguration und Verbindungsstatus an.

PolyHub-Integration

Der PolyHub unter hub.polycrate.io ist die offizielle API-Implementierung von Polycrate.

Authentifizierung

Sie können sich mit Benutzername/Passwort oder API-Key authentifizieren:

# Mit API-Key
polycrate hub inspect ayedo/k8s/cluster --hub-api-key <your-key>

# Mit Benutzername/Passwort
polycrate hub inspect ayedo/k8s/cluster --hub-username user --hub-password pass

Hub-Befehle

# Block-Informationen aus dem Hub abrufen
polycrate hub inspect <block-name>

Beispiel: 

polycrate hub inspect ayedo/k8s/cluster
# Zeigt: Beschreibung, verfügbare Versionen, Actions, Dependencies, etc.

Umgebungsvariablen

Für sensible Daten wie API-Keys empfiehlt sich die Verwendung von Umgebungsvariablen:

export POLYCRATE_API_KEY="your-api-key"
export POLYCRATE_API_URL="https://hub.polycrate.io"

polycrate run my-block install --api-enabled

Sicherheit

  • API-Keys sollten niemals in der Workspace-Konfiguration gespeichert werden
  • Verwenden Sie Umgebungsvariablen oder sichere Secret-Management-Lösungen
  • Bei verschlüsselten Workspaces können API-Keys in der verschlüsselten Konfiguration gespeichert werden

CLI-Referenz

Für eine vollständige Übersicht aller CLI-Befehle siehe: