Operator-Deployment¶

Die Polycrate API bildet ab, welche Cluster den Polycrate-Operator installiert haben, in welcher Version, und wie der Rollout neuer Operator-Versionen gesteuert wird. Das Feature kombiniert mehrere bestehende Bausteine — es gibt bewusst kein eigenes OperatorDeployment-Modell.

Das hier beschriebene Zusammenspiel:

K8sCluster + K8sApp — jeder Cluster hat optional eine App polycrate-operator, deren installed_version den tatsächlichen Zustand am Cluster beschreibt.
Agent (kind=operator) — der Operator registriert sich als Agent an der API und sendet Heartbeats, die sein Leben erhalten.
SystemConfig — globale Keys wie OPERATOR_BLOCK_VERSION (Ziel-Version) und OPERATOR_ROLLOUT_PERCENTAGE (Canary-Prozentsatz) steuern den gewünschten Zustand.
Operator Rollout Dashboard — die UI, die diese Quellen aggregiert darstellt.

Modell-Sicht¶

┌──────────────┐  1..n  ┌──────────────────────┐
│  K8sCluster  │────────▶│ K8sApp               │
└──────┬───────┘         │  name=polycrate-op…  │
       │ optional FK     │  installed_version   │
       ▼                 └──────────────────────┘
┌──────────────┐
│ Agent        │ Operator läuft am Cluster, pingt API
│ kind=operator│
└──────────────┘

