Try Kubius
⌘K

Getting started

Connection problems

When Kubius can’t reach a cluster you’ll see “Connection failed - Couldn’t reach this cluster within 20 seconds…” in the sidebar (and a Couldn’t connect card during launch). Kubius deliberately gives up after 20 seconds rather than spinning forever. This guide covers what to check, plus the authentication specifics for GKE, EKS, AKS, and self-managed clusters.

First, isolate the problem

Run the same context in a terminal:

kubectl --context <your-context> get ns
  • Works in the terminal but not in Kubius → almost always an auth-plugin PATH issue (see the provider sections below). Kubius runs exec credential plugins through a login shell, but a tool installed somewhere only your interactive shell knows about can still be missed.
  • Fails in the terminal too → the problem is your environment or the cluster, not Kubius: VPN, credentials, or the cluster itself.

Things to watch for (any cluster)

  • The cluster no longer exists. Deleted clusters linger in your kubeconfig until you prune them. Remove stale entries:
kubectl config delete-context <name>
  • VPN / network. Private clusters and on-prem API servers are often only reachable over a VPN or through a bastion host - connect it first.
  • Expired credentials. Tokens and SSO sessions expire; re-authenticate (per provider below).
  • Wrong endpoint. A rebuilt cluster gets a new API-server address and certificate - refresh your kubeconfig.
  • Clock skew. A large system-clock drift breaks TLS certificate validation.
  • Firewall / authorized networks. GKE “authorized networks” or AWS security groups may block your current IP.

GKE (Google Kubernetes Engine)

GKE uses the gke-gcloud-auth-plugin exec credential plugin, which calls gcloud to mint a token.

  • Is the plugin installed?
gcloud components install gke-gcloud-auth-plugin
  • Are you authenticated? An expired login is the most common sudden failure:
gcloud auth login
  • Re-fetch the cluster credentials:
gcloud container clusters get-credentials <cluster> --region <region> --project <project>
  • PATH - Kubius invokes the plugin via a login shell. If gcloud or the plugin live somewhere only your interactive shell exports, install them to a standard location or make sure your login shell sets that path.
  • Confirm the cluster still exists:
gcloud container clusters list

  • Several Google accounts signed in? The plugin uses gcloud’s active account. If only one of your accounts can reach the cluster, either make it active (gcloud config set account you@example.com) or - better - right-click the cluster in Kubius → Authentication Options… and pick the account there. Kubius uses just that account for this cluster (via CLOUDSDK_CORE_ACCOUNT), without changing your global gcloud config.

  • “gcloud failed to load. You are running gcloud with Python 3.9, which is no longer supported.” Your Cloud SDK is using an unsupported Python. Point it at a 3.10–3.14 interpreter, then reconnect:

export CLOUDSDK_PYTHON=/opt/homebrew/bin/python3.12   # any 3.10–3.14

Make it permanent in your shell profile, or set the Python path per-cluster in Kubius via Authentication Options…. Reinstalling the Cloud SDK (which bundles a supported Python) also fixes it.

AWS (EKS)

EKS uses the aws eks get-token exec plugin (older kubeconfigs use aws-iam-authenticator).

  • Is the AWS CLI installed and on PATH?
aws --version

  • “Couldn’t find ‘aws’” even though aws --version works in Terminal? This almost always means aws was installed by a version manager (mise, asdf, pyenv) or into a non-standard directory that only reaches your PATH via interactive shell init - which a GUI-launched app doesn’t always inherit. Kubius checks the standard locations and the common version-manager shim dirs (~/.local/share/mise/shims, ~/.asdf/shims, ~/.pyenv/shims) automatically. If yours lives elsewhere, either symlink it into a standard bin (e.g. /usr/local/bin or /opt/homebrew/bin) or add its directory to your login shell profile (~/.zprofile), then retry. Confirm the real path with which aws.

  • SSO / IAM Identity Center. Make sure your SSO session is current - it expires regularly and the token is needed for aws eks get-token:

aws sso login --profile <profile>

Then make sure Kubius uses that profile for the cluster: right-click it → Authentication Options… → pick the AWS profile (Kubius applies it via AWS_PROFILE, no kubeconfig edit needed).

  • Check who you are (verifies static credentials):
aws sts get-caller-identity --profile <profile>
  • Right profile / region - the kubeconfig user usually pins an AWS_PROFILE and --region; make sure that profile is the one with cluster access. If you have several profiles and the wrong one is being used, right-click the cluster in Kubius → Authentication Options… and choose the profile (and region) for this cluster - Kubius applies it via AWS_PROFILE without editing your kubeconfig.
  • Refresh the kubeconfig:
aws eks update-kubeconfig --name <cluster> --region <region> --profile <profile>
  • MFA - if your role requires MFA, the session may have lapsed.
  • Private endpoint - if the cluster’s public endpoint access is disabled, the API server is only reachable from inside the VPC (VPN or bastion).

Azure (AKS)

AKS clusters with Microsoft Entra ID (Azure AD) integration use kubelogin as the exec credential plugin; it mints a token from your Azure login. Non-AAD clusters use a client-certificate admin kubeconfig and need none of this.

  • Are az and kubelogin installed and on PATH?
az version
kubelogin --version
  • Are you logged in to Azure? An expired session is the usual culprit:
az login
  • Which login mode is the kubeconfig using? Run kubelogin convert-kubeconfig -l <mode> to set it. For a desktop app the reliable modes are:
    • azurecli - reuses the token from az login (recommended; no extra prompts). Make sure you’ve run az login first.
    • devicecode - prints a code to enter in a browser. This needs interaction, so Kubius can’t complete it silently - switch the kubeconfig to azurecli instead.
kubelogin convert-kubeconfig -l azurecli
  • Refresh the kubeconfig (sets up the exec plugin again):
az aks get-credentials --resource-group <rg> --name <cluster> --overwrite-existing
kubelogin convert-kubeconfig -l azurecli
  • RBAC - Entra ID auth still needs an Azure role assignment (e.g. Azure Kubernetes Service Cluster User) and a Kubernetes RBAC binding for your identity.
  • Private cluster - a private AKS API server is only reachable over its private endpoint (VPN, Bastion, or a peered network).

Self-managed / traditional Kubernetes

These authenticate with whatever the kubeconfig embeds - a client certificate + key, a bearer token, or (rarely) basic auth - over TLS validated against the cluster CA.

  • Is the API server reachable? (No response = network/endpoint, not auth.)
curl -k https://<api-server>:6443/livez
  • Client certificate expired? Short-lived client certs (some kubeadm setups) expire - renew or regenerate them.
  • Token expired or revoked? ServiceAccount tokens get rotated; obtain a fresh kubeconfig.
  • CA mismatch - if the API server certificate was reissued, your kubeconfig’s certificate-authority-data is stale; update it.
  • Bastion / proxy - if the API server is only reachable through an SSH tunnel or HTTP proxy, establish that first.

How Kubius connects (useful to know)

  • Exec credential plugins (GKE / EKS / AKS) run through a login shell ($SHELL -l -c) so they inherit your normal PATH; Kubius retries with the other of bash/zsh if the first reports “command not found”.
  • Each connection is bounded by a 10-second deadline. If authentication, the TLS handshake, or the first request doesn’t complete in time, Kubius stops and shows the failure instead of hanging.
  • On failure, fix the cause and press Retry, or use Choose another to switch to a different cluster from the list.