Jumpstart ArcBox for IT Pros

ArcBox for IT Pros is a special “flavor” of ArcBox that is intended for users who want to experience Azure Arc-enabled servers capabilities in a sandbox environment.

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
  • Infrastructure-as-code and automation template library for building hybrid cloud management solutions

Azure Arc capabilities available in ArcBox for IT Pros

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.

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, an Azure Monitor workbook, Azure Policy assignments for deploying Log Analytics agents on Windows and Linux Azure Arc-enabled servers, 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

ArcBox Azure Consumption Costs

ArcBox resources generate Azure Consumption charges from the underlying Azure resources including core compute, storage, networking and auxillary services. Note that Azure consumption costs vary depending the region where ArcBox is deployed. Be mindful of your ArcBox deployments and ensure that you disable or delete ArcBox resources when not in use to avoid unwanted charges. Please see the Jumpstart FAQ for more information on consumption costs.

Deployment Options and Automation Flow

ArcBox provides multiple paths for deploying and configuring ArcBox resources. Deployment options include:

  • Azure portal
  • ARM template via Azure CLI
  • Bicep
  • Terraform

Deployment flow diagram for ARM-based deployments

Deployment flow diagram for Terraform-based deployments

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

  • User deploys the primary ARM template (azuredeploy.json), Bicep file (main.bicep), or Terraform plan (main.tf). These objects contain several nested objects that will run simultaneously.
    • ClientVM ARM template/plan - deploys the Client Windows VM. This is the Hyper-V host VM where all user interactions with the environment are made from.
    • Storage account template/plan - used for staging files in automation scripts
    • Management artifacts template/plan - 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 five (5) nested virtual machines in Hyper-V
      • Windows Server 2022 VM - onboarded as Azure Arc-enabled server
      • Windows Server 2019 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)
      • Ubuntu VM - onboarded as Azure Arc-enabled server
      • CentOS VM - onboarded as Azure Arc-enabled server
    • Deploy an Azure Monitor workbook that provides example reports and metrics for monitoring ArcBox components

Prerequisites

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

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

  • Ensure that you have selected the correct subscription you want to deploy ArcBox to by using the az account list --query "[?isDefault]" command. If you need to adjust the active subscription used by Az CLI, follow this guidance.

  • 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
    • Central US
    • West US 2
    • North Europe
    • West Europe
    • France Central
    • UK South
    • Australia East
    • Japan East
    • Korea Central
    • Southeast Asia
  • ArcBox for IT Pros requires 16 DSv4-series 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

  • Register necessary Azure resource providers by running the following commands.

    az provider register --namespace Microsoft.HybridCompute --wait
    az provider register --namespace Microsoft.GuestConfiguration --wait
    az provider register --namespace Microsoft.AzureArcData --wait
    az provider register --namespace Microsoft.OperationsManagement --wait
    
  • Create Azure service principal (SP). To deploy ArcBox, an Azure service principal assigned with multiple role-based access control (RBAC) roles is required:

    • “Contributor” - Required for provisioning Azure resources

    • “Security admin” - Required for installing Microsoft Defender for Cloud Azure-Arc enabled Kubernetes extension and dismiss alerts

    • “Security reader” - Required for being able to view Azure-Arc enabled Kubernetes Cloud Defender extension findings

    • “Monitoring Metrics Publisher” - Required for being Azure Arc-enabled data services billing, monitoring metrics, and logs management

    • (optional) “User Access Administrator” - Required for automatically onboarding the Azure Arc-enabled SQL Server resource

      NOTE: In the event a Service Principal with Owner cannot be created, the SQL Server can be onboarded to Azure Arc post deployment by following the Azure Arc-enabled SQL Server onboarding steps below.

      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
      az ad sp create-for-rbac -n "<Unique SP Name>" --role "Security admin" --scopes /subscriptions/$subscriptionId
      az ad sp create-for-rbac -n "<Unique SP Name>" --role "Security reader" --scopes /subscriptions/$subscriptionId
      az ad sp create-for-rbac -n "<Unique SP Name>" --role "Monitoring Metrics Publisher" --scopes /subscriptions/$subscriptionId
      az ad sp create-for-rbac -n "<Unique SP Name>" --role "User Access Administrator" --scopes /subscriptions/$subscriptionId
      

      For example:

      az login
      subscriptionId=$(az account show --query id --output tsv)
      az ad sp create-for-rbac -n "JumpstartArcBox" --role "Contributor" --scopes /subscriptions/$subscriptionId
      az ad sp create-for-rbac -n "JumpstartArcBox" --role "Security admin" --scopes /subscriptions/$subscriptionId
      az ad sp create-for-rbac -n "JumpstartArcBox" --role "Security reader" --scopes /subscriptions/$subscriptionId
      az ad sp create-for-rbac -n "JumpstartArcBox" --role "Monitoring Metrics Publisher" --scopes /subscriptions/$subscriptionId
      az ad sp create-for-rbac -n "JumpstartArcBox" --role "User Access Administrator" --scopes /subscriptions/$subscriptionId
      

      Output should look similar to this:

      {
      "appId": "XXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "displayName": "JumpstartArcBox",
      "password": "XXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "tenant": "XXXXXXXXXXXXXXXXXXXXXXXXXXXX"
      }
      

      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

  • Generate SSH Key (or use existing ssh key). The SSH key is used to configure secure access to the Linux virtual machines that are used to run the Kubernetes clusters.

    ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
    
  • 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
    • Central US
    • West US 2
    • North Europe
    • West Europe
    • France Central
    • UK South
    • Australia East
    • Japan East
    • Korea Central
    • Southeast Asia

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: ARM template with 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 connections to the Client Windows VM.
    • logAnalyticsWorkspaceName - Unique name for the ArcBox Log Analytics workspace
    • flavor - Use the value “ITPro” to specify that you want to deploy ArcBox for IT Pros

    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

