Polycrate API – Integrations

Overview of the external services the Polycrate API integrates with: Keycloak, GitLab, RocketChat, Mattermost, Grafana, Harbor, PowerDNS, CentralNic, VictoriaMetrics/APM and external status feeds, including what each does for users and where it is configured.

Polycrate API – Integrations

Overview

The Polycrate API integrates with various external services. These integrations enable central identity management, team communication, container registry management, version control and DNS management – all controllable from within the Polycrate API.

graph TB
    subgraph API[Polycrate API]
        ORG[Organizations]
        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

VictoriaMetrics / APM (Unified Credential)

The API manages one credential and one VMUser per organization for metrics, logs and traces, provided the feature is enabled in the system configuration and an APM target cluster (system_apm_cluster) is set.

See the detailed description under Unified APM Credential.

Keycloak

The Polycrate API has two separate Keycloak integrations:

In addition, Keycloak serves as the OIDC IdP for Harbor and RocketChat (not for the Polycrate API or GitLab directly).

What Happens for the User?

• Users log in to Harbor and RocketChat via Keycloak (OIDC)
• For Harbor: the token needs an orgs claim with the organization slugs; Harbor assigns the user to the matching group
• The Polycrate API controls Keycloak via the Admin REST API: creating organizations, provisioning users, managing org memberships

Prerequisites in Keycloak

The Polycrate API uses the Keycloak Organizations REST API. The following prerequisites must be met in the master realm:

Setting Up the Service Account

1. Create user: Users → Add user → Username: polycrate-api-sa, Email verified: ON
2. Set password: Tab Credentials → Set password, Temporary: OFF
3. Assign roles: Tab Role mapping → Assign role → Client roles → Client master-realm:
   • manage-realm – Organizations API (required)
   • manage-users – user provisioning, org members (required)
   • manage-clients – client management (recommended)

The API authenticates via the Resource Owner Password Credentials Grant against the admin-cli client.

Configuration

• System Config → Integration: Keycloak: Endpoint, Realm, Client ID, Username, Password
• Harbor side: Configure OIDC with Keycloak; Group Claim Name = orgs (must match Keycloak)
• RocketChat side: Configure the OIDC provider for Keycloak

→ Authentication (OIDC login, API keys, agent tokens)

GitLab

What Happens for the User?

• Workspace repositories: Every workspace is assigned a GitLab project – this is where the workspace.poly and the block configuration live
• Auto-create: When a workspace is synchronized with the API for the first time and no GitLab project exists yet, a new project is automatically created in the organization group (empty repository)
• Search before create: Existing projects are first searched by name/path; a new one is only created if none is found
• CLI sync: polycrate workspace sync and polycrate git sync synchronize with this project

Configuration

• System Config → Integration: GitLab: API endpoint, API token (with group/project permissions)
• Workspace: Must be assigned to an organization that owns a GitLab group

Benefits

• Single source for infrastructure as code
• Team collaboration via Git
• Versioning and audit via Git history

RocketChat

What Happens for the User?

• Private channel per organization: Organizations with a support product that enables RocketChat channels automatically receive a private RocketChat channel
• OIDC integration: Only users assigned to the organization via Keycloak have access to the channel
• System organization: The organization configured as "System Owner" (e.g. ayedo) has access to all customer channels – for central support
• Channel archiving: When an organization is archived, the associated channel is archived (not deleted)

Configuration

• System Config → Integration: RocketChat: API endpoint, admin user ID, admin auth token, optional channel prefix
• Product feature: The support product must have features.rocketchat_channel: true (e.g. Premium Support, Priority Support) → Pricing & Business Layer
• RocketChat OAuth: Configure the OIDC provider for Keycloak; Group Claim Name must match the Keycloak groups

Benefits

• Direct customer communication in the right channel
• No manual channel creation
• Uniform access control via OIDC

Mattermost

What Happens for the User?

