Polycrate API Kubernetes Block

Deploy the Polycrate API to Kubernetes for centralized platform management.

Overview

This block deploys the complete Polycrate API stack including:

• API - Django REST Framework backend
• Celery Worker - Async task processing
• Celery Beat - Scheduled tasks
• Celery Flower - Task monitoring UI
• Harald - Event processing service

Quick Start

# workspace.poly
blocks:
  - name: polycrate-api
    from: cargo.ayedo.cloud/ayedo/k8s/polycrate-api
    config:
      namespace: polycrate
      ingress:
        enabled: true
        host: polycrate.example.com
        tls:
          enabled: true

Actions

• install - Deploy all components to Kubernetes
• uninstall - Remove all components from Kubernetes
• status - Show deployment status
• info - Show deployment configuration
• create-superuser - Create initial Django superuser

polycrate run polycrate-api install
polycrate run polycrate-api status
polycrate run polycrate-api create-superuser
polycrate run polycrate-api uninstall

Configuration

Basic Settings

• namespace (default: polycrate) - Kubernetes namespace
• loglevel (default: 1) - Log level (1=Info, 2=Debug, 3=Trace)

Image Configuration

• image_registry (default: cargo.ayedo.cloud) - Container registry
• image_name (default: polycrate/polycrate-api) - Image name
• image_tag (default: "") - Image tag (defaults to app_version)

Components

Each component can be individually configured:

config:
  components:
    api:
      enabled: true
      replicas: 3
      resources:
        requests:
          cpu: "100m"
          memory: "256Mi"
        limits:
          cpu: "1000m"
          memory: "1Gi"

Available components: api, celery_worker, celery_beat, celery_flower, harald

Ingress

config:
  ingress:
    enabled: true
    host: polycrate.example.com
    class: nginx
    tls:
      enabled: true
      issuer: letsencrypt-production

Private Registry

config:
  image_credentials:
    enabled: true
    name: polycrate-registry
    registry: cargo.ayedo.cloud
    username: ""      # Set via secrets.poly
    password: ""      # Set via secrets.poly

Metrics (VictoriaMetrics)

config:
  metrics:
    enabled: true
    vmservicescrape:
      enabled: true
      path: /api/v1/metrics

Prerequisites

• Kubernetes cluster with kubectl access
• PostgreSQL database accessible from the cluster
• Redis accessible from the cluster
• (Optional) Ingress controller for external access
• (Optional) VictoriaMetrics Operator for metrics

1. Django Secret Key generieren

python3 -c "import secrets; print(secrets.token_urlsafe(50))"

2. Field Encryption Key generieren

Die API verwendet django-encrypted-model-fields zur Verschlüsselung sensibler Datenbankfelder (Credentials, Tokens etc.). Der Key basiert auf Fernet und muss exakt 32 url-safe base64-kodierte Bytes sein.

python3 -c "import os, base64; print(base64.urlsafe_b64encode(os.urandom(32)).decode())"

3. Environment-Variablen konfigurieren

Die erforderlichen Env-Variablen werden über block.config.env übergeben und als Kubernetes Secret polycrate-api-env deployed.

Environment Variables

Pflichtfelder in block.config.env:

Superuser erstellen

Nach der ersten Installation muss ein Django-Superuser angelegt werden, um Zugang zur Admin-Oberfläche und zur API zu erhalten.

Konfiguration

# workspace.poly
blocks:
  - name: polycrate-api
    config:
      superuser:
        email: admin@example.com
        password: ""  # Via secrets.poly setzen!

Das Passwort niemals im Klartext in workspace.poly speichern:

# secrets.poly
- name: polycrate-api-superuser-password
  value: "<passwort>"
  block: polycrate-api
  path: config.superuser.password

Ausführen

polycrate run polycrate-api create-superuser

Die Action ist idempotent – existiert der User bereits, wird kein Fehler geworfen.

Keycloak Integration

Die Polycrate API hat zwei separate Keycloak-Integrationen:

Voraussetzungen in Keycloak

Die Polycrate API nutzt die Keycloak Organizations REST API (/admin/realms/{realm}/organizations). Folgende Voraussetzungen müssen erfüllt sein:

Service Account in Keycloak anlegen

Die folgenden Schritte beziehen sich auf den master Realm.

1. Keycloak Admin Console öffnen und im master Realm bleiben

2. Organizations aktivieren: - Realm settings → General - Organizations: auf Enabled stellen - Speichern

3. Neuen User anlegen: - Users → Add user - Username: polycrate-api-sa (oder beliebig) - Email verified: aktivieren - Speichern

4. Passwort setzen: - Tab Credentials → Set password - Passwort vergeben, Temporary: deaktivieren

5. Admin-Rechte zuweisen: - Tab Role mapping → Assign role → Client roles - Client master-realm auswählen - Folgende Rollen zuweisen:

   • manage-realm – für Organizations API (Pflicht)
   • manage-users – für User-Provisioning und Org-Members (Pflicht)
   • manage-clients – für Client-Verwaltung (empfohlen)
   • Optional für erweiterten Zugriff: view-realm, view-users, query-users, manage-identity-providers

6. Client für Token-Ausstellung prüfen: - Clients → admin-cli - Direct access grants muss aktiviert sein (Standard: ja)

Konfiguration im Block

Die Keycloak-Admin-API-Integration wird über Environment-Variablen konfiguriert (in secrets.poly oder workspace.poly):

config:
  env:
    KEYCLOAK_INTEGRATION_ENABLED: "true"
    KEYCLOAK_ENDPOINT: "https://id.example.com"   # Keycloak-URL (ohne /auth)
    KEYCLOAK_CLIENT_ID: "admin-cli"                # Client für Token-Ausstellung
    KEYCLOAK_REALM: "master"                       # Realm des Service Accounts
    KEYCLOAK_USERNAME: "polycrate-api-sa"          # Username des Service Accounts
    KEYCLOAK_PASSWORD: ""                          # Passwort via secrets.poly setzen!

Wichtig: KEYCLOAK_PASSWORD niemals im Klartext in workspace.poly setzen – ausschließlich über secrets.poly (verschlüsselt):

# secrets.poly
- name: KEYCLOAK_PASSWORD
  value: "<passwort>"
  block: polycrate-api
  path: config.env.KEYCLOAK_PASSWORD

Diese Werte werden als Defaults beim Start geladen und können über die System Config → Integration: Keycloak in der Web-UI überschrieben werden.

Funktionsweise

Die API authentifiziert sich via Resource Owner Password Credentials Grant gegen den admin-cli Client und erhält ein Bearer-Token, mit dem anschließend die Keycloak Admin REST API aufgerufen wird.

Health Check

Die Keycloak-Verbindung kann mit dem Management Command geprüft werden:

python manage.py check_keycloak_status

Links

• Documentation
• Release Notes
• Website