次の方法で共有

Azure Image Builder Bicep または ARM テンプレート JSON テンプレートを作成する

Applies to: ✔️ Linux VMs ✔️ Windows VMs ✔️ Flexible scale sets

Azure Image Builder では、Bicep ファイルまたは ARM テンプレート JSON テンプレート ファイルを使用して Image Builder サービスに情報を渡します。 この記事では、独自のファイルを作成できるように、ファイルの各セクションについて説明します。 For latest API versions, see template reference. 完全な .json ファイルの例を確認するには、Azure Image Builder の GitHub をご覧ください。

基本的な形式は次のとおりです。

{
  "type": "Microsoft.VirtualMachineImages/imageTemplates",
  "___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/<subnetName1>",
        "containerInstanceSubnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName2>",
        "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>",
        ...
      ]
    }
  }
}

Follow all Best Practices while creating image templates.

API version

API のバージョンは、API の変更に伴って時間の経過と同時に変更されます。 Azure VM Image Builder サービスのすべての主要な API の変更と機能更新については、「Azure VM Image Builder の新機能」を参照してください。

タイプ

type はリソースの種類であり、Microsoft.VirtualMachineImages/imageTemplates にする必要があります。

"type": "Microsoft.VirtualMachineImages/imageTemplates",

Location

VM Image Builder サービスは、次のリージョンで利用できます。

Note

これらのリージョンの外部にイメージを配布することもできます。

  • 米国東部
  • 米国東部 2
  • 米国中西部
  • 米国西部
  • 米国西部 2
  • 米国西部 3
  • 米国中南部
  • 北ヨーロッパ
  • 西ヨーロッパ
  • 東南アジア
  • オーストラリア南東部
  • オーストラリア東部
  • 英国南部
  • 英国西部
  • ブラジル南部
  • カナダ中部
  • インド中部
  • 米国中部
  • フランス中部
  • ドイツ中西部
  • 東日本
  • 米国中北部
  • ノルウェー東部
  • スイス北部
  • JIO インド西部
  • アラブ首長国連邦北部
  • 東アジア
  • 韓国中部
  • 南アフリカ北部
  • カタール中部
  • USGov アリゾナ (パブリック プレビュー)
  • USGov バージニア (パブリック プレビュー)
  • 中国北部 3 (パブリック プレビュー)
  • スウェーデン中部
  • ポーランド中部
  • イタリア北部
  • イスラエル中部
  • ニュージーランド北部
  • Taiwan Northwest

Important

Azure Government リージョン (USGov アリゾナおよび USGov バージニア) で Azure Image Builder パブリック プレビューにアクセスするには、Microsoft.VirtualMachineImages/FairfaxPublicPreview 機能を登録します。

Important

機能 Microsoft.VirtualMachineImages/MooncakePublicPreview を登録して、中国北部 3 リージョンの Azure Image Builder パブリック プレビューにアクセスします。

To access the Azure VM Image Builder public preview in the Azure Government regions (USGov Arizona and USGov Virginia), you must register the Microsoft.VirtualMachineImages/FairfaxPublicPreview feature. これを行うには、PowerShell または Azure CLI のどちらかで次のコマンドを実行します。

Register-AzProviderPreviewFeature -ProviderNamespace Microsoft.VirtualMachineImages -Name FairfaxPublicPreview

To access the Azure VM Image Builder public preview in the China North 3 region, you must register the Microsoft.VirtualMachineImages/MooncakePublicPreview feature. これを行うには、PowerShell または Azure CLI のどちらかで次のコマンドを実行します。

Register-AzProviderPreviewFeature -ProviderNamespace Microsoft.VirtualMachineImages -Name MooncakePublicPreview

"___location": "<region>"

Data residency

Azure VM Image Builder サービスでは、厳格なデータ所在地ルールがあるリージョン内に顧客データが保持されます。 データ所在地の要件が設けられているリージョンでサービスが停止した場合は、別のリージョンや地域に Bicep ファイルまたはテンプレートを作成する必要があります。

Zone redundancy

ディストリビューションはゾーン冗長性をサポートし、仮想ハード ディスク (VHD) は既定でゾーン冗長ストレージ (ZRS) アカウントに配布され、Azure Compute Gallery (旧称 Shared Image Gallery) バージョンは ZRS ストレージの種類 (指定されている場合) をサポートします。

Tags

タグは、生成されるイメージに対して指定できるキー/値ペアです。

Identity

以下で説明するユーザー割り当て ID を追加するには、2 つの方法があります。

Azure Image Builder イメージ テンプレート リソースのユーザー割り当て ID

必須 - Image Builder に対して、イメージの読み取り/書き込みと Azure Storage からのスクリプトの読み取りを行うためのアクセス許可を付与するには、個々のリソースに対するアクセス許可を持つ Azure ユーザー割り当て ID を作成する必要があります。 Image Builder のアクセス許可のしくみと、関連する手順の詳細については、「イメージを作成し、ユーザーが割り当てたマネージド ID を使用して Azure ストレージ アカウント内のファイルにアクセスする」を参照してください。

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

Image Builder サービスのユーザー割り当て ID:

  • 単一の ID のみがサポートされています。
  • カスタム ドメイン名はサポートされていません。

詳しくは、「Azure リソースのマネージド ID とは」をご覧ください。 この機能のデプロイについて詳しくは、「Azure CLI を使用して Azure VM 上に Azure リソースのマネージド ID を構成する」をご覧ください。

Image Builder ビルド VM のユーザー割り当て ID

