Connecting to Clusters

Kubezilla supports three kubeconfig sources. You can mix them in a single session and even open multiple cluster windows at once.

Source types​

Type	When to use
Local File	Standard ~/.kube/* configs or any file on disk
SSH Remote	Cluster's API server is reachable only from a bastion / jump host
Inline YAML	Pasted config (from a CI artifact, vault, or Slack message)

All three can optionally route traffic through an SSH tunnel — useful when the API server is on a private network.

Adding a kubeconfig​

Open Dots menu → Kubeconfigs (or the Kubeconfigs dialog from the kubeconfig dropdown), then click Add.

Local File​

1. Choose Local File.
2. Click Browse and select the kubeconfig.
3. (Optional) Enable Route through SSH tunnel and fill in the SSH fields below.
4. Save.

On macOS sandboxed builds, each file must be granted access individually — the picker creates a persistent security bookmark.

SSH Remote​

Use this when the kubeconfig lives on a remote host (bastion, jump box, dev VM).

1. Choose SSH Remote.
2. Fill in:
   • Host — SSH address (user@host, host.example.com, etc.). Autocomplete suggests entries from ~/.ssh/config.
   • Port — defaults to 22.
   • User — defaults from SSH config or current username.
   • Remote kubeconfig path — e.g. ~/.kube/config. Leave it empty to look for one: your own ~/.kube first, then k3s's /etc/rancher/k3s/k3s.yaml. For a cluster both describe, your own kubeconfig is used (k3s's file holds admin credentials); a k3s file you cannot read is skipped.
   • Use sudo — tick it only if the kubeconfig can be read only as root. It needs passwordless sudo (NOPASSWD); if the host asks for a password, the kubeconfig is read without sudo.
3. Pick an auth method (see below).
4. Click Test Connection to verify.
5. Save.

Inline YAML​

1. Choose Inline YAML.
2. Paste the kubeconfig content.
3. (Optional) Enable Route through SSH tunnel.
4. Save.

SSH auth methods​

Method	What it does
Auto	Tries SSH agent first, then falls back to config-specified keys
SSH Agent	Uses your running agent (ssh-agent, gpg-agent, KeePassXC)
Password	Prompts for password — stored only in memory for the session
Key File	Pick a private key; passphrase field appears if the key is encrypted
SSH Config	Uses ~/.ssh/config directives including ProxyJump

RSA keys negotiate with SHA2 (rsa-sha2-256 / rsa-sha2-512) automatically.

SSH tunnel option for Local/Inline configs​

If your kubeconfig references an API server URL that's only reachable from a bastion (e.g. https://10.0.0.5:6443), enable Route through SSH tunnel on the kubeconfig entry:

1. Fill in the SSH host/user/auth fields.
2. Kubezilla opens an SSH direct-tcpip channel for each kube API call.
3. Sessions are reused across entries that share the same SSH address — you only authenticate once per host.

The kubeconfig is not modified; the tunnel is transparent to the underlying kube client.

Switching between clusters​

Once multiple kubeconfigs are configured:

• Kubeconfig dropdown — type to filter the list.
• Context dropdown — switches contexts within the current kubeconfig (resets namespaces/kinds).
• Namespace dropdown — includes "All namespaces" for cluster-wide views. Per-context choice is remembered across sessions.

Connection timeouts​

• Kubernetes API calls: 5 seconds. If the API server is unreachable, the kubeconfig entry marks itself as errored and the UI moves on — other kubeconfigs stay usable.
• SSH connect: 15 seconds. Applies to SSH Remote entries and to Local/Inline configs with tunneling enabled.

Troubleshooting​

• Sudo is refused — "Use sudo" needs passwordless sudo (NOPASSWD in the remote sudoers). Without it the kubeconfig is read as your own user, so a root-only file stays unreadable.
• "permission denied (publickey)" — check the auth method. SSH Agent is the most common working path.
• "i/o timeout" on kube calls — your API server URL is not reachable; enable SSH tunneling.
• macOS "operation not permitted" on a file picked long ago — the sandbox bookmark expired. Re-add the kubeconfig.