Deployment Option 3: Bicep deployment via Azure CLI

  • Clone the Azure Arc Jumpstart repository

    git clone https://github.com/microsoft/azure_arc.git
    
  • Upgrade to latest Bicep version

    az bicep upgrade
    
  • Edit the main.parameters.json 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 connections to the Client Windows VM.
    • logAnalyticsWorkspaceName - Unique name for the ArcBox Log Analytics workspace
    • flavor - Use the value “ITPro” to specify that you want to deploy ArcBox for IT Pros

    Screenshot showing example parameters

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

    az login
    az group create --name "<resource-group-name>" --location "<preferred-location>"
    az deployment group create -g "<resource-group-name>" -f "main.bicep" -p "main.parameters.json"
    

Deployment Option 4: Terraform Deployment

  • Clone the Azure Arc Jumpstart repository

    git clone https://github.com/microsoft/azure_arc.git
    
  • Download and install the latest version of Terraform here

    NOTE: Terraform 1.x or higher is supported for this deployment. Tested with Terraform v1.011.

  • Create a terraform.tfvars file in the root of the terraform folder and supply some values for your environment.

    azure_location    = "westus2"
    spn_client_id     = "1414133c-9786-53a4-b231-f87c143ebdb1"
    spn_client_secret = "fakeSecretValue123458125712ahjeacjh"
    spn_tenant_id     = "33572583-d294-5b56-c4e6-dcf9a297ec17"
    user_ip_address   = "99.88.99.88"
    client_admin_ssh  = "C:/Temp/rsa.pub"
    deployment_flavor = "ITPro"
    
  • Variable Reference:

    • azure_location - Azure location code (e.g. ‘eastus’, ‘westus2’, etc.)
    • resource_group_name - Resource group which will contain all of the ArcBox artifacts
    • spn_client_id - Your Azure service principal id
    • spn_client_secret - Your Azure service principal secret
    • spn_tenant_id - Your Azure tenant id
    • user_ip_address - Your local IP address. This is used to allow remote RDP connections to the Client Windows VM. If you don’t know your public IP, you can find it here
    • client_admin_ssh - SSH public key path, used for Linux VMs
    • deployment_flavor - Use the value “ITPro” to specify that you want to deploy ArcBox for IT Pros
    • client_admin_username - Admin username for Windows & Linux VMs
    • client_admin_password - Admin password for Windows VMs. 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.
    • workspace_name - Unique name for the ArcBox Log Analytics workspace

    NOTE: Any variables in bold are required. If any optional parameters are not provided, defaults will be used.

  • Now you will deploy the Terraform file. Navigate to the local cloned deployment folder and run the commands below:

    terraform init
    terraform plan -out=infra.out
    terraform apply "infra.out"
    
  • Example output from terraform init:

    terraform init

  • Example output from terraform plan -out=infra.out:

    terraform plan

  • Example output from terraform apply "infra.out":

    terraform plan