このプロパティは、API バージョン 2021-10-01 以降でのみ使用できます。

省略可能 - サブスクリプション内の Image Builder サービスによって作成される Image Builder ビルド VM は、イメージのビルドとカスタマイズに使用されます。 Image Builder ビルド VM に、サブスクリプション内の Azure Key Vault などの他のサービスで認証するためのアクセス許可を付与するには、個々のリソースへのアクセス許可を持つ 1 つ以上の Azure ユーザー割り当て ID を作成する必要があります。 その後、Azure Image Builder は、これらのユーザー割り当て ID をビルド VM に関連付けることができます。 その後、ビルド VM 内で実行されているカスタマイザー スクリプトは、これらの ID のトークンを取り込み、必要に応じて他の Azure リソースと対話することができます。 Azure Image Builder のユーザー割り当て ID をすべての Azure Image Builderがビルド VM に関連付けることができるようにするには、ユーザー割り当て ID で 「マネージド ID オペレーター」 ロールが割り当てられている必要があることに注意してください。

Note

Image Builder ビルド VM には複数の ID を指定できることに注意してください (イメージ テンプレート リソース用に作成した ID を含む)。 既定では、イメージ テンプレート リソース用に作成した ID は、ビルド VM に自動的に追加されません。

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

Image Builder ビルド VM のユーザー割り当て ID:

  • VM で構成する 1 つ以上のユーザー割り当て済みマネージド ID の一覧をサポートします。
  • 複数サブスクリプション間のシナリオをサポートします (1 つのサブスクリプションで ID が作成され、同じテナントの別のサブスクリプションでイメージ テンプレートが作成されている場合)。
  • 複数テナント間のシナリオはサポートしません (1 つのテナントで ID が作成され、別のテナントでイメージ テンプレートがに作成されている場合)。

詳細については、次を参照してください。

Properties: 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 分未満に設定することはお勧めしません。 If you find you're hitting the timeout, review the logs to see if the customization step is waiting on something like user input. カスタマイズが完了するまでにさらに時間が必要な場合は、buildTimeoutInMinutes 値を大きくします。 ただし、エラーが表示される前にタイムアウトするまで待機する必要があるため、設定値を大きくしすぎないでください。

Properties: customize

Image Builder では、複数の "カスタマイザー" がサポートされています。これは、スクリプトの実行やサーバーの再起動など、イメージのカスタマイズに使われる機能です。

customize を使うとき:

  • 複数のカスタマイザーを使用できます。
  • カスタマイザーは、テンプレートで指定されている順序で実行されます。
  • 1 つのカスタマイザーが失敗した場合、カスタマイズ コンポーネント全体が失敗し、エラーが報告されます。
  • テンプレートで使う前に、スクリプトを十分にテストします。 スクリプトを単独でデバッグする方が簡単です。
  • スクリプト内には機密データを記述しないでください。 インライン コマンドは、イメージ テンプレート定義で表示できます。 機密情報 (パスワード、SAS トークン、認証トークンなど) がある場合は、アクセスに認証が必要な Azure Storage 内のスクリプトに移動する必要があります。
  • スクリプトの場所は、 ユーザー割り当て ID を使用している場合を除き、パブリックにアクセスできる必要があります。

customize セクションは配列です。 サポートされているカスタマイザーの種類は、ファイル、PowerShell、シェル、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 customizer

Shell カスタマイザーでは、Linux でのシェル スクリプトの実行がサポートされています。 The shell scripts must be publicly accessible or you must have configured an MSI for Image Builder to access them.

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

Customize properties:

  • type – Shell.

  • name - name for tracking the customization.

  • scriptUri - URI to the ___location of the file.

  • inline - array of shell commands, separated by commas.

  • sha256Checksum - Value of sha256 checksum of the file, you generate this value locally, and then Image Builder will checksum and validate.

    Mac/Linux のターミナルを使用して sha256Checksum を生成するには、sha256sum <fileName> を実行します。

Note

インライン コマンドはイメージ テンプレート定義の一部として格納されます。イメージ定義をダンプ出力したときに、これらを確認できます。 機密性の高いコマンドまたは値 (パスワード、SAS トークン、認証トークンなど) がある場合は、それらをスクリプトに移動し、ユーザー ID を使用して Azure Storage に対する認証を行うことをお勧めします。

スーパー ユーザー特権

スーパー ユーザー特権を使用してコマンドを実行するには、プレフィックスとして 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"
  }
]

Customize properties:

  • Type: WindowsRestart.
  • restartCommand - Command to execute the restart (optional). 既定では、 'shutdown /r /f /t 0 /c \"packer restart\"'です。
  • restartCheckCommand – Command to check if restart succeeded (optional).
  • restartTimeout - Restart time out specified as a string of magnitude and unit. たとえば、5m (5 分) や 2h (2 時間) などです。 既定値は 5m です。

Note

Linux 再起動カスタマイザーはありません。

PowerShell customizer

PowerShell カスタマイザーは、Windows での PowerShell スクリプトとインライン コマンドの実行をサポートしており、サービスがそれらにアクセスするには、スクリプトがパブリックにアクセスできる必要があります。

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

