將資源轉換並遷移至 Bicep 檔案

  • 10 分鐘

開始移轉至 Bicep 時，請務必遵循結構化程序，以確保 Bicep 檔案會正確描述 Azure 資源。 您需要確定 Bicep 程式碼會遵循最佳做法，並經過完整測試可安全用於後續部署。 在此單元中，您將了解 Bicep 移轉的前兩個階段：轉換階段和移轉階段。

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

這兩個階段的主要重點是在您稍後重構和測試之前先準備新的 Bicep 檔案。

轉換階段

將資源移轉到 Bicep 的「轉換」階段的目標是擷取 Azure 資源的初始表示法。 您在此階段建立的 Bicep 檔案不完整，且尚未準備好使用。 但此檔案是移轉的起點。

轉換階段包含兩個可能的步驟，請依序完成：

  1. 擷取 Azure 資源的表示法。
  2. 如有需要，使用 decompile 命令，將 JavaScript 物件標記法表示法轉換為 Bicep。

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

如果要將現有 JSON 範本轉換為 Bicep，第一步很簡單，因為您已有來源範本。 您將在本單元中學習如何將其反向組譯為 Bicep。

如果您要轉換​透過使用 Azure 入口網站或其他工具部署的 Azure 資源，則需要擷取資源定義。 您可以匯出資源定義並將其轉換為 Bicep，也可以使用 Visual Studio Code 中的 [插入資源] 命令來插入 Azure 資源的 Bicep 表示法。

Azure 如何呈現資源

Azure Resource Manager 是用來在 Azure 中部署和管理資源的服務。 無論以何種方法部署資源，Resource Manager 都會追蹤所有部署到 Azure 的資源。 您可以使用 Azure 入口網站、Azure CLI、Azure PowerShell、Resource Manager REST API 和 Azure SDK 來與 Resource Manager 互動。

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

Azure 中執行有兩種類型的作業：控制平面作業和資料平面作業。 控制平面作業可用來管理訂用帳戶中的資源。 資料平面作業可用來存取資源所公開的功能。 例如，您會使用控制平面作業建立虛擬機器，但您會使用資料平面作業透過遠端桌面通訊協定 (RDP) 連線到虛擬機器。

將現有資源匯出至 JSON 範本

無論您的 Azure 資源是如何建立的，Resource Manager 都會以 JSON 格式提供每個資源的相關資訊。 當您想要取得資源的 JSON 表示法複本時，您正在「匯出」資源。 您匯出的 JSON 檔案可以反向組譯為 Bicep。

Resource Manager 提供多種方式來將 Azure 資源匯出至範本。 您可以使用 Azure 入口網站、Azure CLI 和 Azure PowerShell Cmdlet，匯出單一資源、多個資源和整個資源群組。

匯出程序是一項控制平面作業，這表示只會匯出 Azure 資源的設定。 例如，當您匯出虛擬機器時，不會匯出虛擬機器硬碟上的資料。 而且當您匯出儲存體帳戶時，匯出程序中不會包含儲存體帳戶的 Blob 和其他內容。

匯出現有資源時，您需要考量一些事項：

  • 匯出的資源定義是該資源目前狀態的快照集。 其包含資源自初始部署之後所做的所有變更。
  • 匯出的範本可能包含一些通常會從 Bicep 定義中省略的預設資源屬性。 例如，匯出程序可能會新增 Azure 自動設定的唯讀屬性。 這些屬性是唯讀，因此沒有必要納入。 請考慮在移轉到 Bicep 時將這些屬性從資源定義中移除，以免 Bicep 檔案因為不必要的程式碼而造成混淆。
  • 匯出的範本可能不會包含讓範本可重複使用所需的所有參數。 匯出範本時，許多屬性都固定寫在範本中。 稍後您將在本課程模組中了解如何新增參數。
  • 某些資源無法透過此方法匯出，而您需要在 Bicep 檔案中手動定義它們。 稍後您在此單元中了解如何重新建立這些資源。

將部署儲存至 JSON 範本

如果您曾經從 Azure 入口網站手動部署資源，您可能已注意到 [檢閱 + 建立] 索引標籤上的 [下載自動化的範本] 選項。此選項會根據您在入口網站中建立資源時所設定的名稱和屬性來儲存 JSON ARM 範本。

Resource Manager 也會追蹤資源「部署」。 部署作業包括由 Azure 入口網站資源建立體驗及任何 ARM 範本部署所提交的變更。 使用 Azure 入口網站、Azure PowerShell Cmdlet、Azure CLI 或其他工具來變更現有資源時，通常不會建立部署。

如果部署是使用相容的工具所建立，您可以從資源群組的部署歷程記錄存取部署範本。 您可以使用 Azure 入口網站、Azure CLI 或 Azure PowerShell 來儲存部署。

使用此方法儲存範本時，您需要考量一些事項：

  • 儲存的範本會顯示資源在部署時的狀態。 其中不會包含部署之後所做的任何變更。
  • 如果部署包含多個資源，您無法選取要包含或排除的特定資源。 此作業會下載作為初始部署一部分的所有資源定義。 但是，在進入流程的移轉階段時，您可以手動忽略不需要的資源。
  • 範本只會包含部署所需的資源屬性。
  • 範本可能包含可用在多個環境中重新部署範本的參數。 不過，您必須確認這些參數符合您的需求。
  • 範本可能不會包含沒有直接關聯的屬性，但您仍應該檢查範本是否包含您預期的一切，並移除任何不需要的屬性。

注意

無論您匯出資源的方式為何 (透過匯出現有資源或儲存部署)，請將匯出的檔案視為起點，而不要直接使用該檔案。 而是將其用作最終範本的起點。

