Pipelines und Workflows¶

Jedes Deployment läuft aus einer Entry Pipeline im Konfigurations-Repository: Azure-DevOps-YAML unter pipelines/ oder ein GitHub-Actions-Workflow unter .github/workflows/. Entry Pipelines sind schlank. Sie übergeben ein paar Parameter an ein wiederverwendbares Template im Code-Repository, und dieses Template ruft das Modul Xebia.Mcp auf. Azure DevOps und GitHub Actions sind funktional identisch gehalten (docs/PIPELINE_SYNCHRONIZATION.md und .github/workflows/COUNTERPARTS.md im Code- Repository).

Entry Pipelines¶

Entry (ADO `pipelines/` und GitHub `.github/workflows/`)	Ruft Template auf (Code-Repository)	Verwenden für
`hub.yaml`	ADO `.azure-devops/pipelines/templates/stage-mcp-hub.yaml`, GitHub `.github/workflows/stage-mcp-hub.yaml`	Jede hub-Änderung: firewall, App Gateway, Policies, Features, Tags, management groups
`hub-destroy.yaml`	dasselbe, mit `destroy: true`	Einen hub abbauen (im Referenz-Repository nur canary)
`spoke.yaml`	`stage-mcp-spoke.yaml`	spokes erstellen oder ändern
`spoke-destroy.yaml`	`stage-mcp-spoke.yaml`, mit `destroy: true`	spokes löschen
`infrastructure.yaml`	`stage-infrastructure.yaml`	Die Job Runner deployen oder aktualisieren
`container.yaml`	`stage-container.yaml`	Das `mcp` container image bauen

Das Code-Repository enthält außerdem:

update-spn.yaml: speichert und rotiert das Secret des Deployment-SPN im hub Key Vault;
test.yaml: Stresstest der runner;
pull-request.yaml (ADO) und ci.yml (GitHub): CI für den Code selbst, siehe Neue Funktionalität bauen;
report-version.yaml (nur Azure DevOps, zeitgesteuert): meldet die gepinnte Code-Version der Kunden-Repositories an die Plattform-Status-API (scripts/version-watcher);
trigger-sync.yaml (nur GitHub): synchronisiert den Code zu den Kunden-Remotes, siehe Releasing und Code-Synchronisierung.

Welche Plattformumgebung steuert jeder Entry an?

Jeder Entry übergibt pro Stage oder Job eine mcp.json. Prüfe das vor dem Lauf, besonders bei den spoke Pipelines: spoke-destroy muss dieselbe mcp.json verwenden wie der spoke-Lauf, der den spoke erstellt hat. Im Referenz- Konfigurations-Repository zielt spoke.yaml auf prod, während spoke-destroy.yaml auf canary zielt.

Parameter, die du ändern wirst¶

Das sind Template-Parameter. Im Referenz-Konfigurations-Repository sind die meisten davon in der Entry-YAML fest eingetragen. Um einen zu ändern, bearbeite die Entry-Datei in einem pull request oder stelle ihn als Laufzeitparameter bereit (siehe mode und whatIf zur Laufzeit bereitstellen).

Parameter	Werte	Wirkung
`mode`	`Plan`, `Apply`, `ApproveModifications`, `ApproveDestroys`	`Plan` plant nur. `Apply` plant und wendet an, ohne anzuhalten. `ApproveModifications` hält für eine Genehmigung an, wenn ein Plan irgendein Create, Update oder Delete enthält. `ApproveDestroys` hält nur an, wenn der Plan etwas löscht.
`whatIf`	`true`, `false`	`true`: Terraform plant weiterhin, aber der Apply-Schritt wird übersprungen. Siehe die spoke-Ausnahme unten.
`approveLayers` (nur hub)	Liste von Layer-Namen, Standard `[]`	Beschränkt Genehmigungen auf diese Layer. Leer bedeutet, dass jeder Layer eine Genehmigung erfordern kann.
`destroy`	`true`, `false`	Plant und wendet ein Destroy an. Wird von den `*-destroy`-Entry-Dateien gesetzt.
`spokeGlob` (nur spoke)	Wildcard-Muster, relativ zu `<env-folder>/spokes/`	Wählt die spoke-Dateien aus, z. B. `team-a/canvas_app1_dev.json` oder `team-a/*`. Ohne Beachtung der Groß-/Kleinschreibung.
`environments` (nur spoke)	geordnete Liste von spoke-Umgebungen	Welche spoke-Umgebungen laufen und in welcher Reihenfolge. Eine passende Datei, deren `environment` nicht in der Liste steht, lässt den Config-Test fehlschlagen.
`imageRef`	z. B. `mcp:latest`	Der Tag des container image, in dem die Jobs laufen.

