Azure VM Image Builder の新機能

[アーティクル]
05/13/2024

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

この記事には、Azure VM Image Builder (AIB) サービスのすべての主要な API の変更と機能更新が含まれています。

更新プログラム

2024 年 5 月

破壊的変更: 大文字と小文字の区別

2024 年 5 月 21 日から、Azure VM Image Builder の API バージョン 2024-02-01 以降では、すべてのフィールドに大文字と小文字の区別が適用されます。つまり、API 要求の文字の大文字と小文字の使い分けは、想定される形式と正確に一致する必要があります。

重要

既存の Azure Image Builder ユーザー向けの重要な注意事項

Azure VM Image Builder の既存のユーザーである場合は、この変更は既存のリソースに影響を与えないため、ご安心ください。大文字と小文字の区別の適用は、API バージョン 2024-02-01 以降を使用して新しく作成されたリソースにのみ適用されます。既存のリソースは、変更せずに引き続き期待どおりに機能します。

大文字と小文字の区別に関連する問題が発生した場合は、Azure Image Builder の更新された API ドキュメントのガイダンスを参照してください。

以前は、Azure Image Builder の API は、大文字と小文字の区別に寛容でしたが、今後は精度が重要です。 API 呼び出しを行うときは、フィールド名、パラメーター、値に大文字と小文字の区別を正しく使用してください。たとえば、フィールドの名前が "vmBoot" の場合は、"vmBoot" を使用する必要があり、"VMBoot" または "vmboot" を使用することはできません。

Azure Image Builder の API バージョン 2024-02-01 以降に間違った大文字と小文字の使用、または認識されないフィールドを含む API 要求を送信すると、サービスに拒否されます。要求が無効であることを示すエラー応答が表示されます。エラーは次のようになります。

Unmarshalling entity encountered error: unmarshalling type *v2024_02_01.ImageTemplate: struct field Properties: unmarshalling type *v2024_02_01.ImageTemplateProperties: struct field Optimize: unmarshalling type *v2024_02_01.ImageTemplatePropertiesOptimize: unmarshalling type *v2024_02_01.ImageTemplatePropertiesOptimize, unknown field \"vmboot\". There is an issue with the syntax with the JSON template you are submitting. Please check the JSON template for syntax and grammar. For more information on the syntax and grammar of the JSON template, visit http://aka.ms/azvmimagebuildertmplref.

"不明なフィールド" というエラーメッセージが表示され、公式ドキュメント「Azure Image Builder Bicep または ARM (JSON) テンプレートを作成する」に移動します。

Note

API 呼び出し用の Azure Image Builder の Swagger リファレンス

Azure Image Builder サービスを呼び出すときは、常に Swagger ドキュメントを参照してください。これは、Azure Image Builder の API 仕様の信頼できる情報源として役立ちます。パブリックドキュメントは、API リリースの前に適切な大文字と小文字の区別とフィールド名を含むように更新され、Swagger 定義には、サービスへの呼び出しを正しく行うための各 AIB API に関する正確な詳細が含まれています。

API バージョン 2024-02-01 のフィールド名と一致させるために行われたドキュメントの変更の一覧を次に示します。

「Azure Image Builder Bicep または ARM (JSON) テンプレートを作成する」ドキュメント内では次のとおりです。

更新されたフィールド:

vmboot のいくつかのメンションを vmBoot に置き換えました
imageVersionID の 1 つのメンションを imageVersionId に置き換えました

削除されたフィールド:

apiVersion: このフィールドは API で明示的に指定されていないため、要求にこのフィールドを含めないようにすることをお勧めします。JSON テンプレートに含めると、イメージビルドでエラーが発生する可能性があります。

「Azure VM Image Builder のネットワークオプション」ドキュメント内では次のとおりです。

更新されたフィールド:

VirtualNetworkConfig の 1 つのメンションを vnetConfig に置き換えました

削除されたフィールド:

vnetConfig プロパティ内の subnetName - このフィールドは非推奨となり、新しいフィールドは subnetId です
vnetConfig プロパティ内の resourceGroupName - このフィールドは非推奨となり、新しいフィールドは subnetId です

以前の Azure Image Builder API バージョンにピン留めする方法

以前の API バージョンへのピン留めに関する重要な考慮事項

以前の Azure Image Builder API バージョンにピン留めすると、既存のテンプレートとの互換性が提供される可能性がありますが、次の要因により推奨されません。

非推奨のリスク: 以前の API バージョンは、最終的に非推奨になる可能性があります。

不足する機能: 以前の API バージョンにピン留めすることで、新しいバージョンで導入された最新の機能と機能強化を利用できません。これらの機能強化により、多くの場合、パフォーマンス、セキュリティ、および機能が向上します。

