Polycrate API – Integrationen¶

Übersicht¶

Die Polycrate API integriert sich mit verschiedenen externen Diensten. Diese Integrationen ermöglichen zentrales Identitätsmanagement, Team-Kommunikation, Container-Registry-Verwaltung, Versionskontrolle und DNS-Management – alles aus der Polycrate API heraus steuerbar.

graph TB
    subgraph API[Polycrate API]
        ORG[Organisationen]
        WS[Workspaces]
    end

    ORG --> Keycloak[Keycloak SSO]
    ORG --> RocketChat[RocketChat]
    ORG --> Harbor[Harbor Registry]
    WS --> GitLab[GitLab]
    API --> Mattermost[Mattermost]
    API --> PowerDNS[PowerDNS]
    API --> CentralNic[CentralNic]

    Keycloak -->|OIDC| Harbor
    Keycloak -->|OIDC| RocketChat

Keycloak¶

Die Polycrate API hat zwei separate Keycloak-Integrationen:

Zusätzlich dient Keycloak als OIDC-IdP für Harbor und RocketChat (nicht für die Polycrate API oder GitLab direkt).

Was passiert für den Nutzer?¶

• Benutzer loggen sich bei Harbor und RocketChat über Keycloak ein (OIDC)
• Bei Harbor: Der Token braucht einen orgs-Claim mit den Organisation-Slugs; Harbor ordnet den User der passenden Gruppe zu
• Die Polycrate API steuert Keycloak per Admin REST API: Organisationen anlegen, User provisionieren, Org-Memberships verwalten

Voraussetzungen in Keycloak¶

Die Polycrate API nutzt die Keycloak Organizations REST API. Folgende Voraussetzungen müssen im master Realm erfüllt sein:

Service Account einrichten¶

1. User anlegen: Users → Add user → Username: polycrate-api-sa, Email verified: ON
2. Passwort setzen: Tab Credentials → Set password, Temporary: OFF
3. Rollen zuweisen: Tab Role mapping → Assign role → Client roles → Client master-realm:
   • manage-realm – Organizations API (Pflicht)
   • manage-users – User-Provisioning, Org-Members (Pflicht)
   • manage-clients – Client-Verwaltung (empfohlen)

Die API authentifiziert sich via Resource Owner Password Credentials Grant gegen den admin-cli Client.

Konfiguration¶

• System Config → Integration: Keycloak: Endpoint, Realm, Client ID, Username, Password
• Harbor-seitig: OIDC mit Keycloak konfigurieren; Group Claim Name = orgs (muss mit Keycloak übereinstimmen)
• RocketChat-seitig: OIDC-Provider für Keycloak konfigurieren

→ Authentifizierung (OIDC-Login, API-Keys, Agent-Tokens)

GitLab¶

Was passiert für den Nutzer?¶

• Workspace-Repositories: Jedem Workspace ist ein GitLab-Projekt zugeordnet – hier liegt die workspace.poly und die Block-Konfiguration
• Auto-Create: Wenn ein Workspace erstmals mit der API synchronisiert wird und noch kein GitLab-Projekt existiert, wird automatisch ein neues Projekt in der Organisations-Gruppe angelegt (leeres Repository)
• Suche vor Erstellung: Bestehende Projekte werden zuerst per Name/Path gesucht; nur bei Nichtfund wird ein neues erstellt
• CLI-Sync: polycrate workspace sync und polycrate git sync synchronisieren mit diesem Projekt

Konfiguration¶

• System Config → Integration: GitLab: API-Endpoint, API-Token (mit Gruppen-/Projekt-Rechten)
• Workspace: Muss einer Organisation zugeordnet sein, die eine GitLab-Gruppe besitzt

Nutzen¶

• Einheitliche Quelle für Infrastructure-as-Code
• Team-Kollaboration über Git
• Versionierung und Audit über Git-Historie

RocketChat¶

Was passiert für den Nutzer?¶

• Privater Channel pro Organisation: Organisationen mit einem Support-Produkt, das RocketChat-Channels ermöglicht, erhalten automatisch einen privaten RocketChat-Channel
• OIDC-Integration: Nur Benutzer, die über Keycloak der Organisation zugeordnet sind, haben Zugriff auf den Channel
• System-Organisation: Die als „System Owner“ konfigurierte Organisation (z. B. ayedo) hat Zugriff auf alle Kunden-Channels – für zentralen Support
• Channel-Archivierung: Bei Archivierung einer Organisation wird der zugehörige Channel archiviert (nicht gelöscht)

Konfiguration¶

• System Config → Integration: RocketChat: API-Endpoint, Admin-User-ID, Admin Auth Token, optionaler Channel-Prefix
• Produkt-Feature: Das Support-Produkt muss features.rocketchat_channel: true haben (z. B. Premium Support, Priority Support) → Pricing & Business Layer
• RocketChat OAuth: OIDC-Provider für Keycloak konfigurieren; Group Claim Name muss mit Keycloak-Gruppen übereinstimmen

Nutzen¶

• Direkte Kundenkommunikation im richtigen Channel
• Keine manuelle Channel-Erstellung
• Einheitliche Zugriffssteuerung über OIDC

Mattermost¶

Was passiert für den Nutzer?¶