spoke-Ausnahme für whatIf

Der spoke-subscription-Layer wird im Plan-Schritt immer geplant und angewendet, auch mit whatIf: true (Invoke-XebiaSpokePlanAction.ps1). Nur der spoke-canvas-Layer beachtet whatIf. Derzeit erstellt der subscription-Layer nur dann einen Subscription-Alias, wenn azureSubscriptionId leer ist.

Vor dem Lauf prüfen

Im Referenz-Konfigurations-Repository (xms-cloud-platform-config) verwendet hub.yaml mode: Apply mit whatIf: false, sodass canary und prod ohne Genehmigung angewendet werden. spoke.yaml verwendet mode: Apply mit whatIf: true, plant also nur das spoke canvas. Entscheide, welches Verhalten du willst, und passe die Entry-Dateien an, bevor du dich darauf verlässt.

Was ein hub-Lauf macht¶

Prepare. Führt die Unit-Tests und die Config-Tests (Pester) aus:
- firewall-JSON gegen src/Xebia.Mcp/Files/json/firewallschema.json, IP-group-Referenzen und Prioritäten;
- App-Gateway- und WAF-JSON gegen ihre Schemas;
- die DNS-Baseline.
Außerdem baut es die Region-Matrix auf. Ein fehlschlagender Config-Test stoppt den Lauf, bevor Terraform startet. 2. Für jeden Layer, in der Layer-Reihenfolge: 1. <layer>_plan: terraform plan. Die Plan-Datei und eine JSON-Zusammenfassung werden als Artefakte veröffentlicht <layer>_<region>_<level> und <layer>_<region>_<level>_json. Die Zusammenfassung erscheint als Warnung: Plan: X to add, Y to change, Z to destroy. 2. <layer>_analyse und <layer>_approve: nur in den Approve*-Modi. Sie pausieren für eine Genehmigung, wenn der Plan zum Modus passt. 3. <layer>_apply: wendet die gespeicherte Plan-Datei an, sodass genau das angewendet wird, was du genehmigt hast. Im Plan-Modus übersprungen. 3. Clean: gibt die Reservierung des runner frei.

Ein Plan, der Ressourcen löscht, markiert den Plan-Task als Succeeded with issues (orange). Nimm das als Signal, den Plan zu lesen.

Was ein spoke-Lauf macht¶

Wie du Identität, service connections, Code-Zugriff und Integrationen für spoke-Deployments vorbereitest, steht in Die spoke-pipeline vorbereiten und Spoke-Integrationen vorbereiten.

Prepare: führt die Unit-Tests und die hub-Config-Tests aus (ein kaputtes firewall-JSON blockiert also auch spoke-Läufe), danach die spoke-Config-Tests. Es findet *.json unter <env-folder>/spokes/, die zu spokeGlob passen, und gruppiert sie nach spoke- Umgebung. Der Lauf schlägt fehl, wenn:
- der Glob keine Datei trifft;
- eine passende Datei nicht gültig gegen spokeschema.json ist;
- das environment einer passenden Datei nicht in environments steht;
- die managementGroupId einer passenden Datei keine id in <env-folder>/<targetRegions.primary>/foundation.auto.tfvars ist.
Pro spoke-Umgebung, in der Reihenfolge von environments, und erst nachdem die vorherige erfolgreich war oder übersprungen wurde:
1. Plan: plant und wendet an den subscription-Layer und plant dann das spoke canvas.
2. Analyse und Approve: nur Approve*-Modi.
3. Apply: wendet den Plan des spoke canvas an.
Clean.

Was der Apply erstellt, steht in Spoke canvas. Ob ein spoke danach noch zu seiner Datei passt, siehst du in Configuration drift detection.

Genehmigungs-Gates¶

Wie die Entscheidung getroffen wird:

Hub: pro Layer liest der Analyse-Schritt die Plan-Zusammenfassungen der Regionen dieses Layers und fordert eine Genehmigung an, wenn ein Plan zum Modus passt (Invoke-XebiaHubAnalyseAction.ps1). Prüfe die bekannten Probleme: In der Version, die du pinnst, liest der Analyse-Schritt möglicherweise nur die Zusammenfassung der letzten Region.
Spoke: ein Analyse-Schritt pro spoke-Umgebungs-Stage. Er liest jede in diesem Lauf heruntergeladene Plan-Zusammenfassung, einschließlich der Pläne des subscription-Layers und früherer Umgebungen. Die Genehmigung erfolgt daher pro Umgebungs-Stage, nicht pro spoke.

Wo du genehmigst:

Azure DevOps: Der Job <layer>_approve ist ein ManualValidation@1-Server-Job. Das Template setzt weder approvers noch notifyUsers, daher wird niemand benachrichtigt. Behalte den Lauf im Blick.
GitHub Actions: Der Genehmigungs-Job verwendet das GitHub environment approval-required. Lege dieses environment im Konfigurations-Repository an und füge Required Reviewers hinzu. Ohne Reviewer läuft der Job weiter, ohne zu warten.

mode und whatIf zur Laufzeit bereitstellen¶

Azure DevOps (pipelines/hub.yaml):

parameters:
  - name: mode
    type: string
    default: Plan
    values: [Plan, Apply, ApproveModifications, ApproveDestroys]
  - name: whatIf
    type: boolean
    default: false

stages:
  - template: .azure-devops/pipelines/templates/stage-mcp-hub.yaml@mcp-code
    parameters:
      # ...existing parameters...
      mode: ${{ parameters.mode }}
      whatIf: ${{ parameters.whatIf }}

GitHub Actions (.github/workflows/hub.yaml):

on:
  workflow_dispatch:
    inputs:
      mode:
        type: choice
        options: [Plan, Apply, ApproveModifications, ApproveDestroys]
        default: Plan

jobs:
  canary:
    uses: xmms/xms-cloud-platform-code/.github/workflows/stage-mcp-hub.yaml@release/v4.12
    with:
      # ...existing inputs...
      mode: ${{ inputs.mode }}

Mach auf beiden Plattformen dasselbe, um die Parität zu wahren.

Eine Pipeline ausführen¶

Azure DevOps: Pipelines → die Entry Pipeline (zum Beispiel hub) → Run pipeline → den Branch wählen → die Parameter ausfüllen (zum Beispiel spokeGlob) → Run. Öffne einen Plan-Job, um den Terraform-Plan zu lesen, oder lade das Plan-Artefakt herunter.

GitHub Actions: Actions → der Workflow (zum Beispiel spoke) → Run workflow → den Branch wählen → die Inputs ausfüllen → Run workflow. Die Plan-Ausgabe steht in den Job-Logs und den hochgeladenen Artefakten.

Voraussetzungen für die Pipelines¶

Azure DevOps

Service connections mit den Namen aus pipelines/variables.yaml (zum Beispiel <env>.serviceConnectionNameHub und <env>.serviceConnectionNameSpoke).
Eine GitHub-Enterprise-Service-Connection für die Repository-Ressource mcp-code (endpoint: in jeder Entry-Datei; im Referenz-Repository xebia-managed-services-eu.ghe.com).
Die Agent-Pools <AgentPool> (Managed DevOps Pool) und <AgentPool>-CTR (Container-Jobs), die von der infrastructure Pipeline angelegt werden.

GitHub Actions

Ein Federated Credential (OIDC) auf den Service Principals in mcp.json (Azure.TerraformState.Hub.ServicePrincipalId und .Spoke.ServicePrincipalId).
Repository-Variable cloud_platform_gh_app_id und Secret cloud_platform_gh_app_private_key: die GitHub App, die das Code-Repository auscheckt (.github/actions/checkout-mcp-code).
Das environment approval-required.

Eine neue Plattformumgebung aufsetzen (Reihenfolge)¶

Lege die Terraform-State-Storage-Accounts, den spoke-State-Container und die Deployment-Service-Principals an und gib ihnen Zugriff. Das sind Voraussetzungen, die nicht von den Pipelines angelegt werden.
Lege <env-folder>/mcp.json, global.auto.tfvars und die Region-tfvars an.
Führe infrastructure aus: Job Runner sowie den Blob Container im hub-State-Storage-Account.
Führe container aus: das mcp-Image.
Führe hub aus (zuerst im Plan-Modus, dann Apply).
Führe spoke für jeden spoke aus.