Azure Image Builder テンプレートを作成する

適用対象: ✔️ Linux VM ✔️ フレキシブルなスケール セット

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

テンプレートの基本的な形式を次に示します。

{
  "type": "Microsoft.VirtualMachineImages/imageTemplates",
  "apiVersion": "2021-10-01",
  "location": "<region>",
  "tags": {
    "<name>": "<value>",
    "<name>": "<value>"
  },
  "identity": {},
  "properties": {
    "buildTimeoutInMinutes": <minutes>,
    "stagingResourceGroup": "/subscriptions/<subscriptionID>/resourceGroups/<stagingResourceGroupName>",
    "vmProfile": {
      "vmSize": "<vmSize>",
      "proxyVmSize": "<vmSize>",
      "osDiskSizeGB": <sizeInGB>,
      "vnetConfig": {
        "subnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName>"
      },
"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>",
  ...
    ]
    },
    "source": {},
    "customize": [],
    "validate": {},
    "distribute": []
  }
}

種類と API のバージョン

type はリソースの種類であり、"Microsoft.VirtualMachineImages/imageTemplates" にする必要があります。 apiVersion は、API の変更に伴って経時的に変わりますが、現時点では "2021-10-01" にする必要があります。

"type": "Microsoft.VirtualMachineImages/imageTemplates",
"apiVersion": "2021-10-01",

場所

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

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

重要

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

Azure Government リージョン (USGov アリゾナおよび USGov バージニア) で Azure Image Builder の機能を登録するには、次のコマンドを使用します。

az feature register --namespace Microsoft.VirtualMachineImages --name FairfaxPublicPreview
"location": "<region>",

データ所在地

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

ゾーン冗長

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

vmProfile

buildVM

Image Builder では、Gen1 イメージの場合は "Standard_D1_v2"、Gen2 イメージの場合は "Standard_D2ds_v4" という既定の SKU サイズが使用されます。 生成は、source で指定するイメージによって定義されます。 これはオーバーライド可能で、次の理由から行う場合があります:

  1. より大きなメモリや CPU、および大きなファイル (GB) の処理が必要なカスタマイズの実行。
  2. Windows ビルドの実行。"Standard_D2_v2" または同等の VM サイズを使用する必要があります。
  3. VM の分離が必要。
  4. 特定のハードウェアを必要とするイメージをカスタマイズします。 たとえば、GPU VM の場合、GPU VM サイズが必要です。
  5. ビルド 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>"
    }
}

Tags

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

ID

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

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

必須 - スクリプトで Azure Storage から読み取られたイメージを読み書きするアクセスが Image Builder に許可されるようにするには、個々のリソースに対するアクセス許可を持つ Azure ユーザー割り当て ID を作成する必要があります。 Image Builder のアクセス許可のしくみと関連するステップの詳細については、ドキュメントを参照してください。

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

詳細については、「Azure VM 上で Azure リソースのマネージド ID を使用してアクセス トークンを取得する方法」と「Azure VM 上の Azure リソースのマネージド ID を使用してサインインする方法」を参照してください。

プロパティ: stagingResourceGroup

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

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

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

stagingResourceGroup フィールドは空のままにします

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

そのstagingResourceGroup フィールドは、存在するリソース グループと共に指定されます

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

そのステージングリソース グループ フィールドは、存在しないリソース グループと共に指定されます

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

テンプレートの削除

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

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

プロパティ: source

source セクションには、Image Builder によって使われるソース イメージについての情報が含まれます。 現在、Image Builder でネイティブにサポートされているのは、Azure Compute Gallery (SIG) の Hyper-V 第 1 世代 (Gen1) のイメージまたはマネージド イメージの作成のみです。 Gen2 イメージを作成する場合は、ソース Gen2 イメージを使用し、VHD に配布する必要があります。 その後、VHD からマネージド イメージを作成し、これを Gen2 イメージとして SIG に挿入する必要があります。

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

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

Note

