Deploy Rancher k3s on an Azure VM and connect it to Azure Arc using Azure ARM template

The following Jumpstart scenario will guide you on how to use the provided Azure ARM Template to deploy a “Ready to Go” Azure virtual machine installed with single-master Rancher K3s Kubernetes cluster and connected it as an Azure Arc cluster resource.


  • Clone the Azure Arc Jumpstart repository

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

    az --version
  • 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
    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 "JumpstartArcK8s" --role "Contributor" --scopes /subscriptions/$subscriptionId

    Output should look like this:

    "displayName": "JumpstartArcK8s",

    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

  • Enable subscription for two providers for Azure Arc-enabled Kubernetes.

  • 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

Deployment Options and Automation Flow

This Jumpstart scenario provides multiple paths for deploying and configuring resources. Deployment options include:

  • Azure portal
  • ARM template via Azure CLI

For you to get familiar with the automation and deployment flow, below is an explanation.

  1. User provides the ARM template parameter values, either via the portal or editing the ARM template parameters file (1-time edit). These parameters values are being used throughout the deployment.

  2. User deploys the ARM template that will initiate the deployment of the k3s cluster and that will be onboarded as an Azure Arc-enabled Kubernetes cluster.

  3. User configures external access for the cluster.

Deployment Option 1: Azure portal

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

    Screenshot showing Azure portal deployment

    Screenshot showing Azure portal deployment

Deployment Option 2: ARM template with Azure CLI

The deployment is using the template parameters file. Before initiating the deployment, edit the azuredeploy.parameters.json file to include your IP address, the OS username and password as well as the appId, password and tenant generated from the service principal creation.

  • To deploy the ARM template, navigate to the 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> \
    --name <The name of this deployment> \
    --template-uri \
    --parameters <The *azuredeploy.parameters.json* parameters file location>

    For example:

    az group create --name Arc-K3s-Demo --location "East US"
    az deployment group create \
    --resource-group Arc-K3s-Demo \
    --name arck3sdemo01 \
    --template-uri \
    --parameters azuredeploy.parameters.json

    Upon completion, you will have new VM installed as a single-host k3s cluster which is already projected as an Azure Arc-enabled Kubernetes cluster in a new resource group.

    Azure resource group

K3s External Access

Traefik is the (default) ingress controller for k3s and uses port 80. To test external access to k3s cluster, an “hello-world” deployment was for you and it is included in the home directory (credit).

  • Since port 80 is taken by Traefik (read more about here), the deployment LoadBalancer was changed to use port 32323 along side with the matching Azure Network Security Group (NSG).

    Azure Network Security Group (NSG) rule

    hello-kubernetes.yaml file

  • To deploy it, use the kubectl apply -f hello-kubernetes.yaml command. Run kubectl get pods and kubectl get svc to check that the pods and the service has been created.

    kubectl apply -f hello-kubernetes.yaml command

    kubectl get pods command

    kubectl get svc command

  • In your browser, enter the cluster_public_ip:32323 which will bring up the hello-world application.

    hello-kubernetes application in a web browser

Delete the deployment

To delete environment, simply just delete the Azure resource group.

Delete Azure resource group