Deployment

• Deployment-Repo mit der CI-Component
• Merge heißt Deploy
• Rollen und Module versionieren
• Repo-Struktur

Deployment-Repo mit der CI-Component

Zielgruppe: Anwender und Betreuer · Stand: 06.11.2026

Alle Terraform/OpenTofu-Deployments laufen über dieselbe GitLab-CI-Component. Ein Deployment-Repo bindet sie ein und bekommt damit Stages, Promotion, Freigaben, Destroy und die Ansible-Umgebung, ohne eigene Pipeline-Logik.

Voraussetzungen

• Das Repo liegt in der GitLab-Gruppe deiner Abteilung.
• Du hast mindestens die Rolle Reporter im Projekt cloud-core-infrastructure/ci-components/deployment. Die Component ist privat.
• Die vier Stage-Branches existieren und sind geschützt (siehe Stages und Branches).

Vorgehen

1. .gitlab-ci.yml auf das include der Component reduzieren:

   include:
     - component: $CI_SERVER_FQDN/cloud-core-infrastructure/ci-components/deployment/terraform@<version>
       inputs:
         enabled-stages: "development,staging"
         root-config: proxmox
   

   • <version>: immer eine feste Version bzw. einen SHA, nie einen Branch

2. Keine eigenen stages: und keinen workflow: definieren. Eigene Jobs nutzen extends: .deployment:base.

3. Projekt einrichten: scripts/setup-project.sh <projekt> aus dem Component-Repo legt Trigger-Token, Push-Rechte und den Default-Branch pre-development an.

4. Bei root-config: proxmox gehört die erzeugte deployment.generated.tf in die .gitignore. Backend und Standard-Provider bringt die Component dann mit.

5. Braucht das Repo Secrets aus OpenBao: openbao-jwt-role und openbao-addr setzen (siehe Pipeline per GitLab-JWT anmelden).

Prüfen

Die Pipeline auf pre-development zeigt die Jobs plan, apply-freigeben und deploy. Der Plan ist im Job-Log lesbar.

Stolperfallen

• Neue Component-Versionen können Inputs entfernen (z. B. promote-development). Beim Anheben des Pins die Inputs gegen die README prüfen.
• Ansible läuft immer aus Terraform heraus (terraform_data mit local-exec), nie als eigener Job.
• Den SSH-Schlüssel für Ansible liefert eine geschützte Gruppenvariable. Deshalb müssen alle Stage-Branches geschützt sein.

Weiterführend

• README der CI-Component
• Merge heißt Deploy

Merge heißt Deploy

Zielgruppe: Anwender und Betreuer · Stand: 06.11.2026

Ein Merge auf einen Stage-Branch ist kein Code-Review-Abschluss, sondern der Start eines Deployments. Je nach Pin der CI-Component wird sofort angewendet oder erst nach einem Klick. Und je nach Repo wandert der Commit danach weiter in die nächste Stage.

Behandle jeden Merge auf pre-development, development, staging oder production wie ein Deployment. Sieh dir den Plan an, bevor du mergst.

Was ein Merge auslöst

Aktuelle Component (mit Freigabe-Gate):

1. plan plant und legt den Plan geschützt ab.
2. apply-freigeben wartet auf einen manuellen Klick.
3. deploy wendet genau diesen Plan an.

Ältere Pins (ohne Gate): Ein Merge auf pre-development plant und wendet sofort an, ohne Klick.

Promotion: Danach wandert der Commit nach den Regeln der Kaskade weiter. Bei älteren Pins ging das bis development und staging automatisch, z. B. bei den Breeze- und Freeze-Project-Deployern. Mit der aktuellen Component ist der Schritt nach development manuell.

Vorgehen vor einem Merge

1. Den Pin der Component im Repo prüfen: Gibt es apply-freigeben?
2. Den Plan gegen den Ziel-State ansehen (MR-Pipeline oder ein Lauf nur mit Plan).
3. Auf unerwartete Replaces achten. Drift durch neue Modul- oder Rollenversionen läuft im selben Apply mit.
4. Mehrere MRs im selben Repo nacheinander mergen, dazwischen rebasen und neu planen.
5. Bei Repos mit Promotion klären, ob die Änderung weiterwandern soll.

Stolperfallen

