Deploy a local Windows server hosted with Vagrant and connect it to Azure Arc

The following Jumpstart scenario will guide you on how to deploy a local Windows 10 virtual machine using Vagrant and connect it as an Azure Arc-enabled server resource.


  • Clone the Azure Arc Jumpstart repository

    git clone
  • Install or update Azure CLI to version 2.36.0 and above. Use the below command to check your current installed version.

    az --version
  • Vagrant relies on an underlying hypervisor. For the purpose of this guide, we will be using “Oracle VM VirtualBox”.

    • Install VirtualBox.

      • If you are an OSX user, simply run brew cask install virtualbox
      • If you are a Windows user, you can use the Chocolatey package
      • If you are a Linux user, all package installation methods can be found here
    • Install Vagrant

      • If you are an OSX user, simply run brew cask install vagrant
      • If you are a Windows user, you can use the Chocolatey package
      • If you are a Linux user, look here
  • Create Azure service principal (SP)

    To connect the Vagrant virtual machine to Azure Arc, an Azure service principal assigned with the “Contributor” role is required. To create it, login to your Azure account run the below command (this can also be done in Azure Cloud Shell).

    az login
    subscriptionId=$(az account show --query id --output tsv)
    az ad sp create-for-rbac -n "<Unique SP Name>" --role "Contributor" --scopes /subscriptions/$subscriptionId

    For example:

    az login
    subscriptionId=$(az account show --query id --output tsv)
    az ad sp create-for-rbac -n "JumpstartArc" --role "Contributor" --scopes /subscriptions/$subscriptionId

    Output should look like this:

    "displayName": "JumpstartArc",

    NOTE: If you create multiple subsequent role assignments on the same service principal, your client secret (password) will be destroyed and recreated each time. Therefore, make sure you grab the correct password.

    NOTE: The Jumpstart scenarios are designed with as much ease of use in-mind and adhering to security-related best practices whenever possible. It is optional but highly recommended to scope the service principal to a specific Azure subscription and resource group as well considering using a less privileged service principal account

  • Azure Arc-enabled servers depends on the following Azure resource providers in your subscription in order to use this service. Registration is an asynchronous process, and registration may take approximately 10 minutes.

    • Microsoft.HybridCompute

    • Microsoft.GuestConfiguration

    • Microsoft.HybridConnectivity

      az provider register --namespace 'Microsoft.HybridCompute'
      az provider register --namespace 'Microsoft.GuestConfiguration'
      az provider register --namespace 'Microsoft.HybridConnectivity'

      You can monitor the registration process with the following commands:

      az provider show --namespace 'Microsoft.HybridCompute'
      az provider show --namespace 'Microsoft.GuestConfiguration'
      az provider show --namespace 'Microsoft.HybridConnectivity'
  • The Vagrantfile executes a script on the VM OS to install all the needed artifacts as well to inject environment variables. Edit the scripts/vars.ps1 PowerShell script to match the Azure service principal you’ve just created.

    • subscriptionId=Your Azure subscription ID
    • appId=Your Azure service principal name
    • password=Your Azure service principal password
    • tenantId=Your Azure tenant ID
    • resourceGroup=Azure resource group name
    • location=Azure region


Like any Vagrant deployment, a Vagrantfile and a Vagrant Box is needed. At a high-level, the deployment will:

  1. Download the Windows 10 image file Vagrant Box
  2. Execute the Arc installation script

After editing the scripts/vars.ps1 script to match your environment, from the Vagrantfile folder, run vagrant up. As this is the first time you are creating the VM, the first run will be much slower than the ones to follow. This is because the deployment is downloading the Windows 10 box for the first time.

Screenshot of running vagrant up

Once the download is complete, the actual provisioning will start. As you can see in the screenshot below, the process takes can take somewhere between 7 to 10 minutes.

Screenshot of completed vagrant up

Upon completion, you will have a local Windows 10 VM deployed, connected as a new Azure Arc-enabled server inside a new resource group.

Screenshot of the Azure portal showing Azure Arc-enabled server

Screenshot of the Azure portal showing Azure Arc-enabled server detail

Semi-Automated Deployment (Optional)

As you may noticed, the last step of the run is to register the VM as a new Azure Arc-enabled server resource.

Screenshot of vagrant up being completed

In a case you want to demo/control the actual registration process, to the following:

  • In the install_arc_agent PowerShell script, comment out the “Run connect command” section and save the file. You can also comment out or change the creation of the resource group.

    Screenshot of the install_arc_agent PowerShell script

    Screenshot of az group create being run

  • RDP the VM using the vagrant rdp command. Use vagrant/vagrant as the username/password.

    Screenshot of RDP into a Vagrant server

  • Open PowerShell ISE as Administrator and edit the *C:\runtime\vars.ps1- with your environment variables.

    Screenshot of PowerShell ISE

  • Paste the Invoke-Expression "C:\runtime\vars.ps1" commmand, the az group create --location $env:location --name $env:resourceGroup --subscription $env:subscriptionId command and the same azcmagent connect command you’ve just commented and execute the script.

    Screenshot of PowerShell ISE running a script

Delete the deployment

To delete the entire deployment, run the vagrant destroy -f command. The Vagrantfile includes a before: destroy Vagrant trigger which will run the command to delete the Azure resource group before destroying the actual VM. That way, you will be starting fresh next time.

Screenshot of vagrant destroy being run