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

The following README will guide you on how to deploy a local Ubuntu 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.15.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
    az ad sp create-for-rbac -n "<Unique SP Name>" --role contributor

    For example:

    az ad sp create-for-rbac -n "http://AzureArcServers" --role contributor

    Output should look like this:

    "displayName": "AzureArcServers",
    "name": "http://AzureArcServers",

    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

  • The Vagrantfile executes a script on the VM OS to install all the needed artifacts as well to inject environment variables. Edit the scripts/ shell 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 Ubuntu 16.04 image file Vagrant Box
  2. Execute the installation script

After editing the scripts/ 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 Ubuntu box for the first time.

Screenshot of vagrant up being run

Once the download is complete, the actual provisioning will start. As you can see in the screenshot below, the process takes no longer than 3 minutes.

Screenshot of completed vagrant up

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

Screenshot of Azure portal showing Azure Arc-enabled server

Screenshot of 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 run

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

  • In the install_arc_agent shell 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 azcmagent connect command

    Screenshot of the az group create command

  • SSH the VM using the vagrant ssh command.

    Screenshot of of SSH to the Vagrant machine

  • Run the same azcmagent connect command you’ve just commented out using your environment variables.

    Screenshot of the azcmagent connect

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 a script 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