建立 Azure Image Builder Bicep 或 ARM 範本 JSON 範本

適用於: ✔️ Linux VM ✔️ Windows VM ✔️ 彈性擴展集

Azure Image Builder 會使用 Bicep 檔案或 ARM 範本 JSON 範本檔案,將資訊傳遞至 Image Builder 服務。 在本文中,我們會探討檔案的區段,以便您自行建置。 如需最新的 API 版本,請參閱 範本參考。 若要查看完整.json檔案的範例,請參閱 Azure Image Builder GitHub

基本格式為:

{
  "type": "Microsoft.VirtualMachineImages/imageTemplates",
  "apiVersion": "2022-02-14",
  "location": "<region>",
  "tags": {
    "<name>": "<value>",
    "<name>": "<value>"
  },
  "identity": {},
  "properties": {
    "buildTimeoutInMinutes": <minutes>,
    "customize": [],
    "errorHandling":[],
    "distribute": [],
    "optimize": [],
    "source": {},
    "stagingResourceGroup": "/subscriptions/<subscriptionID>/resourceGroups/<stagingResourceGroupName>",
    "validate": {},
    "vmProfile": {
      "vmSize": "<vmSize>",
      "osDiskSizeGB": <sizeInGB>,
      "vnetConfig": {
        "subnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName>",
        "proxyVmSize": "<vmSize>"
      },
      "userAssignedIdentities": [
              "/subscriptions/<subscriptionID>/resourceGroups/<identityRgName>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identityName1>",
        "/subscriptions/<subscriptionID>/resourceGroups/<identityRgName>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identityName2>",
        "/subscriptions/<subscriptionID>/resourceGroups/<identityRgName>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identityName3>",
        ...
      ]
    }
  }
}

類型和 API 版本

type是資源類型,必須是 Microsoft.VirtualMachineImages/imageTemplates。 隨著 API 變更,將會 apiVersion 隨著時間變更而變更。 如需 Azure VM 映射產生器服務的主要 API 變更和功能更新,請參閱 Azure VM 映射產生器服務的新功能。

"type": "Microsoft.VirtualMachineImages/imageTemplates",
"apiVersion": "2022-02-14",

Location

位置是建立自定義映像的區域。 支援下列區域:

  • 美國東部
  • 美國東部 2
  • 美國中西部
  • 美國西部
  • 美國西部 2
  • 美國西部 3
  • 美國中南部
  • 北歐
  • 西歐
  • 東南亞
  • 澳洲東南部
  • 澳大利亞東部
  • 英國南部
  • 英國西部
  • 巴西南部
  • 加拿大中部
  • 印度中部
  • 美國中部
  • 法國中部
  • 德國中西部
  • 日本東部
  • 美國中北部
  • 挪威東部
  • 瑞士北部
  • Jio 印度西部
  • 阿拉伯聯合大公國北部
  • 東亞
  • 南韓中部
  • 南非北部
  • 卡達中部
  • USGov 亞利桑那州 (公開預覽)
  • USGov 維吉尼亞州 (公開預覽)
  • 中國北方 3 (公開預覽)
  • 瑞典中部
  • 波蘭中部

重要

註冊此功能 Microsoft.VirtualMachineImages/FairfaxPublicPreview 以存取 Azure Government 區域中的 Azure Image Builder 公開預覽版(USGov 亞利桑那州和 USGov 維吉尼亞州)。

重要

註冊此功能 Microsoft.VirtualMachineImages/MooncakePublicPreview 以存取中國北方 3 區域中的 Azure Image Builder 公開預覽。

若要存取 Azure Government 區域中的 Azure VM 映射產生器公開預覽版(USGov 亞利桑那州和 USGov 維吉尼亞州),您必須註冊 Microsoft.VirtualMachineImages/FairfaxPublicPreview 功能。 若要這樣做,請在PowerShell或 Azure CLI 中執行下列命令:

Register-AzProviderPreviewFeature -ProviderNamespace Microsoft.VirtualMachineImages -Name FairfaxPublicPreview

若要存取中國北方 3 區域中的 Azure VM 映射產生器公開預覽,您必須註冊 Microsoft.VirtualMachineImages/MooncakePublicPreview 功能。 若要這樣做,請在PowerShell或 Azure CLI 中執行下列命令:

Register-AzProviderPreviewFeature -ProviderNamespace Microsoft.VirtualMachineImages -Name MooncakePublicPreview
"location": "<region>"

資料落地

當客戶要求該區域中的組建時,Azure VM 映射產生器服務不會在具有嚴格單一區域數據落地需求的區域內儲存或處理客戶數據。 如果具有數據落地需求的區域服務中斷,您必須在不同的區域和地理位置中建立 Bicep 檔案/範本。

區域備援

散發支援區域備援,VHD 預設會散發到區域備援 儲存體 (ZRS) 帳戶,且 Azure 計算資源庫(先前稱為 共用映像庫)版本將支援 ZRS 記憶體類型

標籤

標籤是索引鍵/值組,您可以針對產生的影像指定。

身分識別

有兩種方式可以新增使用者指派的身分識別,如下所述。

Azure Image Builder 映像範本資源的使用者指派身分識別

必要 - 若要讓 Image Builder 具有讀取/寫入映射的許可權,以及從 Azure 儲存體 讀取腳本中,您必須建立具有個別資源許可權的 Azure 使用者指派身分識別。 如需映像產生器許可權的運作方式和相關步驟的詳細資訊,請參閱 建立映像並使用使用者指派的受控識別來存取 Azure 記憶體帳戶中的檔案。

"identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
        "<imgBuilderId>": {}
    }
}

Image Builder 服務使用者指派的身分識別:

  • 僅支援單一身分識別。
  • 不支援自定義功能變數名稱。

若要深入瞭解,請參閱 什麼是適用於 Azure 資源的受控識別?。 如需部署這項功能的詳細資訊,請參閱 使用 Azure CLI 為 Azure VM 上的 Azure 資源設定受控識別。

映射產生器建置 VM 的使用者指派身分識別

此屬性僅適用於 API 版本或更新版本 2021-10-01

選擇性 - 映射產生器建置 VM 是由您訂用帳戶中的 Image Builder 服務所建立,用來建置和自定義映像。 若要讓映射產生器建置 VM 具有在訂用帳戶中向 Azure 金鑰保存庫 等其他服務進行驗證的許可權,您必須建立一或多個具有個別資源許可權的 Azure 使用者指派身分識別。 然後,Azure Image Builder 可以將這些使用者指派的身分識別與組建 VM 產生關聯。 自定義程式腳本會在建置 VM 內執行,然後擷取這些身分識別的令牌,並視需要與其他 Azure 資源互動。 請注意,Azure Image Builder 的使用者指派身分識別必須具有 Azure Image Builder 所有使用者指派身分識別的「受控識別操作員」角色指派,才能將它們與組建 VM 產生關聯。

注意

請注意,您可以為映射產生器建置 VM 指定多個身分識別,包括您為映像範本資源建立的身分識別。 根據預設,您為映像範本資源建立的身分識別不會自動新增至組建 VM。

"properties": {
  "vmProfile": {
    "userAssignedIdentities": [
      "/subscriptions/<subscriptionID>/resourceGroups/<identityRgName>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identityName>"
    ]
  }
}

映射產生器建置 VM 使用者指派的身分識別:

  • 支援在 VM 上設定一或多個使用者指派的受控識別清單。
  • 支援跨訂用帳戶案例(在相同租使用者下的另一個訂用帳戶中建立映像範本時,於一個訂用帳戶中建立的身分識別)。
  • 不支援跨租使用者案例(在另一個租使用者中建立映像範本時,在一個租使用者中建立的身分識別)。

若要深入了解,請參閱:

屬性:buildTimeoutInMinutes

建置映像範本時要等候的最大持續時間(包括所有自定義專案、驗證和散發套件)。

如果您未指定 屬性或將值設定為 0,則會使用預設值,也就是 240 分鐘或 4 小時。 最小值為 6 分鐘,最大值為 960 分鐘或 16 小時。 當達到逾時值時(映射組建是否已完成),您會看到類似下列的錯誤:

[ERROR] Failed while waiting for packerizer: Timeout waiting for microservice to
[ERROR] complete: 'context deadline exceeded'

針對 Windows,不建議設定 buildTimeoutInMinutes 低於 60 分鐘。 如果您發現您達到逾時,請檢閱 記錄 ,以查看自定義步驟是否正在等候類似使用者輸入的內容。 如果您發現需要更多時間才能完成自定義,請增加 buildTimeoutInMinutes 值。 但是,不要設定太高,因為您可能必須等待它逾時,再看到錯誤。

屬性:自定義

Image Builder 支援多個「自訂工具」,這是用來自定義映像的函式,例如執行腳本或重新啟動伺服器。

使用 customize時:

  • 您可以使用多個自訂工具。
  • 自訂工具會依範本中指定的順序執行。
  • 如果一個自定義工具失敗,則整個自定義元件將會失敗並回報錯誤。
  • 在範本中使用腳本之前,請先徹底測試腳本。 自行偵錯腳本會比較容易。
  • 請勿將敏感數據放入腳本中。 您可以在映像範本定義中檢視內嵌命令。 如果您有敏感性資訊(包括密碼、SAS 令牌、驗證令牌等),則應將它移至 Azure 儲存體 中的腳本,其中存取需要驗證。
  • 除非您使用 MSI,否則文本位置必須可公開存取。

customize 段是陣列。 支援的自定義工具類型包括:File、PowerShell、Shell、WindowsRestart 和 WindowsUpdate。

"customize": [
  {
    "type": "File",
    "destination": "string",
    "sha256Checksum": "string",
    "sourceUri": "string"
  },
  {
    "type": "PowerShell",
    "inline": [ "string" ],
    "runAsSystem": "bool",
    "runElevated": "bool",
    "scriptUri": "string",
    "sha256Checksum": "string",
    "validExitCodes": [ "int" ]
  },
  {
    "type": "Shell",
    "inline": [ "string" ],
    "scriptUri": "string",
    "sha256Checksum": "string"
  },
  {
    "type": "WindowsRestart",
    "restartCheckCommand": "string",
    "restartCommand": "string",
    "restartTimeout": "string"
  },
  {
    "type": "WindowsUpdate",
    "filters": [ "string" ],
    "searchCriteria": "string",
    "updateLimit": "int"
  }
]

Shell 自定義工具

Shell自訂工具支援在Linux上執行殼層腳本。 殼層腳本必須可公開存取,或者您必須設定 MSI ,讓 Image Builder 存取它們。

"customize": [
  {
    "type": "Shell",
    "name": "<name>",
    "scriptUri": "<link to script>",
    "sha256Checksum": "<sha256 checksum>"
  }
],
"customize": [
  {
    "type": "Shell",
    "name": "<name>",
    "inline": "<commands to run>"
  }
]

自訂屬性:

  • type – Shell。

  • name - 用於追蹤自定義的名稱。

  • scriptUri - 檔案位置的 URI。

  • 內嵌 - 殼層命令的陣列,並以逗號分隔。

  • sha256Checksum - 檔案 sha256 總和檢查碼的值,您會在本機產生此值,然後 Image Builder 會檢查碼並驗證。

    若要產生 sha256Checksum,請使用 Mac/Linux 上的終端機執行: sha256sum <fileName>

注意

內嵌命令會儲存為映像範本定義的一部分,您可以在傾印映像定義時看到這些命令。 如果您有敏感性命令或值(包括密碼、SAS 令牌、驗證令牌等),建議將這些命令移至腳本中,並使用使用者身分識別進行驗證以 Azure 儲存體。

進階用戶許可權

在 命令前面加上 sudo ,以使用進階使用者許可權來執行命令。 您可以將命令新增至文稿,或使用內嵌命令,例如:

"type": "Shell",
"name": "setupBuildPath",
"inline": [
    "sudo mkdir /buildArtifacts",
    "sudo cp /tmp/index.html /buildArtifacts/index.html"
]

使用 sudo 的文稿範例,您可以使用 scriptUri 來參考:

#!/bin/bash -e

echo "Telemetry: creating files"
mkdir /myfiles

echo "Telemetry: running sudo 'as-is' in a script"
sudo touch /myfiles/somethingElevated.txt

Windows 重新啟動自訂工具

WindowsRestart自訂工具可讓您重新啟動 Windows VM,並等候 VM 重新上線,此自定義工具可讓您安裝需要重新啟動的軟體。

"customize": [
  {
    "type": "WindowsRestart",
    "restartCommand": "shutdown /r /f /t 0",
    "restartCheckCommand": "echo Azure-Image-Builder-Restarted-the-VM  > c:\\buildArtifacts\\azureImageBuilderRestart.txt",
    "restartTimeout": "5m"
  }
]

自訂屬性:

  • 類型:WindowsRestart。
  • restartCommand - 執行重新啟動的命令(選擇性)。 預設值為 'shutdown /r /f /t 0 /c \"packer restart\"'
  • restartCheckCommand – 檢查重新啟動是否成功 (選擇性) 的命令。
  • restartTimeout - 重新啟動指定為大小和單位字串串的逾時。 例如, 5m (5 分鐘)或 2h (2 小時)。 預設值為: 5m

注意

沒有 Linux 重新啟動自訂工具。

PowerShell 自定義工具

PowerShell自定義工具支援在 Windows 上執行 PowerShell 腳本和內嵌命令,必須公開存取腳本,IB 才能存取這些腳本。

"customize": [
  {
    "type": "PowerShell",
    "name":   "<name>",
    "scriptUri": "<path to script>",
    "runElevated": <true false>,
    "runAsSystem": <true false>,
    "sha256Checksum": "<sha256 checksum>"
  },
  {
    "type": "PowerShell",
    "name": "<name>",
    "inline": "<PowerShell syntax to run>",
    "validExitCodes": [<exit code>],
    "runElevated": <true or false>,
    "runAsSystem": <true or false>
  }
]

自訂屬性:

  • type – PowerShell。

  • scriptUri - PowerShell 腳本檔案位置的 URI。

  • 內嵌 – 要執行的內嵌命令,以逗號分隔。

  • validExitCodes – 可從腳本/內嵌命令傳回的選擇性有效程序代碼。 屬性可避免腳本/內嵌命令的回報失敗。

  • runElevated – 選擇性、布爾值,支持執行具有更高許可權的命令和腳本。

  • runAsSystem - 選擇性的布爾值,會決定是否應該以系統使用者身分執行 PowerShell 腳本。

  • sha256Checksum - 在本機產生檔案的SHA256總和檢查碼、將總和檢查碼值更新為小寫,而Image Builder 會在部署映像範本期間驗證總和檢查碼。

    若要產生 sha256Checksum,請在 PowerShell 中使用 Get-FileHash Cmdlet。

檔案自訂工具

自訂 File 工具可讓 Image Builder 從 GitHub 存放庫或 Azure 記憶體下載檔案。 自訂工具同時支援Linux和 Windows。 如果您有依賴組建成品的映射組建管線,您可以設定檔案自定義工具以從組建共用下載,並將成品移至映像。

"customize": [
  {
    "type": "File",
    "name": "<name>",
    "sourceUri": "<source location>",
    "destination": "<destination>",
    "sha256Checksum": "<sha256 checksum>"
  }
]

檔案自訂工具屬性:

  • sourceUri - 可存取的記憶體端點,此端點可以是 GitHub 或 Azure 記憶體。 您只能下載一個檔案,而不是整個目錄。 如果您需要下載目錄,請使用壓縮檔案,然後使用Shell或PowerShell自定義工具將其解壓縮。

    注意

    如果 sourceUri 是 Azure 儲存體 帳戶,不論 Blob 是否標示為公用,您必須授與受控使用者識別許可權,才能讀取 Blob 上的存取權。 請參閱此 範例 來設定記憶體許可權。

  • destination – 完整目的地路徑和檔名。 任何參考的路徑和子目錄都必須存在,請使用Shell或PowerShell自定義工具事先設定這些路徑。 您可以使用文稿自訂工具來建立路徑。

Windows 目錄和 Linux 路徑支援此自定義工具,但有一些差異:

  • Linux – 映射產生器唯一可以寫入的路徑是 /tmp。
  • Windows – 沒有路徑限制,但路徑必須存在。

如果嘗試下載檔案時發生錯誤,或將其放在指定的目錄中,則自定義步驟會失敗,而且此錯誤將會在customization.log中。

注意

檔案自訂工具僅適用於小型檔案下載, < 20MB。 針對較大的檔案下載,請使用腳本或內嵌命令,然後使用程式代碼來下載檔案,例如 Linux wgetcurl、Windows、 Invoke-WebRequest。 針對 Azure 記憶體中的檔案,請遵循此處的文件,確定您指派具有許可權的身分識別,以檢視該檔案至組建 VM: 映射產生器組建 VM 的使用者指派身分識別。 Azure Image Builder 必須可公開存取未儲存在 Azure 中的任何檔案,才能下載它。

  • sha256Checksum - 在本機產生檔案的SHA256總和檢查碼、將總和檢查碼值更新為小寫,而Image Builder 會在部署映像範本期間驗證總和檢查碼。

    若要產生 sha256Checksum,請在 PowerShell 中使用 Get-FileHash Cmdlet。

Windows Update 自定義工具

自定義WindowsUpdate工具建置在Packer社群所維護的社群 Windows Update 佈建工具上,這是Packer社群所維護的 開放原始碼 專案。 Microsoft 會使用 Image Builder 服務測試及驗證布建工具,並支持調查其問題,並努力解決問題,不過 Microsoft 並未正式支援 開放原始碼 專案。 如需 Windows Update 佈建程式的詳細文件及說明,請參閱專案存放庫。

"customize": [
  {
    "type": "WindowsUpdate",
    "searchCriteria": "IsInstalled=0",
    "filters": [
      "exclude:$_.Title -like '*Preview*'",
      "include:$true"
    ],
    "updateLimit": 20
  }
]

自訂工具屬性:

  • type – WindowsUpdate。
  • searchCriteria - 選擇性,定義安裝的更新類型(例如建議或重要),BrowseOnly=0 和 IsInstalled=0 (建議) 是預設值。
  • 篩選 – 選擇性,可讓您指定要包含或排除更新的篩選。
  • updateLimit – 選擇性定義可以安裝的更新數目,預設為 1000。

注意

如果有任何未完成的 Windows 重新啟動,或仍在執行的應用程式安裝,Windows Update 自定義工具可能會失敗,通常您可能會在 customization.log 中看到此錯誤。 System.Runtime.InteropServices.COMException (0x80240016): Exception from HRESULT: 0x80240016 我們強烈建議您考慮在 Windows 重新啟動中新增 ,以及/或允許應用程式有足夠的時間使用 內嵌命令或腳本中的睡眠 或等候命令完成安裝,再執行 Windows Update。

一般化

根據預設,Azure Image Builder 也會在每個映像自定義階段結束時執行 deprovision 程序代碼,以將映像一般化。 一般化是映像設定的程式,因此可以重複使用它來建立多個 VM。 針對 Windows VM,Azure Image Builder 會使用 Sysprep。 針對 Linux,Azure Image Builder 會執行 waagent -deprovision

將 Image Builder 使用者一般化命令可能不適合每個情況,因此 Azure Image Builder 可讓您視需要自定義此命令。

如果您要移轉現有的自定義,而且您使用不同的 Sysprep/waagent 命令,您可以使用 Image Builder 泛型命令,如果 VM 建立失敗,請使用您自己的 Sysprep 或 waagent 命令。

如果 Azure Image Builder 成功建立 Windows 自定義映像,並從中建立 VM,然後發現 VM 建立失敗或未順利完成,您需要檢閱 Windows Server Sysprep 檔,或向 Windows Server Sysprep 客戶服務支援小組提出支援要求,他們可以針對正確的 Sysprep 使用量進行疑難解答並建議。

默認 Sysprep 命令

Write-Output '>>> Waiting for GA Service (RdAgent) to start ...'
while ((Get-Service RdAgent).Status -ne 'Running') { Start-Sleep -s 5 }
Write-Output '>>> Waiting for GA Service (WindowsAzureTelemetryService) to start ...'
while ((Get-Service WindowsAzureTelemetryService) -and ((Get-Service WindowsAzureTelemetryService).Status -ne 'Running')) { Start-Sleep -s 5 }
Write-Output '>>> Waiting for GA Service (WindowsAzureGuestAgent) to start ...'
while ((Get-Service WindowsAzureGuestAgent).Status -ne 'Running') { Start-Sleep -s 5 }
if( Test-Path $Env:SystemRoot\system32\Sysprep\unattend.xml ) {
  Write-Output '>>> Removing Sysprep\unattend.xml ...'
  Remove-Item $Env:SystemRoot\system32\Sysprep\unattend.xml -Force
}
if (Test-Path $Env:SystemRoot\Panther\unattend.xml) {
  Write-Output '>>> Removing Panther\unattend.xml ...'
  Remove-Item $Env:SystemRoot\Panther\unattend.xml -Force
}
Write-Output '>>> Sysprepping VM ...'
& $Env:SystemRoot\System32\Sysprep\Sysprep.exe /oobe /generalize /quiet /quit
while($true) {
  $imageState = (Get-ItemProperty HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Setup\State).ImageState
  Write-Output $imageState
  if ($imageState -eq 'IMAGE_STATE_GENERALIZE_RESEAL_TO_OOBE') { break }
  Start-Sleep -s 5
}
Write-Output '>>> Sysprep complete ...'

預設 Linux 取消布建命令

WAAGENT=/usr/sbin/waagent
waagent -version 1> /dev/null 2>&1
if [ $? -eq 0 ]; then
  WAAGENT=waagent
fi
$WAAGENT -force -deprovision+user && export HISTSIZE=0 && sync

覆寫命令

若要覆寫命令,請使用 PowerShell 或 Shell 腳本布建器來建立具有確切檔名的命令檔案,並將其放在正確的目錄中:

  • Windows:c:\DeprovisioningScript.ps1
  • Linux:/tmp/DeprovisioningScript.sh

Image Builder 會讀取這些命令,這些命令會寫出至 AIB 記錄。 customization.log 請參閱 如何收集記錄的疑難解答

屬性:errorHandling

屬性 errorHandling 可讓您設定在映像建立期間如何處理錯誤。

{
  "errorHandling": {
    "onCustomizerError": "abort",
    "onValidationError": "cleanup"
  }
}

屬性 errorHandling 可讓您設定在映像建立期間如何處理錯誤。 它有兩個屬性:

  • onCustomizerError - 指定在映像建立自定義工具階段期間發生錯誤時要採取的動作。
  • onValidationError - 指定在映像範本驗證期間發生錯誤時要採取的動作。

屬性 errorHandling 也有兩個在映像建立期間處理錯誤的可能值:

  • 清除 - 即使 Packer 或其中一個自訂/驗證發生錯誤,仍會清除 Packer 所建立的暫存資源。 這會維持與現有行為的回溯相容性。
  • abort - 如果 Packer 發生錯誤,Azure Image Builder (AIB) 服務會略過暫時資源的清除。 身為 AIB 範本的擁有者,您必須負責從訂用帳戶清除這些資源。 這些資源可能包含有用的資訊,例如暫存 VM 中留下的記錄和檔案,有助於調查 Packer 所遇到的錯誤。

屬性:散發

Azure Image Builder 支援三個散發目標:

  • ManagedImage - 受控映射。
  • sharedImage - Azure 計算資源庫。
  • VHD - 記憶體帳戶中的 VHD

您可以將映像散發至相同組態中的兩個目標類型。

注意

默認的 AIB sysprep 命令不包含 「/mode:vm」,不過,建立將安裝 HyperV 角色的映像時,可能需要此屬性。 如果您需要新增此命令自變數,則必須覆寫 sysprep 命令。

因為您可以有多個要散發的目標,因此 Image Builder 會針對每個可藉由查詢 runOutputName來存取的散發目標維護狀態。 runOutputName是一個物件,您可以查詢發佈后發佈的相關信息。 例如,您可以查詢 VHD 的位置,或映像版本複寫到的區域,或建立 SIG 映射版本的位置。 這是每個散發目標的屬性。 runOutputName每個散發目標都必須是唯一的。 以下是查詢 Azure 計算資源庫散發套件的範例:

subscriptionID=<subcriptionID>
imageResourceGroup=<resourceGroup of image template>
runOutputName=<runOutputName>

az resource show \
  --ids "/subscriptions/$subscriptionID/resourcegroups/$imageResourceGroup/providers/Microsoft.VirtualMachineImages/imageTemplates/ImageTemplateLinuxRHEL77/runOutputs/$runOutputName"  \
  --api-version=2021-10-01

輸出:

{
  "id": "/subscriptions/xxxxxx/resourcegroups/rheltest/providers/Microsoft.VirtualMachineImages/imageTemplates/ImageTemplateLinuxRHEL77/runOutputs/rhel77",
  "identity": null,
  "kind": null,
  "location": null,
  "managedBy": null,
  "name": "rhel77",
  "plan": null,
  "properties": {
    "artifactId": "/subscriptions/xxxxxx/resourceGroups/aibDevOpsImg/providers/Microsoft.Compute/galleries/devOpsSIG/images/rhel/versions/0.24105.52755",
    "provisioningState": "Succeeded"
  },
  "resourceGroup": "rheltest",
  "sku": null,
  "tags": null,
  "type": "Microsoft.VirtualMachineImages/imageTemplates/runOutputs"
}

散發:managedImage

映像輸出是受控映像資源。

{
  "type":"ManagedImage",
  "imageId": "<resource ID>",
  "location": "<region>",
  "runOutputName": "<name>",
  "artifactTags": {
      "<name>": "<value>",
      "<name>": "<value>"
  }
}

散發屬性:

  • type – ManagedImage
  • imageId – 目的地映射的資源標識符,預期格式:/subscriptions/<subscriptionId>/resourceGroups/<destinationResourceGroupName>/providers/Microsoft.Compute/images/<imageName>
  • location - 受控映射的位置。
  • runOutputName – 用來識別散發的唯一名稱。
  • artifactTags - 選擇性使用者指定的索引鍵\值標記。

注意

目的地資源群組必須存在。 如果您想要將映像散發到不同的區域,則會增加部署時間。

散發:sharedImage

Azure 計算資源庫是新的映射管理服務,可管理映射區域復寫、版本控制及共用自定義映射。 Azure Image Builder 支援使用此服務進行散發,因此您可以將映像散發至 Azure 計算資源庫所支援的區域。

Azure 計算資源庫是由:

  • 資源庫 - 多個映像的容器。 資源庫會部署在一個區域中。
  • 影像定義 - 影像的概念群組。
  • 映射版本 - 用於部署 VM 或擴展集的映像類型。 映像版本可以復寫至需要部署 VM 的其他區域。

您必須先建立資源庫和映像定義,才能發佈至資源庫,請參閱 建立資源庫

注意

映像版本標識碼必須與現有 Azure 計算資源庫中的任何映像版本不同或不同。

{
  "type": "SharedImage",
  "galleryImageId": "<resource ID>",
  "runOutputName": "<name>",
  "artifactTags": {
      "<name>": "<value>",
      "<name>": "<value>"
  }
}

下列 JSON 是如何使用 replicationRegions 字段散發至 Azure 計算資源庫的範例。

  "replicationRegions": [
      "<region where the gallery is deployed>",
      "<region>"
  ]

注意

replicationRegions 已取代資源庫散發套件,因為 targetRegions 已更新屬性。 如需詳細資訊,請參閱 targetRegions

散發:targetRegions

下列 JSON 是如何使用 targetRegions 字段散發至 Azure 計算資源庫的範例。

"distribute": [
      {
        "type": "SharedImage",
        "galleryImageId": "<resource ID>",
        "runOutputName": "<name>",
        "artifactTags": {
          "<name>": "<value>",
          "<name>": "<value>"
        },
        "targetRegions": [
             {
              "name": "eastus",
              "replicaCount": 2,
              "storageAccountType": "Standard_ZRS"
             },
             {
              "name": "eastus2",
              "replicaCount": 3,
              "storageAccountType": "Premium_LRS"
             }
          ]
       },
    ]

散發資源庫的屬性:

  • type - sharedImage

  • galleryImageId – Azure 計算資源庫的標識符,此屬性可透過兩種格式指定:

    • 自動版本設定 - 映射產生器會為您產生單調版本號碼,當您想要從相同的範本中繼續重建映射時,此屬性很有用:格式為: /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Compute/galleries/<sharedImageGalleryName>/images/<imageGalleryName>
    • 明確版本控制 - 您可以傳入您想要映射產生器使用的版本號碼。 格式為: /subscriptions/<subscriptionID>/resourceGroups/<rgName>/providers/Microsoft.Compute/galleries/<sharedImageGalName>/images/<imageDefName>/versions/<version - for example: 1.1.1>
  • runOutputName – 用來識別散發的唯一名稱。

  • artifactTags - 選擇性使用者指定的索引鍵\值標記。

  • replicationRegions - 複寫的區域陣列。 其中一個區域必須是資源庫部署所在的區域。 新增區域表示建置時間增加,因為建置在複寫完成之前不會完成。 此欄位已取代為 API 版本 2022-07-01,請在散發 「SharedImage」 類型時使用 targetRegions

  • targetRegions - 複寫的區域陣列。 這是新推出的 2022-07-01 API一部分,僅適用於SharedImage類型散發。

  • excludeFromLatest (選擇性) - 可讓您將您所建立的映射版本標示為資源庫定義中的最新版本,預設值為 'false'。

  • storageAccountType (選擇性) - AIB 支援針對要建立的映射版本指定這些類型的記憶體:

    • "Standard_LRS"
    • “Standard_ZRS”,”

注意

如果映像範本和參考 image definition 的位置不同,您會看到建立映像的額外時間。 映射產生器目前沒有 location 映像版本資源的參數,我們會從其父 image definition代 取得它。 例如,如果映像定義在 中westus,而且您想要將映像版本複寫至 eastuswestus,則會將 Blob 複製到 ,則會建立 中的westus映像版本資源,然後復寫至 eastus。 若要避免額外的復寫時間,請確定 image definition 和映像範本位於相同的位置。

版本控制

版本 設定 屬性 sharedImage 僅適用於散發類型。 這是具有兩個可能值的列舉:

  • latest - 每個設計的新嚴格增加架構
  • source - 根據來源映射的版本號碼架構。

