Tutorial: Deploy an Azure Kubernetes Service (AKS) cluster

Kubernetes provides a distributed platform for containerized applications. With AKS, you can quickly create a production ready Kubernetes cluster. In this tutorial, part three of seven, a Kubernetes cluster is deployed in AKS. You learn how to:

  • Create a service principal for resource interactions
  • Deploy a Kubernetes AKS cluster
  • Install the Kubernetes CLI (kubectl)
  • Configure kubectl to connect to your AKS cluster

In additional tutorials, the Azure Vote application is deployed to the cluster, scaled, and updated.

Before you begin

In previous tutorials, a container image was created and uploaded to an Azure Container Registry instance. If you haven't done these steps, and would like to follow along, start at Tutorial 1 – Create container images.

This tutorial requires that you're running the Azure CLI version 2.0.53 or later. Run az --version to find the version. If you need to install or upgrade, see Install Azure CLI.

Create a service principal

To allow an AKS cluster to interact with other Azure resources, an Azure Active Directory service principal is used. This service principal can be automatically created by the Azure CLI or portal, or you can pre-create one and assign additional permissions. In this tutorial, you create a service principal, grant access to the Azure Container Registry (ACR) instance created in the previous tutorial, then create an AKS cluster.

Create a service principal using the az ad sp create-for-rbac command. The --skip-assignment parameter limits any additional permissions from being assigned. By default, this service principal is valid for one year.

az ad sp create-for-rbac --skip-assignment

The output is similar to the following example:

  "appId": "e7596ae3-6864-4cb8-94fc-20164b1588a9",
  "displayName": "azure-cli-2018-06-29-19-14-37",
  "name": "http://azure-cli-2018-06-29-19-14-37",
  "password": "52c95f25-bd1e-4314-bd31-d8112b293521",
  "tenant": "72f988bf-86f1-41af-91ab-2d7cd011db48"

Make a note of the appId and password. These values are used in the following steps.

Configure ACR authentication

To access images stored in ACR, you must grant the AKS service principal the correct rights to pull images from ACR.

First, get the ACR resource ID using az acr show. Update the <acrName> registry name to that of your ACR instance and the resource group where the ACR instance is located.

az acr show --resource-group myResourceGroup --name <acrName> --query "id" --output tsv

To grant the correct access for the AKS cluster to pull images stored in ACR, assign the AcrPull role using the az role assignment create command. Replace <appId> and <acrId> with the values gathered in the previous two steps.

az role assignment create --assignee <appId> --scope <acrId> --role acrpull

Create a Kubernetes cluster

AKS clusters can use Kubernetes role-based access controls (RBAC). These controls let you define access to resources based on roles assigned to users. Permissions are combined if a user is assigned multiple roles, and permissions can be scoped to either a single namespace or across the whole cluster. By default, the Azure CLI automatically enables RBAC when you create an AKS cluster.

Create an AKS cluster using az aks create. The following example creates a cluster named myAKSCluster in the resource group named myResourceGroup. This resource group was created in the previous tutorial. Provide your own <appId> and <password> from the previous step where the service principal was created.

az aks create \
    --resource-group myResourceGroup \
    --name myAKSCluster \
    --node-count 2 \
    --service-principal <appId> \
    --client-secret <password> \

After a few minutes, the deployment completes, and returns JSON-formatted information about the AKS deployment.


To ensure your cluster to operate reliably, you should run at least 2 (two) nodes.

Install the Kubernetes CLI

To connect to the Kubernetes cluster from your local computer, you use kubectl, the Kubernetes command-line client.

If you use the Azure Cloud Shell, kubectl is already installed. You can also install it locally using the az aks install-cli command:

az aks install-cli

Connect to cluster using kubectl

To configure kubectl to connect to your Kubernetes cluster, use the az aks get-credentials command. The following example gets credentials for the AKS cluster named myAKSCluster in the myResourceGroup:

az aks get-credentials --resource-group myResourceGroup --name myAKSCluster

To verify the connection to your cluster, run the kubectl get nodes command:

$ kubectl get nodes

NAME                       STATUS   ROLES   AGE   VERSION
aks-nodepool1-12345678-0   Ready    agent   32m   v1.13.10

Next steps

In this tutorial, a Kubernetes cluster was deployed in AKS, and you configured kubectl to connect to it. You learned how to:

  • Create a service principal for resource interactions
  • Deploy a Kubernetes AKS cluster
  • Install the Kubernetes CLI (kubectl)
  • Configure kubectl to connect to your AKS cluster

Advance to the next tutorial to learn how to deploy an application to the cluster.