Uw resources converteren en migreren naar een Bicep-bestand

10 minuten

Wanneer u begint met het migreren naar Bicep, is het belangrijk om een gestructureerd proces te volgen om ervoor te zorgen dat uw Bicep-bestand uw Azure-resources correct beschrijft. U moet ervoor zorgen dat uw Bicep-code de aanbevolen procedures volgt en dat deze volledig is getest en veilig kan worden gebruikt voor volgende implementaties. In deze eenheid leert u meer over de eerste twee fasen voor uw Bicep-migratie: de conversiefase en de migratiefase.

diagram met de conversie- en migratiefasen van de aanbevolen werkstroom voor het migreren van Azure-resources naar Bicep.

De belangrijkste focus van deze twee fasen is het voorbereiden van een nieuw Bicep-bestand voordat u het later herstructureert en test.

Fase converteren

Het doel van de -converteren--fase tijdens het migreren van uw resources naar Bicep is het vastleggen van een eerste weergave van uw Azure-resources. Het Bicep-bestand dat u in deze fase maakt, is niet voltooid en kan niet worden gebruikt. Het bestand geeft u echter een beginpunt voor uw migratie.

De conversiefase bestaat uit twee mogelijke stappen, die u in volgorde voltooit:

Een weergave van uw Azure-resources vastleggen.
Converteer indien nodig de JSON-weergave naar Bicep met behulp van de opdracht decompile.

diagram met een JSON-sjabloon die is gedecompileerd naar JSON en Azure-resources die worden geëxporteerd naar een JSON-sjabloon, die vervolgens wordt gedecompileerd.

Als u een bestaande JSON-sjabloon hebt die u converteert naar Bicep, is de eerste stap eenvoudig omdat u al uw bronsjabloon hebt. In deze eenheid leert u hoe u het kunt decompileren naar Bicep.

Als u Azure-resources converteert die zijn geïmplementeerd met behulp van Azure Portal of een ander hulpprogramma, moet u de resourcedefinities vastleggen. U kunt de resourcedefinities exporteren en converteren naar Bicep, of u kunt de opdracht Resource invoegen in Visual Studio Code gebruiken om een Bicep-weergave van uw Azure-resource in te voegen.

Hoe Azure resources vertegenwoordigt

Azure Resource Manager is de service die wordt gebruikt voor het implementeren en beheren van resources in Azure. Alle resources die in Azure zijn geïmplementeerd, worden bijgehouden door Resource Manager, ongeacht de methode die is gebruikt om de resource te implementeren. U kunt Azure Portal, Azure CLI, Azure PowerShell, de Resource Manager REST API en Azure SDK's gebruiken om te communiceren met Resource Manager.

diagram waarin Resource Manager aanvragen accepteert van alle Azure-clients en -bibliotheken.

Er zijn twee typen bewerkingen in Azure: besturingsvlakbewerkingen en gegevensvlakbewerkingen. besturingsvlak bewerkingen worden gebruikt om de resources in uw abonnement te beheren. gegevensvlak bewerkingen worden gebruikt voor toegang tot functies die door een resource worden weergegeven. U gebruikt bijvoorbeeld een besturingsvlakbewerking om een virtuele machine te maken, maar u gebruikt een gegevensvlakbewerking om verbinding te maken met de virtuele machine met behulp van Remote Desktop Protocol (RDP).

Bestaande resources exporteren naar een JSON-sjabloon

Ongeacht hoe uw Azure-resources worden gemaakt, maakt Resource Manager informatie over elke resource beschikbaar in JSON-indeling. Wanneer u een kopie van de JSON-weergave van een resource vraagt, u de resource exporteert. Het JSON-bestand dat u exporteert, kan worden gedecompileerd in Bicep.

Resource Manager biedt meerdere manieren om Azure-resources te exporteren naar een sjabloon. U kunt de Azure Portal-, Azure CLI- en Azure PowerShell-cmdlets gebruiken om afzonderlijke resources, meerdere resources en volledige resourcegroepen te exporteren.

Het exportproces is een besturingsvlakbewerking, wat betekent dat alleen de configuratie van de Azure-resources wordt geëxporteerd. Wanneer u bijvoorbeeld een virtuele machine exporteert, worden de gegevens op de harde schijf van de virtuele machine niet geëxporteerd. En wanneer u een opslagaccount exporteert, worden de blobs en andere inhoud van het opslagaccount niet opgenomen in het exportproces.

