Migreren naar Bicep

Er zijn veel voordelen voor het definiëren van uw Azure-resources in Bicep, waaronder: eenvoudigere syntaxis, modularisatie, automatisch afhankelijkheidsbeheer, typevalidatie en IntelliSense, en een verbeterde ontwerpervaring.

Wanneer u bestaande JSON Azure Resource Manager-sjablonen (ARM-sjablonen) migreert naar Bicep, wordt u aangeraden de werkstroom in vijf fasen te volgen:

De eerste stap in het proces is het vastleggen van een eerste weergave van uw Azure-resources. Indien nodig kunt u het JSON-bestand decompileren naar een initiële Bicep-bestand, waarop u de herstructurering verbetert. Wanneer u een werkbestand hebt, test en implementeert u dit met behulp van een proces waarmee het risico wordt beperkt dat wijzigingen in uw Azure-omgeving worden onderbroken.

In dit artikel wordt deze aanbevolen werkstroom samengevat. Zie Azure-resources en JSON ARM-sjablonen migreren voor het gebruik van Bicep voor gedetailleerde richtlijnen.

Fase 1: Converteren

In de conversiefase van het migreren van uw resources naar Bicep is het doel om een eerste weergave van uw Azure-resources vast te leggen. 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 stappen die u op volgorde hebt voltooid:

1. Een weergave van uw Azure-resources vastleggen. Als u een bestaande JSON-sjabloon hebt die u converteert naar Bicep, is de eerste stap eenvoudig: u hebt al uw bronsjabloon. Als u Azure-resources converteert die zijn geïmplementeerd met behulp van de portal of een ander hulpprogramma, moet u de resourcedefinities vastleggen. U kunt een JSON-weergave van uw resources vastleggen met behulp van de Azure-portal, Azure CLI of Azure PowerShell-cmdlets om één resource, meerdere resources en volledige resourcegroepen te exporteren . U kunt de opdracht Resource invoegen in Visual Studio Code gebruiken om een Bicep-weergave van uw Azure-resource te importeren.

2. Converteer indien nodig de JSON-weergave naar Bicep met behulp van de decompile-opdracht. De Bicep-hulpprogramma's bevatten de decompile opdracht om sjablonen te converteren. U kunt de opdracht vanuit Visual Studio Code aanroepen met de Bicep-extensie, de Azure CLI of de Bicep CLI.decompile Het decompilatieproces is een best effort-proces en garandeert geen volledige toewijzing van JSON aan 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.

Notitie

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

Met Visual Studio Code kunt u JSON plakken als Bicep. Zie JSON plakken als Bicep voor meer informatie.

Fase 2: Migreren

In de migratiefase van het migreren van uw resources naar Bicep is het doel het eerste concept van uw implementeerbare Bicep-bestand te maken en ervoor te zorgen dat alle Azure-resources die binnen het bereik van de migratie vallen, worden gedefinieerd.

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

1. Maak een nieuw leeg Bicep-bestand. Het is een goede gewoonte om een gloednieuw 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 behandelen als definitief of als zodanig implementeren.

2. Kopieer elke resource uit uw gedecompileerde sjabloon. Kopieer elke resource afzonderlijk van het geconverteerde Bicep-bestand naar het nieuwe Bicep-bestand. Dit proces helpt u bij het oplossen van eventuele problemen per resource en om verwarring te voorkomen wanneer uw sjabloon groter wordt.

3. Identificeer ontbrekende resources en maak deze opnieuw. 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) worden bijvoorbeeld niet ondersteund voor export. Voor resources die niet zijn geëxporteerd, zoals extensies van virtuele machines, moet u deze resources opnieuw maken in uw nieuwe Bicep-bestand. U kunt resources opnieuw maken met behulp van verschillende hulpprogramma's en benaderingen, waaronder Azure Resource Explorer, de referentiedocumentatie voor Bicep- en ARM-sjablonen en de site azure-quickstartsjablonen .

Fase 3: Herstructureren

