kuma-operator

Der Rust-Operator synchronisiert Kubernetes-Manifeste mit einer bestehenden Uptime-Kuma-Instanz. Er verwaltet UptimeKumaMonitor, UptimeKumaNotification und UptimeKumaTag unter monitoring.wuastbude.de/v1alpha1: Erstellen, Aktualisieren, Löschen, Referenzen, Status und Korrektur manueller Änderungen.

Image und Helm-Veröffentlichung behalten ihre bestehende Identität: harbor.wuastbude.de/kumaste/operator und oci://harbor.wuastbude.de/kumaste/kumaste. Releasehistorie und vorhandene CRDs bleiben erhalten. Der Operator verwendet Kubernetes und Uptime Kuma als Zustandsquellen; er benötigt keine eigene Datenbank, Redis oder Weboberfläche.

Ressourcen und Referenzen

Alle Monitorfelder und die vollständigen Schemas stehen in der API-Referenz. Die bestehenden CRDs unter helm/kumaste/crds definieren Validierung und Kubernetes-Defaults. Änderungen an Rust-Typen benötigen keinen Go-Generator.

Unterstützte Monitortypen: http, ping, tcp, dns, push, steam, gamedig, keyword, json-query, grpc-keyword, docker, port, mdns, real-browser, mqtt, sqlserver, postgres, mysql, oracledb, mongodb, radius, redis, tailscale-ping, smtp, snmp, rabbit-mq, kafka-producer, websocket-upgrade, group und manual. Uptime Kuma führt die Prüfungen aus; der Operator überträgt die gewünschte Konfiguration einschließlich Authentifizierung, TLS, Bedingungen und typspezifischer Optionen.

spec.name bezeichnet den Anzeigenamen in Kuma und fällt auf metadata.name zurück. parentName, notifications und tags[].name referenzieren dagegen Kubernetes-Ressourcennamen im selben Namespace. Eine Referenz muss synchronisiert sein, bevor der Monitor ihre Kuma-ID verwenden kann. Tagwerte gehören zur Zuordnung zwischen Monitor und Tag.

apiVersion: monitoring.wuastbude.de/v1alpha1
kind: UptimeKumaTag
metadata:
  name: production
  namespace: myapp-ns
spec:
  name: Production
  color: "#50FA7B"
---
apiVersion: monitoring.wuastbude.de/v1alpha1
kind: UptimeKumaNotification
metadata:
  name: webhook
  namespace: myapp-ns
spec:
  name: Operations
  type: webhook
  active: true
  config:
    webhookURL: https://notifications.example.invalid/kuma
    webhookContentType: json
---
apiVersion: monitoring.wuastbude.de/v1alpha1
kind: UptimeKumaMonitor
metadata:
  name: production-group
  namespace: myapp-ns
spec:
  name: Production
  type: group
---
apiVersion: monitoring.wuastbude.de/v1alpha1
kind: UptimeKumaMonitor
metadata:
  name: application
  namespace: myapp-ns
spec:
  name: Application
  type: http
  url: https://application.example.invalid/healthz
  parentName: production-group
  notifications: [webhook]
  tags:
    - name: production
      value: application

Notification-Konfiguration ist eine offene String-Map. Providerfelder werden flach an Kuma übertragen; name, type, isDefault und active werden durch ihre eigenen Specfelder bestimmt. Beispiele sind discordWebhookUrl, telegramBotToken/telegramChatID, smtpHost/smtpPort/smtpPassword oder webhookURL/webhookAdditionalHeaders. Das Schema schränkt die Provider nicht auf diese Beispiele ein.

Der Status enthält monitorID, notificationID beziehungsweise tagID sowie Synced-Conditions mit Generation, Grund und Übergangszeit. Finalizer sorgen für die Upstream-Löschung vor dem Entfernen des Kubernetes-Objekts. Wiederholte Reconciliation korrigiert Drift und erhält Zuordnungen. Nach einem unbekannten Schreibausgang wird zuerst der tatsächliche Zustand ermittelt; ein Create wird nicht blind wiederholt.

