---
name: deployments-strukturieren
description: Strukturiert OpenTofu-Deployments mit eigenen States, zusammengehörigen Modulen und klaren Schnittstellen für unabhängige Entwicklung sowie einzelne oder koordinierte Releases. Verwenden beim Aufteilen gewachsener Infrastruktur, beim Festlegen von Deployment-Grenzen oder beim Planen projektübergreifender Releases; nicht für eine blosse Gerüsterzeugung oder einen unveränderten Routine-Deploy.
---

# Deployments strukturieren

Schneide nach Verantwortung und Lebenszyklus. Ein Deployment darf mehrere
Module enthalten, die gemeinsam geändert, geprüft und betrieben werden.
Ein Modul benötigt nicht automatisch einen eigenen State oder ein Repository.

## Grundlage und Konvention

- [OpenTofu – Module Composition](https://opentofu.org/docs/language/modules/develop/composition/):
  Setze Module über explizite Eingaben zusammen und halte Abhängigkeiten sichtbar.
- [OpenTofu – Workspaces](https://opentofu.org/docs/cli/workspaces/):
  CLI-Workspaces allein ersetzen keine getrennten Konfigurationen und Backends
  für eigenständige Subsysteme.
- [OpenTofu – Remote State](https://opentofu.org/docs/language/state/remote-state-data/):
  Der Zugriff auf Outputs kann Zugriff auf den vollständigen fremden State
  voraussetzen. Prüfe deshalb die Berechtigungsgrenze.
- [GitLab – Downstream Pipelines](https://docs.gitlab.com/ci/pipelines/downstream_pipelines/):
  Projektübergreifende Pipelines können separate Deployments koordinieren.
  GitLab ist ein Beispiel, keine Voraussetzung.

Die folgende Arbeitskonvention trennt vier Begriffe: Repository für Entwicklung,
Modul für wiederverwendbare oder zusammengehörige Infrastruktur, Deployment für
Plan/Apply und State, Release für eine bewusst gewählte Menge von Versionen.
Verwende pro Deployment und Umgebung einen eigenen State mit eindeutiger
Backend-Adresse beziehungsweise eigenem State-Schlüssel. Ein gemeinsamer
Backend-Dienst ist erlaubt; separate Server sind nicht erforderlich.

## Vorgehen

1. Lies Projektregeln, vorhandene Roots, Module, Backend-Konfiguration,
   Pipelines und Ressourcenverantwortung rein lesend. Prüfe Arbeitsstände und
   den autorisierten Umfang. Gib keine Secrets oder vollständigen States aus.
2. Bestimme, was unabhängig geändert oder betrieben werden soll. Frage nur
   nach Grenzen, deren Unklarheit den Entwurf wesentlich verändert. Bewahre
   zusammengehörige Module in einer Deployment-Einheit; trenne gemeinsame
   Plattformressourcen nur bei eigenständiger Verantwortung oder Lebensdauer.
3. Erstelle eine Deployment-Landkarte in der vorhandenen Architekturdokumentation.
   Führe je Deployment Name, Root-Pfad, Module, Repository/Verantwortung,
   Umgebungen und State-Schlüssel, verwaltete Ressourcen, Eingaben/Ausgaben,
   Abhängigkeiten sowie Plan-, Apply- und Prüfeinstieg auf. Ein Monorepo mit
   mehreren Roots und mehrere Repositories sind gleichwertige Möglichkeiten.
4. Weise jede Ressource genau einem Deployment zu. Auch Namespace, gemeinsame
   Datenbank und Registry-Zugang haben einen eindeutigen Eigentümer. Beschreibe
   andere Verwendungen als Abhängigkeit, nicht als zweite Verwaltung. Halte
   Abhängigkeiten gerichtet und ohne Zyklen; zerlege Module nicht allein wegen
   ihrer Anzahl. Verwende weder CLI-Workspaces noch regelmässiges Targeting als
   Ersatz für eigenständige Deployment-Grenzen.
5. Definiere kleine, versionierbare Schnittstellen: Dienstadresse, Ressourcen-ID,
   Secret-Referenz oder kompatible API-Version. Bevorzuge gezielt veröffentlichte
   Konfiguration oder Provider-Abfragen, wenn das fremden State-Zugriff vermeidet.
   Prüfe bei Remote State dessen Rechte und Aktualität. Ein Output-Verweis
   orchestriert keinen fremden Apply. Speichere keine Secret-Werte in der
   Landkarte oder einem Release-Manifest; sichere sensible States und Pläne.
6. Lege für jedes Deployment einen eigenständig nutzbaren Ablauf fest: konkrete
   Versionen auswählen, Plan prüfen, denselben geprüften Plan anwenden und
   Bereitschaft sowie relevante Funktion prüfen. Fixiere auch Deployment-Code,
   Module/Charts und Provider; verwende für Container unveränderliche Digests.
   Bewahre bestehende Projektfreigaben und Installationsregeln.
7. Koordiniere gemeinsame Releases über ein kleines Manifest mit Umgebung,
   ausgewählten Deployments und exakten Versionen. Rufe dieselben Abläufe wie
   beim Einzelrelease auf. Führe unabhängige Einheiten parallel, abhängige erst
   nach erfüllten Voraussetzungen aus. Plane abhängige Einheiten nach Änderungen
   ihrer Eingaben neu; verwende keinen dadurch veralteten gespeicherten Plan.
8. Verwende für Einzel- und Gesamtrelease dieselbe deployment- und
   umgebungsspezifische Sperre über Apply und Nachprüfung. Backend-Locking allein
   schützt nicht den gesamten Release-Ablauf. Beachte bei mehreren Repositories,
   dass gleich benannte CI-Sperren nicht automatisch projektübergreifend wirken.
   Lege fest, wer Releases auslösen darf und wie kollidierende Aufträge warten.
9. Beschreibe Teilfehler ausdrücklich: bereits erfolgreiche Deployments bleiben
   sichtbar; abhängige Schritte stoppen. Definiere Wiederanlauf, erneute Planung
   und gegebenenfalls ein geprüftes Rollback. Versprich keine atomare Transaktion
   über mehrere States. Plane kompatible Übergangsversionen und gestufte
   Datenmigrationen; rolle irreversible Datenänderungen nicht automatisch zurück.
10. Erstelle bei bestehender Infrastruktur einen separaten Übergabeplan für den
    State: Ressourcen-Adressen vorher/nachher, Sicherung und Wiederherstellung,
    Schreibsperre der beteiligten Deployments und versionsgeeignetes Verfahren.
    Prüfe Quell- und Zielplan vor Wiederaufnahme des Betriebs auf unerwartetes
    Löschen/Neuanlegen und doppelte Zuständigkeit. Ein `moved`-Block innerhalb
    einer Konfiguration überträgt allein keine Ressource zwischen zwei States.
    Eine Ordneraufteilung ist noch keine State-Migration.
11. Prüfe am konkreten Entwurf mindestens Einzelrelease, gemeinsames Release,
    konkurrierende Auslösung, Teilfehler und Wiederanlauf. Prüfe bei Aufteilung
    zusätzlich den Erhalt bestehender Ressourcen. Nutze vorhandene Werkzeuge;
    führe ohne Auftrag weder Migration noch Deployment oder Installation aus.

## Ergebnis und Grenze

Liefere eine nachvollziehbare Deployment-Landkarte, Schnittstellen und einen
Einzel-/Gesamtrelease-Ablauf mit Prüfungen und Fehlerbehandlung. Kennzeichne
Annahmen und noch nicht praktisch geprüfte Schritte. Halte konkrete Umsetzung
und Freigaben in den vorhandenen Projektartefakten fest, ohne parallele Register
zu erfinden. Dauerhafte folgenreiche Entscheidungen können ein ADR benötigen.

Stoppe die Strukturierung, sobald genau ein überprüfbarer Umsetzungsschritt
klar ist. Dieser Skill ermächtigt nicht zum Umbau produktiver States. Erzwinge
weder zusätzliche Repositories noch einen Message-Broker, GitOps-Controller,
Terragrunt oder eine bestimmte CI-Plattform.

Verwende `opentofu-initialisieren` für ein neues technisches Gerüst. Dieser Skill
bestimmt dessen Grenzen und Release-Zusammenspiel, ersetzt aber keinen Generator.

## Fertig, wenn

- Zusammengehörige Module innerhalb eines Deployments erhalten bleiben.
- Jede Ressource genau einen Eigentümer und jede Umgebung eindeutige States hat.
- Schnittstellen, Versionen, Abhängigkeiten und Zugriffsgrenzen nachvollziehbar sind.
- Einzel- und Gesamtrelease dieselben Abläufe und wirksame Sperren nutzen.
- Teilfehler, Wiederanlauf und gegebenenfalls State-Übergabe überprüfbar sind.
- Freigabeumfang, tatsächliche Nachweise und offene Umsetzung klar bleiben.