既存の 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>/p  roviders/Microsoft.Compute/galleries/<sharedImageGalleryName>/images/<imageDefinitionName/versions/<imageVersion>"
}

imageVersionId は、イメージ バージョンの ResourceId にする必要があります。 イメージ バージョンの一覧を表示するには、az sig image-version list を使います。

プロパティ: buildTimeoutInMinutes

既定では、Image Builder は 240 分間実行されます。 その後、イメージのビルドが完了しているかどうかにかかわらず、タイムアウトして停止します。 タイムアウトに達した場合は、次のようなエラーが表示されます。

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

buildTimeoutInMinutes の値を指定しなかった場合、または 0 に設定した場合は、既定値が使用されます。 値は、最大で 960 分 (16 時間) まで増減できます。 Windows の場合、この値を 60 分未満に設定することはお勧めしません。 タイムアウトに達していることがわかった場合は、ログを確認し、カスタマイズの手順がユーザー入力などで待機しているかどうかを確認します。

カスタマイズを完了するためにより多くの時間が必要な場合は、オーバーヘッドが小さい必要と思われるものに設定します。 ただし、エラーが表示される前にタイムアウトするまで待機する必要があるため、設定値を大きくしすぎないでください。

Note

値を 0 に設定しない場合、サポートされる最小値は 6 分です。 1 から 5 までの値を使用すると失敗します。

プロパティ: customize

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

customize を使うとき:

  • 複数のカスタマイザーを使用できます
  • カスタマイザーは、テンプレートで指定されている順序で実行されます。
  • 1 つのカスタマイザーが失敗した場合、カスタマイズ コンポーネント全体が失敗し、エラーが報告されます。
  • テンプレートで使う前に、スクリプトを十分にテストすることを強くお勧めします。 独自の VM でスクリプトをデバッグする方が簡単です。
  • スクリプト内には機密データを記述しないでください。
  • MSI を使っていない場合は、パブリックにアクセスできる場所にスクリプトを置く必要があります。
"customize": [
  {
    "type": "Shell",
    "name": "<name>",
    "scriptUri": "<path to script>",
    "sha256Checksum": "<sha256 checksum>"
  },
  {
    "type": "Shell",
    "name": "<name>",
    "inline": [
        "<command to run inline>",
    ]
  }
],

customize セクションは配列です。 Azure Image Builder では、カスタマイザーが順番に実行されます。 いずれかのカスタマイザーでエラーが発生すると、ビルド プロセスが失敗します。

Note

インライン コマンドは、イメージ テンプレート定義で表示できます。 機密情報 (パスワード、SAS トークン、認証トークンなど) がある場合は、アクセスに認証が必要な Azure Storage 内のスクリプトに移動する必要があります。

シェル カスタマイザー

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

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

OS のサポート: Linux

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

  • type - Shell

  • name- カスタマイズを追跡するための名前

  • scriptUri - ファイルの場所への URI

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

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

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

Note

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

スーパー ユーザー特権

先頭に sudo がある、スーパーユーザー特権で実行するコマンドは、スクリプトに追加したり、次の例のように inline コマンドで使用したりすることができます。

"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 再起動カスタマイザー

再起動カスタマイザーでは、Windows VM を再起動して、オンラインに戻るのを待機することができます。これにより、再起動が必要なソフトウェアをインストールできます。

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

OS のサポート: Windows

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

  • [種類] :WindowsRestart
  • restartCommand - 再起動を実行するコマンド (省略可能)。 既定では、 'shutdown /r /f /t 0 /c \"packer restart\"'です。
  • restartCheckCommand - 再起動が成功したかどうかを確認するコマンド (省略可能)。
  • restartTimeout - 大きさと単位の文字列として指定された再起動のタイムアウト。 たとえば、5m (5 分) や 2h (2 時間) などです。 既定値は "5m" です

Linux の再起動

