Migration von einer älteren Plattformversion¶

Diese Seite richtet sich an ein Plattform-Team, das einen tenant übernimmt, in dem eine ältere Generation der Plattform läuft, oder der spokes außerhalb der Plattform hat. Sie behandelt drei Migrationen:

Migration	Einsatz	Abschnitt
Bicep-basierter spoke zum Terraform-spoke-canvas	Eine workload-subscription wurde mit einer früheren, bicep-basierten landing zone gebaut und soll ein spoke dieser Plattform werden, ohne sie neu aufzubauen	Bicep-spoke zu Terraform
Mono-Repository-hub zum geschichteten hub	Der hub stammt aus der Zeit vor dem layered Deployment (vor v4.3.0)	Mono-Repository-hub zu layers
Ältere Plattformversion zur aktuellen	Der hub ist geschichtet, läuft aber mit einem älteren Release oder den älteren pipelines	Ältere Version zur aktuellen Version

Für ein gewöhnliches Upgrade zwischen aktuellen Versionen nutze Was zu tun ist, wenn eine neue Version veröffentlicht wird. Um einen workload in einen spoke zu verschieben, siehe Einen workload auf die Plattform migrieren.

Grundsätze für jede Migration¶

Lass die Konfiguration beschreiben, was in Azure ist, nicht was du gerne hättest. Ziel des ersten Laufs ist ein Plan, der importiert, was existiert, und so wenig wie möglich ändert.
Lies jeden Plan. Achte auf destroys und erzwungene Ersetzungen, die nicht passieren sollten, und auf Ressourcen, die Terraform anlegen will, obwohl sie schon existieren (sie müssen importiert werden).
Sag es zuerst dem Owner. Vereinbare vor dem apply einen Zeitslot mit der Kontaktperson des betroffenen workloads oder hubs. Manche Migrationen verursachen eine kurze Unterbrechung (zum Beispiel beim Neuverbinden eines Netzwerks).
Arbeite auf einem Branch und, wo möglich, in einer Kopie des state. Behalte die alte Definition, bis die neue angewendet und geprüft ist, und entferne die alte dann in einem zweiten pull request.
Lass eine zweite Person den pull request und den Plan prüfen.
Kehre zum normalen pin zurück. Migrationen nutzen oft eine temporäre Code-Version (einen import-tag oder Branch). Setze die Entry-pipeline nach dem apply wieder auf das Release, das du betreiben willst.

Bicep-spoke zu Terraform-spoke¶

Bevor du anfängst¶

Die korrekte subscription ID des spokes.
Eine Kontaktperson (der Product Owner des workloads), die vor dem apply Bescheid bekommt.
Resource group, Region und Umgebung des spokes sowie der Name seiner Virtual-WAN-Verbindung (suche den Namen des virtuellen Netzwerks in der Verbindungsliste des virtual hub).

1. Die Migrationsdatei vorbereiten¶

Das Dokumentationsset enthält ein PowerShell-Hilfsskript, prepareMigrationFile.ps1, das den bestehenden spoke mit der Azure CLI liest und eine spoke-JSON-Datei im Format des spoke canvas schreibt. Melde dich zuerst an der subscription an, die den spoke enthält. Es liest unter anderem die subscription, das virtuelle Netzwerk mit Adressraum, DNS-Servern und Subnets, die route tables und network security groups, den Log-Analytics-workspace, den Key Vault und die tags und nimmt diese Eingaben:

Parameter	Bedeutung
`subscriptionId`	Die subscription, die den spoke enthält
`resourceGroupName`	Die resource group der bestehenden Ressourcen
`region`	Der kurze Regionsname, zum Beispiel `weu`
`environment`	Die spoke-Umgebung, zum Beispiel `nonprod`
`outputFileName`	Der Name der zu schreibenden JSON-Datei
`workloadShortName`	Der workload-Kurzname für das spoke canvas
`virtualWanConnectionName`	Der Name der bestehenden Virtual-WAN-Verbindung

Das Ergebnis enthält die meisten Parameter. Die Blöcke tags und adInfo füllst du weiterhin von Hand aus, und du prüfst alles gegen Azure. Behandle das Skript als Beschleuniger, nicht als Single Source of Truth, und prüfe seine Ausgabe gegen die spoke-JSON-Referenz. Wenn dein Team das Skript nicht hat, erstelle die Datei von Hand aus dem Portal und den bicep-Parametern.

2. Die spoke-Datei erstellen¶