預設版本編號架構為 latest。 最新的架構有一個額外的屬性“major”,指定產生最新版本的主要版本。

注意

散發的現有版本產生邏輯 sharedImage 已被取代。 提供兩個新選項:一律是資源庫中最新版本的單調增加版本,以及根據來源映像的版本號碼所產生的版本。 指定版本產生架構的列舉可讓您在未來使用其他版本產生架構進行擴充。

    "distribute": [
        "versioning": {
            "scheme": "Latest",
            "major": 1
        }
    ]

版本設定屬性:

  • scheme - 產生散發的新版本號碼。 LatestSource 是兩個可能的值。
  • major - 指定要產生最新版本的主要版本。 只有在 設定為 Latestscheme才適用。 例如,在發行下列版本的資源庫中:0.1.1、0.1.2、1.0.0、1.0.1、1.1.0、1.1.1、1.2.0、2.0.0、2.0.1、2.0.1、2.1.0
    • 當主要未設定或主要設定為 2 時,配置 Latest 會產生 2.1.1 版
    • 將主要設定為 1 時,最新配置會產生 1.2.1 版
    • 將主要設定為 0 時,最新配置會產生 0.1.3 版

散發:VHD

您可以輸出至 VHD。 然後,您可以複製 VHD,並使用它發佈至 Azure MarketPlace,或使用 Azure Stack。

{
  "type": "VHD",
  "runOutputName": "<VHD name>",
  "artifactTags": {
      "<name>": "<value>",
      "<name>": "<value>"
  }
}

OS 支援:Windows 和 Linux

散發 VHD 參數:

  • type - VHD。
  • runOutputName – 用來識別散發的唯一名稱。
  • tags - 選擇性使用者指定的索引鍵值組標記。

Azure Image Builder 不允許使用者指定記憶體帳戶位置,但您可以查詢 的狀態 runOutputs 以取得位置。

az resource show \
  --ids "/subscriptions/$subscriptionId/resourcegroups/<imageResourceGroup>/providers/Microsoft.VirtualMachineImages/imageTemplates/<imageTemplateName>/runOutputs/<runOutputName>"  | grep artifactUri

注意

建立 VHD 之後,請儘快將其複製到不同的位置。 VHD 會儲存在將映像範本提交至 Azure Image Builder 服務時所建立的暫存資源群組中的記憶體帳戶中。 如果您刪除映像範本,則會遺失 VHD。

下列 JSON 會將映像發佈為 VHD 至自訂記憶體帳戶。

"distribute": [
  {
    "type": "VHD",
    "runOutputName": "<VHD name>",
    "artifactTags": {
        "<name>": "<value>",
        "<name>": "<value>"
    },
    "uri": "<replace with Azure storage URI>"
  }
]

VHD 散發屬性:

uri - 分散式 VHD Blob 的選擇性 Azure 儲存體 URI。 省略以使用預設的 (空字串),在此情況下,VHD 會發佈至預備資源群組中的記憶體帳戶。

屬性:優化

optimize您可以在建立 VM 映射時啟用 屬性,並允許 VM 優化改善映像建立時間。

"optimize": {
      "vmboot": {
        "state": "Enabled"
      }
    }
  • vmboot:與虛擬機 (VM) 開機程序相關的設定,用來控制可改善開機時間或其他效能層面的優化。
  • state:內 vmboot開機優化功能的狀態,其值 Enabled 表示功能已開啟以改善映射建立時間。

若要深入瞭解,請參閱 使用 Azure VM 映射產生器針對資源庫映像進行 VM 優化。

屬性:來源

source 段包含 Image Builder 將使用的來源影像相關信息。 Azure Image Builder 目前僅支援一般化映射作為來源映像,不支援特殊化映射。

API 需要 SourceType 定義映射組建來源的 ,目前有三種類型:

  • PlatformImage - 指出來源映像是 Marketplace 映射。
  • ManagedImage - 從一般受控映射開始時使用。
  • SharedImageVersion - 當您在 Azure 計算資源庫中使用映像版本做為來源時使用。

注意

使用現有的 Windows 自定義映射時,您可以在單一 Windows 7 或 Windows Server 2008 R2 映射上執行 Sysprep 命令,或在單一 Windows 映射上執行 1001 次,以供更新版本使用;如需詳細資訊,請參閱 sysprep 檔。

PlatformImage 來源

Azure Image Builder 支援 Windows Server 和用戶端,以及 Linux Azure Marketplace 映射,如需完整清單,請參閱 瞭解 Azure Image Builder

"source": {
  "type": "PlatformImage",
  "publisher": "Canonical",
  "offer": "UbuntuServer",
  "sku": "18.04-LTS",
  "version": "latest"
}

此處的屬性與使用 AZ CLI 建立 VM 時所使用的屬性相同,請執行下列動作以取得屬性:

az vm image list -l westus -f UbuntuServer -p Canonical --output table --all

您可以在 版本中使用 latest ,在映射組建發生時評估版本,而不是在提交範本時評估版本。 如果您使用這項功能搭配 Azure 計算資源庫目的地,您可以避免重新提交範本,並依間隔重新執行映射建置,以便從最新的映像重新建立映像。

支援市場地點計劃資訊

您也可以指定計畫資訊,例如:

"source": {
  "type": "PlatformImage",
  "publisher": "RedHat",
  "offer": "rhel-byos",
  "sku": "rhel-lvm75",
  "version": "latest",
  "planInfo": {
    "planName": "rhel-lvm75",
    "planProduct": "rhel-byos",
    "planPublisher": "redhat"
  }
}

ManagedImage 來源

將來源映像設定為一般化 VHD 或 VM 的現有受控映像。

注意

來源受控映像必須是支援的OS,而且映像必須位於與 Azure Image Builder 樣本相同的訂用帳戶和區域中。

"source": {
  "type": "ManagedImage",
  "imageId": "/subscriptions/<subscriptionId>/resourceGroups/{destinationResourceGroupName}/providers/Microsoft.Compute/images/<imageName>"
}

imageId應該是受控映像的 ResourceId。 用來 az image list 列出可用的映像。

SharedImageVersion 來源

將來源映像設定為 Azure 計算資源庫中的現有映像版本。

注意