In de herstructureringsfase van de migratie van uw resources naar Bicep is het doel om de kwaliteit van uw Bicep-code te verbeteren. Deze verbeteringen kunnen wijzigingen bevatten, zoals het toevoegen van codeopmerkingen die de sjabloon afstemmen op uw sjabloonstandaarden.

De implementatiefase bestaat uit acht stappen die u in een willekeurige volgorde hebt voltooid:

1. Resource-API-versies controleren. Wanneer u Azure-resources exporteert, bevat de geëxporteerde sjabloon mogelijk niet de meest recente API-versie voor een resourcetype. Als er specifieke eigenschappen zijn die u nodig hebt voor toekomstige implementaties, werkt u de API bij naar de juiste versie. Het is raadzaam om de API-versies voor elke geëxporteerde resource te controleren.

2. Bekijk de linter-suggesties in uw nieuwe Bicep-bestand. Wanneer u de Bicep-extensie voor Visual Studio Code gebruikt om Bicep-bestanden te maken, wordt bicep linter automatisch uitgevoerd en worden suggesties en fouten in uw code gemarkeerd. Veel van de suggesties en fouten bevatten een optie om een snelle oplossing van het probleem toe te passen. Bekijk deze aanbevelingen en pas uw Bicep-bestand aan.

3. Wijzig parameters, variabelen en symbolische namen. Het is mogelijk dat de namen van parameters, variabelen en symbolische namen die door de decompiler worden gegenereerd, niet overeenkomen met uw standaardnaamconventie. Controleer de gegenereerde namen en breng indien nodig wijzigingen aan.

4. Vereenvoudig expressies. Het decompileringsproces kan niet altijd profiteren van enkele functies van Bicep. Controleer alle expressies die in de conversie worden gegenereerd en vereenvoudig deze. De gedecompileerde sjabloon kan bijvoorbeeld een concat() of format() functie bevatten die kan worden vereenvoudigd met behulp van tekenreeksinterpolatie. Bekijk eventuele suggesties van de linter en breng indien nodig aanpassingen aan.

5. Bekijk onderliggende en extensiebronnen. Er zijn verschillende manieren om onderliggende resources en extensiebronnen in Bicep te declareren, waaronder het samenvoegen van de namen van uw resources, het parent trefwoord en het gebruik van geneste resources. Overweeg deze resources na decompilatie te controleren en ervoor te zorgen dat de structuur voldoet aan uw standaarden. Zorg er bijvoorbeeld voor dat u geen tekenreekssamenvoeging gebruikt om onderliggende resourcenamen te maken. Gebruik de parent eigenschap of een geneste resource. Op dezelfde manier kunnen subnetten worden verwezen als eigenschappen van een virtueel netwerk of als een afzonderlijke resource.

6. Modulariseer. Als u een sjabloon met veel resources converteert, kunt u overwegen om de afzonderlijke resourcetypen te verbreken in modules voor het gemak. Bicep-modules helpen de complexiteit van uw implementaties te verminderen en de herbruikbaarheid van uw Bicep-code te vergroten.

   Notitie

   U kunt uw JSON-sjablonen gebruiken als modules in een Bicep-implementatie. Bicep heeft de mogelijkheid om JSON-modules te herkennen en ernaar te verwijzen zoals u Bicep-modules gebruikt.

7. Voeg opmerkingen en beschrijvingen toe. Goede Bicep-code is zelfdocumenterend. Met Bicep kunt u opmerkingen en @description() kenmerken toevoegen aan uw code waarmee u uw infrastructuur kunt documenteren. Bicep ondersteunt zowel opmerkingen met één regel met behulp van een // tekenreeks als opmerkingen met meerdere regels die beginnen met een /* en eindigen met een */. U kunt opmerkingen toevoegen aan specifieke regels in uw code en voor secties met code.

8. Volg de best practices van Bicep. Zorg ervoor dat uw Bicep-bestand de standaardaanaanveling volgt. Raadpleeg het referentiedocument voor best practices van Bicep voor alles wat u mogelijk hebt gemist.

