Edit

Share via

Deploy a Windows Server container on an Azure Kubernetes Service (AKS) cluster using Azure CLI

  • Article

Azure Kubernetes Service (AKS) is a managed Kubernetes service that lets you quickly deploy and manage clusters. In this article, you use Azure CLI to deploy an AKS cluster that runs Windows Server containers. You also deploy an ASP.NET sample application in a Windows Server container to the cluster.

Note

To get started with quickly provisioning an AKS cluster, this article includes steps to deploy a cluster with default settings for evaluation purposes only. Before deploying a production-ready cluster, we recommend that you familiarize yourself with our baseline reference architecture to consider how it aligns with your business requirements.

Before you begin

This quickstart assumes a basic understanding of Kubernetes concepts. For more information, see Kubernetes core concepts for Azure Kubernetes Service (AKS).

Create a resource group

An Azure resource group is a logical group in which Azure resources are deployed and managed. When you create a resource group, you're asked to specify a location. This location is where resource group metadata is stored and where your resources run in Azure if you don't specify another region during resource creation.

  • Create a resource group using the az group create command. The following example creates a resource group named myResourceGroup in the WestUS2 location. Enter this command and other commands in this article into a BASH shell:
export RANDOM_SUFFIX=$(openssl rand -hex 3)
export REGION="canadacentral"
export MY_RESOURCE_GROUP_NAME="myAKSResourceGroup$RANDOM_SUFFIX"
az group create --name $MY_RESOURCE_GROUP_NAME --location $REGION

Results:

{
  "id": "/subscriptions/xxxxx-xxxxx-xxxxx-xxxxx/resourceGroups/myResourceGroupxxxxx",
  "location": "WestUS2",
  "managedBy": null,
  "name": "myResourceGroupxxxxx",
  "properties": {
    "provisioningState": "Succeeded"
  },
  "tags": null,
  "type": "Microsoft.Resources/resourceGroups"
}

Create an AKS cluster

In this section, we create an AKS cluster with the following configuration:

  • The cluster is configured with two nodes to ensure it operates reliably. A node is an Azure virtual machine (VM) that runs the Kubernetes node components and container runtime.
  • The --windows-admin-password and --windows-admin-username parameters set the administrator credentials for any Windows Server nodes on the cluster and must meet Windows Server password requirements.
  • The node pool uses VirtualMachineScaleSets.

To create the AKS cluster with Azure CLI, follow these steps:

  1. Create a username to use as administrator credentials for the Windows Server nodes on your cluster. (The original example prompted for input; in this Exec Doc, the environment variable is set non-interactively.)
export WINDOWS_USERNAME="winadmin"
  1. Create a password for the administrator username you created in the previous step. The password must be a minimum of 14 characters and meet the Windows Server password complexity requirements.
export WINDOWS_PASSWORD=$(echo "P@ssw0rd$(openssl rand -base64 10 | tr -dc 'A-Za-z0-9!@#$%^&*()' | cut -c1-6)")
  1. Create your cluster using the az aks create command and specify the --windows-admin-username and --windows-admin-password parameters. The following example command creates a cluster using the values from WINDOWS_USERNAME and WINDOWS_PASSWORD you set in the previous commands. A random suffix is appended to the cluster name for uniqueness.
export MY_AKS_CLUSTER="myAKSCluster$RANDOM_SUFFIX"
az aks create \
    --resource-group $MY_RESOURCE_GROUP_NAME \
    --name $MY_AKS_CLUSTER \
    --node-count 2 \
    --enable-addons monitoring \
    --generate-ssh-keys \
    --windows-admin-username $WINDOWS_USERNAME \
    --windows-admin-password $WINDOWS_PASSWORD \
    --vm-set-type VirtualMachineScaleSets \
    --network-plugin azure

After a few minutes, the command completes and returns JSON-formatted information about the cluster. Occasionally, the cluster can take longer than a few minutes to provision. Allow up to 10 minutes for provisioning.

If you get a password validation error, and the password that you set meets the length and complexity requirements, try creating your resource group in another region. Then try creating the cluster with the new resource group.

If you don't specify an administrator username and password when creating the node pool, the username is set to azureuser and the password is set to a random value. For more information, see the Windows Server FAQ

The administrator username can't be changed, but you can change the administrator password that your AKS cluster uses for Windows Server nodes using az aks update. For more information, see Windows Server FAQ.

To run an AKS cluster that supports node pools for Windows Server containers, your cluster needs to use a network policy that uses Azure CNI (advanced) network plugin. The --network-plugin azure parameter specifies Azure CNI.

Add a node pool

By default, an AKS cluster is created with a node pool that can run Linux containers. You must add another node pool that can run Windows Server containers alongside the Linux node pool.

Windows Server 2022 is the default operating system for Kubernetes versions 1.25.0 and higher. Windows Server 2019 is the default OS for earlier versions. If you don't specify a particular OS SKU, Azure creates the new node pool with the default SKU for the version of Kubernetes used by the cluster.

To use the default OS SKU, create the node pool without specifying an OS SKU. The node pool is configured for the default operating system based on the Kubernetes version of the cluster.

Add a Windows node pool using the az aks nodepool add command. The following command creates a new node pool named npwin and adds it to myAKSCluster. The command also uses the default subnet in the default virtual network created when running az aks create. An OS SKU isn't specified, so the node pool is set to the default operating system based on the Kubernetes version of the cluster:

az aks nodepool add \
    --resource-group $MY_RESOURCE_GROUP_NAME \
    --cluster-name $MY_AKS_CLUSTER \
    --os-type Windows \
    --name npwin \
    --node-count 1