┌───────────────────────────┐
│ SystemConfig (globale Keys│
│  OPERATOR_BLOCK_VERSION   │
│  OPERATOR_ROLLOUT_…       │
└───────────────────────────┘

`K8sApp` = der konkrete Operator pro Cluster¶

Der Polycrate-Operator ist ein Polycrate-Block wie jeder andere. Auf jedem Cluster, wo er läuft, existiert ein K8sApp-Eintrag mit name=polycrate-operator:

Feld	Bedeutung
`installed_version`	Die Version, die der Cluster aktuell fährt
`desired_version`	Die gewünschte Version — typisch aus SystemConfig gezogen
`last_reconciled`	Wann der Operator zuletzt seinen Zustand aktualisiert hat
`state`	Aggregiert aus Heartbeats & Probe-Ergebnissen (OK/WARNING/CRITICAL)

Der Abgleich zwischen installed_version und desired_version ist die zentrale Information für das Rollout-Dashboard.

`Agent (kind=operator)` = der Operator am anderen Ende¶

Jeder Operator registriert sich als Agent mit kind=operator an der API. Ab da sendet er:

Heartbeats (aktualisiert last_seen)
Probe-Ergebnisse für ihm zugewiesene Endpoints
K8sApp-Status (inkl. eigener installed_version)

Fällt der Heartbeat aus, wird der Agent CRITICAL und erzeugt eine Downtime. So ist "Operator am Cluster X ist seit 15 Minuten weg" ohne zusätzliche Monitoring-Konfiguration sichtbar.

`SystemConfig`-Keys = gewünschter Zustand¶

Zwei Keys steuern den Plattform-weiten Rollout:

Key	Wirkung
`OPERATOR_BLOCK_VERSION`	Ziel-Version für alle Cluster, sofern nicht per Cluster überschrieben
`OPERATOR_ROLLOUT_PERCENTAGE`	Canary-Gate: wie viel Prozent der Cluster sollen ein Update gleichzeitig bekommen (0–100)

Plattform-Admins setzen diese Werte in der UI unter System → SystemConfig. Eine Änderung an OPERATOR_BLOCK_VERSION wirkt sich per Default auf alle Cluster aus — abgestuft durch OPERATOR_ROLLOUT_PERCENTAGE.

Rollout-Gating¶

Der Rollout neuer Versionen folgt einer einfachen Batching-Regel:

Die API vergleicht für jeden Cluster installed_version gegen desired_version.
Liegen Cluster auseinander (neue Version verfügbar), wird pro Rollout-Lauf nur ein Batch aktualisiert — definiert durch OPERATOR_ROLLOUT_PERCENTAGE.
Cluster mit aktiver Wartung werden bevorzugt aktualisiert (Wartungsslot legitim).
Cluster im Zustand CRITICAL werden zurückgestellt, bis sich ihr State beruhigt.

Ein Admin kann auf dem Dashboard pro Cluster ein Update erzwingen oder aussetzen.

Operator Rollout Dashboard¶

Pfad: System → Operator Rollout

Das Dashboard aggregiert die oben genannten Datenquellen und zeigt pro Cluster-Zeile:

Spalte	Woher
Workspace / Cluster	K8sCluster
Installierte Version	`K8sApp.installed_version` (mit `name=polycrate-operator`)
Gewünschte Version	`K8sApp.desired_version` bzw. `SystemConfig.OPERATOR_BLOCK_VERSION`
Heartbeat	`Agent.last_seen` (Operator-Agent dieses Clusters)
State	Aggregiert aus `K8sApp.state` und `Agent.state`
Rollout-Status	Ob ein Update anliegt, wartet, oder vom Canary-Gate geblockt wird
Blocker	Fehlende Tokens, fehlende Kontaktperson, Wartung aktiv, etc.

Typische Blocker:

Kein Agent-Token — der Cluster hat die API-Credentials noch nicht eingerichtet.
OperatorConfig fehlt — im Cluster existiert noch keine OperatorConfig-CR, die auf die API zeigt.
Canary-Gate — dieser Cluster gehört noch nicht zum aktuellen Rollout-Batch.

CRD-Synchronisation¶

Die Polycrate-CLI exportiert beim Release-Finalize die CRDs des Operators und stellt sie als Teil des Blocks bereit (siehe CLI-Release 0.34.0). Der Operator installiert diese CRDs im Cluster, sobald seine neue Version reconciled wird.

Konsequenz: Ein Upgrade der Operator-Version kann neue Custom Resources einführen — das ist ein gewollter Teil des Rollouts. Die API kennt über den OpenAPI-Export die Label-Konstanten, sodass Dashboards und Filter konsistent mit den neuen Feldern umgehen können (siehe Labels & Konventionen).

Token-Bereitstellung¶

Der Operator benötigt einen API-Token, um sich als Agent zu registrieren. Die Abfolge:

API-Token anlegen (UI → User → API-Tokens) — scope auf den Workspace des Clusters.
Kubernetes Secret erstellen — Secret mit Key token im Namespace des Operators.
OperatorConfig im Cluster → credentials_ref.secret_name und token_key setzen.
Operator neu starten oder auf den nächsten Reconcile warten.

Ab dann sendet der Operator Heartbeats und erscheint im Rollout-Dashboard.

Multi-Version-Flotte¶

Das Dashboard visualisiert auch, wie viele Cluster welche Version fahren — z. B. "30 × 0.34.0, 12 × 0.35.0, 2 × 0.36.0". Das ist nützlich, um:

Kompatibilitäts-Entscheidungen zu treffen ("kann ich das CRD-Feld X entfernen, wenn noch 30 Cluster auf der alten Version sind?"),
Rollout-Tempo anzupassen,
Cluster mit "festklebenden" Versionen gezielt zu adressieren.

API-Endpunkte¶

GET /api/v1/operator-rollout/ — aggregierte Dashboard-Daten.
GET /api/v1/k8sapps/?name=polycrate-operator — rohe Daten pro Cluster.
GET /api/v1/agents/?kind=operator — alle Operator-Agents.
POST /api/v1/operator-rollout/{cluster_id}/force-update/ — Update erzwingen.
POST /api/v1/operator-rollout/{cluster_id}/pause/ — Rollout für diesen Cluster aussetzen.

Zugriffskontrolle¶

Das Operator-Dashboard ist Plattform-Admin-only, weil die Werte global sind und kleine Änderungen große Auswirkungen haben. Einzelne Cluster-Zeilen können über RBAC zugänglich gemacht werden, damit Kunden den Status ihres eigenen Clusters sehen, ohne in die Systemsteuerung zu gelangen.