U moet rekening houden met een aantal dingen wanneer u bestaande resources exporteert:

De geëxporteerde resourcedefinitie is een momentopname van de huidige status van die resource. Deze bevat alle wijzigingen die zijn aangebracht in de resource sinds de eerste implementatie.
De geëxporteerde sjabloon kan enkele standaardresource-eigenschappen bevatten die normaal gesproken worden weggelaten uit een Bicep-definitie. Het exportproces kan bijvoorbeeld eigenschappen met het kenmerk Alleen-lezen toevoegen die automatisch door Azure worden ingesteld. Het is niet zinvol om deze eigenschappen op te nemen omdat ze alleen voor lezen zijn. Overweeg deze eigenschappen te verwijderen uit de resourcedefinities wanneer u migreert naar Bicep om uw Bicep-bestanden vrij te houden van overbodige code die verwarring kan veroorzaken.
De geëxporteerde sjabloon bevat waarschijnlijk niet alle parameters die u nodig hebt om de sjabloon herbruikbaar te maken. Wanneer u een sjabloon exporteert, worden veel van de eigenschappen in de sjabloon vastgelegd. Verderop in deze module ziet u hoe u parameters toevoegt.
Sommige resources kunnen niet worden geëxporteerd met behulp van deze methode en u moet ze handmatig definiëren in uw Bicep-bestand. Verderop in deze les leert u hoe u deze resources opnieuw maakt.

Implementaties opslaan in een JSON-sjabloon

Als u ooit handmatig een resource hebt geïmplementeerd vanuit Azure Portal, hebt u misschien gezien dat u een sjabloon voor automatisering wilt downloaden op het tabblad Controleren en maken. Met deze optie wordt een JSON ARM-sjabloon opgeslagen die is gebaseerd op de namen en eigenschappen die u hebt ingesteld tijdens het maken van de resource in de portal.

Resource Manager houdt ook resource-implementaties bij. Implementatiebewerkingen omvatten wijzigingen die zijn ingediend door de Azure-portal voor het aanmaken van resources en eventuele ARM-sjabloonimplementaties. Wijzigingen in bestaande resources die zijn aangebracht met behulp van Azure Portal, Azure PowerShell-cmdlets, Azure CLI of andere hulpprogramma's maken doorgaans geen implementaties.

Als de implementaties zijn gemaakt met behulp van een compatibel hulpprogramma, hebt u toegang tot de implementatiesjabloon vanuit de implementatiegeschiedenis van de resourcegroep. U kunt Azure Portal, Azure CLI of Azure PowerShell gebruiken om implementaties op te slaan.

U moet rekening houden met een aantal dingen wanneer u uw sjablonen opslaat met behulp van deze methode:

De opgeslagen sjabloon toont de status van de resources op het moment van implementatie. Het bevat geen wijzigingen die zijn aangebracht na de implementatie.
Als de implementatie meerdere resources bevat, kunt u geen specifieke resources selecteren die u wilt opnemen en uitsluiten. Met deze bewerking wordt de definitie gedownload van alle resources die deel uitmaken van de eerste implementatie. Wanneer u echter naar de migratiefase van het proces gaat, kunt u resources die u niet nodig hebt, handmatig negeren.
De sjabloon bevat alleen resource-eigenschappen die nodig zijn voor implementatie.
De sjabloon kan parameters bevatten die u kunt gebruiken om de sjabloon opnieuw te implementeren in meerdere omgevingen. U moet echter bevestigen dat deze parameters aan uw behoeften voldoen.
De sjabloon bevat waarschijnlijk geen overbodige eigenschappen, maar controleer nog steeds of de sjabloon alles bevat wat u verwacht en verwijder overbodige eigenschappen.

Notitie

U exporteert echter resources door bestaande resources te exporteren of door implementaties op te slaan, het geëxporteerde bestand als uitgangspunt te behandelen en het niet rechtstreeks te gebruiken. Gebruik deze in plaats daarvan als uitgangspunt voor uw uiteindelijke sjabloon.

Bestaande resources invoegen in Bicep