Erstelle einen Branch im Konfigurations-Repository.
Erstelle die spoke-Datei in <env-folder>/spokes/<team>/, ausgehend von einer bestehenden spoke-Datei oder der vorbereiteten.
Passe die Datei an die tatsächliche Situation in Azure an: Namen, Adressbereiche, Subnets, Delegierungen, route tables und NSG-Regeln.
Richte die pipeline auf die Code-Version aus, die die import-Definitionen für das spoke canvas enthält (in älteren Versionen ein eigener import-Branch oder -tag, in neueren das Release, das sie enthält). Frage das Produktteam, wenn du unsicher bist, welche es ist.

3. Den Plan ausführen¶

Führe die spoke-pipeline bis zum Plan aus (spokeGlob auf diese eine Datei gesetzt; Modus Plan) und lies ihn:

Ressourcen, die zerstört oder ersetzt würden, obwohl das nicht sein sollte.
Ressourcen, die angelegt würden, obwohl sie existieren, und die daher importiert werden müssen.

Terraform verknüpft bestehende Ressourcen mit seiner Konfiguration über import-Blöcke im Code des spoke canvas. Sie sehen so aus (das spoke canvas läuft in einer Schleife über die virtuellen Netzwerke):

import {
  for_each = local.allVnets
  to       = module.virtualnetwork["${each.key}"].azurerm_virtual_network.resVirtualNetwork[0]
  id       = "/subscriptions/${local.jsonfile.azureSubscriptionId}/resourceGroups/${local.namingConventionSet.ResourceGroup}/providers/Microsoft.Network/virtualNetworks/${each.key}"
}

Wenn der Plan falsch ist, finde heraus, ob der import-Block (eine Änderung für das Produktteam) oder deine spoke-Datei falsch ist. Behebe es, plane erneut und wiederhole das, bis der Plan dem entspricht, was du erwartest.

4. Anwenden¶

Gib der Kontaktperson einen Hinweis.
Führe die apply-Phase aus. Wenn sie fehlschlägt, analysiere das Log und frage eine Kollegin, einen Kollegen oder das Produktteam, wenn die Ursache nicht klar ist.
Führe die pipeline noch einmal aus und prüfe, dass sie keine Änderungen plant.
Sag der Kontaktperson, dass der spoke migriert ist.
Setze die pipeline zurück auf das Release, das du normalerweise pinnst, und öffne einen pull request für das Review durch eine zweite Person.

5. Die alte Definition entfernen¶

Entferne im Repository der alten landing zone die spoke-Definitionsdateien, die du migriert hast (wieder per pull request), damit die alten pipelines nicht denselben spoke verwalten.

Beispiel: Bestehenden Terraform-state verschieben¶

In einer Migration hatte der spoke bereits Terraform-state aus einer früheren Generation des spoke-Repositorys. Wenn deine Situation ähnlich ist, sind diese Schritte ein Ausgangspunkt, kein Rezept:

Erstelle die neue spoke-Datei aus der alten.
Kopiere die state-Datei in den spoke-state-Container und benenne sie nach dem Muster des neuen Layouts um (spoke_<workload>_<environment>.tfstate, siehe Namensgebung und state). Ein falscher Name führt dazu, dass der Plan zeigt, es gäbe keine Ressourcen.
Führe den Plan aus, um die benötigten Ressourcenadressen zu finden.
Füge moved-Blöcke hinzu (und import-Blöcke, wo nötig) für Ressourcen, deren Adresse sich geändert hat, und löse network security groups, die das neue canvas ersetzt, aus ihrer Zuordnung.
Führe die pipeline aus und lies die Änderungen. Key Vault, storage account, virtuelles Netzwerk und Subnets dürfen nicht ersetzt werden. Rechne damit, dass einige role assignments, NSGs, IP-group-Zuordnungen und Entra-Gruppen des alten Layouts ersetzt oder entfernt werden. Eine Netzwerkregel des storage accounts kann bei jedem Lauf als Änderung erscheinen. Prüfe, ob das in deiner Version noch so ist.
Führe erneut aus, bis der Plan sauber ist. Kommentiere die moved- und import-Blöcke dann aus oder entferne sie, aber erst nach der letzten Migration, die sie braucht.
Deaktiviere die alte spoke-Datei (zum Beispiel, indem du sie mit der Endung .disabled umbenennst) und öffne die pull requests.

Mono-Repository-hub zu layers¶

Hubs aus der Zeit vor v4.3.0 wurden aus einem einzigen Repository ohne layers deployt. Releases um v4.4 führten einen import-tag ein, der beim Umstieg die bestehenden Ressourcen in den geschichteten state importiert. Zum Zeitpunkt des Schreibens lautete der tag v4.4.1-import; bestätige den aktuellen Namen im Upgrade-Leitfaden deiner Zielversion.

