Create Azure Local virtual machines enabled by Azure Arc for multi-rack deployments (preview)

• Access to an Azure subscription with the appropriate RBAC role and permissions assigned. For more information, see RBAC roles for Azure Local VM management.
• Access to a resource group where you want to provision the VM.
• Access to one or more VM images on your Azure Local. These VM images could be created using VM image starting from an image in Azure Storage account.

  Note

  If you’re deploying a Windows VM, make sure that the appropriate VirtIO drivers are present in the image.

• A custom location for your Azure Local instance that you'll use to provision VMs. The custom location will also show up in the Overview page for Azure Local.
• If using a client to connect to your Azure Local, see Connect to Azure Local via Azure CLI client.
• Access to a network interface that you created on a logical network or virtual network subnet associated with Azure Local. You can choose a network interface with static IP allocation. For more information, see how to Create network interfaces.
• Details of your proxy server to provide during VM creation. Azure Local VMs wouldn't have external connectivity to enable guest management without proxy details configured at the time of creation.

• Access to an Azure subscription with the appropriate RBAC role and permissions assigned. For more information, see RBAC roles for Azure Local VM management.
• Access to a resource group where you want to provision the VM.
• Access to one or more VM images on your Azure Local.

  Note

  If you’re deploying a Windows VM, make sure that the appropriate VirtIO drivers are present in the image.

• A custom location for your Azure Local instance that you'll use to provision VMs. The custom location will also show up in the Overview page for Azure Local.
• Details of your proxy server to provide during VM creation. Azure Local VMs wouldn't have external connectivity to enable guest management without proxy details configured at the time of creation.

• Access to an Azure subscription with the appropriate RBAC role and permissions assigned. For more information, see RBAC roles for Azure Local VM management.
• Access to a resource group where you want to provision the VM.
• Access to one or more VM images on your Azure Local. These VM images could be created using VM image starting from an image in Azure Storage account.
• A custom location for your Azure Local instance that you'll use to provision VMs. The custom location will also show up in the Overview page for Azure Local.
• Access to a logical network or virtual network subnet that you associate with the VM on your Azure Local instance. For more information, see how to Create logical network.
• Details of your proxy server to provide during VM creation. Azure Local VMs wouldn't have external connectivity to enable guest management without proxy details configured at the time of creation.

Follow these steps on the client running az CLI that is connected to Azure Local.

Sign in and set subscription

1. Connect to a machine on Azure Local.

2. Sign in. Type:

   az login --use-device-code
   

3. Set your subscription.

   az account set --subscription <Subscription ID>
   

Create a Windows VM

Here we create a VM that uses specific memory and processor counts.

1. Set some parameters.

   $vmName ="local-vm"
   $subscription =  "<Subscription ID>"
   $resource_group = "local-rg"
   $customLocationName = "local-cl"
   $customLocationID ="/subscriptions/$subscription/resourceGroups/$resource_group/providers/Microsoft.ExtendedLocation/customLocations/$customLocationName"
   $location = "eastus"
   $computerName = "mycomputer"
   $userName = "local-user"
   $password = "<Password for the VM>"
   $imageName = "/subscriptions/$subscription/resourceGroups/$resource_group/providers/Microsoft.AzureStackHCI/galleryImages/ws22server"
   $nicName ="local-vnic" 
   $httpProxy = "<Proxy server address>"
   $httpsProxy = "<Proxy server address>"
   

   The parameters for VM creation are tabulated as follows:

   Parameters	Description
   name	Name for the VM that you create for Azure Local. Make sure to provide a name that follows the Rules for Azure resources.
   admin-username	Username for the user on the VM you're deploying on Azure Local.
   admin-password	Password for the user on the VM you're deploying on Azure Local.
   image-name	ARM resource ID of the VM image used for provisioning. The VM image may reside in a different subscription and resource group than the target VM.
   location	Azure regions as specified by az locations. For example, this could be eastus, westeurope.
   resource-group	Name of the resource group where you create the VM. For ease of management, we recommend that you use the same resource group as Azure Local.
   subscription	Name or ID of the subscription where your Azure Local is deployed. This could be another subscription you use for VM on Azure Local.
   custom-location	Use this to provide the custom location associated with Azure Local where you're creating this VM.
   authentication-type	Type of authentication to use with the VM. The accepted values are all, password, and ssh. Default is password for Windows and SSH public key for Linux. Use all to enable both ssh and password authentication.
   nics	Names or the IDs of the network interfaces associated with your VM. You must have atleast one network interface when you create a VM, to enable guest management.
   memory-mb	Memory in Megabytes allocated to your VM. If not specified, defaults are used.
   processors	The number of processors allocated to your VM. If not specified, defaults are used.
   proxy-configuration	Use this parameter to configure a proxy server for your VM. It is required to enable guest management on your VM. For more information, see Create a VM with proxy configured.
   zone	(Optional) Name of the availability zone (rack) where you want the VM to be placed.
   strict-placement	(Optional) Choose strict placement if you have specified a zone and want the VM to only be scheduled on the specified availability zone. If the specified zone doesn’t have capacity or is unavailable, VM creation will fail. If you specify no for this parameter, the VM will be scheduled on the specified zone on a best-effort basis.