Fase 4: Testen

In de testfase van het migreren van uw resources naar Bicep is het doel om de integriteit van uw gemigreerde sjablonen te controleren en een testimplementatie uit te voeren.

De testfase bestaat uit twee stappen, die u op volgorde voltooit:

1. Voer de wat-als-bewerking van de ARM-sjabloonimplementatie uit. Om u te helpen bij het controleren van uw geconverteerde sjablonen vóór de implementatie, kunt u de wat-als-bewerking van de Azure Resource Manager-sjabloonimplementatie gebruiken. Hiermee wordt de huidige status van uw omgeving vergeleken met de gewenste status die in de sjabloon is gedefinieerd. Het hulpprogramma voert de lijst met wijzigingen uit die zich voordoen zonder de wijzigingen toe te passen op uw omgeving. U kunt what-if gebruiken met zowel incrementele als volledige modusimplementaties. Zelfs als u van plan bent om uw sjabloon te implementeren met behulp van de incrementele modus, is het een goed idee om uw wat-als-bewerking uit te voeren in de volledige modus.

2. Voer een testimplementatie uit. Voordat u uw geconverteerde Bicep-sjabloon naar productie introduceert, kunt u overwegen om meerdere testimplementaties uit te voeren. Als u meerdere omgevingen (bijvoorbeeld ontwikkeling, testen en productie) hebt, kunt u uw sjabloon eerst implementeren in een van uw niet-productieomgevingen. Na de implementatie vergelijkt u de oorspronkelijke resources met de nieuwe resource-implementaties voor consistentie.

Fase 5: Implementeren

In de implementatiefase van het migreren van uw resources naar Bicep is het doel om uw uiteindelijke Bicep-bestand in productie te implementeren.

De implementatiefase bestaat uit vier stappen, die u in volgorde voltooit:

1. Bereid een terugdraaiplan voor. De mogelijkheid om te herstellen van een mislukte implementatie is cruciaal. Maak een terugdraaistrategie als er belangrijke wijzigingen in uw omgevingen worden geïntroduceerd. Inventariseer de typen resources die zijn geïmplementeerd, zoals virtuele machines, web-apps en databases. Het gegevensvlak van elke resource moet ook worden overwogen. Hebt u een manier om een virtuele machine en de bijbehorende gegevens te herstellen? Hebt u een manier om een database te herstellen na verwijdering? Met een goed ontwikkeld terugdraaiplan kunt u uw downtime tot een minimum beperken als er problemen optreden bij een implementatie.

2. Voer de wat-als-bewerking uit op productie. Voordat u het uiteindelijke Bicep-bestand in productie implementeert, voert u de wat-als-bewerking uit op uw productieomgeving, moet u ervoor zorgen dat u de productieparameterwaarden gebruikt en de resultaten kunt documenteren.

3. Handmatig implementeren. Als u de geconverteerde sjabloon in een pijplijn gaat gebruiken, zoals Azure DevOps of GitHub Actions, kunt u de implementatie eerst uitvoeren vanaf uw lokale computer. Het verdient de voorkeur om de functionaliteit van de sjabloon te testen voordat u deze in uw productiepijplijn opvoegt. Op die manier kunt u snel reageren als er een probleem is.

4. Voer betrouwbaarheidstests uit. Nadat uw implementatie is voltooid, moet u een reeks betrouwbaarheidstests uitvoeren om ervoor te zorgen dat uw toepassing of workload goed werkt. Test bijvoorbeeld of uw web-app toegankelijk is via normale toegangskanalen, zoals het openbare internet of via een bedrijfs-VPN. Voor databases probeert u een databaseverbinding te maken en een reeks query's uit te voeren. Meld u met virtuele machines aan bij de virtuele machine en zorg ervoor dat alle services actief zijn.

Volgende stappen

Zie Decompiling ARM-sjabloon JSON naar Bicep voor meer informatie over bicepdecompiler.