Connect your clusters
The Clusters page, where clusters come from, and how to add EKS, GKE and AKS clusters without editing a kubeconfig.
Kubebay reads your kubeconfig, so every context you can use with kubectl is already a cluster in Kubebay. It reads KUBECONFIG if it’s set, or else ~/.kube/config, and picks up changes to the file as you make them.
The Clusters page
Clusters is the first page Kubebay opens. To come back to it later, click Clusters at the top of the sidebar.
Each row is one context:
- Session: Active for the cluster you’re looking at, Connected for one that’s streaming in the background.
- API: whether the engine can reach the API server. It shows Reachable, Degraded, Unreachable or Config error. Hover over it to see the error and when it was last checked. Connected clusters are checked every 30 seconds; the others are checked when you open this page, at most every 5 minutes each, so with a very large kubeconfig a cluster you have not connected to may show Checking for a moment. With more than 100 clusters the table shows only the rows on screen as you scroll.
- Version: the Kubernetes version.
- Pods and Nodes: counts for connected clusters. The pod bar shows healthy, pending and failing pods.
- CPU · 7 days: hourly peaks over the last week, from usage history.
- Requests: how much of the nodes’ allocatable CPU and memory the pods request.
Drag the right edge of a column header to resize it, as in the Pods table. The Name column starts wide enough to show a full cluster name.
Search by name, context or server to narrow a long list. Click a row to connect and open the cluster’s Overview. A row with a config error opens its error instead.
A cluster’s menu
The ⋮ at the end of a row has:
- Connect in background keeps a cluster streaming without switching to it. Disconnect stops it. Disconnect all, above the list, stops every cluster.
- Pin to top keeps a cluster first in the list.
- Rename… sets a display name. Your kubeconfig isn’t changed.
- Change icon… picks the icon shown in the cluster rail. Choosing a colour changes only the colour; edit the Label (up to three letters) separately.
- Copy context name and Copy server URL.
- Configure Prometheus… sets this cluster’s Prometheus URL, for history graphs. See Settings.
- Open in Rancher appears for clusters Rancher manages.
- Remove from list… hides a context from Kubebay. Show brings it back.
Switching clusters
Kubebay keeps at most 5 clusters streaming at once. Connect a sixth and the one you looked at longest ago goes to sleep: its live updates stop and its memory is released. A sleeping cluster shows a dashed marker on the cluster rail, and clicking it connects it again with fresh data. The cluster you’re on and your pinned clusters never go to sleep. A cluster you haven’t looked at for 30 minutes sleeps too. Change the numbers in Settings, or start the engine with --warm-clusters N (or KUBEBAY_WARM_CLUSTERS, 0 for no limit, at most 50) and --warm-idle 10m (or KUBEBAY_WARM_IDLE, 0 for never) to change this. It does not apply when Kubebay runs in a cluster or with OIDC, where streams are shared between users.
A sleeping cluster is labelled Sleeping in the Session column of the cluster list too, and opening it wakes it. Kubebay also caps the rows it holds in the browser across all connected clusters (about 50,000): past that, the cluster you looked at longest ago goes to sleep the same way. After a dropped connection (a laptop waking), the cluster you’re on and your pinned clusters reconnect first and the others follow over about two seconds.
The cluster rail at the far left shows an icon for each cluster you’re connected to. Click an icon to switch. Right-click one to change its icon. While Kubebay switches, it shows each step: credentials, the API server, then the live stream.
Adding kubeconfig files
Click Add kubeconfig on the Clusters page to open Kubeconfig sources. It lists the files Kubebay has loaded. To add another, type its path and click Add file. Its contexts are merged with your default kubeconfig.
Tick Use only the files listed above to ignore ~/.kube/config and KUBECONFIG, for example to keep work and personal clusters apart.
Finding cloud clusters
The same dialog can find clusters in your cloud accounts, using the CLIs you already have:
- Find EKS clusters runs your
awsCLI with a profile and regions you choose. - Find GKE clusters runs
gcloudfor a project. Imports sign in withgke-gcloud-auth-plugin. - Find AKS clusters runs
azfor a subscription. Only clusters that sign in with Microsoft Entra ID can be imported, throughkubelogin.
Nothing runs until you click. An import writes a kubeconfig that Kubebay owns, in ~/.kubebay/discovered. Your own kubeconfig is never changed.
When you can’t list namespaces
Some identities may only use a few namespaces. Kubebay still works for them. The namespace filter says You can’t list namespaces on this cluster and offers the namespaces your kubeconfig context names. You can add others by typing them. Pages that read the whole cluster, such as the Overview, send you to Pods in those namespaces instead.