Start post-deployment automation

Once your deployment is complete, you can open the Azure portal and see the ArcBox resources inside your resource group. You will be using the ArcBox-Client Azure virtual machine to explore various capabilities of ArcBox such as GitOps configurations and Key Vault integration. You will need to remotely access ArcBox-Client.

Screenshot showing all deployed resources in the resource group

NOTE: For enhanced ArcBox security posture, RDP (3389) and SSH (22) ports are not open by default in ArcBox deployments. You will need to create a network security group (NSG) rule to allow network access to port 3389, or use Azure Bastion or Just-in-Time (JIT) access to connect to the VM.

Connecting to the ArcBox Client virtual machine

Various options are available to connect to ArcBox-Client VM, depending on the parameters you supplied during deployment.

  • RDP - available after configuring access to port 3389 on the ArcBox-NSG, or by enabling Just-in-Time access (JIT).
  • Azure Bastion - available if true was the value of your deployBastion parameter during deployment.

Connecting directly with RDP

By design, ArcBox does not open port 3389 on the network security group. Therefore, you must create an NSG rule to allow inbound 3389.

  • Open the ArcBox-NSG resource in Azure portal and click “Add” to add a new rule.

    Screenshot showing ArcBox-Client NSG with blocked RDP

    Screenshot showing adding a new inbound security rule

  • Specify the IP address that you will be connecting from and select RDP as the service with “Allow” set as the action. You can retrieve your public IP address by accessing https://icanhazip.com or https://whatismyip.com.

    Screenshot showing adding a new allow RDP inbound security rule

    Screenshot showing all inbound security rule

    Screenshot showing connecting to the VM using RDP

Connect using Azure Bastion

  • If you have chosen to deploy Azure Bastion in your deployment, use it to connect to the VM.

    Screenshot showing connecting to the VM using Bastion

    NOTE: When using Azure Bastion, the desktop background image is not visible. Therefore some screenshots in this guide may not exactly match your experience if you are connecting to ArcBox-Client with Azure Bastion.

Connect using just-in-time access (JIT)

If you already have Microsoft Defender for Cloud enabled on your subscription and would like to use JIT to access the Client VM, use the following steps:

  • In the Client VM configuration pane, enable just-in-time. This will enable the default settings.

    Screenshot showing the Microsoft Defender for cloud portal, allowing RDP on the client VM

    Screenshot showing connecting to the VM using RDP

    Screenshot showing connecting to the VM using JIT

The Logon scripts

  • Once you log into the ArcBox-Client VM, 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 automatically. At this point, the deployment is complete.

    Screenshot showing ArcBox-Client

  • Deployment is complete! Let’s begin exploring the features of Azure Arc-enabled servres with ArcBox for IT Pros!

    Screenshot showing complete deployment

    Screenshot showing ArcBox resources in Azure portal

