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 wird global in der Polycrate-Konfigurationsdatei ($HOME/.polycrate/polycrate.yml) oder über CLI-Flags/Umgebungsvariablen konfiguriert – nicht im Workspace.

Globale Konfigurationsdatei (empfohlen)¶

Erstellen oder bearbeiten Sie ~/.polycrate/polycrate.yml:

# ~/.polycrate/polycrate.yml
api:
  enabled: true
  url: https://hub.polycrate.io
  api_key: <your-api-key>
  submit_action_runs: true
  validate_workspace_on_load: false

CLI-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
polycrate run my-block install --api-submit-action-runs

Umgebungsvariablen¶

export POLYCRATE_API_ENABLED=true
export POLYCRATE_API_URL=https://hub.polycrate.io
export POLYCRATE_API_API_KEY=<your-api-key>
export POLYCRATE_API_SUBMIT_ACTION_RUNS=true

Konfiguration anzeigen¶

# Aktuelle API-Konfiguration und Status anzeigen
polycrate api

API-Features¶

ActionRun Submission¶

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

# Standard: Aktiviert
polycrate run my-block install

# Explizit deaktivieren
polycrate --no-api-submit-action-runs run my-block install

Übermittelte Daten:

Features:

• Fail-Safe Design: API-Fehler blockieren niemals erfolgreiche Actions
• Retry-Logic: Automatische Wiederholungen mit exponential Backoff
• Offline-tolerant: Bei Netzwerkproblemen läuft die Action trotzdem durch

Use Cases:

• Zentrale Überwachung aller Action-Ausführungen im Team
• Historie und Audit-Trail für Compliance
• Fehleranalyse und Reporting
• Deployment-Tracking über alle Workspaces

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

API Endpoint Monitoring Agent¶

Der Polycrate Monitoring Agent überwacht HTTP- und ICMP-Endpoints kontinuierlich und meldet Ergebnisse an die API.

Agent starten¶

polycrate api agent \
  --agent-token "your-agent-token" \
  --max-concurrent-checks 10

Optionen:

Features¶

Ablauf¶

graph LR
    Agent[Polycrate Agent] -->|1. Endpoints abrufen| API[Polycrate API]
    Agent -->|2. Checks durchführen| Endpoints[HTTP/ICMP Endpoints]
    Endpoints -->|3. Ergebnisse| Agent
    Agent -->|4. Results senden| API

1. Agent ruft zu prüfende Endpoints von der API ab
2. Führt konfigurierte Checks durch (HTTP, ICMP)
3. Sammelt Ergebnisse (Status, Latenz, Fehler)
4. Übermittelt Ergebnisse an API

Use Cases¶

• Uptime-Monitoring: Überwachung von Produktions-Services
• Multi-Region-Checks: Agents in verschiedenen Regionen
• Alerting: API kann bei Ausfällen alarmieren
• SLA-Tracking: Erfassung von Verfügbarkeitsdaten

Beispiel: Systemd-Service¶

# /etc/systemd/system/polycrate-agent.service
[Unit]
Description=Polycrate Monitoring Agent
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/polycrate api agent --agent-token "$TOKEN"
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl enable polycrate-agent
sudo systemctl start polycrate-agent

CLI Instance Tracking¶

Polycrate trackt automatisch alle CLI-Installationen pro Benutzer. Bei jeder ActionRun-Submission werden Informationen über die CLI-Installation erfasst und mit der API synchronisiert.

Funktionsweise¶

Bei jedem ActionRun werden folgende Daten automatisch übermittelt:

Unique Identification¶

Jede CLI-Installation wird eindeutig identifiziert durch die Kombination:

(user, hostname, os, arch)

Wenn Sie die CLI auf mehreren Maschinen oder in verschiedenen VMs/Containern nutzen, wird jede als separate Installation getrackt.

Version-Tracking¶

Das System erkennt automatisch CLI-Updates:

• current_version: Die aktuell verwendete CLI-Version
• last_version: Die zuvor verwendete Version (vor dem Update)
• first_seen: Wann die Installation erstmals registriert wurde
• last_seen: Wann die Installation zuletzt aktiv war

Benutzeroberfläche¶

Die CLI-Installationen können in der Polycrate Web-UI eingesehen werden:

Pfad: Account → Settings → CLI Installations

Die Übersicht zeigt:

• Alle registrierten CLI-Installationen
• Aktuelle und vorherige Versionen
• Letzte Aktivität pro Installation
• Anzahl der ActionRun-Submissions

Datenschutz¶

• CLI-Installationen sind nur für den jeweiligen Benutzer sichtbar
• Administratoren können alle Installationen für Support-Zwecke einsehen
• Daten können auf Anfrage gelöscht werden (DSGVO)

Deaktivierung¶

Das CLI Instance Tracking ist an ActionRun Submissions gekoppelt. Wenn Sie ActionRun Submissions deaktivieren, werden auch keine CLI-Installations-Daten übermittelt:

polycrate --no-api-submit-action-runs run my-block install

CLI-Referenz¶

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

• CLI-Referenz - Vollständige Dokumentation aller Befehle
• PolyHub - Mehr über den PolyHub
• Konfiguration - Workspace-Konfiguration