Contexts and Clusters

Buoy is a multicluster tool. Every command runs against a single kubeconfig context by default, but you can fan a command out across several contexts at once and see the merged result as one live-updating table. The header bar, the contexts viewer, and the sidebar are the three surfaces for managing that state.

Contents

• The Header Controls
• Single-Context Mode
• Multi-Context Mode
• The Contexts Viewer
• Fan-Out Semantics
• The Sidebar
• Impersonation

The Header Controls

The header bar holds three relevant controls.

The header also shows a port-forward count chip when any forwards are active.

Single-Context Mode

The simplest case. The default context is the one selected in the header combobox; the default namespace is the one selected next to it. You can override either per-command:

pods -c prod-eu              # one-off context
pods -n kube-system          # one-off namespace
pods --context=prod-eu -A    # both

Set or clear defaults from the command bar:

/ctx prod-eu
/ctx -                       # clear
/ns production
/ns -                        # clear

Buoy remembers the last namespace per context. Switching back to a context restores that namespace.

Multi-Context Mode

When you want to operate against several clusters at once, switch to multi-context mode. Two ways to enable it:

/contexts prod-us,prod-eu,prod-ap     # explicit list, comma-separated, no spaces
/contexts -                            # clear back to single-context

Or open the contexts viewer (/contexts with no argument, or g c from anywhere) and select multiple checkboxes.

While multi-context mode is active:

• The header context combobox is replaced by a contexts N chip with the count of selected contexts. Click it to reopen the viewer. The X clears multi-mode and falls back to single-context.
• The header namespace combobox is disabled and shows (multi).
• Every command without an explicit -c or --contexts fans out across the selected contexts.

You can override fan-out per command:

pods --context=prod-eu          # bypass fan-out for one query
pods --contexts=a,b             # different fan-out for one query
pods --all-contexts             # fan out across every context in your kubeconfig

The contexts viewer’s checkbox model is direct: 0 selected clears defaults, 1 selected enters single-context, 2 or more enters multi-context.

The Contexts Viewer

/contexts (also /clusters) opens the cross-cluster viewer. It is a sortable, filterable table of every kubeconfig context. Rows render incrementally as data arrives, so a slow cluster never gates the rest of the view.

Status logic, in priority order:

1. Tauri exception, shown as error.
2. Reachability probe failed, shown as unreachable (red).
3. Reachability probe succeeded but a later read failed (typically RBAC denied on Node list), shown as partial (yellow).
4. Both probes succeeded, shown as ready (green).
5. Probes still in flight, shown as loading.

The viewer loads up to eight clusters in parallel so a 200-context kubeconfig does not exhaust your connection pool. Click Refresh to re-probe everything.

Fan-Out Semantics

A multi-context command spawns one watch per context, capped at sixteen concurrent starts. Each context’s watch behaves identically to a single-context one. Rows from different contexts are tagged with their source so collisions (same name and namespace across clusters) render as distinct rows; the source context is available to CEL expressions as context().

pods --contexts=a,b -A | groupby context()

Errors are reported per context. The watch list shows a banner per failing context rather than a single global error, so one unreachable cluster does not blank the others. Per-context timeouts surface as start timed out after 15 seconds.

Pipeline steps (grep, filter, sortby, groupby, terminal views) run client-side over the merged row stream. Editing them does not restart any watch.

The Sidebar

Press Cmd+B to toggle the sidebar. The sidebar is a navigation tree across clusters. It is independent of the active context: you can navigate one cluster without changing the default for new commands.

At the top, a search input filters the cluster list by name or kubeconfig cluster field. The list is split into Recently Used (the eight most recent contexts) and All Clusters (everything else). Status dots before each cluster name mirror the contexts viewer’s status colors.

Expanding a cluster reveals lazy-loaded groups:

• Cluster-scoped: Nodes, Namespaces, StorageClasses, PersistentVolumes, plus Karpenter NodePools, NodeClaims, and EC2NodeClasses when present.
• Namespaced: an inline namespace picker, then sub-groups gated on what the cluster has installed: Workloads (Pods, Deployments, StatefulSets, DaemonSets, Argo Rollouts and Workflows), Networking (Services, EndpointSlices, Ingresses, VirtualServices, Gateways, HTTPRoutes, GRPCRoutes), Storage (PersistentVolumeClaims), Argo (Applications, ApplicationSets, AppProjects), and Configuration (ConfigMaps, Secrets).

Drag the right edge to resize. Double-click the drag handle to reset to the default width. The width persists across sessions.

Impersonation

/as activates Kubernetes impersonation. Every read and every mutation thereafter sends Impersonate-User, Impersonate-Group, and Impersonate-Uid headers until you clear it.

/as alice
/as alice --groups platform,sre
/as alice --groups platform --uid 1234
/as
/as -

While impersonation is active:

• The app paints a red border around its perimeter. This overrides the active theme’s accent color so impersonated sessions are visually unmistakable.
• A header chip shows as: <user>. The X clears it.
• Every active watch restarts because the impersonation values are part of the watch key. New rows arrive under the impersonated identity.
• Idle and hard timeouts apply. After 10 minutes with no keystroke or mouse activity, or 60 minutes from activation (whichever comes first), Buoy clears impersonation automatically.

If you receive a 403 or 401 while impersonation is off and you have enabled “Impersonate on Auth Failure” in Settings, Buoy prompts you to activate /as with a recent or new identity. The failing action is not auto-retried; you re-run it under the new identity.

Edit this page on GitLab