Azure Arc-enabled SQL Server onboarding

  • During deployment, a check is performed to determine whether or not the Service Principal being used has permissions of ‘Microsoft.Authorization/roleAssignments/write’ on the target resource group. This permission can be found in the Azure built-in roles of Owner, User Access Administrator, or you may have a custom RBAC role which provides this permission. If the Service Principal has been granted the rights to change the role assignments on the resource group, the Azure Arc-enabled SQL Server can be automatically onboarded as part of the port-deployment automation.

  • In the event that the Service Principal does not have ‘Microsoft.Authorization/roleAssignments/write’ on the target resource group, and icon will created on the ArcBox-Client desktop, which will allow you to onboard the Azure Arc-enabled SQL Server after the post-deployment automation is complete. To start the onboarding process in this scenario, simply click the ‘Onboard SQL Server’ icon on the desktop. This process should take around 10-15 minutes to complete.

    Screenshot showing ArcBox-Client

  • A pop-up box will walk you through the target SQL Server which will be onboarded to Azure Arc, as well as provide details around the flow of the onboarding automation and how to complete the Azure authentication process when prompted.

    Screenshot showing ArcBox-Client

  • The automation uses the PowerShell SDK to onboard the Azure Arc-enabled SQL Server on your behalf. To accomplish this, it will login to Azure with the -UseDeviceAuthentication flag. The device code will be copied to the clipboard on your behalf, so you can simply paste the value into box when prompted.

    Screenshot showing ArcBox-Client

  • You’ll then need to provide your Azure credentials to complete the authentication process. The user you login as will need ‘Microsoft.Authorization/roleAssignments/write’ permissions on the ArcBox resource group to complete the onboarding process.

    Screenshot showing ArcBox-Client

  • The output of each step of the onboarding process will be displayed in the PowerShell script window, so you’ll be able to see where the script currently is in the process at all times.

    Screenshot showing ArcBox-Client

  • Once complete, you’ll receive a pop-up notification informing you that the onboarding process is complete, and to check the Azure Arc blade in the Azure portal in the next few minutes.

    Screenshot showing ArcBox-Client

  • From the Azure portal, the SQL Server should now be visible as an Azure Arc-enabled SQL Server.

    Screenshot showing ArcBox-Client

Using ArcBox for IT Pros

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

ArcBox Azure Monitor workbook

Open the ArcBox Azure Monitor workbook documentation and explore the visualizations and reports of hybrid cloud resources.

Screenshot showing Azure Monitor workbook usage

Included tools

The following tools are including on the ArcBox-Client VM.

  • 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 a 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:

  • 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

Basic Troubleshooting

Occasionally deployments of ArcBox may fail at various stages. Common reasons for failed deployments include:

  • Invalid service principal id, service principal secret or service principal Azure tenant ID provided in azuredeploy.parameters.json file.
  • Invalid SSH public key provided in azuredeploy.parameters.json file.
    • An example SSH public key is shown here. Note that the public key includes “ssh-rsa” at the beginning. The entire value should be included in your azuredeploy.parameters.json file.

Screenshot showing SSH public key example

  • Not enough vCPU quota available in your target Azure region - check vCPU quota and ensure you have at least 16 available. See the prerequisites section for more details.

  • Target Azure region does not support all required Azure services - ensure you are running ArcBox in one of the supported regions listed in the above section “ArcBox Azure Region Compatibility”.

  • “BadRequest” error message when deploying - this error returns occasionally when the Log Analytics solutions in the ARM templates are deployed. Typically, waiting a few minutes and re-running the same deployment resolves the issue. Alternatively, you can try deploying to a different Azure region.

    Screenshot showing BadRequest errors in Az CLI

    Screenshot showing BadRequest errors in Azure portal

Exploring logs from the ArcBox-Client virtual machine

Occasionally, you may need to review log output from scripts that run on the ArcBox-Client virtual machine in case of deployment failures. To make troubleshooting easier, the ArcBox deployment scripts collect all relevant logs in the C:\ArcBox\Logs folder on ArcBox-Client. A short description of the logs and their purpose can be seen in the list below:

Logfile Description
C:\ArcBox\Logs\Bootstrap.log Output from the initial bootstrapping script that runs on ArcBox-Client.
C:\ArcBox\Logs\ArcServersLogonScript.log Output of ArcServersLogonScript.ps1 which configures the Hyper-V host and guests and onboards the guests as Azure Arc-enabled servers.
C:\ArcBox\Logs\MonitorWorkbookLogonScript.log Output from MonitorWorkbookLogonScript.ps1 which deploys the Azure Monitor workbook.

Screenshot showing ArcBox logs folder on ArcBox-Client

If you are still having issues deploying ArcBox, please submit an issue on GitHub and include a detailed description of your issue, the Azure region you are deploying to, and the flavor of ArcBox you are trying to deploy. Inside the C:\ArcBox\Logs folder you can also find instructions for uploading your logs to an Azure storage account for review by the Jumpstart team.

Known issues

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