Polycrate API¶

Übersicht¶

Die Polycrate API ist die zentrale Web-Oberfläche und das Backend für die Verwaltung Ihrer gesamten Cloud-Infrastruktur. Sie erweitert die lokale Polycrate CLI um eine kollaborative, team-fähige Plattform mit Echtzeit-Überwachung, Alerting und zentraler Konfigurationsverwaltung.

graph TB
    subgraph ecosystem[Polycrate Ökosystem]
        CLI[Polycrate CLI]

        subgraph api[Polycrate API]
            API_UI[Web-Oberfläche]
            API_MON[Monitoring]
            API_ALERT[Alerting]
            API_COLLAB[Collaboration]
        end

        subgraph hub[Polycrate Hub]
            HUB_REG[Block-Registry]
            HUB_MARKET[Block-Marketplace]
            HUB_VER[Versionierung]
            HUB_DL[CLI-Downloads]
        end

        CLI -->|Reports| api
        CLI -->|Pull Blocks| hub
    end

Für wen ist die Polycrate API?¶

Die Polycrate API richtet sich an:

• Platform-Teams, die eine zentrale Übersicht über alle Workspaces und Deployments benötigen
• DevOps-Engineers, die Infrastruktur-Änderungen nachverfolgen und auditieren müssen
• Managed Service Provider, die mehrere Kundenumgebungen zentral verwalten
• Entwickler, die den Status ihrer Deployments im Team teilen wollen

Kernfunktionalitäten¶

Zentrale Infrastruktur-Übersicht¶

Alle Ihre Ressourcen auf einen Blick – vom Workspace bis zum einzelnen Bucket:

Alerting & Benachrichtigungen¶

Proaktive Überwachung Ihrer Infrastruktur:

• Echtzeit-Alerts bei Problemen mit Deployments, Hosts oder Services
• Flexible Notification-Kanäle: E-Mail, Webhook, Custom Integrations
• Alert-Policies: Regelbasierte Konfiguration von Alert-Bedingungen
• Alert-Aktionen: Bestätigen, Stummschalten, Schließen

Action-Run-Tracking¶

Vollständige Historie aller CLI-Ausführungen:

# CLI sendet automatisch Ergebnisse an die API
polycrate run database install --api-enabled

• Audit-Trail: Wer hat was, wann, wo ausgeführt?
• Exit-Codes & Logs: Erfolg oder Fehler auf einen Blick
• Dauer-Tracking: Performance-Analyse über Zeit
• Team-Visibility: Alle Teammitglieder sehen Deployment-Aktivitäten

Backup-Übersicht¶

Zentrale Read-Only-Ansicht aller Velero-Backups in Ihren Kubernetes-Clustern:

• Backup-Status-Dashboard: Übersicht aller Backups über alle Cluster
• Erfolgs-/Fehlerquoten: Schnelle Erkennung von Backup-Problemen
• Backup-Details: Größe, enthaltene Namespaces, Timestamps
• Alerts bei Problemen: Benachrichtigung wenn Backups fehlschlagen

Wartungsfenster¶

Geplante Wartungen zentral verwalten:

• Maintenance Windows definieren und planen
• Automatische Announcements an betroffene Kontakte
• Alert-Unterdrückung während Wartungszeiten
• Kalender-Integration für Team-Übersicht

Multi-Tenancy & Organisations¶

Mandantenfähige Architektur für Teams und Kunden:

• Organisationen: Logische Trennung von Ressourcen
• Workspaces: Pro-Organisation isolierte Umgebungen
• Rollen & Berechtigungen: Feingranulare Zugriffskontrolle
• SSO-Integration: OIDC/SAML für Enterprise-Authentifizierung

Endpoint-Monitoring¶

Überwachung von HTTP- und ICMP-Endpoints:

• HTTP-Checks: Status-Code, Response-Zeit, SSL-Zertifikate
• ICMP-Checks: Ping-basierte Erreichbarkeit
• Multi-Region-Monitoring: Verteilte Prüfpunkte via Agents
• SLA-Dashboards: Verfügbarkeits-Reports und Trends

Hauptbereiche der Web-Oberfläche¶

Dashboard¶

Die Startseite zeigt eine Übersicht über:

• Aktive Alerts und deren Severity
• Letzte Action-Runs über alle Workspaces
• Kubernetes-Cluster-Health
• Anstehende Wartungsfenster

Workspaces & Blocks¶

Verwaltung aller registrierten Workspaces:

