Clusters
v8s works on a selection of clusters, not one at a time. Every list, search, and the Problems view span whatever you have selected. v8s never connects to a cluster you have not selected.
Where clusters come from
On the desktop and with v8s serve, clusters are the contexts in your kubeconfig. v8s loads them the way kubectl does:
$KUBECONFIG(several paths are merged), otherwise~/.kube/config.--kubeconfig <path>onv8s serveorv8s agentto use one specific file.- New contexts show up without a restart.
In hosted mode, clusters come from the server's configuration, filtered to the ones your identity-provider groups allow.
Credentials and exec plugins
Each context authenticates the way its kubeconfig entry says: client certificates, bearer tokens, token files, or an exec credential plugin. Plugins that work with kubectl work here, including kubelogin (OIDC), aws eks get-token, gke-gcloud-auth-plugin, Azure kubelogin, Teleport tsh, and pinniped.
- Environment. Plugins run with the environment from your login shell, so
aws,gke-gcloud-auth-plugin, andkubeloginare found even when you launch the app from the macOS Dock or Finder. See Troubleshooting if a plugin is still not found. - Browser sign-in. A plugin that opens a browser (for example
kubeloginwith OIDC) shows "waiting for sign-in" on that cluster only. Other clusters keep working. When many contexts share one identity provider client, v8s runs the first sign-in once and the others reuse it, so you get one browser tab, not forty. - Plugins that prompt in the terminal (typing an MFA code) cannot be answered from v8s. Run the plugin once in a terminal to warm its cache, then connect.
- Proxies.
proxy-urlin a kubeconfig, andHTTPS_PROXY/NO_PROXY, are honored.
Choose clusters
Open the cluster selector in the top bar (or type :ctx).
- Tick the clusters you want, or click a group chip to select that group. Shift-click a chip to add it to the current ticks.
- Press Connect.
Ticking boxes connects nothing until you press Connect. A mistaken "select all" on 40 clusters costs nothing. On launch, v8s shows your last selection pre-ticked with a Connect button; it does not reconnect until you press it. Large selections connect in batches, so a stampede of exec plugins and API requests does not happen.
Deselecting a cluster stops its watches after a short grace period (ten seconds, so an accidental click is free) and frees the memory the agent held for it. Selecting it again is a cold start, which is cheap.
You can also change the selection from the keyboard. See the command bar:
:ctx prod-us staging connect exactly these two
:ctx +edge add one
:ctx -staging remove one
:ctx production a group name selects all its clustersGroups
A group is a named set of clusters, such as production, staging, or eu.
- Create one from the selector: tick clusters, choose + New group, and name it.
- Click a group chip to select exactly that group. Shift-click to add it.
- Manage lets you rename a group, change its members to the current ticks, or delete it.
- Mark a group as production. Destructive actions on clusters in a production group always require typing the object name (or the count) to confirm.
On a phone, group chips are the fast way to pick clusters. See On a phone.
Connection states
Each cluster shows its state next to its name in the selector and in the toolbar of multi-cluster views.
| State | What it means | What to do |
|---|---|---|
| not connected | Not selected, or selected but not yet connected. | Press Connect. |
| connecting | v8s is loading the context and running its credential plugin. | Wait. A browser sign-in may be open. |
| sign-in required | The credential is missing or expired. | Sign in again (run the plugin or kubectl once), then reconnect. |
| syncing | Connected; the first rows are arriving. The count shows rows loaded so far. Rows appear as they load. | Nothing. You can use the view while it syncs. |
| ready | Live. Updates arrive within a fraction of a second. | |
| degraded | Connected, but some resource types are forbidden or failing. The message says which, for example "no permission to list ingresses". | Ask for the RBAC, or ignore the affected checks. |
| reconnecting | The connection dropped. Last-known rows stay visible but greyed, marked "stale since" a time. | Wait. v8s retries with backoff. |
| unreachable | The API server cannot be reached. | Check VPN, network, and the server address. See Troubleshooting. |
A cluster that fails does not block the others. Its rows leave the merged views until it recovers, and an unreachable or expired cluster is itself reported as a critical problem in the Problems view.
Linked read and write contexts
Many setups give you two contexts per cluster: one that can only read, and one that can also write. With Warpgate these are two targets, for example prod-eu-operator (read-only) and prod-eu-cluster-admin (writes, during a time-boxed elevated session). v8s can link them so they behave as one cluster:
- Reads, watches, and the Problems view use the read context.
- When an action needs more than the read context can do, v8s runs it through the write context. The confirm dialog names the context it will use, and the cluster wears a small
writetag while it is in use. - Elevation, time limits, and approvals belong to your gateway. v8s adds none.
Link two contexts
- Open the cluster selector and choose Linked contexts… in its footer. The button shows how many links you have.
- Under Link a pair…, pick the Read context and the Write context, then press Link.
- The write context no longer appears as its own cluster.
If context names differ only by a role suffix (-operator and -cluster-admin), the dialog lists them under Suggestions, and the selector shows a note with a Review button. Press Link on a suggestion, Link all to accept every suggestion at once, or Dismiss to hide one. v8s never links by itself.
Use Unlink next to a pair in the same dialog to undo it. Unlinked contexts are ordinary, separate clusters.
Automatic switch
By default, writes switch to the linked write context automatically. If you untick Switch to the linked write context automatically when the read context is denied in the Linked contexts dialog, v8s asks first each time ("This will run as the write context prod-eu-cluster-admin") and proceeds only if you confirm.
Before the first write through a link, v8s checks that both contexts point at the same cluster (it compares the kube-system namespace UID). If they do not match, nothing is written and v8s tells you the link looks wrong.
"Write context rejected"
This means the cluster's write context refused the request. With a gateway, it almost always means your elevated session is not active: start or renew it in the gateway (Warpgate), then retry. Reads keep working in the meantime. Other rejections through the write context (admission webhooks, quota, validation) keep their own message, so read it. See Troubleshooting.
RBAC-aware actions
v8s asks the API server what you are allowed to do, as the endpoint sees you, and caches the answer for a minute. Buttons you cannot use are disabled with the reason ("You can't delete pods in payments"). If the cache is stale, you get a clean error toast, not a broken state. The API server remains the authority on every request.
If you can only access some namespaces, v8s falls back to watching those namespaces: the kubeconfig context's namespace plus a per-cluster namespace list you can extend as you navigate. In that mode it watches the core workload kinds in at most five namespaces by default, and says which namespaces it is showing.
Credentials, in one paragraph
Every request carries your own credential to whatever endpoint the context points at: the API server, or a gateway that authorizes and records you and forwards on. v8s has no gateway-specific mode; a gateway is just a Kubernetes endpoint with OIDC. Details are in Authentication.