Tutorial - Create an Azure Kubernetes Service (AKS) cluster

Kubernetes provides a distributed platform for containerized applications. With Azure Kubernetes Service (AKS), you can quickly create a production ready Kubernetes cluster.

In this tutorial, part three of seven, you deploy a Kubernetes cluster in AKS. You learn how to:

  • Deploy an AKS cluster that can authenticate to an Azure Container Registry (ACR).
  • Install the Kubernetes CLI, kubectl.
  • Configure kubectl to connect to your AKS cluster.

Before you begin

In previous tutorials, you created a container image and uploaded it to an ACR instance. Start with Tutorial 1 - Prepare application for AKS to follow along.

  • If you're using Azure CLI, this tutorial requires that you're running the Azure CLI version 2.0.53 or later. Check your version with az --version. To install or upgrade, see Install Azure CLI.
  • If you're using Azure PowerShell, this tutorial requires that you're running Azure PowerShell version 5.9.0 or later. Check your version with Get-InstalledModule -Name Az. To install or upgrade, see Install Azure PowerShell.
  • If you're using Azure Developer CLI, this tutorial requires that you're running the Azure Developer CLI version 1.5.1 or later. Check your version with azd version. To install or upgrade, see Install Azure Developer CLI.

Create a Kubernetes cluster

AKS clusters can use Kubernetes role-based access control (Kubernetes RBAC), which allows you to define access to resources based on roles assigned to users. If a user is assigned multiple roles, permissions are combined. Permissions can be scoped to either a single namespace or across the whole cluster.

To learn more about AKS and Kubernetes RBAC, see Control access to cluster resources using Kubernetes RBAC and Microsoft Entra identities in AKS.

This tutorial requires Azure CLI version 2.0.53 or later. Check your version with az --version. To install or upgrade, see Install Azure CLI.

Install the Kubernetes CLI

You use the Kubernetes CLI, kubectl, to connect to your Kubernetes cluster. If you use the Azure Cloud Shell, kubectl is already installed. If you're running the commands locally, you can use the Azure CLI or Azure PowerShell to install kubectl.

Create an AKS cluster

AKS clusters can use Kubernetes role-based access control (Kubernetes RBAC), which allows you to define access to resources based on roles assigned to users. Permissions are combined when users are assigned multiple roles. Permissions can be scoped to either a single namespace or across the whole cluster. For more information, see Control access to cluster resources using Kubernetes RBAC and Microsoft Entra ID in AKS.

For information about AKS resource limits and region availability, see Quotas, virtual machine size restrictions, and region availability in AKS.

Note

To ensure your cluster operates reliably, you should run at least two nodes.

To allow an AKS cluster to interact with other Azure resources, the Azure platform automatically creates a cluster identity. In this example, the cluster identity is granted the right to pull images from the ACR instance you created in the previous tutorial. To execute the command successfully, you need to have an Owner or Azure account administrator role in your Azure subscription.

  • Create an AKS cluster using the az aks create command. The following example creates a cluster named myAKSCluster in the resource group named myResourceGroup. This resource group was created in the previous tutorial in the eastus region.

    az aks create \
        --resource-group myResourceGroup \
        --name myAKSCluster \
        --node-count 2 \
        --generate-ssh-keys \
        --attach-acr <acrName>
    

    Note

    If you already generated SSH keys, you may encounter an error similar to linuxProfile.ssh.publicKeys.keyData is invalid. To proceed, retry the command without the --generate-ssh-keys parameter.

To avoid needing an Owner or Azure account administrator role, you can also manually configure a service principal to pull images from ACR. For more information, see ACR authentication with service principals or Authenticate from Kubernetes with a pull secret. Alternatively, you can use a managed identity instead of a service principal for easier management.

Connect to cluster using kubectl

  1. Configure kubectl to connect to your Kubernetes cluster using the az aks get-credentials command. The following example gets credentials for the AKS cluster named myAKSCluster in myResourceGroup.

    az aks get-credentials --resource-group myResourceGroup --name myAKSCluster
    
  2. Verify connection to your cluster using the kubectl get nodes command, which returns a list of cluster nodes.

    kubectl get nodes
    

    The following example output shows a list of the cluster nodes.

    NAME                                STATUS   ROLES   AGE   VERSION
    aks-nodepool1-19366578-vmss000002   Ready    agent   47h   v1.25.6
    aks-nodepool1-19366578-vmss000003   Ready    agent   47h   v1.25.6
    

Next steps

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

  • Deploy an AKS cluster that can authenticate to an ACR.
  • Install the Kubernetes CLI, kubectl.
  • Configure kubectl to connect to your AKS cluster.

In the next tutorial, you learn how to deploy an application to your cluster.