kubectl "The connection to the server localhost:8080 was refused": your kubeconfig is missing

1. Confirm it

kubectl config view

apiVersion: v1
clusters: null
contexts: null
current-context: ""
kind: Config
preferences: {}
users: null

clusters: null is the proof. kubectl reads the files listed in $KUBECONFIG, or ~/.kube/config if that variable is empty. ~ depends on who you are, and that’s behind section 3.

2. Get a kubeconfig for your cluster

kubeadm, on the control plane:

mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

k3s keeps it elsewhere, and readable only by root:

mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $(id -u):$(id -g) ~/.kube/config

From another machine, also change server: https://127.0.0.1:6443 in that file to the server’s address.

Local clusters write it when they start, so start them:

minikube start
kind create cluster

Cloud clusters have a command that adds it:

aws eks update-kubeconfig --region eu-central-1 --name my-cluster
gcloud container clusters get-credentials my-cluster --region europe-west1
az aks get-credentials --resource-group my-group --name my-cluster

Then check:

kubectl config current-context
kubectl get nodes

3. It works without sudo, but not with it (or the reverse)

sudo kubectl runs as root, whose home is /root, so it reads /root/.kube/config, and sudo normally drops your KUBECONFIG too. You rarely need sudo for kubectl: permissions come from the config file, not your Linux user. Run it without sudo. If you must, pass the file:

sudo kubectl --kubeconfig=/home/me/.kube/config get pods

The same catches scripts, cron jobs and CI: they run with a different user or environment. Set KUBECONFIG explicitly there. In a pipeline, store it as a secret: the CI/CD Pipeline Generator shows one way.

4. Several files, or the wrong context

KUBECONFIG can list several files, separated by : on Linux and macOS:

export KUBECONFIG=~/.kube/config:~/.kube/staging.yaml
kubectl config get-contexts
kubectl config use-context staging

Put the export in your shell’s profile, or it’s gone in the next terminal.

5. When the address is a real one

If the error names your real server, kubectl has its config, and the problem is the connection:

The connection to the server 10.0.0.10:6443 was refused - did you specify the right host or port?

That’s a different job: the API server is down, or something’s in the way. On the control plane:

sudo ss -tlnp | grep 6443
sudo systemctl status kubelet --no-pager
sudo crictl ps -a | grep kube-apiserver

If it times out instead of being refused, look at firewalls, as “Connection timed out” vs “Connection refused” explains. The Port Lookup has an entry for 6443, and why it shouldn’t be open to everyone.