kubernetes connectivity ai_generated true

Unable to connect to the server: dial tcp: lookup cluster.example.com: no such host

ID: kubernetes/cluster-unreachable

Also available as: JSON · Markdown
85%Fix Rate
88%Confidence
50Evidence
2023-01-01First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
8 active

Root Cause

Cannot reach the Kubernetes API server. Kubeconfig may be wrong, credentials expired, or the cluster is down.

generic

Workarounds

  1. 90% success Verify kubeconfig points to the correct cluster API endpoint
    kubectl config view --minify
    # Check 'server' URL is correct and reachable:
    curl -k https://<cluster-api-server>:6443/healthz
    # Verify KUBECONFIG env var: echo $KUBECONFIG

    Sources: https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/

  2. 88% success Merge or switch kubeconfig context to point to the correct cluster
    # List available contexts:
    kubectl config get-contexts
    
    # Switch to the correct context:
    kubectl config use-context my-cluster-context
    
    # Merge another kubeconfig file:
    export KUBECONFIG=~/.kube/config:~/new-cluster-config
    kubectl config view --flatten > ~/.kube/config_merged
    mv ~/.kube/config_merged ~/.kube/config

    Sources: https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/

  3. 85% success Renew or refresh expired cluster credentials
    # For EKS:
    aws eks update-kubeconfig --name my-cluster --region us-east-1
    
    # For GKE:
    gcloud container clusters get-credentials my-cluster --zone us-central1-a
    
    # For kubeadm clusters with expired certs:
    kubeadm certs check-expiration
    kubeadm certs renew all
    
    # Restart kube-apiserver after cert renewal.

    Sources: https://kubernetes.io/docs/reference/access-authn-authz/authentication/

Dead Ends

Common approaches that don't work:

  1. Reinstalling kubectl 90% fail

    The issue is connectivity or configuration, not the kubectl binary

Error Chain

Frequently confused with: