Jumpstart ArcBox - Overview

ArcBox is a project that provides an easy to deploy sandbox for all things Azure Arc. ArcBox is designed to be completely self-contained within a single Azure subscription and resource group, which will make it easy for a user to get hands-on with all available Azure Arc technology with nothing more than an available Azure subscription.

ArcBox architecture diagram

Use cases

  • Sandbox environment for getting hands-on with Azure Arc technologies
  • Accelerator for Proof-of-concepts or pilots
  • Training tool for Azure Arc skills development
  • Demo environment for customer presentations or events
  • Rapid integration testing platform

Azure Arc capabilities available in ArcBox

Azure Arc enabled Servers

ArcBox servers diagram

ArcBox includes three Azure Arc enabled server resources that are hosted using nested virtualization in Azure. As part of the deployment, a Hyper-V host (ArcBox-Client) is deployed with three guest virtual machines. These machines, ArcBoxWin, ArcBoxUbuntu, and ArcBoxSQL are connected as Azure Arc enabled servers via the ArcBox automation.

Azure Arc enabled Kubernetes

ArcBox Kubernetes diagram

ArcBox deploys one single-node Rancher K3s cluster running on an Azure virtual machine. This cluster is then connected to Azure as an Azure Arc enabled Kubernetes resource (ArcBox-K3s).

Azure Arc enabled Data Services

ArcBox deploys one single-node Rancher K3s cluster (ArcBox-CAPI-MGMT), which is then transformed to a Cluster API management cluster with the Azure CAPZ provider, and a workload cluster is deployed onto the management cluster. The Azure Arc enabled data services and data controller are deployed onto this workload cluster via a PowerShell script that runs when first logging into ArcBox-Client virtual machine.

ArcBox data services diagram

Hybrid Unified Operations

ArcBox deploys several management and operations services that work with ArcBox’s Azure Arc resources. These resources include an an Azure Automation account, an Azure Log Analytics workspace with the Update Management solution, Azure Policy assignments for deploying Log Analytics agents on Windows and Linux, Azure Policy assignment for adding tags to resources, and a storage account used for staging resources needed for the deployment automation.

ArcBox unified operations diagram

Automation flow

Deployment flow diagram

ArcBox uses an advanced automation flow to deploy and configure all necessary resources with minimal user interaction. The above diagram provides a high-level overview of the deployment flow. A high-level summary of the deployment is:

  • User deploys the primary ARM template (azuredeploy.json). This template contains several nested templates that will run simultaneously.
    • ClientVM ARM template - deploys the Client Windows VM. This is the Hyper-V host VM where all user interactions with the environment are made from.
    • CAPI ARM template - deploys an Ubuntu Linux VM which will have Rancher (K3s) installed and transformed into a Cluster API management cluster via the Azure CAPZ provider.
    • Rancher K3s template - deploys an Ubuntu Linux VM which will have Rancher (K3s) installed on it and connected as an Azure Arc enabled Kubernetes cluster
    • Storage account template - used for staging files in automation scripts
    • Management artifacts template - deploys Azure Log Analytics workspace and solutions and Azure Policy artifacts
  • User remotes into Client Windows VM, which automatically kicks off multiple scripts that:
    • Deploy and configure three (3) nested virtual machines in Hyper-V
      • Windows VM - onboarded as Azure Arc enabled Server
      • Ubuntu VM - onboarded as Azure Arc enabled Server
      • Windows VM running SQL Server - onboarded as Azure Arc enabled SQL Server (as well as Azure Arc enabled Server)
    • Deploy and configure Azure Arc enabled data services on the CAPI workload cluster including a data controller, a SQL MI instance, and a PostgreSQL Hyperscale cluster. After deployment, Azure Data Studio opens automatically with connection entries for each database instance. Data services deployed by the script are:
      • Data controller
      • SQL MI instance
      • Postgres instance


  • ArcBox requires 52 vCPUs when deploying with default parameters such as VM series/size. Ensure you have sufficient vCPU quota available in your Azure subscription and the region where you plan to deploy ArcBox. You can use the below Az CLI command to check your vCPU utilization.

    az vm list-usage --location <your location> --output table

    Screenshot showing az vm list-usage

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

    az --version
  • Login to AZ CLI using the az login command.

  • Create Azure service principal (SP)

    To deploy ArcBox 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://AzureArcBox" --role contributor

    Output should look like this:

    "displayName": "AzureArcBox",
    "name": "http://AzureArcBox",

    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

  • Enable your subscription for the Microsoft.AzureArcData resource provider for Azure Arc enabled data services. Registration is an asynchronous process, and registration may take approximately 10 minutes.

    az provider register --namespace Microsoft.AzureArcData

    You can monitor the registration process with the following commands:

    az provider show -n Microsoft.AzureArcData -o table
  • Generate SSH Key (or use existing ssh key)

    ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

ArcBox Azure Region Compatibility

ArcBox must be deployed to one of the following regions. Deploying ArcBox outside of these regions may result in unexpected results or deployment errors.

  • East US
  • East US 2
  • West US 2
  • North Europe
  • West Europe
  • UK South
  • Southeast Asia
  • Australia East

