Maintenance Mode

Der Maintenance Mode ermöglicht es, ein Product Deployment gezielt in den Wartungsmodus zu versetzen. Dabei werden alle Container gestoppt und alle Child-Stacks erhalten den Operation Mode „Maintenance”. So können Wartungsarbeiten wie Datenbank-Migrationen, Hardware-Updates oder geplante Downtimes sicher durchgeführt werden. Das Trigger-System stellt sicher, dass manuell aktivierter Maintenance nicht versehentlich durch den Observer aufgehoben wird.

Übersicht

Aspekt	Normal Mode	Maintenance Mode
Product Status	Running	Stopped
Stack Status	Running	Stopped
Operation Mode	Normal	Maintenance (propagiert auf alle Stacks)
Trigger	—	Manual oder Observer
Beenden	—	Nur durch den Trigger, der Maintenance aktiviert hat

Trigger-Ownership

Das zentrale Prinzip: Wer Maintenance aktiviert hat, kontrolliert auch das Ende.

• Manual Trigger: Maintenance wurde vom Benutzer über die UI oder API aktiviert. Nur der Benutzer kann Maintenance wieder beenden — der Observer hat keinen Einfluss.
• Observer Trigger: Maintenance wurde automatisch durch den Maintenance Observer aktiviert. Nur wenn der Observer wieder Normal meldet, wird Maintenance aufgehoben.

---

Schritt für Schritt: Maintenance Mode aktivieren

Schritt 1: Product Deployment öffnen

Navigieren Sie zur Product Deployment Detail-Seite. Im Normalzustand sehen Sie den Operation Mode: Normal in den Overview Cards und den Link Enter Maintenance in der Aktionsleiste.

---

Schritt 2: Bestätigungsseite prüfen

Klicken Sie auf Enter Maintenance. Sie werden zur Bestätigungsseite weitergeleitet, die Folgendes anzeigt:

• Produktname und Version
• Das Environment
• Alle betroffenen Stacks mit Service-Anzahl
• Eine Warnung, dass alle Container gestoppt werden

Prüfen Sie die betroffenen Stacks, bevor Sie bestätigen.

---

Schritt 3: Bestätigen und aktivieren

Klicken Sie auf Enter Maintenance Mode um zu bestätigen. ReadyStackGo:

1. Setzt den Product Operation Mode auf Maintenance
2. Propagiert Maintenance auf alle Child-Stacks
3. Stoppt alle Container

Nach erfolgreicher Aktivierung sehen Sie eine Erfolgsseite mit dem Mode-Übergang (Normal → Maintenance).

Maintenance Reason

Beim Aktivieren über die API kann optional ein Grund angegeben werden (z.B. „Scheduled database migration”). Dieser wird im Maintenance Info-Panel auf der Deployment-Detailseite angezeigt.

---

Schritt 4: Stacks während Maintenance

Auf der Product Deployment Detail-Seite zeigen alle Stacks den Status Stopped während Maintenance. Der Product Status zeigt ebenfalls Stopped mit einem Maintenance Badge.

---

Schritt 5: Maintenance Mode beenden

Klicken Sie auf Exit Maintenance um zur Bestätigungsseite zu navigieren. Diese zeigt die aktuelle Maintenance-Info (Trigger-Quelle, Grund, Dauer) und die Stacks, die neu gestartet werden.

Klicken Sie auf Exit Maintenance Mode um zu bestätigen. ReadyStackGo startet alle Container neu und versetzt das Produkt zurück in den Normalbetrieb.

Observer-Maintenance

Wenn Maintenance durch den Observer aktiviert wurde, kann es nicht manuell über die UI beendet werden. Der Exit-Link ist in diesem Fall nicht sichtbar. Maintenance wird erst aufgehoben, wenn die externe Quelle wieder Normal meldet.

---

Das Produkt benachrichtigen (Maintenance-Setter)

Standardmäßig ist die Maintenance-Integration read-only: Der Observer pollt ein Flag, das das Produkt setzt. Daraus entsteht eine Lücke — startet ein Operator die Wartung direkt in ReadyStackGo, erfährt das Produkt selbst nichts davon. Der optionale Maintenance-Setter schließt diese Lücke: Er ist das Spiegelbild zum Observer und propagiert einen RSGO-initiierten Wartungszustand aktiv ans Produkt — so kann das Produkt seine Clients vorwarnen/geordnet beenden, und sein eigenes Maintenance-Flag bleibt mit RSGO konsistent.

Der Setter wird pro Produkt im Manifest deklariert (maintenance.setter) und unterstützt zwei Typen:

Typ	Was er tut	Gut für
sqlExtendedProperty	Schreibt dieselbe SQL-Server-Extended-Property, die der Observer liest	Konsistenz von RSGO & SQL-Flag; funktioniert auch wenn das Produkt down ist
webhook	POST { "state": "maintenance" | "normal" }, HMAC-SHA256-signiert	Synchrone Produkt-Reaktion (z. B. Clients vorwarnen), solange es noch läuft

Wann er feuert:

• Eintritt in Maintenance: Setter schreibt maintenance vor dem Stoppen der Container.
• Rückkehr in Normal: Setter schreibt normal nach dem Neustart der Container.
• Ein optionales gracePeriod verzögert den Container-Stop, damit das Produkt seine Clients drainen kann.

Kein Feedback-Loop

Der Setter feuert nur bei manuellen/Operator-Übergängen — nie bei observer-getriggerten (dort hat das Produkt das Flag bereits gesetzt). Der SQL-Write ist idempotent, sodass Observer (lesen) und Setter (schreiben) sich nicht gegenseitig aufschaukeln können.

Best-effort & sicher

Setter-Fehler (DB nicht erreichbar, Webhook-Timeout/5xx) sind non-fatal: Sie werden geloggt und in der API-Antwort ausgewiesen, verhindern den Wartungsübergang aber nie. Webhook-Secrets werden nie geloggt, externe Webhook-URLs nie serverseitig gelesen (kein SSRF).

Die YAML-Felder sind in der Manifest-Format-Referenz dokumentiert.

---

API-Endpoint

Der Maintenance Mode kann auch über die REST API gesteuert werden:

PUT /api/environments/{environmentId}/product-deployments/{productDeploymentId}/operation-mode

Request Body

Feld	Typ	Pflicht	Beschreibung
mode	string	Ja	"Maintenance" oder "Normal"
reason	string	Nein	Optionaler Grund für die Wartung

Beispiele

Maintenance aktivieren:

{
  "mode": "Maintenance",
  "reason": "Scheduled database migration"
}

Maintenance beenden:

{
  "mode": "Normal"
}

HTTP Status Codes

Code	Bedeutung
200	Modus erfolgreich geändert
404	Product Deployment nicht gefunden
409	Transition blockiert — Trigger-Ownership verletzt (z.B. manuelles Beenden von Observer-Maintenance)

---

Fehlerbehandlung

Situation	Verhalten
Manuelles Exit bei Observer-Maintenance	Blockiert mit HTTP 409 — Observer kontrolliert das Ende
Produkt bereits im gewünschten Modus	Keine Aktion, erfolgreiche Rückgabe (No-Op)
Observer meldet Normal bei manuellem Maintenance	Keine Aktion — manueller Trigger hat Vorrang