Konvertieren und Migrieren Ihrer Ressourcen in eine Bicep-Datei

  • 10 Minuten

Wenn Sie mit der Migration zu Bicep beginnen, ist es wichtig, einen strukturierten Prozess zu befolgen, um sicherzustellen, dass Ihre Bicep-Datei Ihre Azure-Ressourcen richtig beschreibt. Sie müssen sicherstellen, dass Ihr Bicep-Code bewährten Methoden entspricht, vollständig getestet ist und sicher für nachfolgende Bereitstellungen verwendet werden kann. In dieser Lerneinheit erfahren Sie mehr über die ersten beiden Phasen ihrer Bicep-Migration: die Konvertierungsphase und die Migrationsphase.

Diagram that shows the convert and migrate phases of the recommended workflow for migrating Azure resources to Bicep.

Der Hauptfokus für diese beiden Phasen liegt darin, eine neue Bicep-Datei vorzubereiten, bevor Sie später die Umgestaltung und Tests ausführen.

Konvertierungsphase

In der Konvertierungsphase der Migration Ihrer Ressourcen zu Bicep besteht das Ziel darin, eine anfängliche Darstellung Ihrer Azure-Ressourcen zu erfassen. Die Bicep-Datei, die Sie in dieser Phase erstellen, ist nicht vollständig und kann noch nicht verwendet werden. Die Datei bietet Ihnen jedoch einen Ausgangspunkt für Ihre Migration.

Die Konvertierungsphase besteht aus zwei möglichen Schritten, die Sie nacheinander ausführen:

  1. Erfassen einer Darstellung Ihrer Azure-Ressourcen.
  2. Bei Bedarf Konvertieren der JSON-Darstellung mithilfe des decompile-Befehls in Bicep

Diagram that shows a JSON template decompiled to JSON, and Azure resources that are exported to a JSON template, which is then decompiled.

Wenn Sie über eine vorhandene JSON-Vorlage verfügen, die Sie in Bicep konvertieren, ist der erste Schritt einfach – denn Sie verfügen bereits über Ihre Quellvorlage. In dieser Lerneinheit erfahren Sie, wie Sie sie in Bicep dekompilieren.

Wenn Sie Azure-Ressourcen konvertieren, die über das Azure-Portal oder ein anderes Tool bereitgestellt wurden, müssen Sie die Ressourcendefinitionen erfassen. Sie können die Ressourcendefinitionen exportieren und in Bicep konvertieren, oder Sie können den Befehl Ressource einfügen in Visual Studio Code verwenden, um eine Bicep-Darstellung Ihrer Azure-Ressource einzufügen.

Darstellung von Ressourcen in Azure

Azure Resource Manager ist der Dienst zum Bereitstellen und Verwalten von Ressourcen in Azure. Alle in Azure bereitgestellten Ressourcen werden von Resource Manager nachverfolgt, unabhängig von der Methode, die zum Bereitstellen der Ressource verwendet wurde. Sie können das Azure-Portal, die Azure CLI, Azure PowerShell, die Resource Manager-REST-API und Azure SDKs für die Interaktion mit Resource Manager verwenden.

Diagram that shows Resource Manager accepting requests from all Azure clients and libraries.

In Azure gibt es zwei Arten von Vorgängen: auf Steuerungsebene und auf Datenebene. Vorgänge auf Steuerungsebene werden zum Verwalten von Ressourcen in Ihrem Abonnement verwendet. Vorgänge auf Datenebene werden für den Zugriff auf Features verwendet, die von einer Ressource verfügbar gemacht werden. Das Erstellen eines virtuellen Computer ist z. B. ein Vorgang auf Steuerungsebene, aber das Herstellen einer Verbindung mit dem virtuellen Computer über RDP (Remotedesktopprotokoll) erfolgt auf Datenebene.

Exportieren vorhandener Ressourcen in eine JSON-Vorlage

Unabhängig davon, wie Ihre Azure-Ressourcen erstellt werden, stellt Resource Manager Informationen zu jeder Ressource im JSON-Format zur Verfügung. Wenn Sie eine Kopie der JSON-Darstellung einer Ressource wünschen, exportieren Sie die Ressource. Die JSON-Datei, die Sie exportieren, kann in Bicep dekompiliert werden.

Resource Manager bietet mehrere Möglichkeiten zum Exportieren von Azure-Ressourcen in eine Vorlage. Sie können das Azure-Portal, die Azure CLI und Azure PowerShell-Cmdlets verwenden, um einzelne Ressourcen, mehrere Ressourcen und ganze Ressourcengruppen zu exportieren.

