Deploy AKS cluster and connect it to Azure Arc using Terraform

The following README will guide you on how to use the provided Terraform plan to deploy an Azure Kubernetes Service (AKS) cluster and connected it as an Azure Arc-enabled Kubernetes resource.

Note: Since AKS is a 1st-party Azure solution and natively supports capabilities such as Azure Monitor integration as well as GitOps configurations (currently in preview), it is not expected for an AKS cluster to be projected as an Azure Arc-enabled Kubernetes cluster. The following scenario should ONLY be used for demo and testing purposes.


  • 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
  • Install Terraform >=0.12

  • Create Azure service principal (SP)

    To be able to complete the scenario and its related automation, 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://AzureArcK8s" --role contributor

    Output should look like this:

    "displayName": "AzureArcK8s",
    "name": "http://AzureArcK8s",

    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 subscription with the two resource providers for Azure Arc-enabled Kubernetes. Registration is an asynchronous process, and registration may take approximately 10 minutes.

    az provider register --namespace Microsoft.Kubernetes
    az provider register --namespace Microsoft.KubernetesConfiguration
    az provider register --namespace Microsoft.ExtendedLocation

    You can monitor the registration process with the following commands:

    az provider show -n Microsoft.Kubernetes -o table
    az provider show -n Microsoft.KubernetesConfiguration -o table
    az provider show -n Microsoft.ExtendedLocation -o table


The only thing you need to do before executing the Terraform plan is to export the environment variables which will be used by the plan. This is based on the Azure service principal you’ve just created and your subscription.

In addition, validate that the AKS Kubernetes version is available in your region using the below Azure CLI command.

az aks get-versions -l "<Your Azure Region>"

In case the AKS service is not available in your region, you can change the AKS Kubernetes version in the file by searching for kubernetes_version.

  • Export the environment variables needed for the Terraform plan.

    export TF_VAR_client_id=<Your Azure service principal App ID>
    export TF_VAR_client_secret=<Your Azure service principal App Password>

    Note: If you are running in a PowerShell environment, to set the Terraform environment variables, use the Set-Item -Path env: prefix (see example below)

    Set-Item -Path env:TF_VAR_client_id
  • Run the terraform init command which will download the Terraform AzureRM provider.

    Screenshot showing terraform init being run

  • Run the terraform apply --auto-approve command and wait for the plan to finish.

    Once the Terraform deployment is completed, a new AKS cluster in a new Azure resource group is created.

    Screenshot showing terraform plan completing

    Screenshot showing Azure Portal with AKS resource

    Screenshot showing Azure Portal with AKS resource

  • Now that you have a running AKS cluster, edit the environment variables section in the included az_connect_aks shell script.

    Screenshot showing az_connect_aks shell script

  • In order to keep your local environment clean and untouched, we will use Azure Cloud Shell (located in the top-right corner in the Azure portal) to run the az_connect_aks shell script against the AKS cluster. Make sure Cloud Shell is configured to use Bash.

    Screenshot showing how to access Cloud Shell in Visual Studio Code

  • Edit the environment variables in the az_connect_aks shell script to match your parameters, upload it to the Cloud Shell environment and run it using the . ./ command.

    Note: The extra dot is due to the script has an export function and needs to have the vars exported in the same shell session as the rest of the commands.

    Screenshot showing Cloud Shell upload functionality

    Screenshot showing Cloud Shell upload functionality

    Screenshot showing Cloud Shell upload functionality

    Screenshot showing Cloud Shell upload functionality

  • Once the script run has finished, the AKS cluster will be projected as a new Azure Arc-enabled Kubernetes resource.

    Screenshot showing Azure Portal with Azure Arc-enabled resource

    Screenshot showing Azure Portal with Azure Arc-enabled resource

Delete the deployment

The most straightforward way is to delete the Azure Arc-enabled Kubernetes resource via the Azure Portal, just select the cluster and delete it.

Screenshot showing delete function in Azure Portal

If you want to nuke the entire environment, delete both the AKS and the AKS resources resource groups or run the terraform destroy -auto-approve command.

Screenshot showing terraform destroy being run

Screenshot showing terraform destroy being run