Multi-Cluster Management

Kunobi supports connecting to multiple Kubernetes clusters at the same time. This lets you monitor, compare, and operate across clusters without disconnecting from one to access another.

Connecting Multiple Clusters

There is no limit to the number of clusters you can connect to simultaneously.

1. Navigate to the Clusters page
2. Click Connect on each cluster you want to work with
3. Each cluster shows its own status indicator, latency, and Kubernetes version

Switching the Active Cluster

The cluster selector lives in the bottom bar of the application. Click on the currently active cluster name at the bottom left to open the selector dialog.

The dialog shows all available clusters with their connection status. Connected clusters show a Disconnect button; others show Connect. Favorites appear at the top with a star icon and keyboard shortcuts (⌘1, ⌘2, etc.) for quick switching.

You can also search clusters by name using the search bar at the top of the dialog. The active cluster context is persisted per-tab if you're using tab navigation.

Keyboard Shortcuts

Open the cluster selector instantly with a global shortcut:

Action	macOS	Windows / Linux
Open cluster selector	⌘0	Ctrl+0
Switch to cluster 1–9	⌘1 – ⌘9	Ctrl+1 – Ctrl+9

Shortcut assignment priority: favorite clusters (in alphabetical order) are assigned first, then connected non-favorites fill the remaining slots. Reordering favorites on the Clusters page changes which cluster each shortcut points to.

Favorite Clusters

Mark clusters you use frequently with the star icon on the Clusters page. Favorites:

• Float to the top of the clusters list
• Are prioritized by the Auto-Select Cluster setting when you launch Kunobi
• Can be reordered via drag-and-drop on the Clusters page

Reordering favorites also changes keyboard shortcut assignment — ⌘1 / Ctrl+1 always maps to the first favorite, ⌘2 / Ctrl+2 to the second, and so on.

Auto-Select Cluster

When enabled, Kunobi automatically selects a cluster when you launch the app (or when you connect to a cluster), so you can go straight to exploring resources.

Configure this in Settings → General → Auto-Select Cluster. See General Settings for details.

Auto-Reconnect

If a cluster connection drops (e.g., due to a network interruption), Kunobi can automatically attempt to reconnect.

How It Works

Kunobi uses exponential backoff between retries: the first retry waits 1 second, each subsequent wait is multiplied by 1.5, up to a 30-second cap (1s → 1.5s → 2.25s → … → 30s). With the default of 10 retries, total recovery time is approximately 1 minute 45 seconds.

Each retry performs a two-level health check:

1. TCP reachability — verifies the cluster API server is reachable (5-second timeout)
2. K8s API version call — confirms the Kubernetes API is responding

Non-recoverable errors (authentication failures, certificate errors) skip retries immediately rather than waiting through all attempts.

Configuration

Configure the retry count in Settings → General → Auto-Reconnect Retries.

• Set to 0 to disable auto-reconnect entirely
• Increase the value for flaky or high-latency connections

Context Switching

Kunobi reads all contexts from your kubeconfig files (including files in custom directories if you've configured Context Watcher).

The Clusters page lists every available context. Connected clusters show their live status; disconnected ones can be connected with a single click.

Multiple Kubeconfig Files

If you manage multiple kubeconfig files (e.g., one per environment), configure the Context Watcher to point to the directory containing them. Kunobi will merge all contexts into a single list.

See Context Watcher for configuration details.

Tab Navigation

Kunobi supports browser-like tabs in the top bar. Each tab is independent and can show a different page (K8s Resources, Clusters, etc.).

Action	macOS	Windows / Linux
New tab	⌘T	Ctrl+T
Close tab	⌘W	Ctrl+W
Switch to tab 1–9	⌘⇧1 – ⌘⇧9	Ctrl+Shift+1 – Ctrl+Shift+9

You can also pin or unpin a tab by right-clicking it. Pinned tabs stay fixed on the left side of the tab bar and cannot be accidentally closed.

Independent Tab State

Each tab maintains its own state, including:

• Selected cluster — switch the active cluster in one tab without affecting others
• Filters and resource selection — each tab can explore different resource types or namespaces simultaneously
• Workspace selection — workspaces are assigned per-tab, so you can compare different workspace views side by side

Per-Cluster Preferences

Each cluster can have its own connection settings, independent of global defaults. This is useful when clusters have different security requirements, network configurations, or authentication flows.

To configure per-cluster preferences:

1. Navigate to the Clusters page
2. Click on the cluster to open the details sidebar
3. Switch to the Settings tab

Available options include:

• Accept Invalid Certificates — allow connections with self-signed or invalid TLS certificates
• Custom Timeouts — connection and read/write timeouts
• HTTP Proxy — route traffic through a proxy server
• Default Namespace — override the namespace from kubeconfig
• TLS Server Name — override the TLS Server Name Indication (SNI)
• OIDC Auth Timeout — timeout for OIDC authentication flows like kubelogin

See Clusters — Connection Settings for full details on each option.

Troubleshooting

Connection Errors

If a cluster shows an Error status, click on it to open the details sidebar and view the error message. Common causes:

• VPN not connected
• Cluster API server unreachable
• Expired or revoked kubeconfig credentials
• Certificate errors

See the Clusters page for full troubleshooting steps.

Stale Contexts

If you've added or removed clusters from your kubeconfig but they don't appear in Kunobi, the Context Watcher will automatically reload the list. You can also trigger a manual reload by navigating away from and back to the Clusters page.