Deployment Option 1: Azure Portal

  • Click the button and enter values for the the ARM template parameters.

    Screenshot showing Azure Portal deployment of ArcBox

    Screenshot showing Azure Portal deployment of ArcBox

    Screenshot showing Azure Portal deployment of ArcBox

Deployment Option 2: Azure CLI

  • Clone the Azure Arc Jumpstart repository

    git clone https://github.com/microsoft/azure_arc.git
  • Edit the azuredeploy.parameters.json ARM template parameters file and supply some values for your environment.

    • sshRSAPublicKey - Your SSH public key

    • spnClientId - Your Azure service principal id

    • spnClientSecret - Your Azure service principal secret

    • spnTenantId - Your Azure tenant id

    • windowsAdminUsername - Client Windows VM Administrator name

    • windowsAdminPassword - Client Windows VM Password. Password must have 3 of the following: 1 lower case character, 1 upper case character, 1 number, and 1 special character. The value must be between 12 and 123 characters long.

    • myIpAddress - Your local IP address. This is used to allow remote RDP and SSH connections to the Client Windows VM and K3s Rancher VM.

    • logAnalyticsWorkspaceName - Unique name for the ArcBox log analytics workspace

      Screenshot showing example parameters

  • Now you will deploy the ARM template. Navigate to the local cloned deployment folder and run the below command:

    az group create --name <Name of the Azure resource group> --location <Azure Region>
    az deployment group create \
    --resource-group <Name of the Azure resource group> \
    --template-file azuredeploy.json \
    --parameters azuredeploy.parameters.json 

    Screenshot showing az group create

    Screenshot showing az deployment group create

  • After deployment, you should see the ArcBox resources inside your resource group.

    Screenshot showing az deployment group create

Start post-deployment automation

  • Open a remote desktop connection into ArcBox-Client. Upon logging in, multiple automated scripts will open and start running. These scripts usually take 10-20 minutes to finish and once completed the script windows will close. At this point, the deployment is complete.

    Screenshot showing ArcBox-Client

    Screenshot showing ArcBox resources in Azure Portal

Using ArcBox

After deployment is complete, its time to start exploring ArcBox. Most interactions with ArcBox will take place either from Azure itself (Azure Portal, CLI or similar) or from inside the ArcBox-Client virtual machine. When remoted into the client VM, here are some things to try:

  • Open Hyper-V and access the Azure Arc enabled servers

    • Username: arcdemo
    • Password: ArcDemo123!!

    Screenshot showing ArcBox Client VM with Hyper-V

  • Use the included kubectx tool to switch Kubernetes contexts between the Rancher K3s and AKS clusters.

    kubectx arcbox-capi
    kubectl get nodes
    kubectl get pods -n arcdatactrl
    kubectx arcboxk3s
    kubectl get nodes

    Screenshot showing usage of kubectx

  • Login to the Azure Arc data controller with Azdata CLI and explore its functionality.

    • Azdata username: arcdemo
    • Azdata password: ArcPassword123!!
    • Namespace: arcdatactrl
    azdata login --username arcdemo --namespace arcdatactrl
    azdata arc dc status show
    azdata arc sql endpoint list
    azdata arc postgres endpoint list

    Screenshot showing Azdata CLI usage

  • Open Azure Data Studio and explore the SQL MI and PostgreSQL Hyperscale instances.

    Screenshot showing Azure Data Studio usage

Included tools

  • Azure Data Studio with Arc and PostgreSQL extensions
  • kubectl, kubectx, helm
  • Chocolatey
  • Visual Studio Code
  • Putty
  • 7zip
  • Terraform
  • Git

Next steps

ArcBox is a sandbox that can be used for a large variety of use cases, such as an environment for testing and training or kickstarter for proof of concept projects. Ultimately, you are free to do whatever you wish with ArcBox. Some suggested next steps for you to try in your ArcBox are:

  • Login to the Azure Arc data controller using azdata and explore the functionality provided by the data controller
  • Deploy sample databases to the PostgreSQL Hyperscale instance or to the SQL Managed Instance
  • Use the included kubectx to switch contexts between the two Kubernetes clusters
  • Deploy GitOps configurations with Azure Arc enabled Kubernetes
  • Build policy initiatives that apply to your Azure Arc enabled resources
  • Write and test custom policies that apply to your Azure Arc enabled resources
  • Incorporate your own tooling and automation into the existing automation framework
  • Build a certificate/secret/key management strategy with your Azure Arc resources

Do you have an interesting use case to share? Submit an issue on GitHub with your idea and we will consider it for future releases!

Clean up the deployment

To clean up your deployment, simply delete the resource group using Azure CLI or Azure Portal.

az group delete -n <name of your resource group>

Screenshot showing az group delete

Screenshot showing group delete from Azure Portal

Known issues

  • Azure Arc enabled SQL Server assessment report not always visible in Azure Portal

  • Currently, Azure Arc enabled data services are deployed in indirectly connected mode.

  • The custom-location feature required for Azure Arc enabled data services directly connected mode currently cannot be installed using a service principal and will present an “Insufficient privileges” error as part of the data services logon script runtime that can be safely ignored for now.

    Screenshot showing custom location “Insufficient privileges” error