Basic troubleshooting of cluster connection issues with the API server

This article discusses connection issues to an Azure Kubernetes Service (AKS) cluster when you can't reach the cluster's API server through the Kubernetes cluster command-line tool (kubectl) or any other tool, such as using REST API through a programming language.

Prerequisites

• Azure CLI.

Root cause and solutions

Connection issues to the API server can occur for many reasons, but the root cause is often related to an error with one of these items:

• Network
• Authentication
• Authorization

You can take these common troubleshooting steps to check the connectivity to the AKS cluster's API server:

1. Enter the following az aks show command in Azure CLI. This command gets the fully qualified domain name (FQDN) of your AKS cluster.

   az aks show --resource-group <cluster-resource-group> --name <cluster-name> --query fqdn
   

2. With the FQDN, check whether the API server is reachable from the client machine by using the name server lookup (nslookup), client URL (curl), and telnet commands:

   # Check if the DNS Resolution is working:
   $ nslookup <cluster-fqdn>  
   
   # Then check if the API Server is reachable:
   $ curl -Iv https://<cluster-fqdn>
   $ telnet <cluster-fqdn> 443
   

3. If the AKS cluster is private, make sure you run the command from a virtual machine (VM) that can access the AKS cluster's Azure Virtual Network. See Options for connecting to the private cluster.

4. If necessary, follow the steps in the troubleshooting article Client IP address can't access the API server, so the API server adds your client IP address to the IP ranges it authorizes.

5. Make sure the version of kubectl on your client machine isn't two or more minor versions behind the AKS cluster's version of that tool. To install the latest version of kubectl, run the az aks install-cli command in Azure CLI. You can then run kubectl version command to check the version number of the new installation.

   For example, on Linux you would run these commands:

   sudo az aks install-cli
   kubectl version --client
   

   For other client operating systems, use these kubectl installation instructions.

6. If necessary, follow the steps in the troubleshooting article Config file isn't available when connecting, so your Kubernetes configuration file (config) is valid and can be found at connection time.

7. If necessary, follow the steps in the troubleshooting article User can't get cluster resources, so you can list the details of your cluster nodes.

8. If you're using a firewall to control egress traffic from AKS worker nodes, make sure the firewall allows the minimum required egress rules for AKS.

9. Make sure the network security group that's associated with AKS nodes allows communication on TCP port 10250 within the AKS nodes.

For other common troubleshooting steps, see I'm receiving TCP timeouts when using kubectl or other third-party tools connecting to the API server.

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 feedback community.