新しい大文字と小文字の区別ルールのために、既存のイメージテンプレートのプロパティを変更しないことにする場合、Azure VM Image Builder API 呼び出しを以前の API バージョンにピン留めする選択肢があります。これにより、変更を加えずに使い慣れた動作を引き続き使用できます。

既存のテンプレートとの互換性を確保するには、イメージテンプレートを作成または更新するときに、サービスの呼び出しに api-version パラメーターを含めることで、目的の API バージョン (例: api-version=2022-07-01) を指定します。例:

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.VirtualMachineImages/imageTemplates/{imageTemplateName}?api-version=2022-07-01

az resource create \
    --api-version=2022-07-01 \
    --resource-group <resourceGroupName> \
    --properties <jsonResource> \
    --is-full-object \
    --resource-type Microsoft.VirtualMachineImages/imageTemplates \
    -n <imageTemplateName>

New-AzResourceGroupDeployment -ResourceGroupName <resourceGroupName> -TemplateFile <templateFilePath> -TemplateParameterObject @{"api-version" = "2022-07-01"; "imageTemplateName" = <imageTemplateName>; "svclocation" = <location>}

コードのテスト

以前の API バージョンにピン留めした後、コードをテストして、想定どおりに動作することを確認します。既存のテンプレートが引き続き正しく機能することを確認します。

2023 年 11 月

Azure Image Builder では、Azure Container Instances を使用して段階的に分離イメージのビルドを有効にしています。ロールアウトは 2024 年初めに完了する予定です。既存のイメージテンプレートは引き続き機能します。また、新しいイメージテンプレートを作成またはビルドする方法に変更はありません。

一時的な Azure リソースの異なるセットがステージングリソースグループに一時的に表示される場合がありますが、実際のビルドや Azure Image Builder との対話方法には影響しません。詳しくは、Isolated Image Builds に関する記事をご覧ください。

重要

サブスクリプションが Microsoft.ContainerInstance プロバイダーに登録されていて、Azure Container Instances リソースのデプロイをブロックするポリシーがないことを確認します。また、Azure Container Instances リソースに対してクォータを使用できることを確認します。

2023 年 4 月

Azure Image Builder に新しいポータル機能が追加されました。 Azure portal で "イメージテンプレート" を検索し、[作成] をクリックします。ポータル内でカスタムイメージのビルドと検証をこちらから開始することもできます。

API リリース

バージョン 2024-02-01

機能強化

テンプレートの作成または更新時にイメージビルドを実行できる新しい autoRun プロパティ。詳細については、プロパティ: autoRunに関するページを参照してください。
イメージのビルド中に Azure Image Builder サービスがステージングリソースグループに作成する、リソースにタグを適用できる新しい managedResourceTags プロパティ。詳細については、プロパティ: managedResourceTags に関するページを参照してください。
分離ビルド用に Azure Container Instance がデプロイされるサブネットを指定できる新しい containerInstanceSubnetId プロパティ。このフィールドは、subnetId も指定されていて、subnetId で指定されたサブネットと同じ仮想ネットワーク上にある必要がある場合にのみ指定できます。詳細については、「独自のビルド VM サブネットを導入し、独自の ACI サブネットを導入する」を参照してください。
次のフィールドを含む vmProfile プロパティの更新のサポートを追加しました。
- vmSize
- osDiskSizeGB
- userAssignedIdentities
- vnetConfig
  - subnetId
  - containerInstanceSubnetIdvmProfileプロパティの詳細については、vmProfile に関するページを参照してください。

変更 API バージョン 2024-02-01 では、すべてのフィールドに大文字と小文字の区別を適用する破壊的変更が導入されています。つまり、API 要求の文字の大文字と小文字の使い分けは、想定される形式と正確に一致する必要があります。 Azure Image Builder の API バージョン 2024-02-01 以降に間違った大文字と小文字の使用、または認識されないフィールドを含む API 要求を送信すると、サービスに拒否されます。要求が無効であることを示すエラー応答が表示されます。詳細については、「破壊的変更: 大文字と小文字の区別」を参照してください。

バージョン 2023-07-01

近日公開予定

Azure Compute Gallery の配布ターゲットの更新のサポート。

変更点

新しい errorHandling プロパティ。このプロパティを使用すると、イメージの構築プロセス中にエラーがどのように処理されるかをより詳細に制御できます。詳しくは、「errorHandling」をご覧ください。

バージョン 2022-07-01

機能強化

イメージテンプレートのソースとして Azure Compute Gallery に保存された最新のイメージバージョンを使用するための追加サポート
イメージディストリビューションのバージョン番号の生成をサポートするために versioning が追加されました。詳細については、プロパティ: バージョン管理に関するページを参照してください
Azure Compute Gallery に配布するときのリージョンごとの構成のサポートが追加されました。詳細については、配布: targetRegions に関するページを参照してください
新しい検証タイプ 'File' が追加されました。詳細については、プロパティの検証に関するページを参照してください
VHD をカスタムストレージアカウント内のカスタム BLOB またはコンテナーに配布できるようになりました。詳細については、配布: VHD に関するページを参照してください
イメージテンプレートのソースとして直接共有ギャラリーイメージを使用するためのサポートが追加されました

