Developer Good Practice

Plattformweite Grundsätze und Konventionen: Stages, Namensschema, Netz/Edge, Security, Arbeitsweise, Glossar.

Schnelleinstieg

Schnelleinstieg

Schnelleinstieg

Zielgruppe: Anwender und Betreuer · Stand: 06.11.2026

Dieses Buch sammelt die Grundsätze, die für alle Technologien und Teams der DEXPRO-Plattform gelten: Begriffe, Namen, Stages, Deployment, Netz, Secrets und Arbeitsweise. Die einzelnen Technologien haben eigene Bücher, die hierher verlinken.

Als Anwender möchte ich …

Als Betreuer möchte ich …

Weitere Bücher

Grundbegriffe

Grundbegriffe

Glossar

Zielgruppe: Anwender und Betreuer · Stand: 06.11.2026

Begriffe und Abkürzungen, die in der Plattform-Dokumentation immer wieder vorkommen. Andere Seiten verlinken hierher, statt sie jedes Mal zu erklären.

Abteilungen und Produkte

Begriff Bedeutung
CCI Cloud Core Infrastructure: Basis-Infrastruktur (VMs, Netz, Consul, OpenBao, Datenbanken)
CPI Container Platform Infrastructure
CPCS Container Platform Core Services: gemeinsame Dienste auf der Container-Plattform
CPDS Container Platform DEXPRO Services: DEXPRO-Produkte auf der Plattform
SBF Squeeze, Breeze, Freeze: der DEXPRO-Produkt-Stack
SQUEEZE DEXPRO-Produkt SQUEEZE
BREEZE Hosting von Otris DOCUMENTS / documentsOS
FREEZE Hosting von Otris EAS/EDA (Archiv)

Umgebungen

Begriff Bedeutung
Stage Ausbaustufe eines Deployments: pre-development, development, staging, production (siehe Stages und Branches)
Lab Testumgebung für den Plattformbetrieb am Standort Bremen 1. Nicht für Abteilungen gedacht
Lab-PoC Proof of Concept im Lab: funktioniert dort, ist aber noch nicht für DEV oder Produktion freigegeben
DEV Entwicklungsumgebung, die Abteilungen nutzen
Standort Rechenzentrum, z. B. bremen1, nuernberg1, frankfurt1; in Hostnamen abgekürzt (bre1)

Bausteine

Begriff Bedeutung
Stack Deployment-Repo, das eine konkrete Umgebung baut, z. B. bremen1/consul-servers
Modul wiederverwendbares Terraform-Modul, z. B. terraform-modules/proxmox/consul
Rolle Ansible-Rolle, die ein Modul auf den Hosts ausführt
CI-Component gemeinsame GitLab-Pipeline für alle Deployment-Repos (ci-components/deployment)
Promotion Weitergabe eines Commits von einer Stage zur nächsten
Edge Eingangstor von außen (Load Balancer/Reverse Proxy). Oberflächen für Menschen laufen darüber, interne Dienste nie

Werkzeuge

Begriff Bedeutung
OpenBao Secret-Store und Zertifizierungsstelle der Plattform (siehe Buch OpenBao)
Bitwarden Passwort-Tresor. Für Secrets nur noch Übergang bzw. Bootstrap
GitLab-JWT signierter Ausweis einer Pipeline, mit dem sie sich ohne gespeichertes Passwort anmeldet
OIDC / Entra ID Anmeldung von Menschen mit dem DEXPRO-Konto
SG Security Group: Sicherheitsgruppe in Entra ID, über die Rechte vergeben werden. Muster SG-<ABT>-<Team>
Consul Service-Discovery und Konfigurationsspeicher der Plattform
Nomad Orchestrierung der Container-Plattform
Grundbegriffe

Abteilungen, GitLab-Gruppen und Teams

Zielgruppe: Anwender und Betreuer · Stand: 06.11.2026

Die Plattform ist in vier Abteilungen gegliedert. Jede Abteilung ist eine GitLab-Gruppe, und ihr Kürzel taucht überall wieder auf: in OpenBao, in Entra-Gruppen und in Nomad. Wer weiß, zu welcher Abteilung und welchem Team ein Projekt gehört, kann die meisten Namen ableiten.

Abteilungen

Kürzel GitLab-Gruppe Teams
cci cloud-core-infrastructure ein Team (gegliedert nach Standort und Projekt)
cpi container-platform-infrastructure laut Teamliste
cpcs container-platform-core-services laut Teamliste
cpds container-platform-dexpro-services ai, breeze, freeze, peppol, squeeze