Customize properties:

  • type – PowerShell.

  • scriptUri - URI to the ___location of the PowerShell script file.

  • inline – Inline commands to be run, separated by commas.

  • validExitCodes – Optional, valid codes that can be returned from the script/inline command. このプロパティにより、スクリプト/インライン コマンドの報告済みエラーが回避されます。

  • runElevated – Optional, boolean, support for running commands and scripts with elevated permissions.

  • runAsSystem - Optional, boolean, determines whether the PowerShell script should be run as the System user.

  • sha256Checksum - generate the SHA256 checksum of the file locally, update the checksum value to lowercase, and Image Builder will validate the checksum during the deployment of the image template.

    To generate the sha256Checksum, use the Get-FileHash cmdlet in PowerShell.

File customizer

File カスタマイザーを使用すると、Image Builder で GitHub リポジトリまたは Azure Storage からファイルをダウンロードできます。 カスタマイザーは、Linux と Windows の両方をサポートします。 ビルド成果物に依存するイメージ ビルド パイプラインがある場合は、ファイル カスタマイザーを設定して、成果物をビルド共有からダウンロードし、イメージに移動できます。

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

ファイル カスタマイザーのプロパティ:

  • sourceUri - an accessible storage endpoint, this endpoint can be GitHub or Azure storage. ダウンロードできるのは 1 つのファイルだけであり、ディレクトリ全体はできません。 ディレクトリをダウンロードする必要がある場合は、圧縮されたファイルを使用し、シェルまたは PowerShell カスタマイザーを使って圧縮を解除します。

    Note

    sourceUri が Azure Storage アカウントの場合、BLOB に public のマークが付けられているかどうかにかかわらず、BLOB での読み取りアクセス許可をマネージド ユーザー ID に付与します。 See this example to set the storage permissions.

  • destination – the full destination path and file name. 参照されているすべてのパスとサブディレクトリが存在する必要があり、事前にこれらのパスを設定するにはシェルまたは PowerShell カスタマイザーを使います。 スクリプト カスタマイザーを使ってパスを作成できます。

このカスタマイザーは Windows のディレクトリと Linux のパスでサポートされていますが、いくつか違いがあります。

  • Linux - Image Builder で書き込むことができる唯一のパスは /tmp です。
  • Windows – パスの制限はありませんが、パスが存在する必要があります。

ファイルのダウンロードや指定されたディレクトリへの配置を試みたときにエラーが発生した場合、カスタマイズ ステップは失敗し、customization.log にこのエラーが記録されます。

Note

ファイル カスタマイザーは、小さいファイルのダウンロード (20 MB 未満) にのみ適しています。 大きいファイルをダウンロードする場合は、スクリプトまたはインライン コマンドを使用してから、ファイルをダウンロードするコード (Linux の wget または curl、Windows の Invoke-WebRequest など) を使用します。 Azure Storage 内のファイルの場合は、ドキュメント「Image Builder ビルド VM のユーザー割り当て ID」に従って、ビルド VM にそのファイルを表示するアクセス許可を持つ ID を割り当てるようにします。 Azure に格納されていないファイルを Azure Image Builder でダウンロードできるようにするには、それにパブリックにアクセスできる必要があります。

  • sha256Checksum - generate the SHA256 checksum of the file locally, update the checksum value to lowercase, and Image Builder will validate the checksum during the deployment of the image template.

    To generate the sha256Checksum, use the Get-FileHash cmdlet in PowerShell.

Windows Update カスタマイザー

WindowsUpdate カスタマイザーは、Packer のコミュニティ Windows Update Provisioner に基づいて構築されたオープン ソース プロジェクトで、Packer コミュニティによって管理されています。 Microsoft では、Image Builder サービスを使ってプロビジョナーをテストおよび検証し、問題の調査を支援して、解決に取り組んでいきますが、正式にはこのオープン ソース プロジェクトをサポートしていません。 Windows Update Provisioner の詳細なドキュメントとヘルプについては、プロジェクト リポジトリを参照してください。

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

Customizer properties:

  • type – WindowsUpdate.
  • searchCriteria - Optional, defines which type of updates are installed (like Recommended or Important), BrowseOnly=0 and IsInstalled=0 (Recommended) is the default.
  • filters – Optional, allows you to specify a filter to include or exclude updates.
  • updateLimit – Optional, defines how many updates can be installed, default 1000.

Note

Windows Update カスタマイザーは、保留中の Windows の再起動や、まだ実行中のアプリケーションのインストールがある場合に失敗する可能性があります。このエラー System.Runtime.InteropServices.COMException (0x80240016): Exception from HRESULT: 0x80240016 は、通常、customization.log で確認できます。 We strongly advise you consider adding in a Windows Restart, and/or allowing applications enough time to complete their installations using sleep or wait commands in the inline commands or scripts before running Windows Update.

Generalize

既定の 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 またはシェル スクリプトのプロビジョナーを使って正確なファイル名のコマンド ファイルを作成し、適切なディレクトリに置きます。

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

Image Builder では、これらのコマンドが読み取られて、これらのコマンドが AIB ログ customization.log に書き込まれます。 See troubleshooting on how to collect logs.

Properties: errorHandling

errorHandling プロパティを使用すると、イメージの作成時にエラーを処理する方法を構成できます。

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

errorHandling プロパティを使用すると、イメージの作成時にエラーを処理する方法を構成できます。 2 つのプロパティがあります。

  • onCustomizerError - Specifies the action to take when an error occurs during the customizer phase of image creation.
  • onValidationError - Specifies the action to take when an error occurs during validation of the image template.