來源共用映像版本必須是支援的OS,而且映像版本必須位於與 Azure Image Builder 範本相同的區域中,如果不是,請將映像版本複寫至 Image Builder 範本區域。

"source": {
  "type": "SharedImageVersion",
  "imageVersionID": "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>/providers/Microsoft.Compute/galleries/<sharedImageGalleryName>/images/<imageDefinitionName/versions/<imageVersion>"
}
  • imageVersionId - 映射版本的 ARM 範本資源識別碼。 映射版本名稱為「最新」時,映射組建發生時會評估版本。 imageVersionId應該是ResourceId映像版本的 。 使用 az sig image-version list 列出映射版本。

下列 JSON 會將來源映像設定為儲存在直接共用資源庫中映射。

注意

直接共享資源庫目前處於預覽狀態。

    source: {
      "type": "SharedImageVersion",
      "imageVersionId": "<replace with resourceId of the image stored in the Direct Shared Gallery>"
    },

下列 JSON 會將來源映像設定為 Azure 計算資源庫中所儲存映像的最新映像版本。

"properties": {
    "source": {
        "type": "SharedImageVersion",
        "imageVersionId": "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Compute/galleries/<azureComputeGalleryName>/images/<imageDefinitionName>/versions/latest"
    }
},

SharedImageVersion 属性:

imageVersionId - 映射版本的 ARM 範本資源識別碼。 當映像版本名稱為「最新」時,映射組建發生時會評估版本。

屬性:stagingResourceGroup

屬性 stagingResourceGroup 包含映像產生器服務建立以供映像建置程式期間使用之暫存資源群組的相關信息。 對於任何想要在映像建置程式期間對 Image Builder 所建立之資源群組擁有更多控制權的人而言,都是 stagingResourceGroup 選擇性屬性。 您可以建立自己的資源群組, stagingResourceGroup 並在 區段中指定它,或讓 Image Builder 代表您建立一個資源群組。

重要

指定的暫存資源群組無法與另一個映像範本相關聯,在與映像範本相同的區域中必須是空的(沒有內部資源),且已將「參與者」或「擁有者」RBAC 套用至指派給 Azure Image Builder 映射範本資源的身分識別。

"properties": {
  "stagingResourceGroup": "/subscriptions/<subscriptionID>/resourceGroups/<stagingResourceGroupName>"
}

範本建立案例

  • stagingResourceGroup 屬性保留空白

    stagingResourceGroup如果未以空字串指定或指定屬性,Image Builder 服務會建立具有預設名稱慣例 「IT_***」 的預備資源群組。 預備資源群組已套用預設標籤:createdBy、、 imageTemplateNameimageTemplateResourceGroupName。 此外,預設的 RBAC 會套用至指派給 Azure Image Builder 範本資源的身分識別,也就是「參與者」。

  • stagingResourceGroup 屬性是以存在的資源群組來指定

    stagingResourceGroup如果屬性是以確實存在的資源群組來指定,則 Image Builder 服務會檢查以確定資源群組未與另一個映像範本相關聯、在與映像範本相同的區域中是空的(沒有資源),且已將「參與者」或「擁有者」RBAC 套用至指派給 Azure Image Builder 映像範本資源的身分識別。 如果不符合上述任何需求,則會擲回錯誤。 預備資源群組已新增下列標籤:usedBy、、 imageTemplateNameimageTemplateResourceGroupName。 不會刪除預先存在的標籤。

重要

當您嘗試使用 Windows 來源映射將預先存在的資源群組和 VNet 指定給 Azure Image Builder 服務時,您必須將參與者角色指派給對應至 Azure Image Builder 第一方應用程式的服務主體。 如需如何將參與者角色指派給資源群組的 CLI 命令和入口網站指示,請參閱下列針對 VM Azure 映射產生器進行疑難解答的檔 :建立磁碟的授權錯誤

  • stagingResourceGroup 屬性是以不存在的資源群組來指定

    stagingResourceGroup如果屬性是以不存在的資源群組指定,則 Image Builder 服務會使用 屬性中stagingResourceGroup提供的名稱來建立暫存資源群組。 如果指定的名稱不符合資源群組的 Azure 命名需求,就會發生錯誤。 預備資源群組已套用預設標籤:createdBy、、 imageTemplateNameimageTemplateResourceGroupName。 根據預設,指派給 Azure Image Builder 映射範本資源的身分識別會套用至資源群組中的「參與者」RBAC。

範本刪除

映射產生器服務所建立的任何暫存資源群組,將會在刪除映射範本之後刪除。 刪除包含屬性中指定的 stagingResourceGroup 暫存資源群組,但在映像建置之前不存在。

如果 Image Builder 未建立暫存資源群組,但資源群組內的資源,在刪除映像範本之後,將會刪除這些資源,因為 Image Builder 服務具有刪除資源所需的適當許可權或角色。

屬性:驗證

您可以使用 validate 屬性來驗證平臺映射,以及您建立的任何自定義映像,不論您是否使用 Azure Image Builder 來建立它們。

Azure Image Builder 支援可使用 屬性設定 sourceValidationOnly 的「僅限來源驗證」模式。 如果 屬性 sourceValidationOnly 設定為 true,則會直接驗證區段中指定的 source 影像。 不會執行個別的組建來產生,然後驗證自定義映像。

屬性 inVMValidations 會取得將在映像上執行之驗證程序的清單。 Azure Image Builder 支援檔案、PowerShell 和 Shell 驗證程式。

如果驗證失敗,屬性 continueDistributeOnFailure 會負責輸出影像是否會散發。 根據預設,如果驗證失敗,而且此屬性設定為 false,則不會散發輸出影像。 如果驗證失敗,且此屬性設定為 true,則輸出影像仍會散發。 請謹慎使用此選項,因為它可能會導致散發失敗的映像以供使用。 在任一情況下(true 或 false),如果驗證失敗,端對端映像執行將會回報為失敗。 此屬性不會影響驗證是否成功。

使用 validate時:

  • 您可以使用多個驗證程式。
  • 驗證程式會依範本中指定的順序執行。
  • 如果一個驗證程序失敗,則整個驗證元件將會失敗並回報錯誤。
  • 建議您先徹底測試腳本,再將其用於範本。 在您自己的 VM 上偵錯腳本會比較容易。
  • 請勿將敏感數據放入腳本中。
  • 除非您使用 MSI,否則文本位置必須可公開存取。

