共用方式為

遷移 Azure 資源和 JSON ARM 範本以使用 Bicep

  • 發行項

在 Bicep 中定義 Azure 資源有許多優點，包括更簡單的語法、模組化、自動相依性管理、IntelliSense 類型驗證，以及改良的撰寫體驗。

將現有的 JSON Azure Resource Manager 範本 (ARM 範本) 移轉至 Bicep 時，建議您遵循五階段工作流程：

將 Azure 資源遷移至 Bicep 的五個階段圖表：轉換、移轉、重構、測試和部署。

程序中的第一個步驟是擷取 Azure 資源的初始表示法。 必要時，將 JSON 檔案反向組譯成初始 Bicep 檔案，您可以透過重構來改善此檔案。 如果您有工作檔案，則可以使用程序進行測試和部署，將 Azure 環境發生重大變更的風險降至最低。

將 Azure 資源遷移至 Bicep 所需的建議工作流程圖。

在本文中，我們將彙整說明這項建議的工作流程。 如需詳細資訊，請參閱移轉 Azure 資源和 JSON ARM 範本以使用 Bicep Learn 課程模組。

階段 1：轉換

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

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

  1. 擷取 Azure 資源的表示法。 如果要將現有 JSON 範本轉換為 Bicep，第一步很簡單，因為您已經有來源範本。 如果您要轉換以入口網站或其他工具部署的 Azure 資源，必須擷取資源定義。 您可以使用 Azure 入口網站、Azure CLI 或 Azure PowerShell Cmdlet 來擷取資源的 JSON 表示法，以匯出單一資源、多個資源和整個資源群組。 您可以使用 Insert Resource Visual Studio Code 內的 命令來匯入 Azure 資源的 Bicep 表示法。

  2. 如有需要，請使用反編譯命令，將 JSON 表示法轉換成 Bicep。 Bicep 工具包含decompile轉換範本的命令。您可以使用 decompile Bicep 擴充功能、Azure CLI 或 Bicep CLI，從 Visual Studio Code 叫用命令。 反向組譯流程是一種盡力而為流程，不保證從 JSON 完整對應到 Bicep。 使用產生的 Bicep 檔案來部署資源之前，您可能需要將檔案修訂為符合範本最佳做法。

注意

您可以透過開啟 Visual Studio Code 命令選擇區來匯入資源。 在 Windows 和 Linux 上按 Ctrl+Shift+P，並在 macOS 上按 ⌘+Shift+P。

Visual Studio Code 可讓您貼上 JSON 作為 Bicep。 如需詳細資訊，請參閱 將 JSON 貼上為 Bicep 命令。

階段 2: 移轉

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

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

  1. 建立新的空白 Bicep 檔案。 建立全新的 Bicep 檔案是好辦法。 您在「轉換」階段建立的檔案是給您看的參考點，不應該視為最終定案或照現狀部署。

  2. 從您反向組譯的範本中複製每個資源。 從已轉換的 Bicep 檔案中，將每個資源個別複製到新的 Bicep 檔案。 此流程協助您解決每個資源的任何問題，避免隨著範本越來越大而引起任何混淆。

  3. 識別並重新建立任何遺漏的資源。 並非所有 Azure 資源類型都可以透過 Azure 入口網站、Azure CLI 或 Azure PowerShell 匯出。 例如，DependencyAgentWindows 和 MMAExtension (Microsoft Monitoring Agent) 之類的虛擬機器擴充功能不是支援匯出的資源類型。 針對任何未匯出的資源 (例如虛擬機器擴充功能)，您需要在新的 Bicep 檔案中重新建立這些資源。 您可以使用數種工具和方法來重新建立資源，包括 Azure 資源總管、Bicep 和 ARM 範本參考文件和 Azure 快速入門範本網站。

階段 3：重構

在將資源移轉至 Bicep 的重構階段中，目標是要改善 Bicep 程式碼的品質。 這些增強功能包括變更，例如新增程式碼註解，使範本符合範本標準。

部署階段包含八個步驟，請依序完成：

  1. 檢閱資源 API 版本。 匯出 Azure 資源時，匯出的範本可能未包含某資源類型的最新 API 版本。 如果未來部署需要特定的屬性，請將 API 更新為適當的版本。 建議檢閱每個所匯出資源的 API 版本。

  2. 在新的 Bicep 檔案中檢閱 Linter 建議。 使用適用於 Visual Studio Code 的 Bicep 擴充功能建立 Bicep 檔案時，Bicep linter 會自動執行並在程式碼中醒目提示建議和錯誤。 許多建議和錯誤都提供選項，讓您可以套用問題快速修正。 檢閱這些建議並調整 Bicep 檔案。

  3. 修訂參數、變數和符號名稱。 反編譯程式所產生的參數、變數和符號名稱可能不符合您的標準命名慣例。 檢閱產生的名稱，視需要進行調整。

  4. 簡化運算式。 反向組譯流程不見得會用到 Bicep 的某些功能。 檢閱轉換所產生的任何運算式並簡化。 例如，反向組譯的範本可能包含 concat() 和 format() 函數，利用字串內插補點即可簡化。 檢閱 Linter 的任何建議，並視需要進行調整。

  5. 檢閱子資源和擴充資源。 有多種方法可以在 Bicep 中宣告子資源和擴充功能資源，包括串連資源名稱、使用 parent 關鍵字，以及使用巢狀資源。 請在反向組譯後檢閱這些資源，確定結構符合您的標準。 例如，請確定您未使用字串串連來建立子資源名稱，應該使用 parent 屬性或巢狀資源。 同樣地，子網路可以視為虛擬網路的屬性或個別資源來參考。

  6. 模組化。 如果您要轉換的範本有許多資源，為求簡化，請考慮將個別資源類型細分為模組。 Bicep 模組有助於降低部署的複雜度，並提高 Bicep 程式碼的重複使用性。

    注意

    在 Bicep 部署中，JSON 範本可以作為模組。 Bicep 能夠辨識 JSON 模組，並如同使用 Bicep 模組一樣來參考。

  7. 新增註解和描述。 良好的 Bicep 程式碼能夠「自編文件」。 Bicep 可讓您將註解和 @description() 屬性新增至程式碼，以協助您記錄基礎結構。 Bicep 支援單行註解 (使用 // 字元順序) 和多行註解 (首尾分別是 /* 和 */)。 您可以將註解新增至程式碼中的特定行和程式碼區段。

  8. 遵循 Bicep 最佳做法。 請確定 Bicep 檔案遵循標準建議。 檢閱 Bicep 最佳做法參考文件，以免疏漏。

階段 4：測試

在將資源遷移至 Bicep 的「測試」階段，目標是驗證所遷移範本的完整性，並執行測試部署。

測試階段包含兩個步驟，請依序完成：

  1. 執行 ARM 範本部署假設狀況作業。 為了在部署之前協助您驗證已轉換的範本，您可以使用 Azure Resource Manager 範本部署假設狀況作業。 此作業會比較環境的目前狀態與範本中定義的理想狀態。 此工具只輸出將發生的變更清單，「不會」將變更套用至環境。 增量和完整模式部署都可以使用假設狀況。 即使您打算使用增量模式來部署範本，最好還是以完整模式執行假設狀況作業。

  2. 執行測試部署。 將已轉換的 Bicep 範本引進到生產環境之前，請考慮執行多次測試部署。 如果您有多個環境 (例如，開發、測試和生產)，您可能會想要先嘗試將範本部署至其中一個非生產環境。 部署之後，比較原始資源與新的資源部署是否一致。

階段 5：部署

在將資源遷移至 Bicep 的「部署」階段，目標是將最終 Bicep 檔案部署到生產環境。

部署階段包含四個步驟，請依序完成：

  1. 備妥復原計劃。 必須有能力從失敗部署中復原。 如果您的環境中發生任何重大變化，請建立復原策略。 清查所部署的資源類型，例如虛擬機器、Web 應用程式和資料庫。 也應該考慮每個資源的資料平面。 您是否有辦法復原虛擬機器及其資料？ 您是否有辦法在刪除之後復原資料庫？ 如果部署發生任何問題，則完善的復原計畫將有助讓停機時間降至最低。

  2. 對生產環境執行假設狀況作業。 將最終 Bicep 檔案部署到生產環境之前，請先對生產環境執行假設狀況作業，記得要使用生產參數值，然後將結果記錄下來。

  3. 手動部署。 如果您要在管線中使用已轉換的範本 (例如 Azure DevOps 或 GitHub Actions)，請考慮先從本機電腦執行部署。 最好先測試範本的功能，再將其納入生產管線。 這樣才能在有問題時迅速反應。

  4. 執行煙霧測試 (Smoke Test)。 部署完成之後，您應該執行一系列的煙霧測試，以確保您的應用程式或工作負載正常運作。 例如，測試能否透過一般存取管道來存取 Web 應用程式，例如公有網際網路或透過公司 VPN。 對於資料庫，請嘗試建立資料庫連接，然後執行一連串查詢。 使用虛擬機器、登入虛擬機器，並確定所有服務都已啟動並執行。

下一步

若要深入瞭解 Bicep 反編譯程式，請參閱 將 ARM 範本 JSON 反編譯至 Bicep。