Linux 再起動カスタマイザーはありません。 ドライバー、または再起動が必要なコンポーネントをインストールする場合は、それらをインストールし、シェル カスタマイザーを使用して再起動を呼び出すことができます。 ビルド VM には、20 分の SSH タイムアウトがあります。

PowerShell カスタマイザー

シェル カスタマイザーでは PowerShell スクリプトとインライン コマンドの実行がサポートされており、スクリプトは IB がアクセスできるようにパブリックにアクセス可能である必要があります。

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

OS のサポート: Windows

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

  • type - PowerShell。

  • scriptUri - PowerShell スクリプト ファイルの場所への URI。

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

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

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

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

    Windows で PowerShell を使用して sha256Checksum を生成するには、Get-Hash を実行します。

ファイル カスタマイザー

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

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

OS のサポート: Linux、Windows

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

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

Note

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

  • destination - これは、ターゲットの完全なパスとファイル名です。 参照されているすべてのパスとサブディレクトリが存在する必要があり、事前にたこれらを設定するにはシェルまたは PowerShell カスタマイザーを使います。 スクリプト カスタマイザーを使ってパスを作成できます。

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

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

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

Note

ファイル カスタマイザーは、小さいファイルのダウンロード (20 MB 未満) にのみ適しています。 大きいファイルをダウンロードする場合は、スクリプトまたはインライン コマンドを使用してから、ファイルをダウンロードするコード (Linux の wget または curl、Windows の Invoke-WebRequest など) を使用します。

Windows Update カスタマイザー

このカスタマイザーは、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
  }
],

OS のサポート: Windows

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

  • 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 }
Write-Output '>>> Sysprepping VM ...'
if( Test-Path $Env:SystemRoot\system32\Sysprep\unattend.xml ) {
  Remove-Item $Env:SystemRoot\system32\Sysprep\unattend.xml -Force
}
& $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 (トラブルシューティング) に関する記事をご覧ください。

プロパティ: 検証する

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

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

このinVMValidationsフィールドは、画像に対して実行される検証のリストを取得します。 Azure Image Builder では、PowerShell とシェル検証コントロールの両方がサポートされています。

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

validate を使うとき:

  • 複数の検証コントロールを使用できます
  • 検証コントロールは、テンプレートで指定されている順序で実行されます。
  • 1 つの検証コントロールが失敗した場合、検証コントロール コンポーネント全体が失敗し、エラーがレポートされます。
  • テンプレートで使う前に、スクリプトを十分にテストすることを強くお勧めします。 独自の VM でスクリプトをデバッグする方が簡単です。
  • スクリプト内には機密データを記述しないでください。
  • MSI を使っていない場合は、パブリックにアクセスできる場所にスクリプトを置く必要があります。

validateプロパティを使用してWindowsイメージを検証する方法

{
  "properties": {
    "validate": {
      "continueDistributeOnFailure": false,
      "sourceValidationOnly": false,
      "inVMValidations": [
        {
          "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>"
        }
      ]
    },
  }
 }

inVMValidationsプロパティ:

  • type - Shell

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

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

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

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

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

プロパティ: 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=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 - 配布先イメージのリソース 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 をデプロイする必要がある他のリージョンにレプリケートできます。

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

{
  "type": "SharedImage",
  "galleryImageId": "<resource ID>",
  "runOutputName": "<name>",
  "artifactTags": {
      "<name>": "<value>",
      "<name>": "<value>"
  },
  "replicationRegions": [
      "<region where the gallery is deployed>",
      "<region>"
  ]
}

ギャラリーのプロパティを配布する:

  • 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 つは、ギャラリーがデプロイされているリージョンでなければなりません。 リージョンを追加すると、ビルド時間が長くなります。これは、レプリケーションが完了するまでビルドが完了しないためです。

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

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

    • "Standard_LRS"
    • "Standard_ZRS"

Note

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

配布: 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 が失われます。

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

イメージ ビルドの開始

ビルドを開始するには、イメージ テンプレート リソースに対して "Run" を呼び出す必要があります。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

次のステップ

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