• Benachrichtigungen: Alerts, Downtimes, Todo-Updates können an Mattermost gesendet werden
• Zwei Modi:
• Webhook: Einfaches Markdown, klassischer Incoming-Webhook
• API: Rich Formatting, Action-Buttons (z. B. „Downtime bestätigen“, „Snooze“), Message-Updates nach Aktion
• Rück-Aktionen: Klickt ein Benutzer in Mattermost auf einen Button, wird das zugehörige Objekt in der Polycrate API aktualisiert (z. B. Downtime bestätigt)
• User-Matching: Über E-Mail wird der Mattermost-Benutzer dem Polycrate-Benutzer zugeordnet – Aktionen werden dem richtigen Konto zugeschrieben

Konfiguration¶

• Notification Sink: Neuen Sink mit Typ „Mattermost“ anlegen
• Webhook-Modus: Webhook-URL von Mattermost eintragen
• API-Modus: Bot-Token, Server-URL, Channel-ID, Integration-Token (für Callback-Verifikation)

Nutzen¶

• Schnelle Reaktion auf Alerts direkt aus dem Chat
• Kein Wechsel in die Web-UI nötig für Bestätigungen
• Team-weite Sichtbarkeit von Incidents

Harbor (Container Registry)¶

Was passiert für den Nutzer?¶

• Projekt pro Organisation: Jede Organisation erhält automatisch ein Harbor-Projekt – als Container-Registry-Namespace
• OIDC-Gruppe: Eine Harbor-Gruppe wird mit dem Organisation-Slug angelegt; Keycloak-Benutzer mit dem passenden orgs-Claim werden bei Harbor-Login automatisch der Gruppe zugeordnet
• Maintainer-Berechtigung: Die Org-Gruppe erhält Maintainer-Rechte im Projekt – Push, Pull, Repository-Verwaltung
• Quota-Tracking: Die genutzte Speichermenge und das Limit des Harbor-Projekts werden in der Organisation angezeigt (Registry Quota)
• Keine manuelle Anlage: Bei aktivierter Integration erfolgt die Bereitstellung automatisch während der Organisation-Reconciliation

Konfiguration¶

• System Config → Integration: Harbor: Endpoint, Admin-Username, Admin-Passwort, Aktivierung (HARBOR_INTEGRATION_ENABLED)
• Harbor-seitig: OIDC mit Keycloak konfigurieren; Group Claim Name = orgs (muss mit Keycloak übereinstimmen)

Nutzen¶

• Einheitlicher Registry-Namespace pro Organisation
• Keine manuelle Projekt- und Gruppenerstellung
• Quota-Übersicht in der Polycrate API

PowerDNS (DNS)¶

Was passiert für den Nutzer?¶

• Zentrale DNS-Verwaltung: DNS-Zonen und Records werden in der Polycrate API angelegt und bearbeitet
• Sofortige Übertragung: Änderungen werden synchron an PowerDNS übermittelt – keine Wartezeit
• Unterstützte Record-Typen: A, AAAA, CNAME, TXT, NS, SOA und weitere

Konfiguration¶

• System Config → Integration: PowerDNS-API-Endpoint, API-Schlüssel, Nameserver-Liste, SOA-RName

Nutzen¶

• DNS-Verwaltung aus einer Hand mit Infrastruktur
• Konsistente Namensauflösung über alle Workspaces

→ Domains & DNS

CentralNic (Domain-Registrar)¶

Was passiert für den Nutzer?¶

• Domain-Registrierung: Neue Domains können direkt über die Polycrate API bei CentralNic (RRPProxy) registriert werden
• Portfolio-Import: Bestehende Domains aus dem Registrar-Konto können importiert werden
• Verwaltung: Status, Ablaufdatum, Nameserver und Kontakte einsehen und bearbeiten
• Verknüpfung mit DNS: Eine Domain kann optional mit einer DNSZone verknüpft werden – dann ist die technische Auflösung in PowerDNS abgebildet

Konfiguration¶

• Administration → Domain Registrar: Neuen Registrar mit Typ „CentralNic“ anlegen; API-Zugangsdaten eintragen
• System Config: Optional ein „System Domain Registrar“ festlegen, der im Create-Formular vorausgewählt wird

→ Domains & DNS

Übersicht: Wo wird was konfiguriert?¶

Externe Status-Feeds (DataSources)¶

DataSources verbinden die Polycrate API mit externen RSS- und API-Feeds von Cloud-Providern. Importierte Einträge erscheinen als Notes mit kind=provider-status bzw. kind=news und sind direkt dem jeweiligen Provider zugeordnet.

Die Polycrate API wird mit 15 vorkonfigurierten DataSources ausgeliefert – darunter Status-Feeds von AWS, Azure, GCP, Hetzner, STACKIT und weiteren Anbietern sowie ein Sicherheits-Newsfeed (Heise Security).

→ Vollständige Liste und Aktivierungsanleitung

Siehe auch¶

• Authentifizierung – SSO, API-Keys
• Domains & DNS – Domain- und DNS-Verwaltung
• Wartungsfenster – Benachrichtigungen bei Wartungen
• Vorkonfigurierte Daten – Provider, PoPs und Status-Feeds