errorHandling プロパティには、イメージの作成時にエラーを処理するために使用できる値も 2 つあります。

  • cleanup - Ensures that temporary resources created by Packer are cleaned up even if Packer or one of the customizations/validations encounters an error. これにより、既存の動作との下位互換性が維持されます。
  • abort - In case Packer encounters an error, the Azure Image Builder (AIB) service skips the clean up of temporary resources. AIB テンプレートの所有者は、サブスクリプションからこれらのリソースをクリーンアップする責任があります。 これらのリソースには、一時 VM に残されたログやファイルなどの有用な情報が含まれている場合があります。これは、Packer で発生したエラーの調査に役立ちます。

Properties: distribute

Azure Image Builder では、次の 3 つの配布ターゲットがサポートされています。

  • ManagedImage - Managed image.
  • sharedImage - Azure Compute Gallery.
  • VHD - VHD in a storage account.

すべてのターゲットの種類に同じ構成でイメージを配布できます。

Note

既定の AIB sysprep コマンドには、"/mode:vm" は含まれていませんが、HyperV ロールがインストールされるイメージを作成するときにこのプロパティが必要になる場合があります。 このコマンド引数を追加する場合は、sysprep コマンドをオーバーライドする必要があります。

複数のターゲットに配布できるので、Image Builder ではすべての配布ターゲットの状態が維持されており、runOutputName のクエリを実行することによってアクセスできます。 配布の後で runOutputName オブジェクトのクエリを実行して、その配布に関する情報を取得できます。 たとえば、VHD の場所、イメージ バージョンがレプリケートされたリージョン、または作成された SIG イメージのバージョンのクエリを実行できます。 これは、すべての配布ターゲットのプロパティです。 runOutputName は配布ターゲットごとに一意である必要があります。 次に Azure Compute Gallery の配布に対するクエリの例を示します。

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=2023-07-01

Output:

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

Distribute: managedImage

イメージの出力は、マネージド イメージ リソースです。

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

Distribute properties:

  • type – ManagedImage
  • imageId – Resource ID of the destination image, expected format: /subscriptions/<subscriptionId>/resourceGroups/<destinationResourceGroupName>/providers/Microsoft.Compute/images/<imageName>
  • ___location - ___location of the managed image.
  • runOutputName – unique name for identifying the distribution.
  • artifactTags - Optional user specified key\value tags.

Note

配布先のリソース グループは存在している必要があります。 イメージが別のリージョンに配布されるようにする場合は、デプロイ時間が長くなります。

Distribute: sharedImage

Azure Compute Gallery は新しいイメージ管理サービスであり、イメージのリージョン レプリケーションの管理、バージョン管理、カスタム イメージの共有を行うことができます。 Azure Image Builder ではこのサービスによる配布がサポートされているので、Azure Compute Gallery でサポートされているリージョンにイメージを配布できます。

Azure Compute Gallery は次のもので構成されています。

  • Gallery - Container for multiple images. ギャラリーは、1 つのリージョンにデプロイされます。
  • Image definitions - a conceptual grouping for images.
  • Image versions - an image type used for deploying a VM or scale set. イメージ バージョンは、VM をデプロイする必要がある他のリージョンにレプリケートできます。

ギャラリーに配布するには、その前にギャラリーとイメージの定義を作成しておく必要があります。ギャラリーの作成に関する記事をご覧ください。

Note

イメージのバージョン ID は、既存の Azure Compute Gallery にあるイメージ バージョンとは異なる必要があります。

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

次の JSON は、replicationRegions フィールドを使用して Azure Compute Gallery に配布する方法の例です。

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

Note

replicationRegions が更新されたプロパティであるため、targetRegions はギャラリー配布では非推奨です。 For more information, see targetRegions.

Distribute: targetRegions

次の JSON は、targetRegions フィールドを使用して Azure Compute Gallery に配布する方法の例です。

"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 – ID of the Azure Compute Gallery, this property can be specified in two formats:

    • 自動バージョン管理 - Image Builder によって、モノトニックなバージョン番号が自動的に生成されます。このプロパティは、同じテンプレートからイメージのリビルドを続ける場合に便利です。形式は /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Compute/galleries/<sharedImageGalleryName>/images/<imageGalleryName> です。
    • 明示的なバージョン管理 - Image Builder で使用するバージョン番号を渡すことができます。 形式は /subscriptions/<subscriptionID>/resourceGroups/<rgName>/providers/Microsoft.Compute/galleries/<sharedImageGalName>/images/<imageDefName>/versions/<version - for example: 1.1.1> です。

  • runOutputName – unique name for identifying the distribution.

  • artifactTags - optional user specified key\value tags.

  • replicationRegions - array of regions for replication. リージョンの 1 つは、ギャラリーがデプロイされているリージョンでなければなりません。 リージョンを追加すると、ビルド時間が長くなります。これは、レプリケーションが完了するまでビルドが完了しないためです。 このフィールドは API バージョン 2022-07-01 の時点で非推奨です。"SharedImage" の種類を配布する場合は、targetRegions を使用してください。

  • targetRegions - an array of regions for replication. It's newly introduced as part of the 2022-07-01 API and applies only to the SharedImage type distribute.

  • excludeFromLatest (optional) - allows you to mark the image version you create not be used as the latest version in the gallery definition, the default is 'false'.

  • storageAccountType (optional) - AIB supports specifying these types of storage for the image version that is to be created:

    • "Standard_LRS"
    • "Standard_ZRS","

Note