Der Exportvorgang ist ein Vorgang auf Steuerungsebene, d. h. er exportiert nur die Konfiguration der Azure-Ressourcen. Wenn Sie beispielsweise eine VM exportieren, werden die Daten auf einer Festplatte der VM nicht exportiert. Und wenn Sie ein Speicherkonto exportieren, werden die Blobs und andere Inhalte des Speicherkontos nicht in den Exportvorgang einbezogen.

Beim Exportieren vorhandener Ressourcen müssen Sie einiges berücksichtigen:

  • Die exportierte Ressourcendefinition ist eine Momentaufnahme des aktuellen Zustands dieser Ressource. Sie enthält alle Änderungen, die seit der ersten Bereitstellung an der Ressource vorgenommen wurden.
  • Die exportierte Vorlage kann einige Standardressourceneigenschaften enthalten, die normalerweise in einer Bicep-Definition ausgelassen werden. Beispielsweise kann der Exportvorgang schreibgeschützte Eigenschaften hinzufügen, die Azure automatisch festlegt, und es ist nicht sinnvoll, diese einzubeziehen, da sie schreibgeschützt sind. Ziehen Sie in Erwägung, diese Eigenschaften aus den Ressourcendefinitionen zu entfernen, wenn Sie zu Bicep migrieren, um Ihre Bicep-Dateien frei von unnötigem Code zu halten, der Verwirrung stiften könnte.
  • Die exportierte Vorlage enthält wahrscheinlich nicht alle Parameter, die Sie benötigen, um die Vorlage wiederverwendbar zu machen. Wenn Sie eine Vorlage exportieren, werden viele der Eigenschaften in der Vorlage hartcodiert. Sie erfahren später in diesem Modul, wie Sie Parameter hinzufügen.
  • Einige Ressourcen können nicht mit diesem Ansatz exportiert werden, und Sie müssen sie manuell in Ihrer Bicep-Datei definieren. Später in dieser Lerneinheit erfahren Sie, wie Sie diese Ressourcen erneut erstellen.

Speichern von Bereitstellungen in einer JSON-Vorlage

Wenn Sie schon einmal eine Ressource manuell über das Azure-Portal bereitgestellt haben, ist Ihnen vielleicht die Option Eine Vorlage für die Automatisierung herunterladen auf der Registerkarte Überprüfen + erstellen aufgefallen. Diese Option speichert eine JSON-ARM-Vorlage basierend auf den Namen und Eigenschaften, die Sie beim Erstellen der Ressource im Portal festgelegt haben.

Resource Manager verfolgt auch Bereitstellungen von Ressourcen nach. Bereitstellungsvorgänge umfassen Änderungen, die von der Ressourcenerstellungsumgebung im Azure-Portal übermittelt werden, sowie alle ARM-Vorlagenbereitstellungen. Änderungen an vorhandenen Ressourcen, die über das Azure-Portal, mithilfe von Azure PowerShell-Cmdlets, der Azure-Befehlszeilenschnittstelle oder mit anderen Tools vorgenommen wurden, erstellen in der Regel keine Bereitstellungen.

Wenn die Bereitstellungen mit einem kompatiblen Tool erstellt wurden, können Sie über den Bereitstellungsverlauf der Ressourcengruppe auf die Bereitstellungsvorlage zugreifen. Sie können das Azure-Portal, die Azure-Befehlszeilenschnittstelle oder Azure PowerShell verwenden, um Bereitstellungen zu speichern.

Beim Speichern ihrer Vorlagen mit dieser Methode müssen Sie einige Punkte berücksichtigen:

  • Die gespeicherte Vorlage zeigt den Status der Ressourcen zum Zeitpunkt der Bereitstellung an. Sie enthält keine Änderungen, die nach der Bereitstellung vorgenommen wurden.
  • Wenn die Bereitstellung mehrere Ressourcen enthielt, können Sie keine bestimmten Ressourcen auswählen, die eingeschlossen und ausgeschlossen werden sollen. Dieser Vorgang lädt die Definition aller Ressourcen herunter, die Teil der anfänglichen Bereitstellung waren. Wenn Sie jedoch in die Migrationsphase des Prozesses wechseln, können Sie die nicht benötigten Ressourcen manuell ignorieren.
  • Die Vorlage enthält nur Ressourceneigenschaften, die für die Bereitstellung erforderlich sind.
  • Die Vorlage kann Parameter enthalten, mit denen Sie die Vorlage in mehreren Umgebungen erneut bereitstellen können. Sie müssen jedoch bestätigen, dass diese Parameter Ihren Anforderungen entsprechen.
  • Die Vorlage enthält wahrscheinlich keine überflüssigen Eigenschaften, aber Sie sollten trotzdem überprüfen, ob die Vorlage alles enthält, was Sie erwarten, und alle nicht erforderlichen Eigenschaften entfernen.