De Bicep-extensie voor Visual Studio Code bevat de opdracht Resource invoegen, waarmee een Bicep-weergave van een Azure-resource wordt vastgelegd. Met deze opdracht wordt de JSON-definitie van de resource uit Azure gelezen, worden eigenschappen verwijderd die als alleen-lezen worden herkend en worden de JSON gedecompileert naar Bicep. Net als bij de exportfunctie kan de resulterende Bicep-code worden gebruikt als uitgangspunt voor uw uiteindelijke Bicep-bestand.

U kunt een resource invoegen door het Opdrachtenpalet van Visual Studio Code te openen. Gebruik Ctrl+Shift+P- in Windows en Linux en ⌘+Shift+P in macOS.

De bron-JSON ARM-sjabloon decompileren

De tweede stap bij het migreren van uw Azure-resources naar Bicep is het converteren van uw JSON ARM-sjablonen en Azure-resources naar Bicep-sjablonen. De Bicep-hulpprogramma's bevatten de opdracht decompile om sjablonen te converteren. U kunt de opdracht decompile aanroepen vanuit Azure CLI of bicep CLI.

Het decompilatieproces garandeert geen volledige correspondentie van JSON naar Bicep. Mogelijk moet u het gegenereerde Bicep-bestand aanpassen om te voldoen aan de aanbevolen procedures voor uw sjabloon voordat u het bestand gebruikt om resources te implementeren. Overweeg het als uitgangspunt voor uw migratie. Verderop in deze module leert u hoe u eventuele problemen kunt oplossen die u ondervindt tijdens het decompilatieproces.

Nadat u de sjabloon hebt gedecompileerd, hebt u de conversiefase voltooid. U hebt nu een geldig Bicep-bestand om vanaf te beginnen.

Migratiefase

Het doel van de migrantiefase van het migreren van uw resources naar Bicep is het maken van het eerste concept van uw implementeerbare Bicep-bestand en ervoor te zorgen dat het alle Azure-resources definieert die binnen het bereik van de migratie vallen.

De migratiefase bestaat uit drie stappen, die u op volgorde voltooit:

Maak een nieuw leeg Bicep-bestand.
Kopieer elke resource uit uw gedecompileerde sjabloon.
Identificeer en maak eventuele ontbrekende resources opnieuw.

diagram met de stappen voor het migreren van een sjabloon naar Bicep.

Een nieuw Bicep-bestand maken

Het is een goede gewoonte om een nieuw Bicep-bestand te maken. Het bestand dat u in de conversiefase hebt gemaakt, is een referentiepunt dat u kunt bekijken, maar u moet het niet als definitief beschouwen of uitrollen as-is.

Resources kopiëren naar het nieuwe Bicep-bestand

Kopieer elke resource afzonderlijk van het geconverteerde Bicep-bestand naar het nieuwe Bicep-bestand. Met dit proces kunt u eventuele problemen per resource oplossen en verwarring voorkomen wanneer uw sjabloon groter wordt.

Niet-ondersteunde bronnen opnieuw maken

Niet alle Azure-resourcetypen kunnen worden geëxporteerd via Azure Portal, Azure CLI of Azure PowerShell. Extensies van virtuele machines zoals DependencyAgentWindows en MMAExtension (Microsoft Monitoring Agent) zijn bijvoorbeeld resourcetypen die u niet kunt exporteren.

Wanneer u een resource probeert te exporteren met behulp van Azure Portal, Azure CLI of Azure PowerShell en een niet-ondersteund resourcetype wordt opgenomen, wordt er een gedetailleerd foutbericht gegenereerd. U moet alle resources die niet zijn geëxporteerd, zoals extensies voor virtuele machines, opnieuw maken in uw nieuwe Bicep-bestand. U kunt kiezen uit verschillende hulpprogramma's en benaderingen voor het opnieuw maken van resources, waaronder Azure Resource Explorer, de ARM-sjabloonverwijzing en Azure-quickstartsjablonen.

Azure Resource Explorer

Azure Resource Explorer is een hulpprogramma dat is ingesloten in Azure Portal. In de portal worden bepaalde resourcetypen niet weergegeven, maar Resource Explorer geeft u een JSON-weergave van uw resources. Als u toegang wilt krijgen tot Resource Explorer, zoekt u ernaar in het zoekvak:

schermopname van Azure Portal waarin het zoekvak wordt weergegeven waarin resourceverkenner is ingevoerd.

