Clusters

The Clusters page is your central hub for managing all Kubernetes cluster connections. View, connect, and manage multiple clusters from a single interface.

What You'll Find

The Clusters page displays all available Kubernetes contexts from your kubeconfig files in a searchable table.

Table Columns

• Favorite - Star icon to mark frequently-used clusters for quick access
• Shortcut - Quick-switch shortcut (e.g., ⌘1, ⌘2) assigned to favorited clusters
• Context Name - The name of your Kubernetes context
• Provider - Where the cluster comes from (e.g., Kind, Kunobi | Kind)
• Path - Location of the kubeconfig file
• Version - Kubernetes server version (shown when connected)
• Actions - Connect, disconnect, or open connection settings

Connecting to a Cluster

1. Find the cluster you want to connect to in the table
2. Click the Connect button in the Actions column
3. The status will change to Connecting (orange indicator)
4. Once connected, the status shows Connected (green indicator) with latency and version information

Once connected, you can explore the cluster's resources, namespaces, and workloads.

Cluster Details

Click on a cluster's name or row to open the details sidebar. The sidebar has two tabs: Details and Settings.

The Details tab shows:

• Connection Status - Current state with color-coded indicator and Kubernetes version (e.g., v1.32.8)
• Cluster Information
  • ID - Unique cluster identifier with copy button
  • Name - Context name
  • Config Path - Full path to the kubeconfig file with copy button
• Cluster Metrics (when connected)
  • CPU Usage and Memory Usage percentages
  • Total Resources - Node count, pod count, CPU and memory allocation

Connection Settings (Per-Cluster)

The Settings tab in the cluster details sidebar lets you configure connection preferences for each cluster individually:

• Accept Invalid Certificates — Allow connections to clusters with self-signed or invalid TLS certificates
• Default Namespace — Override the default namespace from kubeconfig
• Connection Timeout — How long to wait when establishing a connection (default: 30s)
• Read/Write Timeout — Timeout for API requests (default: 60s)
• HTTP Proxy — Route traffic through a proxy server
• TLS Server Name — Override the TLS Server Name Indication (SNI)
• OIDC Auth Timeout — Timeout for OIDC authentication flows like kubelogin (default: 60s)

Status Indicators

Clusters can be in different states, each with its own visual indicator:

• Disconnected (Gray text) - Not currently connected
• Connecting (Orange text) - Connection in progress
• Connected (Green text with latency/version) - Actively connected and ready to use
• Error (Red text) - Connection failed or cluster unavailable

When a cluster is connected, the table row shows additional information including response latency and Kubernetes version.

Connection States

Connecting:

Connected:

Error:

Disconnecting from a Cluster

You can disconnect from a cluster in two ways:

From the table:

1. Find the connected cluster (shows green "Connected" status)
2. Click the Disconnect button in the Actions column
3. The status will change to Disconnected

From the details sidebar:

1. Open the cluster details by clicking on its name
2. Click the Disconnect button at the bottom of the sidebar

You can reconnect at any time by clicking Connect again.

Searching Clusters

Use the search box at the top right (⌘F shortcut) to quickly find clusters by context name or path.

Favorite Clusters

Click the star icon next to any cluster to mark it as a favorite. This helps you quickly identify your most frequently-used clusters.

Quick Switch Shortcuts

Favorited clusters get keyboard shortcuts assigned automatically: ⌘1 through ⌘9 (macOS) / Ctrl+1 through Ctrl+9 (Windows/Linux).

• Assignment order — Favorite clusters alphabetically first, then connected non-favorite clusters alphabetically
• Up to 9 shortcuts are available at a time
• Shortcuts are visible in the Shortcut column on the clusters table

This lets you instantly switch between your most important clusters without reaching for the mouse.

Recent Clusters

Kunobi automatically tracks recently accessed clusters to help you pick up where you left off.

• A Recent badge appears on recently used clusters
• Connected clusters are automatically considered recent
• Useful for quickly identifying which clusters you've been working with across sessions

Troubleshooting

Connection Errors

When a cluster shows an Error status, click on the cluster name to open the details sidebar and view the error details:

The sidebar will display:

• Connection Error indicator (red)
• Error Details with copy button - Shows the specific error message (e.g., "Kubernetes API Error: ServiceError: Client error (Connect)")

Common solutions:

• Verify the kubeconfig file exists and is valid
• Check that the API server is accessible
• Ensure you have network connectivity to the cluster
• Verify your kubeconfig credentials are valid
• Check if the cluster requires VPN or specific network access

Auto-Reconnect Behavior

When a connection drops, Kunobi uses exponential backoff to automatically reconnect:

• Starts at 1 second, increases up to 30 seconds between attempts
• Two-level health check — TCP reachability first, then K8s API verification
• Non-recoverable errors (authentication failures, certificate errors) skip retries and show Error immediately
• Default: 10 retry attempts (~1 minute 45 seconds to exhaust)
• Configure in Settings → General → Auto-Reconnect Retries