Azure VM Image Builder: Isolated Builds & BYO ACI Subnet documentation

Author: sumit-kalra

articles/virtual-machines/TOC.yml

@@ -687,7 +687,7 @@
           href: ./windows/image-builder-virtual-desktop.md
       - name: Security
         items:
-        - name: Security mechanisms
+        - name: Isolated image builds
           displayName: Image builder, images, building
           href: ./security-isolated-image-builds-image-builder.md
         - name: Security controls by Azure Policy

articles/virtual-machines/image-builder-best-practices.md

@@ -20,6 +20,7 @@ This article describes best practices to be followed while using Azure VM Image
 - Make sure your image templates are set up for disaster recovery by following [reliability recommendation for AIB](../reliability/reliability-image-builder.md?toc=/azure/virtual-machines/toc.json&bc=/azure/virtual-machines/breadcrumb/toc.json).
 - Set up AIB [triggers](image-builder-triggers-how-to.md) to automatically rebuild your images and keep them updated.
 - Enable [VM Boot Optimization](vm-boot-optimization.md) in AIB to improve the create time for your VMs.
+- Specify your own Build VM and ACI subnets for a tighter control over deployment of networking related resource by AIB in your subscription. Specifying both these subnets also leads to faster image build times. See [template reference](./linux/image-builder-json.md#vnetconfig-optional) to learn more about specifying these options.
 - Follow the [principle of least privilege](/entra/identity-platform/secure-least-privileged-access) for your AIB resources.
   - **Image Template**: A principal that has access to your image template is able to run, delete, or tamper with it. Having this access, in turn, allows the principal to change the images created by that image template.
   - **Staging Resource Group**: AIB uses a staging resource group in your subscription to customize your VM image. You must consider this resource group as sensitive and restrict access to this resource group only to required principals. Since the process of customizing your image takes place in this resource group, a principal with access to the resource group is able to compromise the image building process - for example, by injecting malware into the image. AIB also delegates privileges associated with the Template identity and Build VM identity to resources in this resource group. Hence, a principal with access to the resource group is able to get access to these identities. Further, AIB maintains a copy of your customizer artifacts in this resource group. Hence, a principal with access to the resource group is able to inspect these copies.

articles/virtual-machines/linux/image-builder-json.md

@@ -44,7 +44,8 @@ The basic format is:
       "vmSize": "<vmSize>",
       "osDiskSizeGB": <sizeInGB>,
       "vnetConfig": {
-        "subnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName>",
+        "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": [
@@ -80,7 +81,8 @@ resource azureImageBuilder 'Microsoft.VirtualMachineImages/imageTemplates@2022-0
       vmSize: '<vmSize>'
       osDiskSizeGB: <sizeInGB>
       vnetConfig: {
-        subnetId: '/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName>'
+        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: [
@@ -1704,18 +1706,41 @@ If you don't specify any VNet properties, Image Builder creates its own VNet, Pu
 
 ```json
 "vnetConfig": {
-  "subnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName>"
+  "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>"
 }
 ```
 
 # [Bicep](#tab/bicep)
 
 ```bicep
 vnetConfig: {
-  subnetId: '/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName>'
+  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
+Resource id of a pre-existing subnet on which the build VM and validation VM will be deployed.
+
+#### containerInstanceSubnetId (optional)
+Resource id of a pre-existing subnet on which Azure Container Instance (ACI) will be deployed for [Isolated Builds](../security-isolated-image-builds-image-builder.md). This property is only available in API versions `2024-02-01` or newer though existing templates created using earlier API versions can be updated to specify this property.
+
+This field may be specified only if `subnetId` is also specified and must meet the following requirements:
+- It must not be the same subnet as the one specified in `subnetId`.
+- It must be on the same Virtual Network as the subnet specified in `subnetId`.
+- There must be a network path from the ACI subnet to the Build VM subnet. This is required so that the container instance running in the ACI can connect to the Build VM over ssh/WinRM to perform customizations & validations. Specifically, if there are Network Security Groups (NSGs) associated with the ACI and Build VM subnets then they must allow access from the ACI subnet to the Build VM subnet on port 5986 (for Windows) or port 22 (for Linux).
+- This subnet needs to be delegated to the ACI service so that it can be used to deploy ACI resources . This can be achieved in one of the two ways:
+  - You manage the delegation: The subnet must be delegated to ACI and must contain no resources (or only other ACI resources).
+  - AIB manages the delegation: The subnet must not be delegated to any service and must contain no resources.
+
+You can read more about subnet delegation for Azure services [here](../../virtual-network/manage-subnet-delegation.md). ACI specific subnet delegation information is available [here](../../container-instances/container-instances-virtual-network-concepts.md).
+
+#### proxyVmSize (optional)
+Size of the proxy virtual machine used to pass traffic to the build VM and validation VM. This must not be specified if `containerInstanceSubnetId` is specified because no proxy virtual machine is deployed in that case. Omit or specify empty string to use the default (Standard_A1_v2).
+
 ---
 
 ## Image Template Operations

articles/virtual-machines/linux/image-builder-troubleshoot.md

@@ -22,7 +22,7 @@ Use this article to troubleshoot and resolve common issues that you might encoun
 When you're creating a build, do the following:
 
 - The VM Image Builder service communicates to the build VM by using WinRM or Secure Shell (SSH). Don't* disable these settings as part of the build.
-- VM Image Builder creates resources in the staging resource group as part of the builds. Be sure to verify that Azure Policy doesn't prevent VM Image Builder from creating or using necessary resources.
+- VM Image Builder creates resources in the staging resource group as part of the builds. The exact list of resources depends on the [networking configuration](./image-builder-json.md#vnetconfig-optional) specified in the image template.  Be sure to verify that Azure Policy doesn't prevent VM Image Builder from creating or using necessary resources.
   - Create an IT_ resource group.
   - Create a storage account without a firewall.
   - Deploy [Azure Container Instances](../../container-instances/container-instances-overview.md).
@@ -800,7 +800,7 @@ Azure Image Builder builds can fail for reasons listed elsewhere in this documen
 
 #### Solution
 If you determine that a build is failing due to Isolated Image Builds, you can do the following:
-- Ensure there's no [Azure Policy](../../governance/policy/overview.md) blocking the deployment of resources mentioned in the Prerequisites section, specifically Azure Container Instances, Azure Virtual Networks, and Azure Private Endpoints.
+- Ensure there's no [Azure Policy](../../governance/policy/overview.md) blocking the deployment of resources mentioned in the [Prerequisites section](./image-builder-troubleshoot.md#prerequisites), specifically Azure Container Instances.
 - Ensure your subscription has sufficient quota of Azure Container Instances to support all your concurrent image builds. For more information, see, Azure Container Instances [quota exceeded](./image-builder-troubleshoot.md#azure-container-instances-quota-exceeded).
 
 Azure Image Builder is currently in the process of deploying Isolated Image Builds. Specific image templates are not tied to Isolated Image Builds and the same image template might or might not utilize Isolated Image Builds during different builds. You can do the following to temporarily run your build without Isolated Image Builds.