Hinweis

Wie auch immer Sie Ressourcen exportieren (durch Export vorhandener Ressourcen oder durch Speichern von Bereitstellungen), betrachten Sie die exportierte Datei als Ausgangspunkt und verwenden Sie sie nicht direkt. Verwenden Sie sie stattdessen als Ausgangspunkt für die endgültige Vorlage.

Einfügen vorhandener Ressourcen in Bicep

Die Bicep-Erweiterung für Visual Studio Code umfasst den Befehl Ressource einfügen, mit dem eine Bicep-Darstellung einer Azure-Ressource erfasst wird. Dieser Befehl liest die JSON-Definition der Ressource aus Azure, entfernt Eigenschaften, die als schreibgeschützt erkannt werden, und dekompiliert den JSON-Code in Bicep. Ähnlich wie bei der Exportfunktion kann der resultierende Bicep-Code als Ausgangspunkt für Ihre endgültige Bicep-Datei verwendet werden.

Zum Einfügen einer Ressource können Sie die Visual Studio Code-Befehlspalette öffnen. Verwenden Sie unter Windows und Linux STRG+UMSCHALT+P und unter macOS ⌘+UMSCHALT+P.

Dekompilieren der JSON-ARM-Quellvorlage

Der zweite Schritt bei der Migration Ihrer Azure-Ressourcen zu Bicep besteht darin, Ihre JSON-ARM-Vorlagen und Azure-Ressourcen in Bicep-Vorlagen zu konvertieren. Die Bicep-Tools enthalten den Befehl decompile zum Konvertieren von Vorlagen. Sie können den decompile-Befehl entweder über die Azure-Befehlszeilenschnittstelle oder die Bicep-CLI aufrufen.

Der Dekompilierungsprozess garantiert keine vollständige Zuordnung von JSON zu Bicep. Möglicherweise müssen Sie die generierte Bicep-Datei überarbeiten, um die bewährten Methoden Ihrer Vorlage zu erfüllen, bevor Sie die Datei zum Bereitstellen von Ressourcen verwenden. Betrachten Sie sie als Ausgangspunkt für Ihre Migration. Später in diesem Modul erfahren Sie, wie Sie Probleme beheben können, die während des Dekompilierungsprozesses auftreten.

Nachdem Sie Ihre Vorlage dekompiliert haben, haben Sie die Konvertierungsphase abgeschlossen. Nun verfügen Sie über eine gültige Bicep-Datei, mit der Sie beginnen können.

Migrationsphase

In der Migrationsphase der Migration Ihrer Ressourcen zu Bicep besteht das Ziel darin, den ersten Entwurf Ihrer bereitstellbaren Bicep-Datei zu erstellen und sicherzustellen, dass sie alle Azure-Ressourcen definiert, die sich im Geltungsbereich der Migration befinden.

Die Migrationsphase besteht aus drei Schritten, die Sie nacheinander ausführen:

  1. Erstellen einer neuen leeren Bicep-Datei.
  2. Kopieren der jeweiligen Ressourcen aus der dekompilierten Vorlage.
  3. Identifizieren und Neuerstellen fehlender Ressourcen

Diagram that shows the steps for migrating a template to Bicep.

Erstellen einer neuen Bicep-Datei

Es hat sich bewährt, eine neue Bicep-Datei zu erstellen. Die in der Konvertierungsphase erstellte Datei ist ein Referenzpunkt, den Sie sich ansehen können, aber Sie sollten die Datei nicht als endgültig betrachten oder in diesem Zustand bereitstellen.

Kopieren von Ressourcen in die neue Bicep-Datei

Kopieren Sie jede Ressource einzeln aus der konvertierten Bicep-Datei in die neue Bicep-Datei. Dieser Prozess hilft Ihnen, mögliche Probleme ressourcenweise zu lösen und Verständnisschwierigkeiten zu vermeiden, wenn Ihre Vorlage an Umfang zunimmt.

Neuerstellen nicht unterstützter Ressourcen

Nicht alle Azure-Ressourcentypen können über das Azure-Portal, die Azure-Befehlszeilenschnittstelle oder Azure PowerShell exportiert werden. Beispielsweise sind VM-Erweiterungen wie DependencyAgentWindows und MMAExtension (Microsoft Monitoring Agent) Ressourcentypen, die Sie nicht exportieren können.

