Getting started

Adding a cluster manually

Kubius normally discovers clusters from your kubeconfig (~/.kube/config, or whatever KUBECONFIG points at). When a cluster isn’t in your kubeconfig - a ServiceAccount token you just minted, a raw client certificate, a one-off test endpoint - you can add it by hand instead of editing kubeconfig files. Kubius connects to it exactly the way it connects to a kubeconfig cluster; you’re just entering the details directly.

When to use it

You have a bearer / ServiceAccount token (from CI, automation, or a ServiceAccount you created) and the API server address.
You have an X.509 client certificate and key issued by the cluster’s CA.
The cluster simply isn’t in your kubeconfig and you don’t want to add it there.

If the cluster is already in your kubeconfig, you don’t need this - it appears in the cluster list automatically.

What you’ll need

The API server URL, e.g. https://10.0.0.12:6443.
One credential: either a bearer token, or a client certificate and its private key.
Optionally, the cluster’s CA certificate so Kubius can verify the server over TLS. Without it you can still connect by skipping verification (see below), but that’s only appropriate for local or test clusters.

Adding the cluster

Open Add cluster - it’s at the bottom of the CLUSTERS list in the sidebar, and as Add a cluster manually on the connect screen when you’re not connected to anything yet.
Give it a display name - this is just how it’s labelled in Kubius.
Enter the API server URL (it must start with https://).
Set up TLS:
- Paste the CA certificate (PEM) or use Choose CA file… to load a .crt/.pem, or
- turn on Skip TLS verification to trust any server certificate. This disables a real security check, so use it only for local/test clusters.
Optionally set a default namespace (defaults to default).
Pick an authentication method and fill it in (details below).
Click Add & connect. Kubius saves the cluster and connects straight away.

Manually-added clusters are tagged with a violet DEV badge in the cluster list so you can tell them apart from kubeconfig contexts at a glance.

Bearer / ServiceAccount tokens

A long-lived token string sent to the API server as an Authorization: Bearer … header. ServiceAccounts use these heavily for automation and CI/CD.

To mint a short-lived token for a ServiceAccount:

kubectl create token <serviceaccount> -n <namespace>

Paste the token into the Token field, or use Choose token file… to load it from a file. Treat tokens like passwords - anyone holding one can act as that account until it expires or is revoked.

X.509 client certificates

The cluster’s certificate authority signs a personal certificate for you; your identity is the certificate, and requests are authenticated by the matching private key over mutual TLS. This is common on self-managed/kubeadm clusters.

Provide both:

Client certificate - the .crt (PEM), pasted or loaded with Choose .crt file….
Client key - the matching .key (PEM), pasted or loaded with Choose .key file….

Client certificates are hard to revoke without rotating the CA, so keep the key safe and prefer short-lived certs where you can.

Testing it against a GKE cluster

You don’t need a special cluster to try this out - a single GKE cluster is enough to exercise the token method, and it’s a real test because the token talks to the API server directly, bypassing the gke-gcloud-auth-plugin.

Create a ServiceAccount, give it read access, and mint a token:

kubectl create serviceaccount kubius-test -n default
kubectl create clusterrolebinding kubius-test \
  --clusterrole=view \
  --serviceaccount=default:kubius-test
kubectl create token kubius-test -n default --duration=24h

Grab the two cluster details the form needs:

# API server URL
kubectl config view --minify --raw -o jsonpath='{.clusters[0].cluster.server}'; echo
# CA certificate (PEM)
kubectl config view --minify --raw \
  -o jsonpath='{.clusters[0].cluster.certificate-authority-data}' | base64 -d

Then in Add cluster choose Bearer / ServiceAccount token, paste the token, the API server URL and the CA (or toggle Skip TLS verification to leave the CA out on a first attempt). Use cluster-admin instead of view if you want to see everything. Clean up afterwards:

kubectl delete clusterrolebinding kubius-test
kubectl delete serviceaccount kubius-test -n default

GKE doesn’t hand out client certificates, so the client-certificate method is easiest to try against a local kind or minikube cluster (their kubeconfig already embeds a client cert + key you can copy straight into the form).

Where your details are stored

Kubius keeps the two kinds of data apart:

Non-secret fields (display name, server URL, CA certificate, namespace) are saved in the app’s support folder.
Secrets (your token, or your client certificate and key) are stored in the macOS Keychain - never written to disk in plain text. They’re scoped per Kubius build, so they never leak between installs.

Removing a cluster

Right-click a manually-added cluster (the ones with the DEV badge) and choose Remove Cluster. Kubius removes it from the list and deletes its Keychain secrets. This only affects Kubius - the cluster itself is untouched.