將現有資源插入至 Bicep

Visual Studio Code 的 Bicep 延伸模組包含插入資源命令，其會擷取 Azure 資源的 Bicep 表示法。 此命令會從 Azure 中讀取資源的 JSON 定義、移除辨識為唯讀的屬性，並將 JSON 反向組譯為 Bicep。 與匯出功能一樣，產生的 Bicep 程式碼可以用作最終 Bicep 檔案的起點。

您可以開啟 Visual Studio Code 命令選擇區來插入資源。 在 Windows 和 Linux 上使用 Ctrl+Shift+P，或在 macOS 上使用 ⌘+Shift+P。

反向組譯來源 JSON ARM 範本

將 Azure 資源移轉至 Bicep 時，第二步是將 JSON ARM 範本和 Azure 資源轉換為 Bicep 範本。 Bicep 工具包含 decompile 命令來轉換範本。 您可以從 Azure CLI 或 Bicep CLI 叫用 decompile 命令。

反向組譯過程不保證會從 JSON 完整對應到 Bicep。 使用產生的 Bicep 檔案來部署資源之前，您可能需要修訂該檔案以符合範本最佳做法。 請考慮以其作為移轉的起點。 稍後在本課程模組中，您將學習如何修正在反向組譯過程中遇到的任何問題。

反向組譯範本之後，即已完成轉換階段。 您現在擁有一個有效的 Bicep 檔案，可供開始使用。

移轉階段

將資源移轉到 Bicep 的「移轉」階段的目標是為可部署的 Bicep 檔案建立初稿，並確保其會定義移轉範圍內的所有 Azure 資源。

移轉階段包含三個步驟，請依序完成：

  1. 建立新的空白 Bicep 檔案。
  2. 從您反向組譯的範本中複製每個資源。
  3. 識別並重新建立任何遺漏的資源。

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

建立新的 Bicep 檔案

建立新的 Bicep 檔案是個好做法。 您在轉換階段建立的檔案是供您查看的參考點，但不應將其視為最終定案或照現狀部署。

將資源複製到新的 Bicep 檔案

從已轉換的 Bicep 檔案中，將每個資源個別複製到新的 Bicep 檔案。 此過程可協助您解決每個資源的任何問題，並避免在範本變大時出現任何混亂。

重新建立不支援的資源

並非所有 Azure 資源類型都可以透過 Azure 入口網站、Azure CLI 或 Azure PowerShell 匯出。 例如，DependencyAgentWindows 和 MMAExtension (Microsoft Monitoring Agent) 之類的虛擬機器擴充功能是您無法匯出的資源類型。

當您嘗試透過 Azure 入口網站、Azure CLI 或 Azure PowerShell 匯出資源且包含不受支援的資源類型時，則會產生詳細的錯誤訊息。 您需要在新的 Bicep 檔案中重新建立任何未匯出的資源，例如虛擬機器擴充功能。 您可以從數種工具和方法中進行選擇來重新建立資源，包括 Azure 資源總管、ARM 範本參考和 Azure 快速入門範本。

Azure 資源總管

Azure 資源總管是內嵌於 Azure 入口網站中的工具。 入口網站不會顯示特定的資源類型，但資源總管可為您提供資源的 JSON 表示法。 若要存取資源總管，請在搜尋方塊中加以搜尋：

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

結果窗格會顯示您的訂用帳戶已註冊的資源提供者清單，以及您有權檢視的所有資源、資源群組和訂用帳戶的詳細資料。 若要檢視資源的 JSON 表示法，請選取窗格左側的階層：

Screenshot of the Azure portal that shows Azure Resource Explorer.

您可以選取資源來檢視 JSON 表示法，如下列範例所示：

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

您可以使用 JSON 表示法來定義 Bicep 資源：

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

注意

JSON 表示法包含名為 provisioningState 的屬性。 provisioningState 屬性是唯讀的，且由 Azure 自動設定，因此不會包含在 Bicep 資源定義中。

提示

Visual Studio Code 的 Bicep 延伸模組可協助您在 Bicep 中定義 Azure 資源。 例如，資源的 Bicep 表示法包含 API 版本，但匯出的 JSON 版本則不包含。 在 Visual Studio Code 中，當您開始輸入資源類型時，系統會自動建議 API 版本。

ARM 範本參考

ARM 範本參考是 Azure 資源的 ARM 範本結構、資源類型、API 版本和屬性定義之相關資訊的來源。 該文件提供了 Bicep 和 JSON 格式的範例。

您可以選擇特定的資源提供者和資源類型，例如 Microsoft.Web/serverfarms 及其 API 版本。 您可以檢閱哪些資源屬性是必要，哪些是選用。 您也可以檢視屬性描述，以協助您了解屬性的用途。

Azure 快速入門範本

Azure 快速入門範本存放庫是一組由社群貢獻的範本。 這個包含可搜尋範本的存放庫提供許多 Azure 資源和解決方案的範例。 在某些快速入門中，同時提供 JSON ARM 範本和 Bicep ARM 範本可供您查看。 您可以使用這些範本作為參考點，以協助您建置和驗證要部署的範本。

假設您想要尋找用來建置 Azure App Service 方案和應用程式的範本。 每個快速入門範本都可讓您選擇要直接將範本部署到 Azure，還是檢視 GitHub 上的範本。

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

請記住，Azure 快速入門範本是由社群提供。 有些範例可能已過時，因為功能會定期新增至 Azure 服務。 這些範例也可能包含您在使用範本時不需要的資源和屬性。 不過，快速入門範本的存放庫是可協助您了解如何使用 ARM 範本來部署資源的實用資源。