次の方法で共有

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

API バージョン

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

Type

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

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

場所

location は、カスタム イメージを作成するリージョンです。 次のリージョンがサポートされています。

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

重要

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

重要

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

Azure Government リージョン (USGov アリゾナおよび USGov バージニア) で Azure VM Image Builder パブリック プレビューにアクセスするには、Microsoft.VirtualMachineImages/FairfaxPublicPreview 機能を登録する必要があります。 これを行うには、PowerShell または Azure CLI のどちらかで次のコマンドを実行します。

Register-AzProviderPreviewFeature -ProviderNamespace Microsoft.VirtualMachineImages -Name FairfaxPublicPreview

中国北部 3 リージョンで Azure VM Image Builder パブリック プレビューにアクセスするには、Microsoft.VirtualMachineImages/MooncakePublicPreview 機能を登録する必要があります。 これを行うには、PowerShell または Azure CLI のどちらかで次のコマンドを実行します。

Register-AzProviderPreviewFeature -ProviderNamespace Microsoft.VirtualMachineImages -Name MooncakePublicPreview

"location": "<region>"

データの保存場所

Azure VM Image Builder サービスでは、顧客が単一リージョンのデータ所在地の要件が厳しいリージョンでの構築を要求した場合に、そのリージョンの外部に顧客のデータが保存されたり、外部で処理されたりすることはありません。 データ所在地の要件が設けられているリージョンでサービスが停止した場合は、別のリージョンや地域に Bicep ファイルまたはテンプレートを作成する必要があります。

ゾーン冗長性

配布ではゾーン冗長がサポートされており、VHD は既定でゾーン冗長ストレージ (ZRS) アカウントに配布されます。Azure Compute Gallery (旧称 Shared Image Gallery) バージョンでは、ZRS ストレージの種類がサポートされます (指定されている場合)。

Tags

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

ID

以下で説明するユーザー割り当て 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 オペレーター」 ロールが割り当てられている必要があることに注意してください。

注意

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 が作成され、別のテナントでイメージ テンプレートがに作成されている場合)。

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

プロパティ: 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 値を大きくします。 ただし、エラーが表示される前にタイムアウトするまで待機する必要があるため、設定値を大きくしすぎないでください。

プロパティ: customize

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

customize を使うとき:

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

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 カスタマイザーでは、Linux でのシェル スクリプトの実行がサポートされています。 シェル スクリプトには、パブリックにアクセスできる必要があります。または、Image Builder からアクセスするには、MSI が構成されている必要があります。

"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。

  • inline - コンマで区切られたシェル コマンドの配列。

  • sha256Checksum - ファイルの sha256 チェックサムの値。この値をローカルで生成すると、Image Builder によってチェックサムと検証が実行されます。

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

カスタマイズのプロパティ:

  • Type: 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。

  • inline - コンマで区切って指定された、実行するインライン コマンド。

  • validExitCodes – 省略可能。スクリプト/インライン コマンドから返すことができる有効なコード。 このプロパティにより、スクリプト/インライン コマンドの報告済みエラーが回避されます。

  • runElevated - 省略可能。ブール値。昇格されたアクセス許可でコマンドとスクリプトを実行するためのサポート。

  • runAsSystem - オプションのブール値であり、PowerShell スクリプトをシステム ユーザーとして実行するかどうかを決定します。

  • sha256Checksum - ファイルの SHA256 チェックサムをローカルで生成し、チェックサム値を小文字に更新します。Image Builder でイメージ テンプレートのデプロイ中にチェックサムが検証されます。

    sha256Checksum を生成するには、PowerShell で Get-FileHash コマンドレットを使用します。

ファイル カスタマイザー

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

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

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

  • sourceUri - アクセス可能なストレージ エンドポイント。このエンドポイントには、GitHub または Azure Storage を指定できます。 ダウンロードできるのは 1 つのファイルだけであり、ディレクトリ全体はできません。 ディレクトリをダウンロードする必要がある場合は、圧縮されたファイルを使用し、シェルまたは PowerShell カスタマイザーを使って圧縮を解除します。

    Note

    sourceUri が Azure Storage アカウントの場合、BLOB に public のマークが付けられているかどうかにかかわらず、BLOB での読み取りアクセス許可をマネージド ユーザー ID に付与します。 ストレージのアクセス許可を設定するには、この例を参照してください。

  • destination - ターゲットの完全なパスとファイル名。 参照されているすべてのパスとサブディレクトリが存在する必要があり、事前にこれらのパスを設定するにはシェルまたは 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 - ファイルの SHA256 チェックサムをローカルで生成し、チェックサム値を小文字に更新します。Image Builder でイメージ テンプレートのデプロイ中にチェックサムが検証されます。

    sha256Checksum を生成するには、PowerShell で Get-FileHash コマンドレットを使用します。

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

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

  • type - WindowsUpdate。
  • searchCriteria - 省略可能。インストールされている更新プログラムの種類を定義します (推奨または重要など)。既定値は、BrowseOnly=0 と IsInstalled=0 (推奨) です。
  • filters – 省略可能。更新プログラムを含めるか除外するフィルターを指定できます。
  • updateLimit – 省略可能。インストールできる更新プログラムの数を定義します。既定値は 1000 です。

