Ga naar inhoud

Migreren vanaf een oudere platformversie

Deze pagina is bedoeld voor een platformteam dat een tenant overneemt die een oudere generatie van het platform draait, of die spokes buiten het platform heeft. Er zijn drie migraties:

Migratie Gebruik het wanneer Sectie
Bicep-gebaseerde spoke naar de Terraform spoke canvas Een workload-subscription is gebouwd met een eerdere, bicep-gebaseerde landing zone en moet een spoke van dit platform worden, zonder haar opnieuw op te bouwen Bicep-spoke naar Terraform
Monorepository-hub naar de hub met layers De hub dateert van vóór de gelaagde deployment (vóór v4.3.0) Monorepository-hub naar layers
Oudere platformversie naar de huidige De hub is gelaagd, maar draait een oudere release of de oudere pipelines Oudere versie naar de huidige versie

Gebruik voor een gewone upgrade tussen huidige versies Wat te doen als een nieuwe versie wordt gereleased. Om een workload naar een spoke te verplaatsen, zie Een workload naar het platform migreren.

Uitgangspunten voor elke migratie

  • Laat de configuratie beschrijven wat er in Azure staat, niet wat je graag zou willen. Het doel van de eerste run is een plan dat importeert wat bestaat en zo min mogelijk wijzigt.
  • Lees elk plan. Zoek naar destroys en geforceerde vervangingen die niet mogen gebeuren, en naar resources die Terraform wil aanmaken terwijl ze al bestaan (die moeten worden geïmporteerd).
  • Informeer eerst de eigenaar. Spreek een tijdslot af met de contactpersoon van de betrokken workload of hub voordat je apply doet. Sommige migraties veroorzaken een korte verstoring (bijvoorbeeld het opnieuw verbinden van een netwerk).
  • Werk op een branch en, waar mogelijk, in een kopie van de state. Bewaar de oude definitie totdat de nieuwe is toegepast en gecontroleerd, en verwijder de oude dan in een tweede pull request.
  • Laat een tweede persoon de pull request en het plan reviewen.
  • Ga terug naar de normale pin. Migraties gebruiken vaak een tijdelijke codeversie (een import-tag of branch). Zet na de apply de entry pipeline terug op de release die je wilt draaien.

Bicep-spoke naar Terraform-spoke

Voordat je begint

  • De juiste subscription ID van de spoke.
  • Een contactpersoon (de product owner van de workload) die een heads-up krijgt voordat je apply doet.
  • De resource group, regio en omgeving van de spoke, en de naam van zijn Virtual WAN-verbinding (zoek de naam van het virtual network in de verbindingslijst van de virtual hub).

1. Bereid het migratiebestand voor

De documentatieset bevat een hulp-PowerShell-script, prepareMigrationFile.ps1, dat de bestaande spoke leest met de Azure CLI en een spoke JSON-bestand schrijft in het formaat van de spoke canvas. Meld je eerst aan bij de subscription die de spoke bevat. Het leest onder andere de subscription, het virtual network met adresruimte, DNS-servers en subnets, de route tables en network security groups, de Log Analytics workspace, de Key Vault en de tags, en gebruikt deze invoer:

Parameter Betekenis
subscriptionId De subscription die de spoke bevat
resourceGroupName De resource group van de bestaande resources
region De korte regionaam, bijvoorbeeld weu
environment De spoke-omgeving, bijvoorbeeld nonprod
outputFileName De naam van het JSON-bestand dat wordt geschreven
workloadShortName De korte workloadnaam voor de spoke canvas
virtualWanConnectionName De naam van de bestaande Virtual WAN-verbinding

Het resultaat bevat de meeste parameters. De blokken tags en adInfo vul je nog met de hand in, en je controleert alles tegen Azure. Zie het script als een versneller, niet als de bron van waarheid, en controleer de uitvoer tegen de spoke JSON-referentie. Heeft je team het script niet, maak het bestand dan met de hand aan op basis van de portal en de bicep-parameters.

2. Maak het spoke-bestand

  1. Maak een branch in de configuratierepository.
  2. Maak het spoke-bestand in <env-folder>/spokes/<team>/, uitgaand van een bestaand spoke-bestand of van het voorbereide bestand.
  3. Zorg dat het bestand overeenkomt met de werkelijke situatie in Azure: namen, adresbereiken, subnets, delegations, route tables en NSG-regels.
  4. Richt de pipeline op de codeversie die de import-definities voor de spoke canvas bevat (een aparte import-branch of -tag in oudere versies, en de release die ze bevat in nieuwere). Vraag het productteam als je niet zeker weet welke.

3. Draai het plan

Draai de spoke-pipeline tot en met het plan (spokeGlob ingesteld op dit ene bestand; modus Plan) en lees het:

  • Resources die vernietigd of vervangen zouden worden en dat niet zouden moeten.
  • Resources die aangemaakt zouden worden terwijl ze bestaan, en dus moeten worden geïmporteerd.

Terraform koppelt bestaande resources aan zijn configuratie met import-blokken in de code van de spoke canvas. Ze zien er zo uit (de spoke canvas loopt over de virtual networks):

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}"
}

Klopt het plan niet, zoek dan uit of het import-blok (een wijziging voor het productteam) of je spoke-bestand fout is. Herstel het, plan opnieuw en herhaal dit totdat het plan is wat je verwacht.

4. Apply

  1. Geef de contactpersoon een heads-up.
  2. Draai de apply-fase. Mislukt die, troubleshoot dan met de log en vraag een collega of het productteam als de oorzaak niet duidelijk is.
  3. Draai de pipeline nog een keer en controleer dat er geen wijzigingen worden gepland.
  4. Meld de contactpersoon dat de spoke is gemigreerd.
  5. Zet de pipeline terug op de release die je normaal pint, en open een pull request die een tweede persoon reviewt.

