Resolve the TLS error in kubectl get pods on Azure by verifying that the kubeconfig file points to the correct public IP address of your Kubernetes control plane. Misconfigured network settings or NAT rules often cause this certificate validation failure, preventing secure communication between the client and the cluster API server.
Understanding the TLS Handshake Failure
When you execute a command likekubectl get pods, the client initiates a secure connection to the Kubernetes API server using HTTPS. This process relies on Transport Layer Security (TLS) certificates to authenticate the server and encrypt the data stream. If the connection fails with a TLS error, it typically indicates that the client cannot verify the identity of the server or cannot establish a secure channel at all.
In an Azure environment, this issue frequently stems from a mismatch between the IP address stored in your local kubeconfig file and the actual public endpoint of the cluster. When a cluster is provisioned on an Azure Virtual Machine, the control plane node must be accessible via a public IP if you are connecting from outside the virtual network. If the kubeconfig references an internal IP, a private IP range, or an outdated public IP, the TLS handshake will fail because the certificate subject alternative names (SANs) do not match the requested host.
Additionally, firewalls and network security groups (NSGs) play a critical role. If port 6443, which is the default for the Kubernetes API server, is blocked by an NSG rule, the TCP connection may time out or reset before the TLS negotiation can even begin. However, a pure TLS error usually suggests that the connection reaches the server, but the certificate verification step rejects it due to hostname mismatches or expired certificates.
Verifying the Kubeconfig Configuration
The first step in troubleshooting is to inspect the configuration file used bykubectl. By default, this file is located at ~/.kube/config on Linux and macOS systems, or at %USERPROFILE%\.kube\config on Windows. You can view the contents of this file using a text editor or by running cat ~/.kube/config in your terminal.
Look for the clusters section within the YAML structure. Specifically, identify the server field under the relevant cluster entry. This field should contain the URL of the API server, which typically looks like https://:6443 . Compare this IP address with the public IP assigned to your Azure VM hosting the Kubernetes control plane. You can find this IP in the Azure Portal under the network interface associated with the VM or by using the Azure CLI command az vm show -d -g -n --query publicIps -o tsv .
If the IP addresses do not match, you need to update the kubeconfig file. Use the kubectl config set-cluster command to correct the server address. For example:
kubectl config set-cluster kubernetes \
--server=https://:6443 kubectl cluster-info to test the connectivity. If the TLS error persists, proceed to check the certificate details.
Checking Certificate Validity and SANs
Even with the correct IP address, TLS errors can occur if the server's certificate is invalid or does not include the requested IP in its Subject Alternative Names. Kubernetes clusters generated by tools like kubeadm or AKS usually handle certificate rotation automatically, but manual setups or older clusters might have stale certificates. You can inspect the certificate presented by the server using OpenSSL. Run the following command, replacing the IP and port with your cluster's details:openssl s_client -connect :6443 -showcerts Network Security Group Rules
While TLS errors primarily indicate certificate issues, sometimes they are misinterpreted symptoms of broader network connectivity problems. Check the Network Security Group attached to your Azure VM subnet or network interface. Ensure that an inbound rule allows TCP traffic on port 6443 from your client's IP address or CIDR range. If you are connecting from a dynamic IP address, consider whitelisting your entire home IP block or using a static IP for your management workstation. Additionally, verify that there are no outbound restrictions on the VM that might interfere with certificate revocation checks or OCSP responses, although this is less common for basickubectl operations.
Setting Timeout for Preceding Command in Kubectl Wait provides further insights into managing connection stability during cluster interactions.
Frequently Asked Questions
Why does the error mention 'x509: certificate signed by unknown authority'?
This specific message means your client does not trust the CA that issued the cluster's certificate. You likely need to add the cluster's CA certificate to your system's trusted store or specify it in your kubeconfig using thecertificate-authority field.
Can I bypass TLS verification for testing purposes?
Yes, you can use the--insecure-skip-tls-verify=true flag with kubectl commands, but this is highly discouraged for production environments as it exposes your cluster to man-in-the-middle attacks.
How do I check if my Azure VM is reachable on port 6443?
Use thetelnet or nc (netcat) command from your local machine: nc -zv 6443 . A successful connection indicates that the network path is open, isolating the issue to TLS or application-layer configurations.
What should I do if the certificate has expired?
If the certificate is expired, you must renew it. For kubeadm clusters, you can runkubeadm certs renew all followed by restarting the kubelet service to generate new valid certificates.