• Notifications: Alerts, downtimes, maintenances, todos — including firing alert attachments
• Two modes:
• Webhook: Simple Markdown, incoming webhook
• API: Rich formatting, silence actions, message updates
• Alert content: Grafana dashboard link, values table, alert rate (24h/30d), cluster/workspace link
• Silence sync: silence_ends_at is synchronized with Grafana and shown in the dashboard
• Pull sync: Operations Grafana is the primary source for the alert state
• User matching: Email maps Mattermost users to Polycrate users

Configuration

• Notification Sink: Type "Mattermost"
• Webhook mode: Webhook URL
• API mode: Bot token, server URL, channel ID, integration token

Benefits

• React to alerts from the chat (including silence)
• Team-wide visibility of Incidents and alerts

Grafana (Dual Instance)

What Happens for the User?

• Two Grafana instances can run in parallel (e.g. Platform + Operations)
• Datasources and operations alerts are reconciled automatically per organization
• Members of the system org can be set/revoked as Grafana Server Admin
• Mattermost firing notifications link to the matching dashboards (see above)

Configuration

• System Config → Integration: Grafana — endpoints/credentials for the instances
• Org reconciliation creates datasources/alerts; manual maintenance is largely unnecessary

Harbor (Container Registry)

What Happens for the User?

• Project per organization: Every organization automatically receives a Harbor project – as a container registry namespace
• OIDC group: A Harbor group is created with the organization slug; Keycloak users with the matching orgs claim are automatically assigned to the group on Harbor login
• Maintainer permission: The org group receives maintainer rights in the project – push, pull, repository management
• Quota tracking: The used storage and the limit of the Harbor project are shown in the organization (Registry Quota)
• No manual creation: With the integration enabled, provisioning happens automatically during organization reconciliation

Configuration

• System Config → Integration: Harbor: Endpoint, admin username, admin password, activation (HARBOR_INTEGRATION_ENABLED)
• Harbor side: Configure OIDC with Keycloak; Group Claim Name = orgs (must match Keycloak)

Benefits

• Uniform registry namespace per organization
• No manual project and group creation
• Quota overview in the Polycrate API

PowerDNS (DNS)

What Happens for the User?

• Central DNS management: DNS zones and records are created and edited in the Polycrate API
• Immediate propagation: Changes are transmitted synchronously to PowerDNS – no waiting time
• Supported record types: A, AAAA, CNAME, TXT, NS, SOA and more

Configuration

• System Config → Integration: PowerDNS API endpoint, API key, nameserver list, SOA RName

Benefits

• DNS management from a single source together with infrastructure
• Consistent name resolution across all workspaces

→ Domains & DNS

CentralNic (Domain Registrar)

What Happens for the User?

• Domain registration: New domains can be registered directly via the Polycrate API at CentralNic (RRPProxy)
• Portfolio import: Existing domains from the registrar account can be imported
• Management: View and edit status, expiry date, nameservers and contacts
• Link with DNS: A domain can optionally be linked to a DNSZone – the technical resolution is then mapped in PowerDNS

Configuration

• Administration → Domain Registrar: Create a new registrar of type "CentralNic"; enter the API credentials
• System Config: Optionally define a "System Domain Registrar" that is preselected in the create form

→ Domains & DNS

Overview: What Is Configured Where?

External Status Feeds (DataSources)

DataSources connect the Polycrate API with external RSS and API feeds from cloud providers. Imported entries appear as Notes with kind=provider-status or kind=news and are directly assigned to the respective provider.

The Polycrate API ships with 15 preconfigured DataSources – including status feeds from AWS, Azure, GCP, Hetzner, STACKIT and other providers as well as a security news feed (Heise Security).

→ Complete list and activation guide

See Also

• Authentication – SSO, API keys
• Domains & DNS – Domain and DNS management
• Maintenance Windows – Notifications for maintenances
• Preconfigured Data – Providers, PoPs and status feeds