如何使用 validate 屬性來驗證 Windows 映射:

{
   "properties":{
      "validate":{
         "continueDistributeOnFailure":false,
         "sourceValidationOnly":false,
         "inVMValidations":[
            {
               "type":"File",
               "destination":"string",
               "sha256Checksum":"string",
               "sourceUri":"string"
            },
            {
               "type":"PowerShell",
               "name":"test PowerShell validator inline",
               "inline":[
                  "<command to run inline>"
               ],
               "validExitCodes":"<exit code>",
               "runElevated":"<true or false>",
               "runAsSystem":"<true or false>"
            },
            {
               "type":"PowerShell",
               "name":"<name>",
               "scriptUri":"<path to script>",
               "runElevated":"<true false>",
               "sha256Checksum":"<sha256 checksum>"
            }
         ]
      }
   }
}

inVMValidations 性能:

  • type – PowerShell。

  • name - 驗證程序的名稱

  • scriptUri - PowerShell 腳本檔案的 URI。

  • 內嵌 – 要執行的命令陣列,並以逗號分隔。

  • validExitCodes – 可從 script/inline 命令傳回的選擇性有效程式代碼,這可避免腳本/內嵌命令回報失敗。

  • runElevated – 選擇性、布爾值,支持執行具有更高許可權的命令和腳本。

  • sha256Checksum - 檔案 sha256 總和檢查碼的值,您會在本機產生此檢查碼,然後 Image Builder 會檢查碼並驗證。

    若要產生 sha256Checksum,請在 Windows Get-Hash 上使用 PowerShell

如何使用 validate 屬性來驗證 Linux 映射:

{
  "properties": {
    "validate": {
      "continueDistributeOnFailure": false,
      "sourceValidationOnly": false,
      "inVMValidations": [
        {
          "type": "Shell",
          "name": "<name>",
          "inline": [
            "<command to run inline>"
          ]
        },
        {
          "type": "Shell",
          "name": "<name>",
          "scriptUri": "<path to script>",
          "sha256Checksum": "<sha256 checksum>"
        },
        {
          "type": "File",
          "destination": "string",
          "sha256Checksum": "string",
          "sourceUri": "string"
        }
      ]
    }
  }
}

inVMValidations 性能:

  • type – 指定為要執行之驗證類型的殼層或檔案。

  • name - 驗證程序的名稱

  • scriptUri - 腳本檔案的 URI

  • 內嵌 - 要執行的命令陣列,並以逗號分隔。

  • sha256Checksum - 檔案 sha256 總和檢查碼的值,您會在本機產生此檢查碼,然後 Image Builder 會檢查碼並驗證。

    若要產生 sha256Checksum,請使用 Mac/Linux 上的終端機執行: sha256sum <fileName>

  • destination - 檔案的目的地。

  • sha256Checksum - 指定檔案的 SHA256 總和檢查碼。

  • sourceUri - 檔案的來源 URI。

屬性:vmProfile

vmSize (選擇性)

映射產生器會針對 Gen1 映像和 Standard_D2ds_v4 Gen2 映像使用的預設 SKU 大小Standard_D1_v2。 產生是由您在 中指定的 source映像所定義。 您可以覆寫 vmSize,原因如下:

  • 執行需要增加記憶體、CPU 和處理大型檔案 (GB) 的自定義專案。
  • 執行 Windows 組建時,您應該使用「Standard_D2_v2」或對等的 VM 大小。
  • 需要 VM 隔離
  • 自定義需要特定硬體的映像。 例如,針對 GPU VM,您需要 GPU VM 大小。
  • 需要建置 VM 的其餘部分端對端加密,您必須指定不支援不使用本機暫存磁碟的組建 VM 大小

osDiskSizeGB

根據預設,Image Builder 不會變更影像的大小,它會使用來源影像的大小。 您可以選擇性地 增加 OS 磁碟的大小(Win 和 Linux),而值為 0 表示保留與來源映射相同的大小。 您無法將 OS 磁碟大小縮減為小於來源映像的大小。

{
  "osDiskSizeGB": 100
}

vnetConfig (選擇性)

如果您未指定任何 VNet 屬性,Image Builder 會建立自己的 VNet、公用 IP 和網路安全組 (NSG)。 公用IP用於服務與組建VM通訊。 如果您不想擁有公用IP,或想要 Image Builder 存取現有的 VNet 資源,例如組態伺服器(DSC、Chef、Puppet、Ansible)、檔案共用,則可以指定 VNet。 如需詳細資訊,請檢閱 網路檔

"vnetConfig": {
  "subnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName>"
}

映像範本作業

啟動映像建置

若要啟動組建,您必須在映像範本資源上叫用 「執行」,命令範例 run

Invoke-AzResourceAction -ResourceName $imageTemplateName -ResourceGroupName $imageResourceGroup -ResourceType Microsoft.VirtualMachineImages/imageTemplates -ApiVersion "2021-10-01" -Action Run -Force
az resource invoke-action \
  --resource-group $imageResourceGroup \
  --resource-type  Microsoft.VirtualMachineImages/imageTemplates \
  -n helloImageTemplateLinux01 \
  --action Run

取消映像組建

如果您執行的映像組建認為不正確,請等候使用者輸入,或您覺得永遠不會順利完成,則您可以取消組建。

您可以隨時取消組建。 如果發佈階段已啟動,您仍然可以取消,但您需要清除可能未完成的任何映像。 cancel 命令不會等候取消完成、使用這些狀態命令監視lastrunstatus.runstate取消進度。

命令範例 cancel

Invoke-AzResourceAction -ResourceName $imageTemplateName -ResourceGroupName $imageResourceGroup -ResourceType Microsoft.VirtualMachineImages/imageTemplates -ApiVersion "2021-10-01" -Action Cancel -Force
az resource invoke-action \
  --resource-group $imageResourceGroup \
  --resource-type  Microsoft.VirtualMachineImages/imageTemplates \
  -n helloImageTemplateLinux01 \
  --action Cancel

下一步

Azure Image Builder GitHub 中的不同案例有範例.json檔案。