In het resultatenvenster ziet u een lijst met de geregistreerde resourceproviders voor uw abonnement en details voor alle resources, resourcegroepen en abonnementen die u mag weergeven. Als u een JSON-weergave van een resource wilt weergeven, selecteert u de hiërarchie aan de linkerkant van het deelvenster:

schermopname van Azure Portal waarin Azure Resource Explorer wordt weergegeven.

Als u een resource selecteert, kunt u de JSON-weergave bekijken, zoals in dit voorbeeld:

{
    "name": "DependencyAgentWindows",
    "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/rg-app-prod-truckline/providers/Microsoft.Compute/virtualMachines/vm-prod-001/extensions/DependencyAgentWindows",
    "type": "Microsoft.Compute/virtualMachines/extensions",
    "location": "eastus",
    "properties": {
        "autoUpgradeMinorVersion": true,
        "provisioningState": "Succeeded",
        "publisher": "Microsoft.Azure.Monitoring.DependencyAgent",
        "type": "DependencyAgentWindows",
        "typeHandlerVersion": "9.10"
    }
}

U kunt de JSON-weergave gebruiken om een Bicep-resource te definiëren:

resource dependencyAgentWindows 'Microsoft.Compute/virtualMachines/extensions@2022-08-01' = {
  parent: virtualMachine
  name: 'DependencyAgentWindows'
  location: 'eastus'
  properties: {
    autoUpgradeMinorVersion: true
    publisher: 'Microsoft.Azure.Monitoring.DependencyAgent'
    type: 'DependencyAgentWindows'
    typeHandlerVersion: '9.10'
  }
}

Notitie

De JSON-weergave bevat een eigenschap met de naam provisioningState. De provisioningState-eigenschap is een alleen-lezen-eigenschap en wordt automatisch door Azure ingesteld, dus deze eigenschap wordt niet opgenomen in de Bicep-resourcedefinitie.

Fooi

De Bicep-extensie voor Visual Studio Code helpt u bij het definiëren van uw Azure-resources in Bicep. De Bicep-weergave van de resource bevat bijvoorbeeld een API-versie, maar de geëxporteerde JSON-versie niet. Wanneer u in Visual Studio Code begint met het invoeren van het resourcetype, wordt automatisch een API-versie voorgesteld.

ARM-sjabloonreferentie

De ARM-sjabloonreferentie is een bron van informatie over arm-sjabloonstructuur, resourcetypen, API-versies en eigenschapsdefinities voor Azure-resources. De documentatie bevat voorbeelden in zowel Bicep- als JSON-indelingen.

U kunt specifieke resourceproviders en resourcetypen kiezen, zoals Microsoft.Web/serverfarmsen hun API-versies. U kunt controleren welke resource-eigenschappen vereist zijn en welke optioneel zijn. U kunt ook beschrijvingen van eigenschappen weergeven waarmee u begrijpt wat de eigenschappen doen.

Azure-snelstartsjablonen

De Azure-quickstartsjablonen opslagplaats is een verzameling door de community bijgedragen sjablonen. Deze opslagplaats met doorzoekbare sjablonen biedt voorbeelden van veel Azure-resources en -oplossingen. In sommige quickstarts zijn zowel een JSON ARM-sjabloon als een Bicep ARM-sjabloon beschikbaar om weer te geven. U kunt deze sjablonen gebruiken als referentiepunt om u te helpen bij het bouwen en verifiëren van uw sjablonen voor implementatie.

Stel dat u een sjabloon wilt vinden waarmee een Azure App Service-plan en -app worden gebouwd. Elke quickstart-sjabloon biedt u de mogelijkheid om de sjabloon rechtstreeks in Azure te implementeren of om de sjabloon op GitHub weer te geven.

Schermopname van een Azure-quickstartsjabloon waarmee een eenvoudige Linux-web-app wordt geïmplementeerd.

Houd er rekening mee dat de Azure-quickstartsjablonen bijdragen aan de community zijn. Sommige voorbeelden zijn mogelijk verouderd omdat functies regelmatig worden toegevoegd aan Azure-services. De voorbeelden kunnen ook resources en eigenschappen bevatten die u niet nodig hebt voor het gebruik van de sjabloon. De opslagplaats met quickstart-sjablonen is echter een handige resource om inzicht te krijgen in hoe u uw resources kunt implementeren met behulp van ARM-sjablonen.