変更点

replicationRegions は、ギャラリーディストリビューションでは非推奨になりました。詳細については、gallery-replicated-regions を使用してください
VHD をカスタムストレージアカウント内のカスタム BLOB またはコンテナーに配布できるようになりました
targetRegions 配列が追加され、"SharedImage" 型の配布にのみ適用されるようになりました。 targetRegions の詳細については、Azure Compute Gallery に関するページを参照してください
イメージテンプレートのソースとして直接共有ギャラリーイメージを使用するためのサポートが追加されました。直接共有ギャラリーは現在、プレビュー段階です。
パブリックプレビューでトリガーを使用して、自動イメージビルドを設定できるようになりました。詳しくは、AIB トリガーの使用方法をご覧ください

バージョン 2022-02-14

機能強化

検証のサポート
- Shell (Linux): スクリプトまたはインライン
- PowerShell (Windows): スクリプトまたはインライン、管理者特権で実行、システムとして実行
- ソース検証専用モード
カスタマイズされたステージングリソースグループのサポート

バージョン 2021-10-01

重大な変更

API バージョン 2021-10-01 では、今後のすべての API リリースに含まれるエラースキーマが変更されています。 Azure VM Image Builder の自動化がある場合は、API バージョン 2021-10-01 以降に切り替えるとき、新しいエラー出力に注意してください。最新の API バージョンに切り替えたら、以前のエラースキーマを生成するために自動化をもう一度変更する必要があるため、以前のバージョンに戻さないことをお勧めします。今後のリリースでは、エラースキーマが再び変更されることを想定していません。

バージョン 2020-02-14 以前のエラー出力

{ 
  "code": "ValidationFailed",
  "message": "Validation failed: 'ImageTemplate.properties.source': Field 'imageId' has a bad value: '/subscriptions/subscriptionID/resourceGroups/resourceGroupName/providers/Microsoft.Compute/images/imageName'. Please review  http://aka.ms/azvmimagebuildertmplref  for details on fields requirements in the Image Builder Template." 
}

バージョン 2021-10-01 以降のエラー出力

{ 
  "error": {
    "code": "ValidationFailed", 
    "message": "Validation failed: 'ImageTemplate.properties.source': Field 'imageId' has a bad value: '/subscriptions/subscriptionID/resourceGroups/resourceGroupName/providers/Microsoft.Compute/images/imageName'. Please review  http://aka.ms/azvmimagebuildertmplref  for details on fields requirements in the Image Builder Template." 
  }
}

機能強化

ビルド VM MSI のサポートが追加されました。
プロキシ VM サイズのカスタマイズのサポートが追加されました。

バージョン 2020-02-14

機能強化

次のソースからイメージを作成するためのサポートが追加されました。
- マネージドイメージ
- Azure Compute Gallery
- プラットフォームイメージリポジトリ (プラットフォームイメージ購入プランを含む)
次のカスタマイズのサポートが追加されました。
- Shell (Linux): スクリプトまたはインライン
- PowerShell (Windows): スクリプトまたはインライン、管理者特権で実行、システムとして実行
- ファイル (Linux と Windows)
- Windows 再起動 (Windows)
- Windows Update (Windows): 検索基準、フィルター、更新上限
次のディストリビューションタイプのサポートが追加されました。
- VHD (仮想ハードディスク)
- マネージドイメージ
- Azure Compute Gallery
その他の機能:
- お客様が独自の仮想ネットワークを使用するためのサポートが追加されました
- ビルド VM (VM サイズ、オペレーティングシステムディスクサイズ) をカスタマイズするためのサポートが追加されました
- ユーザー割り当て Microsoft Windows インストーラー (MSI) のサポートが追加されました (カスタマイズ/配布手順用)
- Gen2 イメージのサポートが追加されました

プレビュー API

次の API は非推奨ですが、引き続きサポートされます。

バージョン 2019-05-01-プレビュー

次のステップ

VM Image Builder の詳細を確認します。

次の方法で共有

Azure VM Image Builder の新機能

更新プログラム

2024 年 5 月

破壊的変更: 大文字と小文字の区別

以前の Azure Image Builder API バージョンにピン留めする方法

2023 年 11 月

2023 年 4 月

API リリース

バージョン 2024-02-01

バージョン 2023-07-01

バージョン 2022-07-01

バージョン 2022-02-14

バージョン 2021-10-01

バージョン 2020-02-14 以前のエラー出力

バージョン 2021-10-01 以降のエラー出力

バージョン 2020-02-14

プレビュー API

次のステップ

フィードバック

フィードバック

その他のリソース