Merge pull request #273421 from kof-f/patch-67

American-Dipper · web-flow · commit 2e905314b044 · 2024-05-10T14:17:14.000-07:00
Breaking Change AIB API Version 2024-02-01 Documentation Update
diff --git a/articles/virtual-machines/image-builder-api-update-release-notes.md b/articles/virtual-machines/image-builder-api-update-release-notes.md
@@ -18,6 +18,93 @@ This article contains all major API changes and feature updates for the Azure VM
 
 ## Updates
 
+### May 2024
+#### Breaking Change: Case Sensitivity
+
+Starting from May 21, 2024, Azure VM Image Builder's API version 2024-02-01 and beyond will enforce case sensitivity for all fields. This means that the capitalization of letters in your API requests must match exactly with the expected format. 
+
+> **Important Note for Existing Azure Image Builder Users**
+>
+> If you're an existing user of Azure VM Image Builder, rest assured that this change will **not** impact your existing resources. The case sensitivity enforcement applies only to **newly created resources** using **API version 2024-02-01 and beyond**. Your existing resources will continue to function as expected without any changes.
+>
+> If you encounter any issues related to case sensitivity, please refer to Azure Image Builder's updated API documentation for guidance.
+
+Previously, Azure Image Builder's API was more forgiving in terms of case, but moving forward, precision is crucial. When making API calls, ensure that you use the correct capitalization for field names, parameters, and values. For example, if a field is named “vmBoot,” you must use “vmBoot” (not “VMBoot” or “vmboot”).
+
+If you send an API request to Azure Image Builder's API version 2024-02-01 and beyond with incorrect case or unrecognized fields, the service will reject it. You will receive an error response indicating that the request is invalid. The error will look something like this:
+
+`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.`
+
+The error message will mention an "unknown field" and direct you to the official documentation: [Create an Azure Image Builder Bicep or ARM template JSON template](./linux/image-builder-json.md).
+
+> **Reference Azure Image Builder's Swagger for API Calls**
+> 
+> When making calls to the Azure Image Builder service, always reference the [Swagger documentation](https://github.com/Azure/azure-rest-api-specs/tree/main/specification/imagebuilder/resource-manager/Microsoft.VirtualMachineImages/stable), which serves as the definitive source of truth for Azure Image Builder's API specifications. While the public documentation has been updated to include the proper capitalization and field names ahead of the API release, the Swagger definition contains precise details about each AIB API to ensure you are making calls to the service correctly.
+
+Below is a list of the documentation changes that were made to match the field names in API version 2024-02-01:
+
+In the [Create an Azure Image Builder Bicep or ARM template JSON template](./linux/image-builder-json.md) documentation:
+
+**Fields Updated:**
+
+- Replaced several mentions of `vmboot` with `vmBoot`
+- Replaced one mention of `imageVersionID` with `imageVersionId`
+
+**Field Removed:**
+
+- `apiVersion`: We recommend avoiding the inclusion of this field in your requests because it is not explicitly specified in our API, so including it in your JSON template _may_ lead to errors in your image build.
+
+In the [Azure VM Image Builder networking options](./linux/image-builder-networking.md) documentation:
+
+**Field Updated:**
+
+- Replaced one mention of `VirtualNetworkConfig` with `vnetConfig`
+
+**Fields Removed:**
+
+- `subnetName` in the `vnetConfig` property – this field is deprecated and the new field is `subnetId`
+- `resourceGroupName` in the `vnetConfig` property – this field is deprecated and the new field is `subnetId`
+
+#### How to Pin to an Older Azure Image Builder API Version
+
+> **Important Consideration for Pinning to Older API Versions**
+>
+> Pinning to an older Azure Image Builder API version can provide compatibility with your existing templates, but it's not recommended due to the following factors:
+>
+> - Deprecation Risk: Older API versions may eventually be deprecated.
+>
+> - Missing Features: By pinning to an older API version, you miss out on the latest features and improvements introduced in newer versions. These enhancements often improve performance, security, and functionality.
+
+If you’d like to avoid making changes to the properties in your image templates due to the new case sensitivity rules, you have the option to pin your Azure VM Image Builder API calls to a previous API version. This allows you to continue using the familiar behavior without any modifications.
+
+To ensure compatibility with your existing templates, when creating or updating an image template, specify the desired API version (e.g., api-version=2022-07-01) by including the `api-version` parameter in your call to the service. Example:
+
+# [HTTP](#tab/http)
+```http
+PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.VirtualMachineImages/imageTemplates/{imageTemplateName}?api-version=2022-07-01
+```
+
+# [Azure CLI](#tab/-interactive)
+
+```azurecli-interactive
+az resource create \
+    --api-version=2022-07-01 \
+    --resource-group <resourceGroupName> \
+    --properties <jsonResource> \
+    --is-full-object \
+    --resource-type Microsoft.VirtualMachineImages/imageTemplates \
+    -n <imageTemplateName>
+```
+
+# [Azure PowerShell](#tab/azurepowershell-interactive)
+
+```azurepowershell-interactive
+New-AzResourceGroupDeployment -ResourceGroupName <resourceGroupName> -TemplateFile <templateFilePath> -TemplateParameterObject @{"api-version" = "2022-07-01"; "imageTemplateName" = <imageTemplateName>; "svclocation" = <location>}
+```
+> **Test Your Code**
+>
+> After pinning to the older API version, test your code to verify that it behaves as expected. Ensure that your existing templates continue to function correctly.
+
 ### November 2023
 Azure Image Builder is enabling Isolated Image Builds using Azure Container Instances in a phased manner. The rollout is expected to be completed by early 2024. Your existing image templates will continue to work and there is no change in the way you create or build new image templates. 
 
diff --git a/articles/virtual-machines/linux/image-builder-json.md b/articles/virtual-machines/linux/image-builder-json.md
@@ -24,7 +24,6 @@ The basic format is:
 ```json
 {
   "type": "Microsoft.VirtualMachineImages/imageTemplates",
-  "apiVersion": "2022-02-14",
   "location": "<region>",
   "tags": {
     "<name>": "<value>",
@@ -98,16 +97,16 @@ resource azureImageBuilder 'Microsoft.VirtualMachineImages/imageTemplates@2022-0
 ```
 
 ---
+## API version
+The API version will change over time as the API changes. See [What's new in Azure VM Image Builder](../image-builder-api-update-release-notes.md) for all major API changes and feature updates for the Azure VM Image Builder service.
 
-## Type and API version
-
-The `type` is the resource type, which must be `Microsoft.VirtualMachineImages/imageTemplates`. The `apiVersion` will change over time as the API changes. See [What's new in Azure VM Image Builder](../image-builder-api-update-release-notes.md) for all major API changes and feature updates for the Azure VM Image Builder service.
+## Type
+The `type` is the resource type, which must be `Microsoft.VirtualMachineImages/imageTemplates`. 
 
 # [JSON](#tab/json)
 
 ```json
 "type": "Microsoft.VirtualMachineImages/imageTemplates",
-"apiVersion": "2022-02-14",
 ```
 
 # [Bicep](#tab/bicep)
@@ -852,8 +851,8 @@ 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
+  --ids "/subscriptions/$subscriptionID/resourcegroups/$imageResourceGroup/providers/Microsoft.VirtualMachineImages/imageTemplates/ImageTemplateLinuxRHEL77/runOutputs/$runOutputName" \
+--api-version=2023-07-01
 ```
 
 Output:
@@ -1207,7 +1206,7 @@ The `optimize` property can be enabled while creating a VM image and allows VM o
 
 ```json
 "optimize": {
-      "vmboot": {
+      "vmBoot": {
         "state": "Enabled"
       }
     }
@@ -1217,15 +1216,15 @@ The `optimize` property can be enabled while creating a VM image and allows VM o
 
 ```bicep
 optimize: {
-      vmboot: {
+      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: The state of the boot optimization feature within `vmboot`, with the value `Enabled` indicating that the feature is turned on to improve image creation time.
+- **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: The state of the boot optimization feature within `vmBoot`, with the value `Enabled` indicating that the feature is turned on to improve image creation time.
 
 To learn more, see [VM optimization for gallery images with Azure VM Image Builder](../vm-boot-optimization.md).
 
@@ -1361,7 +1360,7 @@ Sets the source image as an existing image version in an Azure Compute Gallery.
 ```json
 "source": {
   "type": "SharedImageVersion",
-  "imageVersionID": "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>/providers/Microsoft.Compute/galleries/<sharedImageGalleryName>/images/<imageDefinitionName/versions/<imageVersion>"
+  "imageVersionId": "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>/providers/Microsoft.Compute/galleries/<sharedImageGalleryName>/images/<imageDefinitionName/versions/<imageVersion>"
 }
 ```
 
@@ -1755,7 +1754,7 @@ Size of the proxy virtual machine used to pass traffic to the build VM and valid
 To start a build, you need to invoke 'Run' on the Image Template resource, examples of `run` commands:
 
 ```azurepowershell-interactive
-Invoke-AzResourceAction -ResourceName $imageTemplateName -ResourceGroupName $imageResourceGroup -ResourceType Microsoft.VirtualMachineImages/imageTemplates -ApiVersion "2021-10-01" -Action Run -Force
+Invoke-AzResourceAction -ResourceName $imageTemplateName -ResourceGroupName $imageResourceGroup -ResourceType Microsoft.VirtualMachineImages/imageTemplates -ApiVersion "2023-07-01" -Action Run -Force
 ```
 
 ```azurecli-interactive
@@ -1775,7 +1774,7 @@ The build can be canceled anytime. If the distribution phase has started you can
 Examples of `cancel` commands:
 
 ```azurepowershell-interactive
-Invoke-AzResourceAction -ResourceName $imageTemplateName -ResourceGroupName $imageResourceGroup -ResourceType Microsoft.VirtualMachineImages/imageTemplates -ApiVersion "2021-10-01" -Action Cancel -Force
+Invoke-AzResourceAction -ResourceName $imageTemplateName -ResourceGroupName $imageResourceGroup -ResourceType Microsoft.VirtualMachineImages/imageTemplates -ApiVersion "2023-07-01" -Action Cancel -Force
 ```
 
 ```azurecli-interactive
diff --git a/articles/virtual-machines/linux/image-builder-networking.md b/articles/virtual-machines/linux/image-builder-networking.md
@@ -58,18 +58,14 @@ The deployed proxy VM size is *Standard A1_v2*, in addition to the build VM. The
 ### Image template parameters to support the virtual network
 
 ```json
-"VirtualNetworkConfig": {
-        "name": "",
-        "subnetName": "",
-        "resourceGroupName": ""
+"vnetConfig": {
+        "subnetId": ""
         },
 ```
 
 | Setting | Description |
 |---------|---------|
-| `name` | (Optional) The name of a pre-existing virtual network. |
-| `subnetName` | The name of the subnet within the specified virtual network. You must specify this setting if, and only if, the `name` setting is specified. |
-| `resourceGroupName` | The name of the resource group containing the specified virtual network. You must specify this setting if, and only if, the `name` setting is specified. |
+| `subnetId` | Resource ID of a pre-existing subnet on which the build VM and validation VM is deployed. |
 
 Private Link requires an IP from the specified virtual network and subnet. Currently, Azure doesn’t support network policies on these IPs. Hence, you must disable network policies on the subnet. For more information, see the [Private Link documentation](../../private-link/index.yml).
 