Namespaceauswahl und Pruning

watchNamespaces: [] überwacht und synchronisiert alle Namespaces. Eine explizite Liste begrenzt Watches, Referenzauflösung und Kubernetes-Schreibrechte. Unabhängig davon liest der Operator die drei Ressourcentypen clusterweit, um vorhandene Zuordnungen zu schützen und doppelte Claims zu erkennen.

Mit prune.enabled: true ist der gesamte Cluster maßgeblich: Monitore, Notifications und Tags ohne zugehöriges Manifest werden aus Kuma gelöscht. Eine erfolgreich gelesene leere Ressourcenliste entfernt alle unbeanspruchten Kuma-Ressourcen dieses Typs. Ein Kubernetes- oder Kuma-Lesefehler autorisiert keine Löschung. Bestehende IDs und noch laufende Create-Zuordnungen bleiben geschützt. Pruning ist standardmäßig ausgeschaltet; das Intervall beträgt 5m.

Alle Mutationen werden auch bei mehreren Replikas durch eine Kubernetes-Lease im Operator-Namespace koordiniert. leaderElect ist zusätzlich verfügbar und standardmäßig false. Die ServiceAccount benötigt daher immer Zugriff auf die Mutation-Lease sowie clusterweite Leserechte auf die drei CRDs. Das Chart erzeugt bei ausgewählten Namespaces dort die benötigten Schreibrechte.

Helm und Zugangsdaten

Das bestehende Chart liegt unter helm/kumaste. uptimeKuma.existingSecret verweist auf ein Secret im vorhandenen Operator-Namespace mit diesen Schlüsseln:

UPTIME_KUMA_URL: https://kuma.example.invalid
UPTIME_KUMA_USERNAME: operator
UPTIME_KUMA_PASSWORD: <passwort>

Alternativ erzeugt das Chart das Secret aus uptimeKuma.url, uptimeKuma.username und uptimeKuma.password. Bestehende Namespace-, Release- und Deployment-Bezüge werden im GitOps-Repository gepflegt. Die Produktionsumschaltung erfolgt über diesen GitOps-Weg.

Beispiel für die lokale Prüfung eines veröffentlichten Charts mit einem bestehenden Secret:

helm template kuma-operator oci://harbor.wuastbude.de/kumaste/kumaste \
  --version "$CHART_VERSION" --namespace "$OPERATOR_NAMESPACE" \
  --set uptimeKuma.existingSecret=kuma-credentials \
  --set prune.enabled=true

image.digest erlaubt eine unveränderliche Image-Referenz und hat Vorrang vor image.tag. Ohne expliziten Tag verwendet ein veröffentlichtes Chart seine appVersion. Weitere Optionen erhalten ServiceAccount, RBAC, Replikazahl, Ressourcen, SecurityContexts, Placement und Podannotationen; siehe values.yaml.

Konfiguration und Betrieb

Einstellung	Default	Verhalten
UPTIME_KUMA_URL	erforderlich	HTTP(S)- oder WS(S)-URL, auch mit Pfadpräfix
UPTIME_KUMA_USERNAME / UPTIME_KUMA_PASSWORD	erforderlich	Login; Credentialbytes einschließlich Leerzeichen bleiben erhalten
--health-probe-bind-address	:8081	Probe-HTTP-Listener; Hostnamen möglich, 0 oder leer deaktiviert
--metrics-bind-address	:8080	Metrics-HTTP-Listener; Hostnamen möglich, 0 deaktiviert, leer verwendet den Default
--sync-interval	60s	Periodische Driftkorrektur; 0s oder negative Dauer deaktiviert sie. Wiederverbindung und Fehler-Retry bleiben aktiv
--enable-prune	false	Clusterweites Entfernen nicht deklarierter Kuma-Ressourcen
--prune-interval	5m	Pruningintervall
--leader-elect	false	Zusätzliche Controller-Leaderwahl
--watch-namespaces / WATCH_NAMESPACES	alle	Kommagetrennte Namespaceauswahl
POD_NAMESPACE	Kubernetes-Konfiguration	Namespace der Koordinations-Leases; im Chart aus Podmetadaten
POD_UID	Library-Identität	Lease-Halter; im Chart aus Podmetadaten
SHUTDOWN_TIMEOUT_SECS	Common-Default	Positive HTTP-/Worker-Drainfrist
LOG_LEVEL	info	Gemeinsamer Logging-Level
LOG_FORMAT	automatisch	JSON im Container, Pretty bei TTY; json/pretty als Override
RUST_LOG	—	Individueller Filter; sensible Transport-Payloadlogs bleiben gesperrt