5. Verwijder de oude definitie

Verwijder in de repository van de oude landing zone de spoke-definitiebestanden die je hebt gemigreerd (weer een pull request), zodat de oude pipelines niet dezelfde spoke beheren.

Voorbeeld: bestaande Terraform state verplaatsen

Bij één migratie had de spoke al Terraform state uit een eerdere generatie van de spoke-repository. Lijkt jouw situatie hierop, dan zijn deze stappen een startpunt, geen recept:

  1. Maak het nieuwe spoke-bestand op basis van het oude.
  2. Kopieer het state-bestand naar de spoke state-container en hernoem het naar het patroon van de nieuwe indeling (spoke_<workload>_<environment>.tfstate, zie Naamgeving en state). Een verkeerde naam betekent dat het plan laat zien dat er geen resources bestaan.
  3. Draai het plan om de resource-adressen te vinden die je nodig hebt.
  4. Voeg moved-blokken toe (en import-blokken waar nodig) voor resources waarvan het adres is veranderd, en koppel network security groups los die de nieuwe canvas vervangt.
  5. Draai de pipeline en lees de wijzigingen. Key Vault, storage account, virtual network en subnets mogen niet worden vervangen. Verwacht dat sommige role assignments, NSG's, IP-groepkoppelingen en Entra-groepen van de oude indeling worden vervangen of verwijderd. Een netwerkregel van een storage account kan bij elke run als wijziging verschijnen. Controleer of dat in jouw versie nog zo is.
  6. Draai opnieuw totdat het plan schoon is. Zet daarna de moved- en import-blokken in commentaar of verwijder ze, maar pas na de laatste migratie die ze nodig heeft.
  7. Schakel het oude spoke-bestand uit (bijvoorbeeld door het te hernoemen met een .disabled-suffix) en open de pull requests.

Monorepository-hub naar layers

Hubs van vóór v4.3.0 werden uitgerold vanuit één repository zonder layers. Releases rond v4.4 introduceerden een import- tag die de bestaande resources importeert in de gelaagde state wanneer je overstapt. Op het moment van schrijven was de tag v4.4.1-import; controleer de actuele naam in de upgradehandleiding van je doelversie.

  1. Maak een branch in de configuratierepository van de klant.
  2. Wijzig in de entry pipeline de codereferentie naar de import-tag.
  3. Volg de upgradehandleiding van de eerste gelaagde versie (de v4.4.0-handleiding): daarin staan configuratiebestanden die uit de configuratierepository moeten worden verwijderd en wijzigingen die je moet doorvoeren.

  4. Verwijder de bestaande custom policy definitions voor alerts op de platform management group, zodat ze door de nieuwe layers opnieuw worden aangemaakt. In PowerShell, met de 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

  5. Draai de pipeline voor de import-tag, layer voor layer, in deze volgorde, met een plan vóór elke apply, en lees het plan:

    1. management
    2. firewall
    3. identity
    4. postdeployment
    5. foundation
    6. connectivity (een korte verstoring is te verwachten: spreek een tijdslot af met de klant)
  6. Wijzig de codereferentie naar de eerste normale release van de gelaagde generatie (bijvoorbeeld v4.4.1), draai die voor de omgeving en controleer dat alles nog werkt.
  7. Ga door naar de huidige versie met de cumulatieve upgradehandleidingen (volgende sectie).

Oudere versie naar de huidige versie

Van een oudere gelaagde release naar de huidige gaan is een normale upgrade, met een paar structurele verschillen die de upgradehandleidingen release voor release behandelen. Plan tijd in voor deze punten:

Verandering over de generaties Wat te doen
Eén main.yaml-pipeline, layers draaien één voor één, met de parameters Environment, Region en Layer Vervang door de entry pipelines hub, spoke, infrastructure, container en hun destroy-tegenhangers (Pipelines)
Instellingen verspreid over pipelinevariabelen, een variable group en secrets Zet ze in mcp.json (Config)
Vier repositories (platform en spoke, code en config) Twee repositories (Repo-opzet)
Agents op een virtual machine scale set, gebouwd vanuit een image gallery Managed DevOps Pool en Container Apps-jobs, uitgerold door infrastructure (Agents voorbereiden)
De ghrunners layer voor GitHub Runners vanuit infrastructure, geregistreerd via een GitHub App (GitHub-variant)
Spoke-bestanden in spokes/tfspokes/<workload>/ van een aparte spoke-repository <env-folder>/spokes/<team>/ in de configuratierepository (Spoke-config)

Procedure:

  1. Noteer de huidige versie en lees elke upgradehandleiding tot en met de doelversie, de oudste eerst (Upgradestappen).
  2. Voer de versiespecifieke opruimstappen van elke handleiding uit. Sommige vereisen dat je eerst oude policy definitions of assignments in de portal verwijdert.
  3. Voer de structurele wijzigingen uit de tabel door op een branch: maak mcp.json aan, maak de nieuwe entry pipelines aan, draai infrastructure en container, en verplaats de spoke-bestanden.
  4. Plan de hub in canary en lees het plan. Het verplaatsen van de configuratie mag geen destroys plannen voor bestaande hub-resources. Verschillen state keys of paden, stop dan en vraag het productteam voordat je apply doet.
  5. Pas toe op canary, daarna op prod, zoals in Het platform deployen.
  6. Plan één spoke per soort spoke en lees het resultaat (De spoke-plannen lezen).
  7. Haal weg wat de nieuwe generatie vervangt: oude agents, oude pipelines, oude repositories.

Informeer de workload teams

Een migratie kan het netwerk (connectivity layer) en de identiteitsobjecten van spokes raken. Kondig het aan zoals elk ander onderhoud (Onderhoudskalender).