Azure Kubernetes Service (AKS) common issues FAQ

This article answers frequently asked questions (FAQ) about common issues that can occur when you're working with an Azure Kubernetes Service (AKS) cluster.

In general, where do I find information about debugging Kubernetes problems?

Try the official guide to troubleshooting Kubernetes clusters. There's also a troubleshooting guide that was published by a Microsoft engineer. This guide helps you troubleshoot pods, nodes, clusters, and other features.

I'm trying to enable Kubernetes role-based access control (Kubernetes RBAC) on an existing cluster. How can I do that?

Enabling Kubernetes role-based access control (Kubernetes RBAC) on existing clusters isn't supported at this time. This feature can be set only when you create new clusters. Kubernetes RBAC is enabled by default when you use the Azure CLI, the Azure portal, or an API version later than 2020-03-01.

Can I move my cluster to a different subscription, or move my subscription with my cluster to a new tenant?

If you've moved your AKS cluster to a different subscription or the cluster's subscription to a new tenant, the cluster won't function because of missing cluster identity permissions. AKS doesn't support moving clusters across subscriptions or tenants because of this constraint.

What naming restrictions are enforced for AKS resources and parameters?

Naming restrictions are implemented by both the Azure platform and AKS. If a resource name or parameter breaks one of these restrictions, an error is returned that asks you provide a different input. The following common naming guidelines apply:

  • Cluster names must be 1-63 characters in length. The only allowed characters are letters, numbers, dashes, and underscore. The first and last character must be a letter or a number.

  • The AKS node or MC_ resource group name combines the resource group name and resource name. The autogenerated syntax of MC_resourceGroupName_resourceName_AzureRegion must be no greater than 80 characters in length. If necessary, reduce the length of your resource group name or AKS cluster name. You may also customize your node's resource group name.

  • The Domain Name System (DNS) prefix must start and end with alphanumeric values and must be between 1-54 characters in length. Valid characters include alphanumeric values and hyphens ("-"). The DNS prefix can't include special characters, such as periods (".").

  • AKS node pool names must be all lowercase. The names must be 1-11 characters in length for Linux node pools and 1-6 characters for Windows node pools. A name must start with a letter, and the only allowed characters are letters and numbers.

  • The admin-username, which sets the administrator user name for Linux nodes, must start with a letter. This user name may only contain letters, numbers, hyphens, and underscores. It has a maximum length of 64 characters.

Third-party information disclaimer

The third-party products that this article discusses are manufactured by companies that are independent of Microsoft. Microsoft makes no warranty, implied or otherwise, about the performance or reliability of these products.

Contact us for help

If you have questions or need help, create a support request, or ask Azure community support. You can also submit product feedback to Azure community support.