イメージ テンプレートと参照されている image definition が同じ場所にない場合は、イメージを作成するための追加の時間が表示されます。 現在、イメージ バージョン リソースの ___location パラメーターは Image Builder にはなく、その親の image definition から取得されます。 たとえば、イメージ定義が westus にあり、イメージ バージョンが eastus にレプリケートされるようにする場合は、BLOB が westus にコピーされ、westus のイメージ バージョン リソースが作成された後、eastus にレプリケートされます。 追加のレプリケーション時間を回避するには、image definition とイメージ テンプレートが同じ場所にあるようにします。

バージョン管理

The versioning property is for the sharedImage distribute type only. これは、次の 2 つの値を指定できる列挙型です。

  • latest - New strictly increasing schema per design
  • source - Schema based upon the version number of the source image.

既定のバージョン番号付けスキーマは latest です。 最新のスキーマには、最新バージョンを生成するメジャー バージョンを指定する "major" というプロパティが追加されています。

Note

sharedImage 配布の既存のバージョン生成ロジックは、非推奨です。 2 つの新しいオプションがあります。ギャラリー内で常に最新バージョンである単調に増加するバージョンと、ソース イメージのバージョン番号に基づいて生成されるバージョンです。 バージョン生成スキーマを指定する列挙型を使用すると、将来、追加のバージョン生成スキーマを使用して拡張できます。

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

versioning properties:

  • scheme - Generate new version number for distribution. Latest と Source が、指定できる 2 つの値です。
  • major - Specifies the major version under which to generate the latest version. scheme が Latest に設定されている場合にのみ適用できます。 たとえば、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.1.0 の各バージョンが公開されているギャラリーでは、
    • メジャーが設定されていないか、メジャーが 2 に設定されている場合、Latest スキームでは、バージョン 2.1.1 が生成されます
    • メジャーが 1 に設定されている場合、Latest スキームではバージョン 1.2.1 が生成されます
    • メジャーが 0 に設定されている場合、Latest スキームではバージョン 0.1.3 が生成されます

Distribute: VHD

VHD に出力することができます。 その後、VHD をコピーし、それを使って Azure MarketPlace に発行したり、Azure Stack で使ったりできます。

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

OS のサポート: Windows、Linux

VHD 配布のパラメーター:

  • type - VHD.
  • runOutputName – unique name for identifying the distribution.
  • tags - Optional user specified key value pair tags.

Azure Image Builder ではユーザーはストレージ アカウントの場所を指定できませんが、runOutputs の状態のクエリを実行して場所を取得できます。

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

Note

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 - Optional Azure Storage URI for the distributed VHD blob. 既定値 (空の文字列) は使用しません。その場合、VHD はステージング リソース グループ内のストレージ アカウントに発行されることになります。

Properties: optimize

optimize プロパティは VM イメージの作成中に有効にすることができ、VM の最適化によりイメージの作成時間を短縮できます。

"optimize": {
      "vmBoot": {
        "state": "Enabled"
      }
    }
  • vmBoot: A configuration related to the booting process of the virtual machine (VM), used to control optimizations that can improve boot time or other performance aspects.
  • state: vmBoot 内のブート最適化機能の状態。値 Enabled は、イメージの作成時間を短縮するために機能がオンになっていることを示します。

詳細については、Azure VM Image Builder を使用したギャラリー イメージ VM の最適化を参照してください。

Properties: source

source セクションには、Image Builder によって使われるソース イメージについての情報が含まれます。 Azure Image Builder ではソース イメージとして一般化されたイメージのみがサポートされます。現在のところ、特殊化されたイメージはサポートされていません。

API ではイメージ ビルド用のソースを定義する SourceType が必要であり、現在は次の 3 つの種類があります。

  • PlatformImage - ソース イメージが Marketplace イメージであることを示します。
  • ManagedImage - 標準のマネージド イメージから始めるときに使われます。
  • SharedImageVersion - ソースとして Azure Compute Gallery 内のイメージ バージョンを使うときに使われます。

Note

When using existing Windows custom images, you can run the Sysprep command up to three times on a single Windows 7 or Windows Server 2008 R2 image, or 1001 times on a single Windows image for later versions; for more information, see the sysprep documentation.

PlatformImage source

Azure Image Builder では、Windows Server とクライアント、および Linux Azure Marketplace のイメージがサポートされます。完全な一覧については、「Azure Image Builder の概要」を参照してください。

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

ここでのプロパティは VM の作成に使われるものと同じであり、プロパティを取得するには AZ CLI を使って以下を実行します。

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

latest バージョンを使用できますが、バージョンは、テンプレートが送信されるときではなく、イメージのビルドが行われるときに評価されます。 Azure Compute Gallery 送信先でこの機能を使用する場合、テンプレートを再送信するのは避け、間隔を置いてイメージ ビルドを再実行します。これにより、最新のイメージから、ご自身のイメージが再作成されます。

マーケットプレース プラン情報のサポート

次の例のように、プラン情報を指定することもできます。

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

ManagedImage source

ソース イメージを、一般化された VHD または VM の既存のマネージド イメージとして設定します。

Note

ソース マネージド イメージは、サポート対象の OS のものでなければならず、このイメージは Azure Image Builder テンプレートと同じサブスクリプションおよびリージョンに存在する必要があります。

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

imageId は、マネージド イメージの ResourceId にする必要があります。 使用可能なイメージの一覧を表示するには、az image list を使います。

SharedImageVersion source

ソース イメージを、Azure Compute Gallery 内の既存のイメージ バージョンとして設定します。

Note

ソース共有イメージのバージョンは、サポート対象の 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 テンプレート リソース ID。 イメージのバージョン名が "latest" である場合、イメージ ビルドが行われるときにそのバージョンが評価されます。 imageVersionId は、イメージ バージョンの ResourceId にする必要があります。 イメージ バージョンの一覧を表示するには、az sig image-version list を使います。

次の JSON は、ソース イメージを、直接共有ギャラリーに格納されているイメージとして設定します。

Note

直接共有ギャラリーは現在、プレビュー提供です。

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

次の JSON は、ソース イメージを、Azure Compute Gallery に格納されているイメージの最新のイメージ バージョンとして設定します。

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

SharedImageVersion properties:

imageVersionId - ARM template resource ID of the image version. イメージのバージョン名が "latest" である場合、イメージ ビルドが行われるときにそのバージョンが評価されます。

Properties: stagingResourceGroup

stagingResourceGroup プロパティには、Image Builder サービスがイメージ ビルド プロセス中に使用するために作成するステージング リソース グループに関する情報が含まれています。 この stagingResourceGroup は、イメージ ビルド プロセス中に Image Builder によって作成されたリソース グループをより制御する必要があるユーザー向けのオプション プロパティです。 独自のリソース グループを作成し、stagingResourceGroupセクションで 指定することも、代わりにAzure VM Image Builderが作成することもできます。

Important

ステージング リソース グループが別のイメージ テンプレートに関連付けられていないこと、空である (内部にリソースがない) こと、イメージ テンプレートと同じリージョンにあること、Azure Image Builder イメージ テンプレート リソースに割り当てられた ID に "共同作成者" または "所有者" の RBAC が適用されていること。 Image Builder は、ステージング リソース グループのタグを imageTemplateResourceGroupName キーと imageTemplateName でチェックして、イメージ テンプレートでステージング リソース グループが使用されているかどうかを判断します。 イメージ テンプレートの送信前にこれらのタグが存在する場合、またはイメージのビルド中に実行中のイメージ テンプレートと一致しない場合、操作は失敗します。

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

テンプレート作成シナリオ

  • stagingResourceGroup プロパティは空のままにします

    stagingResourceGroup プロパティが指定されていないか、空の文字列で指定されている場合、Image Builder サービスは、既定の名前規則「IT_***」を使用してステージング リソース グループを作成します。 このステージング リソース グループには、既定のタグが適用されます: createdBy、imageTemplateName、imageTemplateResourceGroupName。 また、既定の RBAC (「共同作成者」) が、Azure Image Builder テンプレート リソースに割り当てられた ID に適用されます。

  • stagingResourceGroup プロパティには、存在するリソース グループが指定されます

    stagingResourceGroup プロパティに、存在するリソース グループが指定されている場合、Image Builder サービスは、そのリソース グループが別のイメージ テンプレートに関連付けられていないこと、空である (内部にリソースがない) こと、イメージ テンプレートと同じリージョン内にあること、Azure Image Builder イメージ テンプレート リソースに割り当てられた ID に「共同作成者」または「所有者」の RBAC が適用されていることを確認します。 前述の要件のいずれかが満たされていない場合は、エラーがスローされます。 このステージング リソース グループには、次のタグが追加されます: usedBy、imageTemplateName、imageTemplateResourceGroupName。 既存のタグは削除されません。

Important

Windows ソース イメージを使用して既存のリソース グループと VNet を Azure Image Builder サービスに指定しようとする場合は、Azure Image Builder のファースト パーティ アプリに対応するサービス プリンシパルのリソース グループに共同作成者ロールを割り当てる必要があります。 リソース グループに共同作成者ロールを割り当てる方法に関する CLI コマンドとポータルの手順については、「VM Azure Image Builder のトラブルシューティング: ディスク作成中の承認エラー」に関するドキュメントを参照してください。

  • stagingResourceGroup プロパティには、存在しないリソース グループが指定されます

    stagingResourceGroup プロパティに、存在しないリソース グループが指定されている場合、Image Builder サービスは、stagingResourceGroup プロパティで指定された名前を持つステージング リソース グループを作成します。 指定された名前がリソース グループの Azure の名前付け要件を満たしていない場合は、エラーが発生します。 このステージング リソース グループには、既定のタグが適用されます: createdBy、imageTemplateName、imageTemplateResourceGroupName。 既定では、Azure Image Builder イメージ テンプレート リソースに割り当てられた ID には、リソース グループ内で「共同作成者」の RBAC が適用されます。

Template deletion

Image Builder サービスによって作成されたどのステージング リソース グループも、イメージ テンプレートが削除された後に削除されます。 この削除には、stagingResourceGroup プロパティで指定されたが、イメージ ビルド前には存在しなかったステージング リソース グループが含まれます。

Image Builder がステージング リソース グループを作成しなかったが、リソース グループの中にリソースを作成した場合、Image Builder サービスにリソースの削除に必要な適切なアクセス許可またはロールがあれば、イメージ テンプレートが削除された後にそれらのリソースが削除されます。

Properties: validate

このvalidateプロパティを使用すると、Azure Image Builder を使用して作成したかどうかに関係なく、プラットフォーム イメージとカスタマイズされたイメージを検証できます。

Azure Image Builder では、sourceValidationOnly プロパティを使用して設定できる「Source-Validation-Only」モードがサポートされています。 sourceValidationOnly プロパティが true に設定されている場合、source セクションで指定されたイメージが直接検証されます。 カスタマイズされたイメージを生成して検証するために、個別のビルドは実行されません。

この inVMValidations プロパティは、イメージに対して実行される検証コントロールの一覧を取得します。 Azure Image Builder は、File、PowerShell、Shell 検証コントロールをサポートしています。

この continueDistributeOnFailure プロパティは、検証が失敗した場合に出力イメージが配布されるかどうかを決定します。 既定では、検証が失敗し、このプロパティが false に設定されている場合、出力イメージは配布されません。 検証が失敗しても、このプロパティが true に設定されている場合、出力イメージは配布されます。 このオプションを使用すると、使用に関してイメージの配布に失敗する可能性があるため、注意して使用してください。 (true または false の) いずれの場合も、検証エラーが発生すると、エンド ツー エンドのイメージ実行が失敗として報告されます。 このプロパティは、検証が成功するかどうかには影響しません。

validate を使うとき:

  • 複数の検証コントロールを使用できます。
  • 検証コントロールは、テンプレートで指定されている順序で実行されます。
  • 1 つの検証コントロールが失敗した場合、検証コントロール コンポーネント全体が失敗し、エラーがレポートされます。
  • テンプレートで使う前に、スクリプトを十分にテストすることをお勧めします。 独自の VM でスクリプトをデバッグする方が簡単です。
  • スクリプト内には機密データを記述しないでください。
  • The script locations need to be publicly accessible, unless you're using 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 - name of the validator

  • scriptUri - URI of the PowerShell script file.

  • inline – array of commands to be run, separated by commas.

  • validExitCodes – Optional, valid codes that can be returned from the script/inline command, this avoids reported failure of the script/inline command.

  • runElevated – Optional, boolean, support for running commands and scripts with elevated permissions.

  • sha256Checksum - Value of sha256 checksum of the file, you generate this locally, and then Image Builder will checksum and validate.

    To generate the sha256Checksum, using a PowerShell on Windows Get-Hash

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 – Shell or File specified as the validation type to be performed.

  • name - name of the validator

  • scriptUri - URI of the script file

  • inline - array of commands to be run, separated by commas.

  • sha256Checksum - Value of sha256 checksum of the file, you generate this locally, and then Image Builder will checksum and validate.

    Mac/Linux のターミナルを使用して sha256Checksum を生成するには、sha256sum <fileName> を実行します。

  • destination - Destination of the file.

  • sha256Checksum - Specifies the SHA256 checksum of the file.

  • sourceUri - The source URI of the file.

Properties: vmProfile

vmSize (optional)

Image Builder は、既定の SKU サイズとして、Gen1 イメージでは Standard_D1_v2 を、Gen2 イメージでは Standard_D2ds_v4 を使用します。 生成は、source で指定するイメージによって定義されます。 vmSize は、次の理由でオーバーライドできます。

  • より大きなメモリや CPU、および大きなファイル (GB) の処理が必要なカスタマイズの実行。
  • Windows ビルドの実行。"Standard_D2_v2" または同等の VM サイズを使用する必要があります。
  • Require VM isolation.
  • 特定のハードウェアを必要とするイメージをカスタマイズします。 たとえば、GPU VM の場合、GPU VM サイズが必要です。
  • Require end to end encryption at rest of the build VM, you need to specify the support build VM size that doesn't use local temporary disks.

osDiskSizeGB

既定では Image Builder はイメージのサイズを変更しません。ソース イメージのサイズが使用されます。 You can optionally only increase the size of the OS Disk (Win and Linux), and a value of 0 means leaving the same size as the source image. OS ディスクのサイズをソース イメージのサイズより小さくすることはできません。

{
  "osDiskSizeGB": 100
}

vnetConfig (optional)

VNet プロパティを指定しない場合、Image Builder によって独自の VNet、パブリック IP、およびネットワーク セキュリティ グループ (NSG) が作成されます。 パブリック IP は、サービスがビルド VM と通信するために使用されます。 パブリック IP が不要な場合、または Image Builder が既存の VNet リソース (構成サーバー (DSC、Chef、Puppet、Ansible)、ファイル共有など) にアクセスできるようにする場合は、VNet を指定できます。 For more information, review the networking documentation.

"vnetConfig": {
  "subnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName1>",
  "containerInstanceSubnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName2>",
  "proxyVmSize": "<vmSize>"
}

subnetId

ビルド VM と検証 VM がデプロイされている既存のサブネットのリソース ID。

containerInstanceSubnetId (optional)

Resource ID of a pre-existing subnet on which Azure Container Instance (ACI) is deployed for Isolated Builds. このフィールドが指定されていない場合、サブネットとネットワーク セキュリティ グループと共に一時的な仮想ネットワークが、他のネットワーク リソース (プライベート エンドポイント、プライベート リンク サービス、Azure Load Balancer、プロキシ VM) に加えてステージング リソース グループにデプロイされ、ACI とビルド VM の間の通信が有効になります。

[このプロパティは API バージョン 2024-02-01 以降でのみ使用できますが、以前のバージョンの API を使用して作成された既存のテンプレートは、このプロパティを指定するように更新できます。

このフィールドは、 subnetId も指定され、次の要件を満たす必要がある場合にのみ指定できます。

  • このサブネットは、 subnetIdで指定されたサブネットと同じ仮想ネットワーク上にある必要があります。
  • このサブネットは、 subnetIdで指定されたものと同じサブネットにすることはできません。
  • ACI リソースのデプロイに使用できるように、このサブネットを ACI サービスに委任する必要があります。 You can read more about subnet delegation for Azure services here. ACI specific subnet delegation information is available here.
  • このサブネットでは、インターネットと、 subnetIdで指定されたサブネットへの送信アクセスを許可する必要があります。 これらのアクセスは、ACI をプロビジョニングし、ビルド VM と通信してカスタマイズ/検証を実行できるようにするために必要です。 もう一方の側では、 subnetId で指定されたサブネットは、このサブネットからの受信アクセスを許可する必要があります。 一般に、 これらのアクセスを許可 、Azure ネットワーク セキュリティ グループ (NSG) の既定のセキュリティ規則です。 ただし、NSG にセキュリティ規則を追加する場合は、次のアクセスを引き続き許可する必要があります。
    1. containerInstanceSubnetIdで指定されたサブネットからの送信アクセス:
      1. ポート 443 上のインターネット (コンテナー イメージのプロビジョニング)。
      2. ポート 445 のインターネット ( Azure Storage からのファイル共有のマウント)。
      3. ポート 22 (ssh/Linux の場合) とポート 5986 (WinRM/Windows の場合) の subnetId で指定されたサブネット (ビルド VM に接続する場合)。
    2. subnetIdで指定されたサブネットへの受信アクセス:
      1. containerInstanceSubnetIdで指定されたサブネットからポート 22 (ssh/Linux の場合) とポート 5986 (WinRM/Windows の場合) (ACI がビルド VM に接続)。
  • The template identity must have permission to perform 'Microsoft.Network/virtualNetworks/subnets/join/action' action on this subnet's scope. You can read more about Azure permissions for Networking here.

proxyVmSize (optional)

ビルド VM と検証 VM にトラフィックを渡すために使用されるプロキシ仮想マシンのサイズ。 この場合、プロキシ仮想マシンがデプロイされないため、 containerInstanceSubnetId が指定されている場合は、このフィールドを指定しないでください。 既定値 (Standard_A1_v2) を使用するには、空の文字列を省略または指定します。

Properties: autoRun

autoRun プロパティを使用して、テンプレートの作成時にイメージ テンプレートのビルド プロセスを自動的に開始するかどうかを制御できます。 これは、次の 2 つの値を指定できる列挙型です。

  • Enabled - Auto run is enabled, so your image template build process will automatically start when the template is created.
  • Disabled - Auto run is disabled, so you will have to manually start the image build process after the template is created.
"properties": {
    "autoRun": {
        "state": "Enabled"
    }
 }

Note

When you set autoRun to "Enabled," the image build process runs once upon template creation. これにより、初期イメージのビルドがシームレスに行われます。 ただし、一貫性のある継続的なイメージ ビルドは提供されません。 イメージ テンプレートの更新後に実行される一貫性のある継続的なイメージ ビルドについては、「 Azure Image Builder トリガーを使用して自動イメージ ビルドを設定する方法を参照してください。

autoRunとは異なり、Azure Image Builder トリガー リソースを使用したイメージの自動作成により、イメージ ビルドが一貫して実行されます。 テンプレートに変更が加わると、Azure Image Builder サービスによってイメージのビルド プロセスが自動的にトリガーされます。

テンプレートの作成時にすぐにイメージ ビルドを行う場合は、 autoRun を選択します。 イメージ ビルドで継続的な整合性が必要な場合は、イメージの自動作成を選択します。 特定の要件を考慮し、ワークフローに基づいて適切なオプションを使用します。

Properties: managedResourceTags

managedResourceTags プロパティを使用すると、イメージのビルド中に Azure Image Builder サービスがステージング リソース グループに作成するリソースにタグを適用できます。 ステージング リソース グループの詳細については、「 Azure Image Builder の概要」を参照してください。

"properties": {
    "managedResourceTags": {
      "tag1": "value1",
            "tag2": "value2"
              }
}

イメージ テンプレートの操作

イメージ ビルドの開始

ビルドを開始するには、イメージ テンプレート リソースに対して "Run" を呼び出す必要があります。run コマンドの例は次のとおりです。

Invoke-AzResourceAction -ResourceName $imageTemplateName -ResourceGroupName $imageResourceGroup -ResourceType Microsoft.VirtualMachineImages/imageTemplates -ApiVersion "2023-07-01" -Action Run -Force

az resource invoke-action \
  --resource-group $imageResourceGroup \
  --resource-type  Microsoft.VirtualMachineImages/imageTemplates \
  -n helloImageTemplateLinux01 \
  --action Run

イメージ ビルドの取り消し

イメージのビルドを実行しているときに、正しくないと思われる場合、ユーザーの入力を待っている場合、または正常に完了しないと考えられる場合は、ビルドを取り消すことができます。

ビルドはいつでも取り消すことができます。 配布フェーズが始まっている場合でも取り消しはできますが、完了していない可能性があるイメージをすべてクリーンアップする必要があります。 The cancel command doesn't wait for cancel to complete, monitor lastrunstatus.runstate for canceling progress, using these status commands.

cancel コマンドの例を次に示します。

Invoke-AzResourceAction -ResourceName $imageTemplateName -ResourceGroupName $imageResourceGroup -ResourceType Microsoft.VirtualMachineImages/imageTemplates -ApiVersion "2023-07-01" -Action Cancel -Force

az resource invoke-action \
  --resource-group $imageResourceGroup \
  --resource-type  Microsoft.VirtualMachineImages/imageTemplates \
  -n helloImageTemplateLinux01 \
  --action Cancel

Next steps

さまざまなシナリオの .json ファイルのサンプルが、Azure Image Builder の GitHub にあります。

  • Last updated on