Das Kürzel ist immer der letzte Teil des GitLab-Gruppenpfads in Kleinbuchstaben.

Teams

Ein Standort wie bremen1 ist kein Team. Er erscheint nur bei CCI im Pfad.

Weiterführend

Grundbegriffe

Abgeleitete Namen

Zielgruppe: Anwender und Betreuer · Stand: 06.11.2026

Aus Abteilung und Team ergeben sich alle Namen nach festen Mustern. Niemand muss sie sich ausdenken: Die Teamliste ist die einzige Quelle, und Terraform erzeugt daraus Rollen, Policies und Gruppen.

Muster

Was Muster Beispiel
Entra-Gruppe (Security Group) SG-<ABT>-<Team> SG-CPDS-breeze
OpenBao-Mount <abt>/ cpds/
OpenBao-Policy <abt>-<team> cpds-breeze
JWT-Rolle (Pipelines) <abt>-<team>-ci cpds-breeze-ci
Nomad-Namespace <abt>-<team> cpds-breeze
Secret-Pfad <abt>/<team>/<stage>/… cpds/breeze/development/…

Für CCI gelten Standort und Projekt statt Team, z. B. Secret-Pfad cci/<standort>/<stage>/<projekt>/… (siehe Pfadschema und Teamtrennung).

Hostnamen

Hosts heißen <kürzel>-<cluster>-<standort>-<nr>, z. B. cs-002-bre1-01 (Consul-Server, Cluster 002, Bremen 1, Knoten 1). Häufige Kürzel:

Kürzel Dienst
cs / cl Consul-Server / -Client
ns / nc Nomad-Server / -Client
ng Nomad-Client mit GPU
ob OpenBao
edge Edge-Router

Der interne Domain-Suffix ist .dexpro.parts. Dienste für Menschen laufen unter *.<umgebung>.<standort>.dexpro.services, z. B. *.lab.bre1.dexpro.services.

Stolperfallen

Weiterführend

Stages und Umgebungen

Stages und Umgebungen

Stages und Branches

Zielgruppe: Anwender und Betreuer · Stand: 06.11.2026

Jedes Deployment-Repo kennt vier Stages, und jede Stage ist ein eigener Branch. Ein Commit wandert von Stage zu Stage. Ob er weiterwandert, entscheiden feste Gates: mal manuell, mal automatisch.

Die vier Stages

Stage = Branch Zweck Weiter zur nächsten Stage
pre-development Einstieg, Default-Branch; im Lab die einzige Stage manuell (promote-next-branch)
development Entwicklungsumgebung automatisch
staging Abnahme vor Produktion manuell (approve-and-promote-production)
production Produktion –

Stages ein- und ausschalten

Wie die Stage an anderen Stellen heißt

Ort Schreibweise
Branch, OpenBao-Pfad, Terraform (TF_VAR_deployment_stage) pre-development, development, staging, production
Maschinen-Module (VM-Variable stage) nur dev, mngmt, prd. Lab-VMs laufen als dev, staging läuft mit prd
Consul-KV und Namen im Lab lab, z. B. services/lab/…

Das sind drei Vokabulare für ähnliche Dinge. Für Secret-Pfade gilt immer der Branch-Name. lab, dev oder prd im OpenBao-Pfad findet keine Pipeline.

Weiterführend

Stages und Umgebungen

Lab, DEV und Produktion

Zielgruppe: Anwender und Betreuer · Stand: 06.11.2026

Die Plattform wird am Standort Bremen 1 neu aufgebaut. Zuerst entsteht alles im Lab als Proof of Concept. Erst danach folgen DEV und Produktion, und die alten Umgebungen werden abgelöst.

Die Umgebungen

Umgebung Für wen Stand
Lab nur Plattformbetrieb (Betreuer) Neuaufbau läuft (Consul, OpenBao, Edge, Datenbanken, Nomad)
DEV (neu) Abteilungen und Teams geplant, entsteht nach dem Lab-PoC
Produktion (neu) Kunden geplant
Bestand (alte DEV/PRD) laufender Betrieb wird nach dem Lab-PoC abgelöst

Regeln

Unterschiede Lab und DEV