Kuberneteszugriff verwendet die reguläre kube-Konfiguration: Incluster-Zugang oder lokal KUBECONFIG. Fehlende Credentials, ungültige URLs, Bindadressen oder nichtpositive Pruningintervalle verhindern den Start. Booleanflags akzeptieren die kurze Form sowie beispielsweise --leader-elect=false.

HTTP-Pfad	Vertrag
GET /healthz	Prozess-Liveness
GET /ready, GET /readyz	200 bei Bereitschaft, sonst 503; Kuma-Verbindungsverlust wird direkt übernommen
GET /metrics	Gemeinsame HTTP- und Jobmetriken

Probes lesen den gemeinsamen Prozesszustand ohne Fremdaufruf pro Anfrage. Unbekannte HTTP-Routen liefern RFC-9457-Problem-Details. Ablauf, Transport und Shutdown sind in docs/runtime.md beschrieben.

Entwicklung und Nachweise

Voraussetzungen: Rust über rustup, just, Git, Docker und Helm. Pins stehen in rust-toolchain.toml und den Tool-Lockdateien. Die gemeinsame Basis kommt aus veröffentlichtem wuast-common; Betriebsverträge folgen rust-template.

just setup
just fmt
just gate
just docker-build
just runtime-check harbor.wuastbude.de/kumaste/operator:latest
just push

just gate führt Formatierung, strenges Clippy, die vollständige Testsuite, Dependencyprüfungen und Helm-Lint aus. Die Tests verwenden isolierte Kubernetes- und Kuma-Container mit eigenem Zustand. Sie prüfen Zustandsübergänge, reale CRUD-Nebenwirkungen, Referenzen, Drift, Wiederverbindung, Fehler und Prozessende. Normale App-Credentials oder produktive Ressourcen werden dabei nicht verwendet. just coverage misst zusätzlich auf ausdrücklichen Bedarf; Ergebnisse erscheinen im Terminal.

Cargo verwendet --locked und die Produktionsdefaults aus Cargo.toml. Gemeinsamer S3-/Docker-Cache unterstützt die Builds. just push reicht Git-Argumente weiter und entfernt nach erfolgreichem tatsächlichem Push ausschließlich das repo-eigene target/; externe Caches und Appdaten bleiben erhalten. Die Regeln und die Ausnahme für reine Dokumentationsänderungen stehen in AGENTS.md.

Veröffentlichung und Migration

Forgejo prüft nativ und veröffentlicht über die bestehende Releasehistorie. Conventional Commits bestimmen die nächste Version. Das Produktionsimage ist statisch, läuft als UID/GID 65532 auf scratch und enthält CA-Roots und Zeitzonendaten. Kandidatenruntime und unsignierte, digestgebundene Harbor-SBOM werden vor der Promotion geprüft. Das Helmchart wird weiterhin unter dem bestehenden OCI-Ziel veröffentlicht; die Version und appVersion werden beim Packaging gesetzt.

Der aktuelle Migrationsstand und die tatsächlich ausgeführten Nachweise stehen im Inventar und Abschlussbericht. docs/migration.md beschreibt die Abnahme und den Umgang mit Altcode. Ein veröffentlichtes Image allein ersetzt keinen vollständigen Funktionsnachweis.