Connecting to a cluster (test)

Test content. This tutorial exists to check scrolling, the table of contents, image sizing, WebP conversion and the image modal. The text is long on purpose.

Connecting a desktop client to a Kubernetes cluster sounds like a single step, but in practice it is a chain: a kubeconfig file, a context inside it, credentials that are still valid, and a network path to the API server. When any link breaks, the error message usually describes the symptom rather than the cause. This guide walks through each link in order, so you can tell where a connection fails and fix the right thing.

Before you start

You need three things before connecting:

1. A kubeconfig file. Most cluster providers can generate one for you. By default, Kubernetes tools read ~/.kube/config, or the files listed in the KUBECONFIG environment variable.
2. Network access to the API server. If the cluster is private, you may need a VPN, a bastion host or an SSH tunnel first.
3. Valid credentials. Tokens and client certificates expire. Cloud providers often use an exec plugin that fetches short-lived tokens on demand.

If you already use kubectl from the same machine, the desktop client can read the same files, and nothing extra is needed.

Checking your kubeconfig

A kubeconfig has three lists — clusters, users and contexts — plus a pointer to the current context. A minimal file looks like this:

apiVersion: v1
kind: Config
clusters:
  - name: production
    cluster:
      server: https://203.0.113.10:6443
      certificate-authority-data: LS0tLS1CRUdJTi...
users:
  - name: production-admin
    user:
      client-certificate-data: LS0tLS1CRUdJTi...
      client-key-data: LS0tLS1CRUdJTi...
contexts:
  - name: production
    context:
      cluster: production
      user: production-admin
      namespace: default
current-context: production

A context is just a named pair of which cluster and which user, with an optional default namespace. Most connection problems come from a context that points at a cluster or user entry that no longer exists, or that exists in a different file.

Several files at once

KUBECONFIG can list several files, separated by : on Linux and macOS and by ; on Windows. Tools merge them in order; the first file that sets a value wins. This is convenient, but it also means that an old file early in the list can silently override a newer one.

export KUBECONFIG="$HOME/.kube/config:$HOME/.kube/staging.yaml"
kubectl config get-contexts

If a context shows up twice in that list, rename one of them so you always know which one you are using.

Sharpness test

A 665px UI screenshot (PNG upload). It should look exactly as sharp as the original.

Adding the cluster

The screenshot below is a large PNG upload. On publish it is converted to WebP, and the page serves a copy sized for your screen.

Open the cluster list and choose the context you want. The client reads the same contexts as kubectl, so the names should look familiar. If the list is empty, the client could not find a kubeconfig: check the path and the KUBECONFIG variable that the desktop session sees. Variables set in a terminal profile are not always visible to apps started from the desktop.

Choosing a default namespace

Every context can carry a default namespace. Setting it saves you from picking a namespace each time and reduces the chance of running a command against the wrong one.

kubectl config set-context --current --namespace=payments

The setting is stored in the kubeconfig file itself, so every tool that reads that file picks it up.

Naming contexts so you can tell them apart

Cloud tools tend to generate long context names that include an account ID, a region and a cluster name. Renaming them makes the cluster list easier to scan:

kubectl config rename-context arn:aws:eks:eu-north-1:123456789012:cluster/prod prod-eu

Short, consistent names — for example prod-eu, staging-eu, dev-local — also make it obvious when you are about to act on production.

Authentication

Kubernetes supports several ways to prove who you are. Which one your cluster uses depends on how it was set up.

Client certificates

Certificates embedded in the kubeconfig work offline and need no extra tools, which makes them common on self-managed clusters. Their weakness is expiry: when a certificate runs out, every request fails with Unauthorized, and nothing in the error says expired. You can check the end date like this:

kubectl config view --raw -o jsonpath='{.users[0].user.client-certificate-data}' \
  | base64 -d | openssl x509 -noout -enddate

Exec plugins

Managed clusters on AWS, Google Cloud and Azure usually configure an exec plugin. Instead of storing a token, the kubeconfig names a command that prints one. The client runs that command whenever it needs fresh credentials.

users:
  - name: prod-eu
    user:
      exec:
        apiVersion: client.authentication.k8s.io/v1beta1
        command: aws
        args: ["eks", "get-token", "--cluster-name", "prod"]

