Use a Terraform plan to deploy an Amazon Web Services Amazon Elastic Compute Cloud instance and connect it to Azure Arc

This article provides guidance for using the provided Terraform plan to deploy an Amazon Web Services (AWS) Amazon Elastic Compute Cloud (EC2) instance and connect it as an Azure Arc-enabled server resource.


  1. Clone the Azure Arc Jumpstart repository.

    git clone
  2. Install or update Azure CLI to version 2.7 and above. Use the following command to check your current installed version.

    az --version
  3. Generate SSH key (or use existing SSH key)

  4. Create free AWS account

  5. Install Terraform >= 0.12

  6. Create an Azure service principal.

    To connect the AWS virtual machine to Azure Arc, an Azure service principal assigned with the Contributor role is required. To create it, sign in to your Azure account and run the following command. You can also run this command 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://AzureArcAWS" --role contributor

    Output should look like this:

      "displayName": "AzureArcAWS",
      "name": "http://AzureArcAWS",


    We highly recommend that you scope the service principal to a specific Azure subscription and resource group.

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.

  1. Sign in to the AWS management console

  2. After signing in, select the Services dropdown list in the top left. Under Security, Identity, and Compliance, select IAM to access the identity and access management page

    A screenshot of an AWS cloud console.

    A screenshot of identity and access management in the AWS cloud console.

  3. Click on Users from the left menu, and then select Add user to create a new IAM user.

    A screenshot of creating a new user in an AWS cloud console.

  4. On the Add User page, name the user Terraform and select the Programmatic Access checkbox, and then select Next.

    Second screenshot of creating a new user in an AWS cloud console.

  5. On the Set Permissions page, select Attach existing policies directly and then select the box next to AmazonEC2FullAccess as seen in the screenshot, and then select Next.

    Third screenshot of creating a new user in an AWS cloud console.

  6. On the Tags page, assign a tag with a key of azure-arc-demo and select Next to proceed to the Review page.

    A screenshot of tags in an AWS cloud console.

  7. Verify that everything is correct and select Create user when ready.

    Fourth screenshot of creating a user in an AWS cloud console.

  8. After the user is created, you will see the user's access key ID and secret access key. Copy these values before selecting Close. On the next page, 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.

    A screenshot of creating a user successfully in an 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.

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

  2. 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 application 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
  3. From the Azure CLI, navigate to the azure_arc_servers_jumpstart/aws/ubuntu/terraform directory of the cloned repo.

  4. 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/
  5. 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 set up correctly. If not, you may need to modify to use a key with a different path.

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

    A screenshot of the terraform init command.


  1. 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.

  2. Open the Azure portal and navigate to the arc-aws-demo resource group. The virtual machine created in AWS will be visible as a resource.

    A screenshot showing an Azure Arc-enabled server in the Azure portal.

    A screenshot of AWS console displaying EC2 instances.

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.

A screenshot of the azcmagent connect command.

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

  1. In the script template, comment out the run connect command section and save the file.

    A screenshot showing being commented out to disable automatic onboarding of an Azure Arc agent.

  2. Get the public IP of the AWS VM by running terraform output.

    A screenshot of output from Terraform.

  3. SSH the VM using the ssh ubuntu@xx.xx.xx.xx where xx.xx.xx.xx is the host IP.

    A screenshot of an SSH key connecting to an EC2 server.

  4. Export all the environment variables in

    A screenshot of exported environment variables in

  5. 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

    Another screenshot of the azcmagent connect command.

  6. When complete, your VM will be registered with Azure Arc and visible in the resource group via the 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.

A screenshot of the terraform destroy command.

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.

A screenshot of how to terminate an instance in the AWS console.

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