Skip to content
Switch branches/tags
Go to file
Cannot retrieve contributors at this time

AKS on Azure China Best Practices

Azure Kubernetes Service is in General Available, this page provides best practices about how to operate AKS on Azure China cloud.

Limitations of current AKS General Available on Azure China

  • Preview features on Global Azure won't be supported on Azure China, e.g. Windows Container

1. How to create AKS on Azure China

Currently AKS on Azure China could be created by Azure portal or azure cli, AKS on chinaeast2, chinanorth2 regions are available now. This page shows to create AKS cluster by azure cli.

You need the Azure CLI version 2.0.61 or later installed and configured. Run az --version to find the version. If you need to install or upgrade, see Install Azure CLI.

  • How to use azure cli on Azure China.

    az cloud set --name AzureChinaCloud
    az login
    az account list
    az account set -s <subscription-name>
  • Pick one available AKS version on chinaeast2 or chinanorth2.

az aks get-versions -l chinaeast2 -o table
KubernetesVersion    Upgrades
-------------------  -----------------------
1.21.2               None available
1.21.1               1.21.2
1.20.7               1.21.1, 1.21.2
1.20.5               1.20.7, 1.21.1, 1.21.2
1.19.11              1.20.5, 1.20.7
1.19.9               1.19.11, 1.20.5, 1.20.7
1.18.19              1.19.9, 1.19.11
1.18.17              1.18.19, 1.19.9, 1.19.11
  • Example: create an AKS cluster on Azure China

    LOCATION=chinaeast2  #or chinanorth2
    VERSION=1.20.7  # select an available version by "az aks get-versions -l chinaeast2 -o table"
    # create a resource group
    az group create -n $RESOURCE_GROUP_NAME -l $LOCATION
    # create AKS cluster with 1 agent node (if your azure cli version is low, remove `--disable-rbac`)
    az aks create -g $RESOURCE_GROUP_NAME -n $CLUSTER_NAME --node-count 1 --node-vm-size Standard_D3_v2 --generate-ssh-keys --kubernetes-version $VERSION -l $LOCATION --node-osdisk-size 128
    # wait about 5 min for `az aks create` running complete
    # get the credentials for the cluster
    az aks get-credentials -g $RESOURCE_GROUP_NAME -n $CLUSTER_NAME
    # get all agent nodes
    kubectl get nodes
    # open the Kubernetes dashboard
    az aks browse --resource-group $RESOURCE_GROUP_NAME -n $CLUSTER_NAME
    # scale up/down AKS cluster nodes 
    az aks scale -g $RESOURCE_GROUP_NAME -n $CLUSTER_NAME --node-count=2
    # delete AKS cluster node
    az aks delete -g $RESOURCE_GROUP_NAME -n $CLUSTER_NAME

    Get more detailed AKS set up steps

    Detailed "az aks" command line manual could be found here

2. Container Registry

2.1 Azure Container Registry(ACR)

Azure Container Registry(ACR) provides storage of private Docker container images, enabling fast, scalable retrieval, and network-close deployment of container workloads on Azure.

  • ACR does not provide public anonymous access functionality on Azure China, this feature is in public preview on global Azure.

  • AKS has good integration with ACR, container image stored in ACR could be pulled in AKS after Configure ACR authentication.

2.2 Container Registry Proxy

Since some container registries like, are not accessible or very slow in China, we have set up container registry proxy servers for Azure China VMs:

First docker pull of new image will be still slow, and then image would be cached, would be much faster in the next docker pull action.

Note: currently * could only be accessed by Azure China IP, we don't provide public outside access any more. If you have such requirement to whitelist your IP, please contact, provide your IP address, we will decide whether to whitelist your IP per your reasonable requirement, thanks for understanding.

Global Proxy in China format example
dockerhub (<repo-name>/<image-name>:<version><repo-name>/<image-name>:<version><repo-name>/<image-name>:<version><repo-name>/<image-name>:<version><repo-name>/<image-name>:<version><repo-name>/<image-name>:<version>
  • Container Registry Proxy Example

    specify defaultBackend.image.repository as in nginx-ingress chart since original does not work in Azure China:

    helm install stable/nginx-ingress --set --set defaultBackend.image.tag=1.4

3. Install kubectl

az aks install-cli command is used to download kubectl binary, it works on Azure China from version 2.0.61 or later, another alternative is use following command to download kubectl if don't have azure-cli:

# docker run -v ${HOME}:/root -v /usr/local/bin/:/kube -it
root@09feb993f352:/# az cloud set --name AzureChinaCloud
root@09feb993f352:/# az aks install-cli --install-location /kube/kubectl

run sudo az aks install-cli if hit following permission error

Connection error while attempting to download client ([Errno 13] Permission denied: '/usr/local/bin/kubectl'

4. Install helm

  • Install helm v3
tar -xvf helm-$VER-linux-amd64.tar.gz
sudo mv linux-amd64/helm /usr/local/bin
  • Helm application example:
# Install wordpress
helm repo add bitnami
helm install bitnami/wordpress --generate-name --set

# Install nginx-ingress
helm repo add stable
helm install stable/nginx-ingress --generate-name --set --set


Hands on


  • For production usage:

    • agent VM size should have at least 8 CPU cores(e.g. D4_v2) since k8s components would also occupy CPU, memory resources on the node, details about AKS resource reservation.
    • it's better set a bigger os disk size on agent VM in AKS cluster creation, e.g. set --node-osdisk-size 128, original 30GB os disk size is not enough since all images are stored on os disk.
  • GPU workload support best practices on Azure China