Deploy an AWS Ubuntu EC2 instance and connect it to Azure Arc using a Terraform plan

The following Jumpstart scenario will guide you on how to use the provided Terraform plan to deploy an AWS EC2 virtual machine 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.49.0 and above. Use the below command to check your current installed version.

    az --version
  • Generate a new SSH key pair or use an existing one (Windows 10 and above now comes with a built-in ssh client).

    ssh-keygen -t rsa -b 4096

    To retrieve the SSH public key after it’s been created, depending on your environment, use one of the below methods:

    • In Linux, use the cat ~/.ssh/ command.
    • In Windows (CMD/PowerShell), use the SSH public key file that by default, is located in the C:\Users\WINUSER/.ssh/ folder.

    SSH public key example output:

    ssh-rsa o1djFhyNe5NXyYk7XVF7wOBAAABgQDO/QPJ6IZHujkGRhiI+6s1ngK8V4OK+iBAa15GRQqd7scWgQ1RUSFAAKUxHn2TJPx/Z/IU60aUVmAq/OV9w0RMrZhQkGQz8CHRXc28S156VMPxjk/gRtrVZXfoXMr86W1nRnyZdVwojy2++sqZeP/2c5GoeRbv06NfmHTHYKyXdn0lPALC6i3OLilFEnm46Wo+azmxDuxwi66RNr9iBi6WdIn/zv7tdeE34VAutmsgPMpynt1+vCgChbdZR7uxwi66RNr9iPdMR7gjx3W7dikQEo1djFhyNe5rrejrgjerggjkXyYk7XVF7wOk0t8KYdXvLlIyYyUCk1cOD2P48ArqgfRxPIwepgW78znYuwiEDss6g0qrFKBcl8vtiJE5Vog/EIZP04XpmaVKmAWNCCGFJereRKNFIl7QfSj3ZLT2ZXkXaoLoaMhA71ko6bKBuSq0G5YaMq3stCfyVVSlHs7nzhYsX6aDU6LwM/BTO1c= user@pc
  • Create free AWS account

  • Install Terraform >=1.3.5

  • Create Azure service principal (SP)

    To connect the AWS 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'

Create an AWS identity

In order for Terraform to create resources in AWS, we will need to create a new AWS IAM role with appropriate permissions and configure Terraform to use it.

  • Login to the AWS management console

  • After logging in, click the “Services” dropdown in the top left. Under “Security, Identity, and Compliance” select “IAM” to access the Identity and Access Management page

    Screenshot of AWS cloud console

    Screenshot of IAM AWS cloud console

  • Click on “Users” from the left menu and then click on “Add user” to create a new IAM user.

    Screenshot of new user creation in AWS cloud console

  • On the “Add User” screen, name the user “terraform” and select the “Programmatic Access” checkbox then click “Next”

    Screenshot of new user creation in AWS cloud console

  • On the next “Set Permissions” screen, select “Attach existing policies directly” and then check the box next to AmazonEC2FullAccess as seen in the screenshot then click “Next”

    Screenshot showing new user in AWS cloud console

  • On the tags screen, assign a tag with a key of “azure-arc-demo” and click “Next” to proceed to the Review screen.

    Screenshot showing tags in AWS cloud console

  • Double check that everything looks correct and click “Create user” when ready.

    Screenshot showing creating a user in AWS cloud console

  • After the user is created, you will see the user’s Access key ID and Secret access key. Copy these values down before clicking the Close button. In the screen below, you can see an example of what this should look like. Once you have these keys, you will be able to use them with Terraform to create AWS resources.

    Screenshot showing created user in AWS cloud console

Configure Terraform

Before executing the Terraform plan, you must export the environment variables which will be used by the plan. These variables are based on your Azure subscription and tenant, the Azure service principal, and the AWS IAM user and keys you just created.

  • Retrieve your Azure subscription ID and tenant ID using the az account list command.

  • The Terraform plan creates resources in both Microsoft Azure and AWS. It then executes a script on an AWS EC2 virtual machine to install the Azure Arc agent and all necessary artifacts. This script requires certain information about your AWS and Azure environments. Edit scripts/ and update each of the variables with the appropriate values.

    • TF_VAR_subscription_id=Your Azure subscription ID
    • TF_VAR_client_id=Your Azure service principal app id
    • TF_VAR_client_secret=Your Azure service principal password
    • TF_VAR_tenant_id=Your Azure tenant ID
    • AWS_ACCESS_KEY_ID=AWS access key
    • AWS_SECRET_ACCESS_KEY=AWS secret key
  • From CLI, navigate to the “azure_arc_servers_jumpstart/aws/ubuntu/terraform” directory of the cloned repo.

  • Export the environment variables you edited by running scripts/ with the source command as shown below. Terraform requires these to be set for the plan to execute properly. Note that this script will also be automatically executed remotely on the AWS virtual machine as part of the Terraform deployment.

    source ./scripts/
  • Make sure your SSH keys are available in ~/.ssh and named and id_rsa. If you followed the ssh-keygen guide above to create your key then this should already be setup correctly. If not, you may need to modify to use a key with a different path.

  • Run the terraform init command which will download the Terraform AzureRM provider.

    Screenshot of terraform init being run


  • Run the terraform apply --auto-approve command and wait for the plan to finish. Upon completion, you will have an AWS Amazon Linux 2 EC2 instance deployed and connected as a new Azure Arc-enabled server inside a new resource group.

  • Open the Azure portal and navigate to the resource group “Arc-AWS-Demo”. The virtual machine created in AWS will be visible as a resource.

    Screenshot of Azure portal showing Azure Arc-enabled server

    Screenshot of AWS cloud console showing EC2 instance

Semi-Automated Deployment (Optional)

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

If you want to demo/control the actual registration process, do the following:

  • In the script template, comment out the “Run connect command” section and save the file.

    Screenshot showing azcmagent connect script commented out

  • Get the public IP of the AWS VM by running terraform output

    Screenshot of terraform output being run

  • SSH the VM using the ssh ubuntu@x.x.x.x where x.x.x.x is the host ip.

    Screenshot of SSH into EC2 server

  • Export all the environment variables in

    Screenshot showing export of environment variables in

  • Run the following command

    azcmagent connect --service-principal-id $TF_VAR_client_id --service-principal-secret $TF_VAR_client_secret --resource-group "Arc-AWS-Demo" --tenant-id $TF_VAR_tenant_id --location "westus2" --subscription-id $TF_VAR_subscription_id --correlation-id "d009f5dd-dba8-4ac7-bac9-b54ef3a6671a"

    Screenshot of azcmagent connect being run

  • When complete, your VM will be registered with Azure Arc and visible in the resource group inside Azure Portal.

Delete the deployment

To delete all the resources you created as part of this demo use the terraform destroy --auto-approve command as shown below. Screenshot showing terraform destroy being run

Alternatively, you can delete the AWS EC2 instance directly by terminating it from the AWS Console. Note that it will take a few minutes for the instance to actually be removed. Screenshot of AWS cloud console showing terminating instance

If you delete the instance manually, then you should also delete ./scripts/ which is created by the Terraform plan.