Clusters and namespaces

Where contexts come from

kdashboard reads the contexts of one kubeconfig file: the path set in Settings, or ~/.kube/config when that is empty. Edits made to the file by other tools are picked up the next time the list is read.

Two things worth knowing:

• The KUBECONFIG environment variable is not used. If yours lists several files, either set the path of the one you want in Settings, or import the others into it.
• Switching context is written to the file. kdashboard updates current-context, exactly like kubectl config use-context, so your terminal follows.

Authentication is whatever the kubeconfig says: client certificates, tokens, and exec plugins such as aws, gcloud, az and kubelogin. kdashboard adopts the PATH of your login shell at start-up, so those plugins are found even when the app is launched from the Dock or a desktop launcher. TLS settings — CA, client certificate, insecure-skip-tls-verify — come from the kubeconfig too. HTTP proxies (proxy-url, HTTPS_PROXY) are not supported yet.

Use another kubeconfig

Settings (⌘,) → Kubernetes → Kubeconfig: type the path and Save. Leave it empty to go back to ~/.kube/config.

Import contexts

To merge the contexts of another kubeconfig — a file your cloud CLI wrote, or YAML a colleague sent you — into the active one:

1. Go to Settings → Kubernetes → Import another kubeconfig.
2. Type a path or click Browse…, or paste the YAML into the box. Then click Preview.
3. Tick the contexts you want. Each one is marked new, identical (already there; nothing to do) or conflict (same name, different contents).
4. For conflicts, your existing entry is kept unless you tick Overwrite conflicting entries.
5. Click Import.

Before it writes, kdashboard backs the file up next to the original as <file>.kdash-backup-<timestamp>. Only clusters, users, contexts and current-context are touched.

Remove a context

Settings → Kubernetes → Contexts, expand the context, Remove from kubeconfig. The cluster and user entries go with it if nothing else uses them. A backup is written first. You cannot remove the active context — switch to another one first.

Tell contexts apart

The rail shows initials taken from the context name. To make production impossible to mistake for staging, expand a context in Settings → Kubernetes → Contexts and give it:

• a label of up to three characters — PRD, STG, DEV;
• an icon — cloud providers, infrastructure, environments and generic shapes;
• a colour — accent, green, blue, yellow or red.

An icon takes precedence over a label in the rail. The X on the row resets all three.

Switching context

Click a tile in the rail, or press ⌘K and type the context name. A switch:

• closes your tabs and starts again from the Pods table,
• stops active port-forwards, and starts the saved forwards of the new context that have auto-start on,
• ends a running AI agent session, which is pinned to the context it started on.

The namespace picker

The picker sits in the toolbar of every namespaced table and view. It is hidden for cluster-scoped kinds such as Nodes.

• It lists the namespaces in which you may list pods, checked with a SelfSubjectAccessReview per namespace and cached for five minutes. If those checks fail, it shows every namespace rather than none.
• All namespaces is the first entry. In that mode tables gain a Namespace column; with a single namespace selected the column hides itself.
• Type to filter the list. You can also switch from the command palette: ⌘K, then the namespace name.
• One namespace at a time: there is no multi-select.

On a new context kdashboard selects default, or the first namespace you can read.

When a cluster goes away

• At start-up, an overlay titled Cluster connection lost shows the error and a Retry connection button.
• In the middle of a session, you keep the rows you had. A banner reads Cluster unreachable since 14:02 · showing data from 14:01, the context tile gets a red dot, and the table footer says Not watching. Click Retry when the cluster is back; watches resume where they left off.