API Server / kubectl Unreachable¶

Symptom¶

kubectl commands time out, fail TLS handshakes, or return unreachable-host errors even though the cluster still appears provisioned in Azure.

Possible Causes¶

Wrong or stale kubeconfig endpoint.
Valid RBAC but blocked network path to the API server.
Private DNS does not resolve the private API FQDN from the operator network.
Missing or broken private endpoint, peering, VPN, or ExpressRoute path.
Authorized IP ranges no longer include the operator egress IP.
Firewall, UDR, or proxy blocks API traffic.

Diagnosis Steps¶

flowchart TD
    A[kubectl cannot reach API server] --> B[Check cluster API settings]
    B --> C[Refresh kubeconfig]
    C --> D{Private cluster?}
    D -->|Yes| E[Resolve private FQDN and test private path]
    D -->|No| F[Check authorized IP ranges and public path]
    E --> G[Inspect peering, VPN, ExpressRoute, and private DNS]
    F --> H[Check firewall, proxy, and egress IP drift]
    G --> I[Retest readyz and node listing]
    H --> I

Confirm the cluster API exposure model and the FQDN currently published by AKS.

az aks show \
    --resource-group "$RG" \
    --name "$CLUSTER_NAME" \
    --query "{fqdn:fqdn,privateFqdn:privateFqdn,apiServerAccessProfile:apiServerAccessProfile,enablePrivateCluster:apiServerAccessProfile.enablePrivateCluster}" \
    --output yaml

Command	Purpose
`az aks show`	Show the API server FQDN and access profile.
`--resource-group`	Resource group that contains the AKS cluster.
`--name`	Name of the AKS cluster.
`--query`	Selects FQDN, private FQDN, and API server access profile.
`--output`	Output format for the result.

Re-download kubeconfig to eliminate a stale endpoint hypothesis.

az aks get-credentials \
    --resource-group "$RG" \
    --name "$CLUSTER_NAME" \
    --overwrite-existing

Command	Purpose
`az aks get-credentials`	Merge cluster credentials into the local kubeconfig.
`--resource-group`	Resource group that contains the AKS cluster.
`--name`	Name of the AKS cluster.
`--overwrite-existing`	Overwrite any existing kubeconfig entry for the cluster.

Test whether the client can reach the API server at all.

kubectl cluster-info
kubectl get --raw=/readyz
kubectl get nodes --request-timeout=10s

For private clusters, verify private DNS resolution from the operator environment.

nslookup <private-api-fqdn>
az network private-dns zone list \
    --resource-group "$RG" \
    --output table
az network vnet peering list \
    --resource-group "$RG" \
    --vnet-name "$VNET_NAME" \
    --output table

Command	Purpose
`nslookup`	Resolve the private API server FQDN.
`az network private-dns zone list`	List private DNS zones in the resource group.
`--resource-group`	Resource group that contains the private DNS zones.
`--output`	Output format for the result.
`az network vnet peering list`	List virtual network peerings.
`--resource-group`	Resource group that contains the virtual network.
`--vnet-name`	Name of the virtual network.
`--output`	Output format for the result.

For public endpoints, compare the operator egress IP with the authorized IP range configuration and inspect any firewall, proxy, or UDR path in front of the API traffic.

Resolution¶

Re-download kubeconfig if the local endpoint or certificate data is stale.
Fix private DNS zone links, forwarding rules, or resolver paths for the private API FQDN.
Connect from a network that actually reaches the private endpoint through VNet, peering, VPN, or ExpressRoute.
Update authorized IP ranges when operator egress IPs change.
Correct firewall, UDR, or proxy rules that block TCP 443 to the API endpoint.
Document and test a break-glass operator path from a known-good reachable network.

Prevention¶

Treat operator API access as a supported platform path with named owners.
Include private DNS resolution checks in private-cluster runbooks.
Review authorized IP ranges whenever outbound internet or VPN egress changes.
Avoid assuming API Server VNet Integration removes the need to validate operator connectivity.