Ein Merge, der „nur etwas hinzufügt“, kann trotzdem Replaces anwenden, wenn sich seit dem letzten Lauf Module oder Rollen geändert haben.

• -o ci.skip verhindert nur die Pipeline des Branch-Pushs, nicht die nach dem Merge.
• MR-Pipelines mit OpenBao-Anbindung planen nicht. Den Plan liefert dann erst die Pipeline auf dem Stage-Branch vor dem Gate.

Weiterführend

• Deployment-Repo mit der CI-Component
• Stages und Branches

Rollen und Module versionieren

Zielgruppe: Betreuer · Stand: 06.11.2026

Terraform-Module und Ansible-Rollen werden unterschiedlich versioniert. Module haben Versionslinien, Rollen nur zwei Branches. Kompatibilität entsteht immer im Modul, nie in der Rolle.

Ansible-Rollen

• Zwei Branches: latest (Default, Entwicklung) und stable (Konsum). Es gibt keine Tags.
• Module binden Rollen immer auf stable.
• Eine Rolle bekommt keine Aliase oder Fallbacks für alte Variablennamen.

Terraform-Module

• Versionslinien als Branches <major>.<minor>, z. B. 0.3. Jeder Merge in den Linien-Branch veröffentlicht die nächste Patchversion.
• Stacks pinnen eine Linie, z. B. ~> 0.3.1 bzw. >= 0.3.1, < 0.4.0.
• Ein inkompatibler Umbau bekommt eine neue Linie (z. B. 0.2 → 0.3). Die alte Linie bleibt für den Bestand.
• Die gerenderten Ansible-Requirements (requirements.*.yml) erzeugt ein CI-Job im Modul. Er pusht selbst einen Commit.

Kompatibilität bei Umbenennungen

1. Die Rolle benennt Variablen einfach um, ohne Alias.
2. Das Modul übergibt alte und neue Namen nebeneinander an das Playbook.
3. Geht das nicht, entsteht eine neue Modul-Linie.
4. Modul-MRs werden gemergt, bevor die Rolle auf stable kommt.

Globale Kontext-Variablen (site, stage, role_slug, state, checkmk_server) bleiben ohne Präfix.

Stolperfallen

Das Anlegen eines neuen Linien-Branches veröffentlicht sofort X.Y.0 mit dem Inhalt der Vorgängerlinie. Diese Version nicht verwenden, erst ab X.Y.1 pinnen.

• Ein Modul, das eine Rolle auf einen Feature-Branch pinnt, hängt an diesem Branch. Den Branch nicht löschen oder force-pushen, bevor das Modul umgestellt ist.
• Nach einer Änderung an CI-Variablen auf den Folgecommit des Requirements-Jobs achten.

Weiterführend

• Merge heißt Deploy

Repo-Struktur

Zielgruppe: Anwender und Betreuer · Stand: 06.11.2026

Jeder Nomad-Job und jeder Infrastruktur-Stack bekommt ein eigenes Repository in der Gruppe seiner Abteilung. Nichts lebt nur lokal oder als Unterordner in einem fremden Repo.

Regeln

• Ein Repo je Nomad-Job, z. B. container-platform-core-services/nomad-jobs/pilot-graylog. Ein Job ist oft ein ganzer Stack aus mehreren Diensten: Er enthält dann mehrere Groups und darin mehrere Tasks. Zusammengehörige Dienste stehen deshalb als Groups und Tasks in einem Job, nicht in getrennten Repos. Diese Regel ist Good Practice und wird nicht technisch erzwungen. Wie ein Dienst auf Jobs und Repos aufgeteilt wird, entscheidet der jeweilige Software-Betreuer.
• Ein Repo je Infrastruktur-Stack (Terraform, Umgebung eines Standorts), z. B. cloud-core-infrastructure/bremen1/consul-servers.
• Lab-Repos tragen lab im Namen (z. B. bremen1/lab-edge-routers), deployen nur pre-development und promoten nicht.
• Wiederverwendbares gehört in Module (terraform-modules/…) bzw. Rollen (ansible/roles/…), nicht in Stacks.
• Default-Branch ist pre-development (Rollen: latest).

Konfiguration, die nur auf einem Rechner oder Server liegt, geht verloren. Auch Testkonfigurationen gehören in ein Repo.

Weiterführend

• Abteilungen, GitLab-Gruppen und Teams
• Rollen und Module versionieren