2. Run the following commands to create the applicable VM.

   To create a standard Azure Local VM for multi-rack deployments:

    az stack-hci-vm create --name $vmName --resource-group $resource_group --admin-username $userName --admin-password $password --computer-name $computerName --image $imageName --location $location --authentication-type all --nics $nicName --custom-location $customLocationID --hardware-profile memory-mb="8192" processors="4" --zone $zone –-strict-placement true --enable-agent true --enable-vm-config-agent true --proxy-configuration http_proxy=$httpProxy https_proxy=$httpsProxy no_proxy="" cert_file_path="" 
   

The VM is successfully created when the provisioningState shows as succeededin the output.

Create a Linux VM

To create a Linux VM, use the same command that you used to create the Windows VM.

• The gallery image specified should be a Linux image.
• For Linux VMs, we recommend using SSH keys. For SSH keys, you need to pass the ssh-key-values parameters along with authentication-type ssh. If you are using an existing key, ensure that the public key is in OpenSSH format.
• If you want to use username and password, use the authentication-type password parameter.

Create a VM with proxy configured

Use this parameter proxy-configuration to configure a proxy server for your VM.

Proxy configuration for VMs is applied only to the onboarding of the Azure connected machine agent and set as environment variables within the guest VM operating system. Browsers and applications on the VM aren't necessarily all enabled with this proxy configuration.

As such, you may need to specifically set the proxy configuration for your applications if they don't reference the environment variables set within the VM.

If creating a VM behind a proxy server, run the following command:

az stack-hci-vm create --name $vmName --resource-group $resource_group --admin-username $userName --admin-password $password --computer-name $computerName --image $imageName --location $location --authentication-type all --nics $nicName --custom-location $customLocationID --hardware-profile memory-mb="8192" processors="4" --zone $zone –-strict-placement true --enable-agent true --enable-vm-config-agent true --proxy-configuration http_proxy="<Http URL of proxy server>" https_proxy="<Https URL of proxy server>" no_proxy="<URLs which bypass proxy>" cert_file_path="<Certificate file path for your machine>"

You can input the following parameters for proxy-server-configuration:

Here's a sample command:

az stack-hci-vm create --name $vmName --resource-group $resource_group --admin-username $userName --admin-password $password --computer-name $computerName --image $imageName --location $location --authentication-type all --nics $nicName --custom-location $customLocationID --hardware-profile memory-mb="8192" processors="4" --proxy-configuration http_proxy="http://ubuntu:ubuntu@192.168.200.200:3128" https_proxy="http://ubuntu:ubuntu@192.168.200.200:3128" no_proxy="localhost,127.0.0.1,.svc,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,100.0.0.0/8,s-cluster.test.contoso.com" cert_file_path="C:\ClusterStorage\UserStorage_1\server.crt"

For proxy authentication, you can pass the username and password combined in a URL as follows:"http://username:password@proxyserver.contoso.com:3128".

Follow these steps in Azure portal for Azure Local.

1. Go to Azure Arc cluster view > Virtual machines.

2. From the top command bar, select + Create VM.

   

3. On the Basics tab, input the following parameters in the Project details section:

   

   1. Subscription – The subscription is tied to the billing. Choose the subscription that you want to use to deploy this VM.

   2. Resource group – Create new or choose an existing resource group where you deploy all the resources associated with your VM.

4. In the Instance details section, input the following parameters:

   

   1. Virtual machine name – Enter a name for your VM. The name should follow all the naming conventions for Azure virtual machines.

      Important

      VM names should be in lowercase letters and can include hyphens and numbers.

   2. custom-location – Select the custom location for your VM. The custom locations are filtered to only show those locations that are enabled for Azure Local.

      The Virtual machine kind is automatically set to Azure Local.

   3. Security type - Only Standard security type is supported and selected by default.

   4. Image - Select from the VM images you previously created on your Azure Local instance.

      • If you selected a Windows image, provide a username and password for the administrator account, and then confirm the password.

      • If you selected a Linux image, you can choose between password and ssh key.

        

   5. Virtual processor count – Specify the number of vCPUs you would like to use to create the VM.

   6. Memory – Specify the memory in MB for the VM you intend to create.

   7. Memory type – Only Static memory type is supported and selected by default.

   8. Availability Zone - Name of the availability zone (rack) where you want the VM to be placed.

   9. Strict placement - Choose strict placement if you want a VM to only be scheduled on the specified availability zone. If the specified zone doesn’t have capacity or is unavailable, VM creation will fail. If you specify no for this field, the VM will be scheduled on the specified zone on a best-effort basis.

5. In the VM extensions section, select the checkbox to enable guest management and input the following parameters. You can install extensions on VMs where the guest management is enabled.

   Note

   • Add at least one network interface through the Networking tab to complete guest management setup.
   • The network interface that you enable, must have a valid IP address and internet access by setting VM proxy.

6. In the VM proxy configuration section, to configure a proxy for your VM, input the following parameters:

   Note

   Proxy configuration for VMs is applied only to the onboarding of the Azure connected machine agent and set as environment variables within the guest VM operating system. Browsers and applications on the VM aren't necessarily all enabled with this proxy configuration. As such, you may need to specifically set the proxy configuration for your applications if they don't reference the environment variables set within the VM.

   • Http proxy - Provide an HTTP URL for the proxy server. An example URL is: http://proxy.example.com:3128.
   • Https proxy - Provide an HTTPS URL for the proxy server. The server may still use an HTTP address as shown in this example: http://proxy.example.com:3128.
   • No proxy - Specify URLs to bypass the proxy. Typical examples would be: localhost,127.0.0.1,.svc,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,100.0.0.0/8.
   • Certificate file - Select the certificate file used to establish trust with your proxy server.

   Note

   For proxy authentication, you can pass the username and password combined in a URL as follows: http://username:password@proxyserver.contoso.com:3128.

7. Set the local VM administrator account credentials used when connecting to your VM via RDP. For Windows VM, in the Administrator account section, input the following parameters:

   

   1. Specify the local VM administrator account username.
   2. Specify the password and then Confirm password.

8. If you selected a Windows VM image, you can domain join your Windows VM. In the Domain join section, input the following parameters:

   1. Select Enable domain join.

   2. Only the Active Directory domain join is supported and selected by default.

   3. Provide the UPN of an Active Directory user who has privileges to join the virtual machine to your domain.

      Important

      For your Active Directory, if your SAM Account Name and UPN are different, enter the SAM Account Name in the UPN field as: SAMAccountName@domain.

   4. Provide the domain administrator password. If using SAM Account Name in the UPN field, enter the corresponding password.

   5. Specify domain or organizational unit. You can join virtual machines to a specific domain or to an organizational unit (OU) and then provide the domain to join and the OU path.

      If the domain isn't specified, the suffix of the Active Directory domain join UPN is used by default. For example, the user guspinto@contoso.com would get the default domain name contoso.com.

      For Linux VM, provide root user details.

9. (Optional) Create new or add more disks to the VM.

   

   1. Select + Add new disk.
   2. Provide a Name and Size.
   3. Select Add. After it's created, you can see the new disk in the list view.

10. (Optional) Create or add a network interface for the VM.

    Note

    • If you enabled guest management, you must add at least one network interface.
    • If you need more than one network interface with static IPs for your VM, create one or more interfaces now before you create the VM. Adding a network interface with static IP, after the VM is provisioned, isn't supported.

    

    1. Provide a Name for the network interface.

    2. From the drop-down list, select the Network. Based on the logical network selected, you see the IPv4 type automatically populate as Static or DHCP.

    3. For Static IP, choose the Allocation method as Automatic or Manual. For Manual IP, provide an IP address.

       Note

       To create a VM with virtual network, use Azure CLI or ARM templates.

    4. Select Add.

11. (Optional) Add tags to the VM resource if necessary.

12. Review all the properties of the VM.

13. Select Create. It should take a few minutes to provision the VM.

Follow these steps to deploy the Resource Manager template:

1. In the Azure portal, from the top search bar, search for deploy a custom template. Select Deploy a custom template from the available options.

2. On the Select a template tab, select Build your own template in the editor.

3. You see a blank template.

4. Replace the blank template with the template that you downloaded during the prerequisites step. This template creates an Azure Local VM for multi-rack deployments. First, a virtual network interface is created. You can optionally enable domain-join and attach a virtual disk to the VM you create. Finally, the VM is created with the guest management enabled.

   {
       "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
       "contentVersion": "1.0.0.0",
       "parameters": {
           "name": {
               "type": "String",
               "metadata": {
                   "description": "The name of the Virtual Machine."
               }
           },
           "location": {
               "type": "String",
               "metadata": {
                   "description": "The Azure region where the resources will be deployed."
               }
           },
           "customLocationId": {
               "type": "String",
               "metadata": {
                   "description": "The custom location ID where the resources will be deployed."
               }
           },
           "adminUsername": {
               "type": "String",
               "metadata": {
                   "description": "The username for the administrator account of the VM."
               }
           },
           "adminPassword": {
               "type": "SecureString",
               "metadata": {
                   "description": "The password for the administrator account of the VM. This should be a secure string."
               }
           },
           "securityType": {
               "type": "String",
               "metadata": {
                   "description": "The type of security configuration for the VM."
               }
           },
           "vNicName": {
               "type": "String",
               "metadata": {
                   "description": "The name of the vNic."
               }
           },
           "privateIPAddress": {
               "type": "String",
               "metadata": {
                   "description": "The IP address for the network interface."
               }
           },
           "subnetId": {
               "type": "String",
               "metadata": {
                   "description": "The Azure Resource Manager ID of the logical network or virtual network subnet for the network interface."
               }
           },
           "vmSize": {
               "type": "String",
               "metadata": {
                   "description": "The size of the virtual machine instance. It is 'Default' by default."
               }
           },
           "enableVirtualDisk": {
               "type": "bool",
               "metadata": {
                   "description": "Enable or disable the virtual disk."
               }
           },
           "diskName": {
               "type": "String",
               "defaultValue": "",
               "metadata": {
                   "description": "The name of the virtual data disk for your VM. Required if enableVirtualDisk is true."
               }
           },
           "diskSize": {
               "type": "Int",
               "defaultValue": 0,
               "metadata": {
                   "description": "Specify the size of the additional virtual disk to be added to your VM. Required if enableVirtualDisk is true."
               }
           },
           "processors": {
               "type": "Int",
               "metadata": {
                   "description": "The number of processors for the virtual machine."
               }
           },
           "memoryMB": {
               "type": "Int",
               "metadata": {
                   "description": "The amount of memory in MB for the virtual machine."
               }
           },
           "imageReferenceId": {
               "type": "String",
               "metadata": {
                   "description": "The Azure Resource Manager ID of the image to be used for the virtual machine."
               }
           },
           "enableDomainJoin": {
               "type": "bool",
               "metadata": {
                   "description": "Enable or disable the domain join extension."
               }
           },
           "domainToJoin": {
               "type": "String",
               "defaultValue": "",
               "metadata": {
                   "description": "The domain to join. Required if enableDomainJoin is true."
               }
           },
           "orgUnitPath": {
               "type": "String",
               "defaultValue": "",
               "metadata": {
                   "description": "The Organizational Unit path. Optional, used if enableDomainJoin is true."
               }
           },
           "domainUsername": {
               "type": "String",
               "defaultValue": "",
               "metadata": {
                   "description": "The domain username. Required if enableDomainJoin is true."
               }
           },
           "domainPassword": {
               "type": "SecureString",
               "defaultValue": "",
               "metadata": {
                   "description": "The domain password. Required if enableDomainJoin is true."
               }
           }
       },
       "variables": {
           "domainJoinExtensionName": "[if(parameters('enableDomainJoin'), concat(parameters('name'),'/joindomain'), '')]",
           "virtualDiskName": "[if(parameters('enableVirtualDisk'), parameters('diskName'), '')]"
       },
       "resources": [
           {
               "type": "Microsoft.HybridCompute/machines",
               "apiVersion": "2023-03-15-preview",
               "name": "[parameters('name')]",
               "location": "[parameters('location')]",
               "kind": "HCI",
               "identity": {
                   "type": "SystemAssigned"
               }
           },
           {
               "condition": "[parameters('enableVirtualDisk')]",
               "type": "Microsoft.AzureStackHCI/virtualHardDisks",
               "apiVersion": "2025-09-01-preview",
               "name": "[variables('virtualDiskName')]",
               "location": "[parameters('location')]",
               "extendedLocation": {
                   "type": "CustomLocation",
                   "name": "[parameters('customLocationId')]"
               },
               "properties": {
                   "diskSizeGB": "[parameters('diskSize')]",
               }
           },
           {
               "type": "Microsoft.AzureStackHCI/networkInterfaces",
               "apiVersion": "2025-09-01-preview",
               "name": "[parameters('vNicName')]",
               "location": "[parameters('location')]",
               "extendedLocation": {
                   "type": "CustomLocation",
                   "name": "[parameters('customLocationId')]"
               },
               "properties": {
                   "ipConfigurations": [
                       {
                           "name": "[parameters('vNicName')]",
                           "properties": {
                               "privateIPAddress": "[parameters('privateIPAddress')]",
                               "subnet": {
                                   "id": "[parameters('subnetId')]"
                               }
                           }
                       }
                   ]
               }
           },
           {
               "type": "Microsoft.AzureStackHCI/VirtualMachineInstances",
               "apiVersion": "2023-09-01-preview",
               "name": "default",
               "extendedLocation": {
                   "type": "CustomLocation",
                   "name": "[parameters('customLocationId')]"            },
               "dependsOn": [
                   "[resourceId('Microsoft.HybridCompute/machines', parameters('name'))]",
                   "[resourceId('Microsoft.AzureStackHCI/networkInterfaces', parameters('vNicName'))]",
                   "[resourceid('Microsoft.AzureStackHCI/virtualHardDisks', parameters('diskName'))]"
               ],
               "properties": {
                   "osProfile": {
                       "adminUsername": "[parameters('adminUsername')]",
                       "adminPassword": "[parameters('adminPassword')]",
                       "computerName": "[parameters('name')]",
                       "windowsConfiguration": {
                           "provisionVMAgent": true,
                           "provisionVMConfigAgent": true
                       }
                   },
                   "hardwareProfile": {
                       "vmSize": "Default",
                       "processors": 4,
                       "memoryMB": 8192
                   },
                   "storageProfile": {
                       "imageReference": {
                           "id": "[parameters('imageReferenceId')]"
                       },
                       "dataDisks": [
                           {
                               "id": "[resourceid('Microsoft.AzureStackHCI/virtualHardDisks',parameters('diskName'))]"
                           }
                       ]
                   },
                    "httpProxyConfig": {
                       "httpProxy": "http://proxy.example.com:3128",
                       "httpsProxy": "http://proxy.example.com:3128"
                    },
                   "networkProfile": {
                       "networkInterfaces": [
                           {
                               "id": "[resourceId('Microsoft.AzureStackHCI/networkInterfaces', parameters('vNicName'))]"
                           }
                       ]
                   }
               },
               "scope": "[concat('Microsoft.HybridCompute/machines/', parameters('name'))]"
           },
           {
               "condition": "[parameters('enableDomainJoin')]",
               "type": "Microsoft.HybridCompute/machines/extensions",
               "apiVersion": "2023-03-15-preview",
               "name": "[variables('domainJoinExtensionName')]",
               "location": "[parameters('location')]",
               "dependsOn": [
                   "[concat(resourceId('Microsoft.HybridCompute/machines', parameters('name')), '/providers/Microsoft.AzureStackHCI/virtualmachineinstances/default')]"
               ],
               "properties": {
                   "publisher": "Microsoft.Compute",
                   "type": "JsonADDomainExtension",
                   "typeHandlerVersion": "1.3",
                   "autoUpgradeMinorVersion": true,
                   "settings": {
                       "Name": "[parameters('domainToJoin')]",
                       "OUPath": "[parameters('orgUnitPath')]",
                       "User": "[concat(parameters('domainToJoin'), '\\', parameters('domainUsername'))]",
                       "Restart": "true",
                       "Options": "3"
                   },
                   "protectedSettings": {
                       "Password": "[parameters('domainPassword')]"
                   }
               }
           }
       ]
   }
   

5. Select Save.

   

6. You see the blade for providing deployment values. Again, select the resource group. You can use the other default values. When you're done providing values, select Review + create

   

7. After the portal validates the template, select Create. A deployment job should start.

   

8. When the deployment completes, you see the status of the deployment as complete. After the deployment has successfully completed, a VM is created.