• Workspaces: Details, Konfiguration, APM-Status
• Blocks: Verwendete Blöcke mit Versionen
• Action-Runs: Vollständige Ausführungshistorie
• APM Tracking: Warnung bei fehlendem Monitoring-Stack im Cluster

Kubernetes¶

Kubernetes-spezifische Ressourcen:

• Cluster: Alle verwalteten K8s-Cluster mit Health-Status
• Apps: Deployments, StatefulSets, DaemonSets
• Services: LoadBalancer, Ingress, NodePort
• Backups: Velero-Backup-Status (Read-Only)
• Loadbalancer: Traffic-Statistiken, Multi-Region-Übersicht

Storage (S3)¶

Object Storage Management:

• S3 Cluster: Übersicht aller S3-Cluster (Ceph, MinIO, etc.)
• S3 Buckets: Bucket-Liste mit Object Count und Usage
• Credentials: S3-Zugangsdaten pro Cluster

Artifacts¶

Registry-Integrationen:

• Helm Charts: Verfügbare Charts und Versionen
• Docker Images: Container-Images aus verbundenen Registries
• Polycrate Blocks: Verfügbare Blöcke aus dem PolyHub

Networking¶

Netzwerk-Ressourcen:

• Endpoints: Via Ingress erkannte exposed Hostnames/Apps
• Loadbalancer: Traffic Count, Multi-Region-Status
• Domains: DNS-Verwaltung (falls konfiguriert)

Monitoring¶

Überwachungsfunktionen:

• Endpoints: HTTP/ICMP-Monitoring-Konfiguration
• Agents: Verteilte Monitoring-Agents verwalten
• Alerts: Alert-Regeln und aktive Incidents
• Logs: Zentraler Log-Explorer (VictoriaLogs-Integration)

Collaboration¶

Team-Zusammenarbeit:

• Tasks & Todos: Aufgabenverwaltung pro Workspace
• Knowledge Base: Dokumentation und Wissensmanagement
• Conversations: Integriertes Ticketing und E-Mail-Kommunikation
• Notes: Notizen an Ressourcen anhängen

Credentials¶

Zentrale Secret-Verwaltung:

• Alle Credential-Typen: SSH, Kubeconfig, Cloud, S3, Custom
• Organisations- und Workspace-Ebene: Hierarchische Vererbung
• Verschlüsselte Speicherung: Sichere Aufbewahrung aller Secrets
• Audit-Logging: Zugriffsprotokolle

Administration¶

Systemeinstellungen und Benutzerverwaltung:

• Benutzer & Rollen: Zugriffsrechte verwalten
• Organisationen: Multi-Tenancy-Konfiguration
• API-Keys: Programmatischer Zugriff
• System-Settings: Globale Konfiguration

Erste Schritte¶

1. API-Zugang erhalten¶

2. CLI konfigurieren¶

Verbinden Sie Ihre lokale Polycrate CLI mit der API:

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

3. Workspace registrieren¶

Führen Sie Ihre erste Action aus – der Workspace wird automatisch registriert:

polycrate run my-block install

4. Web-UI nutzen¶

Öffnen Sie die Web-Oberfläche und erkunden Sie Ihre Infrastruktur:

• Dashboard mit Übersicht
• Workspace-Details und Action-Historie
• Alerts und Benachrichtigungen konfigurieren

Weiterführende Themen¶

• Organisationen & Workspaces – Multi-Tenancy verstehen
• Endpoint-Monitoring – HTTP/ICMP-Überwachung
• Backup-Übersicht – Velero-Backup-Status überwachen
• API-Keys & Authentifizierung – Programmatischer Zugriff
• Wartungsfenster – Maintenances planen

Architektur¶

graph TB
    CLI[Polycrate CLI] -->|ActionRun Reports| API[Polycrate API]
    Agent[Monitoring Agent] -->|Check Results| API

    API -->|Speichert| DB[(PostgreSQL)]
    API -->|Cache| Redis[(Redis)]
    API -->|Logs| VL[(VictoriaLogs)]
    API -->|Metriken| VM[(VictoriaMetrics)]

    API -->|Auth| KC[Keycloak SSO]
    API -->|Alerts| Email[E-Mail]
    API -->|Alerts| Webhook[Webhooks]

    User[Benutzer] -->|Web UI| API
    User -->|REST API| API

Die Polycrate API ist eine moderne Django-Anwendung mit:

• PostgreSQL für persistente Daten
• Redis für Caching und Task Queue
• VictoriaMetrics/VictoriaLogs für Monitoring-Daten
• Keycloak für Enterprise SSO
• HTMX für reaktive Web-Oberfläche