This only works if the command is installed and on the PATH that the desktop client sees. A very common failure is a CLI installed through a shell-only package manager, which works in the terminal but is invisible to desktop apps.

OIDC

With OIDC, you sign in through your identity provider in a browser, and the cluster trusts the token it issues. Tokens are short-lived and refreshed in the background. If refresh fails — for example because your session at the identity provider ended — sign in again and the connection recovers.

Network paths

Even with valid credentials, the client has to reach the API server.

The screenshot above was uploaded as a JPEG and converted to WebP on publish, because the WebP version came out smaller.

Public endpoints

Many managed clusters expose a public endpoint protected by authentication, and optionally by an IP allow-list. If your office or home IP changes, an allow-list can start rejecting you overnight. The symptom is usually a timeout rather than an error.

Private endpoints

Private clusters only accept connections from inside their network. Common ways in:

• VPN into the cluster's network. Simple once set up; the client needs no changes.
• Bastion host with an SSH tunnel that forwards a local port to the API server.
• Cloud-native proxies, such as connecting through a managed bastion service.

With an SSH tunnel, point the kubeconfig at the local end of the tunnel:

ssh -N -L 6443:10.0.0.10:6443 user@bastion.example.com

clusters:
  - name: private-prod
    cluster:
      server: https://127.0.0.1:6443
      tls-server-name: kubernetes.default.svc

The tls-server-name field keeps certificate validation working even though you are connecting to 127.0.0.1.

Corporate proxies

Behind an HTTP proxy, set proxy-url on the cluster entry instead of relying on environment variables, so every tool behaves the same:

clusters:
  - name: prod-eu
    cluster:
      server: https://prod.example.com
      proxy-url: http://proxy.corp.example.com:3128

Troubleshooting

When a connection fails, work from the bottom up: network first, then TLS, then authentication, then authorization.

The animation above is a GIF. GIFs are never converted or resized, so animations keep working. It also uses #nozoom at the end of its URL, so it shows as a plain image and does not open the full-size view.

Timeouts

A timeout means nothing answered. Check that the server address is right, that a VPN or tunnel is up, and that no allow-list blocks your IP. From a terminal:

curl -k https://203.0.113.10:6443/healthz

Any HTTP response — even 401 or 403 — proves the network path works.

Certificate errors

x509: certificate signed by unknown authority means the client does not trust the server's certificate. Usually the certificate-authority-data in the kubeconfig belongs to a different or rebuilt cluster. Download a fresh kubeconfig from the provider rather than turning off verification.

Unauthorized

401 Unauthorized means the server did not accept your credentials at all: an expired certificate, a revoked token, or an exec plugin that failed. Run the plugin command by hand to see its real error message.

Forbidden

403 Forbidden is different: the server knows who you are, but your role does not allow the action. This is RBAC, not connectivity. Ask what you are allowed to do:

kubectl auth can-i list pods --namespace payments
kubectl auth can-i --list --namespace payments

Slow connections

If the connection works but everything feels slow, the usual causes are a distant region, a congested VPN, or an exec plugin that fetches a new token on every request because its cache directory is not writable.

Working with several clusters

Once the first cluster works, adding more follows the same steps. A few habits keep multi-cluster work safe:

• Give production contexts names that stand out, and never make production the default context.
• Keep one kubeconfig file per environment, and combine them with KUBECONFIG only when needed.
• Remove contexts for clusters that no longer exist, so stale entries do not confuse anyone.
• Review who has access to each kubeconfig; a file with an embedded admin certificate is as sensitive as a password.

Switching quickly

Switching context changes which cluster every following command talks to. Make a habit of checking the current context before acting:

kubectl config current-context

Summary

A working connection needs a kubeconfig with a valid context, credentials the cluster accepts, and a network path to the API server. When something fails, the error type tells you which of these to look at: timeouts point to the network, x509 errors to certificates, 401 to credentials and 403 to permissions. Fix the lowest broken layer first, and the rest usually follows.

Checklist

• The kubeconfig is in a path the client reads
• The context points at existing cluster and user entries
• Credentials are valid and not expired
• Exec plugins are installed and on the desktop PATH
• The API server is reachable from this machine
• Your role allows what you are trying to do