Note

Windows Update カスタマイザーは、保留中の Windows の再起動や、まだ実行中のアプリケーションのインストールがある場合に失敗する可能性があります。このエラー System.Runtime.InteropServices.COMException (0x80240016): Exception from HRESULT: 0x80240016 は、通常、customization.log で確認できます。 Windows Update を実行する前に、Windows の再起動を取り入れることや、インライン コマンドやスクリプトに sleep や待機のコマンドを追加して、アプリケーションにインストールを完了するのに十分な時間を与えることを強くお勧めします。

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 に書き込まれます。 ログを収集する方法については、troubleshooting (トラブルシューティング) に関する記事をご覧ください。

プロパティ: errorHandling

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

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

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

  • onCustomizerError - イメージの作成のカスタマイザー フェーズでエラーが発生したときに実行するアクションを指定します。
  • onValidationError - イメージ テンプレートの検証中にエラーが発生したときに実行するアクションを指定します。

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

  • cleanup - Packer またはいずれかのカスタマイズ/検証でエラーが発生した場合でも、Packer によって作成された一時的なリソースがクリーンアップされるようにします。 これにより、既存の動作との下位互換性が維持されます。
  • abort - Packer でエラーが発生した場合、Azure Image Builder (AIB) サービスは一時的なリソースのクリーンアップをスキップします。 AIB テンプレートの所有者は、サブスクリプションからこれらのリソースをクリーンアップする責任があります。 これらのリソースには、一時 VM に残されたログやファイルなどの有用な情報が含まれている場合があります。これは、Packer で発生したエラーの調査に役立ちます。

プロパティ: distribute

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

  • ManagedImage - マネージド イメージ。
  • sharedImage - Azure Compute Gallery。
  • VHD - ストレージ アカウント内の VHD。

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

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

出力:

{
  "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 - 配布先イメージのリソース ID。必要な形式: /subscriptions/<subscriptionId>/resourceGroups/<destinationResourceGroupName>/providers/Microsoft.Compute/images/<imageName>
  • location - マネージド イメージの場所。
  • runOutputName – 配布を示す一意の名前。
  • artifactTags - 省略可能なユーザー指定のキーと値のタグ。

Note

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

配布: sharedImage

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

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

  • ギャラリー - 複数のイメージ用のコンテナー。 ギャラリーは、1 つのリージョンにデプロイされます。
  • イメージ定義 - イメージの概念的なグループ化。
  • イメージ バージョン - VM またはスケール セットのデプロイに使われるイメージの種類。 イメージ バージョンは、VM をデプロイする必要がある他のリージョンにレプリケートできます。

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

注意

イメージのバージョン 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>"
  ]

注意

targetRegions が更新されたプロパティであるため、replicationRegions はギャラリー配布では非推奨です。 詳細については、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 - Azure Compute Gallery の ID です。このプロパティは、次の 2 つの形式で指定できます。

    • 自動バージョン管理 - 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 – 配布を示す一意の名前。

  • artifactTags - 省略可能なユーザー指定のキーと値のタグ。

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

  • replicationRegions - レプリケーション用のリージョンの配列。 これは、2022-07-01 API の一部として新しく導入され、SharedImage の種類の配布にのみ適用されます。

  • excludeFromLatest (省略可能) - 作成したイメージ バージョンをギャラリー定義で最新バージョンとして使用しないように設定できます。既定値は "false" です。

  • storageAccountType (省略可能) - AIB では、作成されるイメージ バージョンに対して、次の種類のストレージを指定することがサポートされています。

    • "Standard_LRS"
    • "Standard_ZRS","

注意

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

バージョン管理

versioning プロパティは、sharedImage 配布の種類専用です。 これは、次の 2 つの値を指定できる列挙型です。

  • latest - デザインごとに新しく厳密に増加するスキーマ
  • source - ソース イメージのバージョン番号に基づくスキーマ。

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

注意

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

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

バージョン管理のプロパティ:

  • scheme - 配布用の新しいバージョン番号を生成します。 Latest と Source が、指定できる 2 つの値です。
  • major - 最新バージョンを生成するメジャー バージョンを指定します。 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 が生成されます

配布: 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

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

プロパティ: 最適化

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

"optimize": {
      "vmBoot": {
        "state": "Enabled"
      }
    }
  • vmBoot: 仮想マシン (VM) の起動プロセスに関連する構成。ブート時間やその他のパフォーマンス面を向上させる最適化を制御するために使用されます。
  • state: vmBoot 内のブート最適化機能の状態。値 Enabled は、イメージの作成時間を短縮するために機能がオンになっていることを示します。

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

プロパティ: source

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

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

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

注意

