Tutorial - Create an Azure Kubernetes Service (AKS) cluster

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.

This tutorial requires Azure PowerShell version 5.9.0 or later. Check your version with Get-InstalledModule -Name Az. To install or upgrade, see Install Azure PowerShell.

This tutorial requires Azure Developer CLI version 1.5.1 or later. Check your version with azd version. To install or upgrade, see Install Azure Developer CLI.

• Install kubectl locally using the az aks install-cli command.

  az aks install-cli
  

• Install kubectl locally using the Install-AzAksCliTool cmdlet.

  Install-AzAksCliTool
  

azd environments in a codespace automatically download all dependencies found in ./devcontainer/devcontainer.json. This includes the Kubernetes CLI along with any Azure Container Registry (ACR) images.

• To install kubectl locally, use the az aks install-cli command.

  az aks install-cli
  

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.

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 New-AzAksCluster cmdlet. 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.

  New-AzAksCluster -ResourceGroupName myResourceGroup -Name myAKSCluster -NodeCount 2 -GenerateSshKey -AcrNameToAttach <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 -GenerateSshKey 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.

azd packages the deployment of clusters with the application itself using the azd up command. This command is covered in the next tutorial.

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
   

1. Configure kubectl to connect to your Kubernetes cluster using the Import-AzAksCredential cmdlet. The following example gets credentials for the AKS cluster named myAKSCluster in myResourceGroup.

   Import-AzAksCredential -ResourceGroupName 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
   

1. Configure authentication to your cluster using the azd auth login command.

   azd auth login 
   

2. Follow the directions for your auth method.

3. Verify the connection to your cluster using the kubectl get nodes command.

   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
   

azd auth workaround

This workaround requires you to have the Azure CLI installed.

1. Open a terminal window and log in with the Azure CLI using the az login command with the --scope parameter set to https://graph.microsoft.com/.default.

   az login --scope https://graph.microsoft.com/.default
   

   You should be redirected to an authentication page in a new tab to create a browser access token, as shown in the following example:

   https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize?clientid=<your_client_id>.
   

2. Copy the localhost URL of the webpage you received after attempting to sign in with azd auth login.

3. In a new terminal window, use the following curl request to log in. Make sure you replace the <localhost> placeholder with the localhost URL you copied in the previous step.

   curl <localhost>
   

   A successful login outputs an HTML webpage, as shown in the following example:

   <!DOCTYPE html>
   <html>
   <head>
       <meta charset="utf-8" />
       <meta http-equiv="refresh" content="60;url=https://docs.microsoft.com/cli/azure/">
       <title>Login successfully</title>
       <style>
           body {
               font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
           }
   
           code {
               font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace;
               display: inline-block;
               background-color: rgb(242, 242, 242);
               padding: 12px 16px;
               margin: 8px 0px;
           }
       </style>
   </head>
   <body>
       <h3>You have logged into Microsoft Azure!</h3>
       <p>You can close this window, or we will redirect you to the <a href="https://docs.microsoft.com/cli/azure/">Azure CLI documentation</a> in 1 minute.</p>
       <h3>Announcements</h3>
       <p>[Windows only] Azure CLI is collecting feedback on using the <a href="https://learn.microsoft.com/windows/uwp/security/web-account-manager">Web Account Manager</a> (WAM) broker for the login experience.</p>
       <p>You may opt-in to use WAM by running the following commands:</p>
       <code>
           az config set core.allow_broker=true<br>
           az account clear<br>
           az login
       </code>
   </body>
   </html>
   

4. Close the current terminal and open the original terminal. You should see a JSON list of your subscriptions.

5. Copy the id field of the subscription you want to use.

6. Set your subscription using the az account set command.

   az account set --subscription <subscription_id>