Sign In

Curriculum 3: Your First Kubectl Commands

Connecting to a Cluster

12 min · 15 XP

Connecting to a Cluster

kubectl is installed -- now you need to connect it to a Kubernetes cluster. This lesson explains how kubectl knows where your cluster is and how to authenticate.

What Is kubeconfig?

The kubeconfig file is a YAML file that tells kubectl everything it needs to connect to a cluster. It contains three key pieces of information:

  • Clusters -- the API server address and CA certificate for each cluster
  • Users -- credentials (tokens, certificates, or auth plugins) for authentication
  • Contexts -- named combinations that pair a cluster with a user and optionally a default namespace

A single kubeconfig file can hold configurations for multiple clusters, making it easy to switch between them.

Default kubeconfig Location

By default, kubectl looks for the config file at:

~/.kube/config

On macOS and Linux, that is your home directory. On Windows, it is typically C:\Users\<username>\.kube\config.

You can check if the file exists:

# Check for the kubeconfig file
ls -la ~/.kube/config

Most Kubernetes installers and cloud provider CLIs automatically create or update this file for you. For example, when you enable Kubernetes in Docker Desktop, it adds a context to your kubeconfig automatically.

Using the --kubeconfig Flag

If your config file is in a different location, you can point kubectl to it directly:

# Use a specific kubeconfig file
kubectl --kubeconfig=/path/to/my-config get pods

You can also set the KUBECONFIG environment variable:

# Set a custom kubeconfig path
export KUBECONFIG=/path/to/my-config

# Now all kubectl commands use that file
kubectl get pods

You can even merge multiple config files by separating paths with a colon:

export KUBECONFIG=~/.kube/config:~/.kube/staging-config

Checking Cluster Info

Once your kubeconfig is set up, verify the connection:

# Display cluster endpoint information
kubectl cluster-info

If the connection is working, you will see output like:

Kubernetes control plane is running at https://127.0.0.1:6443
CoreDNS is running at https://127.0.0.1:6443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

Verifying Your Connection

Here are several commands to confirm everything is working:

# List all nodes in the cluster
kubectl get nodes

# Show your current context
kubectl config current-context

# List all available contexts
kubectl config get-contexts

# Switch to a different cluster context
kubectl config use-context docker-desktop

If kubectl get nodes returns a list of nodes with a STATUS of "Ready," you are connected and ready to start working.

Troubleshooting Connection Issues

If you cannot connect, check these common issues:

# Is the kubeconfig file present?
cat ~/.kube/config

# Is the cluster reachable?
kubectl cluster-info

# Are you using the right context?
kubectl config current-context

Common errors and fixes:

  • "The connection to the server was refused" -- the cluster is not running or the address is wrong
  • "Unauthorized" -- your credentials have expired or are incorrect
  • "No resources found" -- you are connected, but the namespace is empty (this is actually success)

Key Takeaways

  • kubeconfig stores cluster addresses, credentials, and contexts
  • The default location is ~/.kube/config
  • Use --kubeconfig or the KUBECONFIG environment variable for custom paths
  • kubectl cluster-info and kubectl get nodes confirm a working connection
  • Most Kubernetes tools automatically configure kubeconfig for you