既存の Windows カスタム イメージを使用する場合、1 つの Windows 7 または Windows Server 2008 R2 イメージで Sysprep コマンドを最大 3 回実行できます。それ以降のバージョンでは、1 つの 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"
}

ここでのプロパティは 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 ソース

ソース イメージを、一般化された 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 ソース

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

注意

ソース共有イメージのバージョンは、サポート対象の 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 は、ソース イメージを、直接共有ギャラリーに格納されているイメージとして設定します。

注意

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

    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 のプロパティ:

imageVersionId - イメージ バージョンの ARM テンプレート リソース ID。 イメージのバージョン名が "latest" である場合、イメージ ビルドが行われるときにそのバージョンが評価されます。

プロパティ: stagingResourceGroup

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

重要

ステージング リソース グループが別のイメージ テンプレートに関連付けられていないこと、空である (内部にリソースがない) こと、イメージ テンプレートと同じリージョンにあること、Azure Image Builder イメージ テンプレート リソースに割り当てられた ID に "共同作成者" または "所有者" の RBAC が適用されていること。

"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。 既存のタグは削除されません。

重要

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 が適用されます。

テンプレートの削除

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

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

プロパティ: 検証する

この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 でスクリプトをデバッグする方が簡単です。
  • スクリプト内には機密データを記述しないでください。
  • 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。

  • inline - コンマで区切って指定された、実行するコマンドの配列。

  • validExitCodes - 省略可能。スクリプトまたはインライン コマンドから返すことができる有効なコード。これにより、スクリプトやインライン コマンドの失敗報告が回避されます。

  • runElevated - 省略可能。ブール値。昇格されたアクセス許可でコマンドとスクリプトを実行するためのサポート。

  • sha256Checksum - ファイルの sha256 チェックサムの値。これをローカルで生成すると、Image Builder によってチェックサムと検証が実行されます。

    Windows で PowerShell を使用して sha256Checksum を生成するには、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 または File。

  • name - 検証コントロールの名前

  • scriptUri - スクリプト ファイルのURI

  • inline - コンマで区切って指定された、実行するコマンドの配列。

  • sha256Checksum - ファイルの sha256 チェックサムの値。これをローカルで生成すると、Image Builder によってチェックサムと検証が実行されます。

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

  • destination - ファイルの宛先。

  • sha256Checksum - ファイルの SHA256 チェックサムを指定します。

  • sourceUri - ファイルのソース URI。

プロパティ: vmProfile

vmSize (省略可能)

Image Builder は、既定の SKU サイズとして、Gen1 イメージでは Standard_D1_v2 を、Gen2 イメージでは Standard_D2ds_v4 を使用します。 生成は、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/<subnetName1>",
  "containerInstanceSubnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName2>",
  "proxyVmSize": "<vmSize>"
}

subnetId

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

containerInstanceSubnetId (省略可能)

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

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

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

  • このサブネットは、 subnetIdで指定されたサブネットと同じ仮想ネットワーク上にある必要があります。
  • このサブネットは、 subnetIdで指定されたものと同じサブネットにすることはできません。
  • ACI リソースのデプロイに使用できるように、このサブネットを ACI サービスに委任する必要があります。 Azure サービスのサブネット委任の詳細については、 こちらを参照してください。 ACI 固有のサブネット委任情報は、 参照。
  • このサブネットでは、インターネットと、 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 に接続)。
  • テンプレート IDには、このサブネットのスコープに対して 'Microsoft.Network/virtualNetworks/subnets/join/action' アクションを実行するためのアクセス許可が必要です。 ネットワークに対する Azure のアクセス許可の詳細については、 こちらを参照してください。

proxyVmSize (省略可能)

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

プロパティ: autoRun

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

  • 有効 - 自動実行が有効になっているため、テンプレートの作成時にイメージ テンプレートのビルド プロセスが自動的に開始されます。
  • 無効 - 自動実行は無効になっているため、テンプレートの作成後にイメージのビルド プロセスを手動で開始する必要があります。
"properties": {
    "autoRun": {
        "state": "Enabled"
    }
 }

Note

autoRunを "有効" に設定すると、イメージビルドプロセスはテンプレートの作成時にonce を実行します。 これにより、初期イメージのビルドがシームレスに行われます。 ただし、一貫性のある継続的なイメージ ビルドは提供されません。 イメージ テンプレートの更新後に実行される一貫性のある継続的なイメージ ビルドについては、「 Azure Image Builder トリガーを使用して自動イメージ ビルドを設定する方法を参照してください。

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

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

プロパティ: 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

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

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

ビルドはいつでも取り消すことができます。 配布フェーズが始まっている場合でも取り消しはできますが、完了していない可能性があるイメージをすべてクリーンアップする必要があります。 cancel コマンドでは、取り消しの完了まで待つことはしません。これらの状態コマンドを使用して、lastrunstatus.runstate で取り消しの進行状況をモニターしてください。

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

次のステップ

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