Erstelle einen Branch im Konfigurations-Repository des Kunden.
Ändere in der Entry-pipeline die Code-Referenz auf den import-tag.
Folge dem Upgrade-Leitfaden der ersten geschichteten Version (dem Leitfaden zu v4.4.0): Er nennt Konfigurationsdateien, die aus dem Konfigurations-Repository zu entfernen sind, und Änderungen, die zu machen sind.

Entferne die bestehenden custom policy definitions für Alerts an der platform management group, damit die neuen layers sie neu anlegen. In PowerShell, mit der platform management group als scope:

Get-AzPolicyDefinition -ManagementGroupName "<platform management group>" -Custom | Where-Object { $_.Name -like "Deploy_*_Alert" } | Remove-AzPolicyDefinition
Get-AzPolicyDefinition -ManagementGroupName "<platform management group>" -Custom | Where-Object { $_.Name -like "Deploy_activitylog*" } | Remove-AzPolicyDefinition
Get-AzPolicyDefinition -ManagementGroupName "<platform management group>" -Custom | Where-Object { $_.Name -eq "Deploy_AlertProcessing_Rule" } | Remove-AzPolicyDefinition

Führe die pipeline für den import-tag layer für layer in dieser Reihenfolge aus, mit einem Plan vor jedem apply, und lies den Plan:
1. management
2. firewall
3. identity
4. postdeployment
5. foundation
6. connectivity (eine kurze Unterbrechung ist zu erwarten: vereinbare einen Zeitslot mit dem Kunden)
Ändere die Code-Referenz auf das erste normale Release der geschichteten Generation (zum Beispiel v4.4.1), führe es für die Umgebung aus und prüfe, dass noch alles funktioniert.
Gehe mit den kumulativen Upgrade-Leitfäden weiter zur aktuellen Version (nächster Abschnitt).

Ältere Version zur aktuellen Version¶

Der Wechsel von einem älteren geschichteten Release zum aktuellen ist ein normales Upgrade, mit einigen strukturellen Unterschieden, die die Upgrade-Leitfäden Release für Release abdecken. Plane Zeit dafür ein:

Änderung über die Generationen	Was zu tun ist
Eine `main.yaml`-pipeline, layers laufen einzeln, mit den Parametern Environment, Region und Layer	Ersetze sie durch die Entry-pipelines `hub`, `spoke`, `infrastructure`, `container` und ihre destroy-Gegenstücke (Pipelines)
Einstellungen verteilt auf pipeline-Variablen, eine Variable Group und secrets	Lege sie in `mcp.json` ab (Konfiguration)
Vier Repositories (Plattform und spoke, Code und Konfiguration)	Zwei Repositories (Repo-Setup)
Agents auf einer virtual machine scale set, gebaut aus einer image gallery	Managed DevOps Pool und Container-Apps-Jobs, deployt durch `infrastructure` (Agents vorbereiten)
Der layer `ghrunners` für GitHub	Runners aus `infrastructure`, registriert über eine GitHub App (GitHub-Variante)
spoke-Dateien in `spokes/tfspokes/<workload>/` eines separaten spoke-Repositorys	`<env-folder>/spokes/<team>/` im Konfigurations-Repository (spoke-Konfiguration)

Vorgehen:

Notiere die aktuelle Version und lies jeden Upgrade-Leitfaden bis zur Zielversion, den ältesten zuerst (Upgrade-Schritte).
Führe die versionsspezifischen Aufräumschritte jedes Leitfadens aus. Manche verlangen, zuerst alte policy definitions oder assignments im Portal zu entfernen.
Mache die strukturellen Änderungen aus der Tabelle auf einem Branch: mcp.json erstellen, die neuen Entry-pipelines erstellen, infrastructure und container ausführen, die spoke-Dateien verschieben.
Plane den hub in canary und lies den Plan. Das Verschieben der Konfiguration darf keine destroys für bestehende hub-Ressourcen planen. Wenn state-Keys oder Pfade abweichen, höre auf und frage das Produktteam, bevor du anwendest.
Wende zuerst auf canary an, dann auf prod, wie unter Die Plattform deployen.
Plane einen spoke pro spoke-Art und lies das Ergebnis (Die spoke-Pläne lesen).
Baue zurück, was die neue Generation ersetzt: alte Agents, alte pipelines, alte Repositories.

Sag es den workload-Teams

Eine Migration kann das Netzwerk (connectivity layer) und die Identitätsobjekte von spokes berühren. Kündige sie an wie jede andere Wartung (Wartungskalender).