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.

What each status means:

Even a large kubeconfig stays responsive: the viewer probes clusters incrementally and Click Refresh re-probes everything.

Fan-Out Semantics

A multi-context command runs against every selected context at once and merges the results into one table. Rows are tagged with their source context, so two objects with the same name and namespace in different 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: a failing cluster shows its own banner rather than blanking the whole table, so one unreachable cluster doesn’t take down the others.

Pipeline steps (grep, filter, sortby, groupby, terminal views) run over the merged rows and refine the view instantly.

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 runs as the impersonated user (and groups, and UID, when you set them) 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 open view reloads under the impersonated identity, so what you see reflects that user’s access.
• Impersonation expires on its own: after 10 minutes with no keyboard or mouse activity, or 60 minutes from activation (whichever comes first).

If a request is denied 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 retried automatically; you re-run it under the new identity.

Edit this page on GitLab