Thema Lab DEV
Datenbanken (OpenSearch, MongoDB, Journal/Index) dürfen im Nomad-Cluster laufen laufen außerhalb von Nomad
Menschen-Login an OpenBao Admin-Token OIDC mit Entra ID
Stages nur pre-development alle vier
Repo-Namen enthalten lab, z. B. bremen1/lab-edge-routers ohne lab

Dienste im Lab sind unter *.lab.bre1.dexpro.services erreichbar.

Weiterführend

Deployment

Deployment

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

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

Weiterführend

Deployment

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.

Weiterführend

Deployment

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

Terraform-Module

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.

Weiterführend

Deployment

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

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

Weiterführend

Netz

Netz

Edge-Grundsatz

Zielgruppe: Anwender und Betreuer · Stand: 06.11.2026

Der Edge ist das Eingangstor für Menschen. Oberflächen und Dashboards bekommen dort einen eigenen Hostnamen. Maschinen sprechen intern miteinander und nie über den Edge.

Regeln

Ein interner Dienst, der über den Edge erreichbar ist, ist von außen angreifbar. Im Zweifel bleibt ein Dienst intern.

Vorgehen: Oberfläche veröffentlichen

  1. Hostnamen unter der Wildcard der Umgebung wählen.
  2. Bei Diensten in Nomad oder Consul: Route über Tags im Consul-Katalog definieren. Der Edge übernimmt sie automatisch. Wie das geht, steht in Router per Consul-Tags definieren. Ob der Weg direkt oder über den internen Ingress läuft, erklärt Dienst veröffentlichen: Edge oder interner Ingress.
  3. Prüfen, dass die Oberfläche eine Anmeldung hat. Der Edge ersetzt keine Authentifizierung.

Stolperfallen

Weiterführend

Netz

Firewall-Freigaben anfragen

Zielgruppe: Anwender · Stand: 06.11.2026

Zwischen den Netzen (z. B. von den GitLab-Runnern zu Diensten im Lab) filtert eine Firewall. Fehlt eine Freigabe, scheitern Pipelines oder Dienste mit Timeouts. So bekommst du eine Freigabe.

Vorgehen

  1. Verbindung genau beschreiben: Quelle (Host bzw. Gruppe, z. B. „GitLab-Runner“), Ziel (Hostname), Port und Protokoll (TCP/UDP), Zweck.
  2. Nur das Nötigste anfragen: einzelne Ports, keine Bereiche „zur Sicherheit“.
  3. Die Freigabe beim Netzteam bzw. den Betreuern beantragen. Firewall-Regeln setzen nur sie.
  4. Nach der Freigabe die Verbindung testen.

Prüfen

nc -vz <ziel-hostname> <port>

„succeeded“ bzw. „open“ heißt: Die Freigabe wirkt.

Stolperfallen

Weiterführend

Netz

Dienst veröffentlichen: Edge oder interner Ingress

Zielgruppe: Anwender und Betreuer · Stand: 06.11.2026

Du willst einen Dienst erreichbar machen und fragst Dich, ob das über den Edge oder den internen Ingress läuft. Diese Seite erklärt den Unterschied und zeigt die Wege. Wie Du Tags und Router konkret schreibst, steht in den Büchern Traefik und Consul.

Erst klären: Wer greift zu?

Edge und interner Ingress

Edge Interner Ingress
Was Traefik-Paar auf eigenen VMs mit VIPs Traefik als Nomad-Job im Cluster
Aufgabe Eingangstor: Hostnamen, Zertifikate, Allowlists, öffentliche Entrypoints verteilt Anfragen im Cluster weiter an Dienste im Mesh
Erreichbar über die VIPs der Umgebung (intern bzw. öffentlich) nur vom Edge, über Consul Connect (mTLS), ohne feste Ports 80/443
Routen kommen aus Tags im Consul-Katalog und Dateien der Rolle traefik der Konfiguration im Nomad-Job des Ingress
Zertifikate Let's Encrypt am Edge keine eigenen, die TLS-Verbindung endet am Edge

Wichtig: Der interne Ingress ist kein zweiter Eingang. Jede Anfrage von Menschen kommt zuerst am Edge an.

Die Wege für einen Dienst

A: Dienst auf einer VM. Der Dienst registriert sich im Consul-Katalog mit Traefik-Tags, der Edge routet direkt dorthin.

Browser → Edge → Dienst

B: Nomad-Dienst direkt vom Edge. Der Dienst hängt im Mesh und trägt traefik.consulcatalog.connect=true. Der Edge spricht ihn per Connect an. Ein Beispiel ist Grafana im Lab.

Browser → Edge → Connect → Dienst

C: Nomad-Dienst über den internen Ingress. Der Ingress trägt die Tags für den Edge und leitet per Connect-Upstream an den Dienst weiter. Ein Beispiel ist der Demo-Dienst im Namespace cpi im Lab.

Browser → Edge → Connect → interner Ingress → Connect → Dienst

Welchen Weg Dein Nomad-Dienst nimmt (B oder C), stimmst Du mit den Betreuern ab.

Vorgehen

  1. Klären, ob ein Mensch oder ein Dienst zugreift (siehe oben). Für Dienste ist hier Schluss: Sie bleiben intern.
  2. Hostnamen unter der Wildcard der Umgebung wählen. Lab-PoC: *.lab.bre1.dexpro.services.
  3. Dienst im Consul-Katalog registrieren: Dienst im Consul-Katalog registrieren.
  4. Router-Tags setzen, bei Weg C am Ingress statt am Dienst: Router per Consul-Tags definieren.
  5. Bei Weg B und C die Intentions bei den Betreuern anfragen: Edge → Dienst bzw. Edge → Ingress und Ingress → Dienst.
  6. Prüfen, dass die Oberfläche eine eigene Anmeldung hat.

Stolperfallen

Öffentlich (Entrypoint public) ist ein Dienst nur nach Absprache mit den Betreuern. Ein interner Dienst, der über den Edge erreichbar ist, ist angreifbar.

Weiterführend

Secrets und Security

Secrets und Security

Secrets-Grundsätze

Zielgruppe: Anwender und Betreuer · Stand: 06.11.2026

Ein Secret, das einmal in einem Log, einem Ticket oder einem Commit stand, gilt als bekannt und muss rotiert werden. Diese Grundsätze verhindern das.

Regeln

Taucht ein Secret doch in einem Job-Log auf: Fehler beheben, Secret rotieren und danach das Log löschen. In dieser Reihenfolge.

Stolperfallen

Weiterführend

Secrets und Security

Wohin mit Secrets

Zielgruppe: Anwender und Betreuer · Stand: 06.11.2026

Neue Secrets gehören nach OpenBao. Bitwarden bleibt nur für den Übergang und für die Zugänge, die OpenBao selbst aufbauen.

Wohin

Secret Ablage
Zugänge und Passwörter für Deployments und Dienste OpenBao, Pfad nach Abteilung, Team und Stage
Von Terraform erzeugte Passwörter OpenBao (Umstellung der Module läuft per Schalter)
Zugänge des Stacks, der OpenBao baut Bitwarden, dauerhaft
Bestehende Secrets, die noch nicht umgezogen sind Bitwarden, bis zum Umzug

Wie Secrets entstehen

OpenBao gibt es bisher nur im Lab. Dort entstehen Secrets bis zur DEV-Umgebung nur über Pipelines.

Weiterführend

Arbeitsweise

Arbeitsweise

Testen ohne Risiko

Zielgruppe: Anwender und Betreuer · Stand: 06.11.2026

Tests sollen Fehler finden, nicht verursachen. Deshalb laufen sie dort, wo nichts kaputtgehen kann.

Regeln

Ein Test mit echten Modulen gegen eine falsche Zielgruppe löscht echte Daten. Vor jedem Lauf prüfen, gegen welche Hosts er geht.

Weiterführend

Arbeitsweise

Freigaben

Zielgruppe: Anwender und Betreuer · Stand: 06.11.2026

Manche Aktionen lassen sich nicht zurücknehmen. Für sie gilt: erst zeigen, was passiert, dann ausdrücklich freigeben lassen, dann ausführen.

Was eine Freigabe braucht

Wie eine Freigabe aussieht

  1. Konkret: was genau, wo (Repo, Branch, Stage, Host) und mit welcher Wirkung (Plan, Liste der betroffenen Objekte).
  2. Ausdrücklich: Ein „klingt gut“ zu einem Plan ist keine Freigabe zum Mergen. Eine Freigabe für den Merge deckt keine anschließende Promotion.
  3. Einmalig: Eine Freigabe gilt für die gezeigte Aktion, nicht für ähnliche später.

Stolperfallen

Löschen nur über eine eindeutige ID, nie über eine Namenssuche. Gleichnamige Objekte in anderen Umgebungen werden sonst mitgelöscht.

Weiterführend