Wenn Sie versuchen, eine Ressource, die einen nicht unterstützten Ressourcentyp enthält, über das Azure-Portal, die Azure-Befehlszeilenschnittstelle oder Azure PowerShell zu exportieren, wird eine ausführliche Fehlermeldung generiert. Sie müssen alle Ressourcen, die nicht exportiert wurden (z. B. VM-Erweiterungen), in Ihrer neuen Bicep-Datei neu erstellen. Sie können für das Neuerstellen von Ressourcen aus mehreren Tools und Ansätzen wählen, darunter der Azure-Ressourcen-Explorer, die Referenz zu ARM-Vorlagen und Azure-Schnellstartvorlagen.

Azure-Ressourcen-Explorer

Azure-Ressourcen-Explorer ist ein Tool, das in das Azure-Portal eingebettet ist. Im Portal werden bestimmte Ressourcentypen nicht angezeigt, aber der Ressourcen-Explorer kann Ihnen eine JSON-Darstellung dieser Ressourcen liefern. Suchen Sie im Suchfeld nach dem Ressourcen-Explorer, um darauf zuzugreifen:

Screenshot of the Azure portal that shows the search box with resource explorer entered.

Im Ergebnisbereich werden eine Liste der registrierten Ressourcenanbieter für Ihr Abonnement und Details zu allen Ressourcen, Ressourcengruppen und Abonnements angezeigt, für die Sie die Berechtigung zum Anzeigen haben. Wählen Sie die Hierarchie auf der linken Seite des Bereichs aus, um eine JSON-Darstellung einer Ressource anzuzeigen:

Screenshot of the Azure portal that shows Azure Resource Explorer.

Wenn Sie eine Ressource auswählen, können Sie die JSON-Darstellung wie in diesem Beispiel anzeigen:

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

Sie können diese JSON-Darstellung wie folgt verwenden, um eine Bicep-Ressource zu definieren:

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

Hinweis

Die JSON-Darstellung enthält eine Eigenschaft namens provisioningState. Die Eigenschaft provisioningState ist schreibgeschützt und wird automatisch von Azure festgelegt, sodass sie nicht in der Bicep-Ressourcendefinition enthalten ist.

Tipp

Mit der Bicep-Erweiterung für Visual Studio Code können Sie Ihre Azure-Ressourcen in Bicep definieren. Die Bicep-Darstellung der Ressource enthält beispielsweise eine API-Version, die exportierte JSON-Version jedoch nicht. Wenn Sie in Visual Studio Code mit der Eingabe des Ressourcentyps beginnen, wird automatisch eine API-Version vorgeschlagen.

ARM-Vorlagenreferenz

Die Referenz zu ARM-Vorlagen ist eine Informationsquelle für die ARM-Vorlagenstruktur, Ressourcentypen, API-Versionen und Eigenschaftendefinitionen für Azure-Ressourcen. Die Dokumentation enthält Beispiele sowohl im Bicep- als auch im JSON-Format.

Sie können bestimmte Ressourcenanbieter und Ressourcentypen auswählen, z. B. Microsoft.Web/serverfarms und die zugehörigen API-Versionen. Sie können überprüfen, welche Ressourceneigenschaften erforderlich und welche optional sind. Sie können auch Eigenschaftenbeschreibungen anzeigen, die Ihnen helfen zu verstehen, wozu die Eigenschaften dienen.

Azure-Schnellstartvorlagen

Das Repository Azure-Schnellstartvorlagen ist eine Sammlung von Vorlagen, die von der Community bereitgestellt werden. Dieses Repository mit durchsuchbaren Vorlagen enthält Beispiele für viele Azure-Ressourcen und -Lösungen. In einigen Schnellstarts stehen sowohl eine JSON-ARM-Vorlage als auch eine Bicep-ARM-Vorlage für die Anzeige zur Verfügung. Diese Vorlagen können Sie als Referenzpunkt verwenden. Sie sollen Ihnen beim Erstellen und Überprüfen Ihrer Vorlagen für die Bereitstellung zu unterstützen.

Angenommen, Sie möchten eine Vorlage suchen, die einen Azure App Service-Plan und eine App erstellt. Jede Schnellstartvorlage gibt Ihnen die Möglichkeit, die Vorlage direkt in Azure bereitzustellen oder die Vorlage auf GitHub zu durchsuchen.

Screenshot that shows an Azure Quickstart Template that deploys a basic Linux web app.

Beachten Sie, dass die Azure-Schnellstartvorlagen Communitybeiträge sind. Einige der Beispiele können veraltet sein, da Azure-Diensten regelmäßig Features hinzugefügt werden. Die Beispiele können auch Ressourcen und Eigenschaften enthalten, die Sie für die Verwendung der Vorlage nicht benötigen. Das Repository mit Schnellstartvorlagen ist jedoch eine nützliche Ressource, mit der Sie nachvollziehen können, wie Sie Ihre Ressourcen mithilfe von ARM-Vorlagen bereitstellen können.