First cluster

After you install Kubron and create your local administrator, the app is empty until you add a cluster.

Before you start

You need a way to reach the cluster:

• a kubeconfig file. The default one is ~/.kube/config (on Windows %USERPROFILE%\.kube\config), or whatever your KUBECONFIG variable points to;
• network access from your computer to the cluster's API server (VPN, bastion rules and so on are up to you);
• if the kubeconfig uses an exec credential plugin that Kubron does not handle itself, that command installed and on your PATH. Kubron signs in to Azure AKS, AWS EKS and Google GKE on its own; for any other plugin it shows the command and asks you to confirm before running it. See Connecting to Kubernetes.

Check that it works with any tool you have. If kubectl get nodes works, Kubron will too. Kubron itself does not need kubectl.

Add the cluster

1. Open Settings → Clusters or the cluster switcher and choose Add cluster.
2. Give it a name, for example Production EU.
3. Under Connection, choose the kubeconfig source:
   • File: pick your kubeconfig file;
   • Paste text: paste the contents of a kubeconfig.
4. Under Appearance, set an optional color, icon and environment tag (dev, test, stage, prod). These stay visible everywhere, which makes it much harder to run a command against production by accident.
5. (Optional) If the cluster runs Argo CD behind an Ingress, enter its published address so Kubron opens it directly instead of forwarding a port.
6. Click Add cluster.

Kubron copies the kubeconfig contents into its own folder (your original ~/.kube/config is not changed), readable only by you. If you later change the original file, use the cluster settings to replace the stored copy.

Several contexts in one file

If your kubeconfig contains several contexts, add the cluster once per context and give each a clear name and tag.

Limited access? It still works

Kubron does not require cluster-wide list permission. If you can only see certain namespaces, restrict the namespace set in the cluster settings. Kubron shows what you are allowed to see and reports what it could not read, rather than an empty screen.

What you get

Kubron uses shared informers, so lists and the dashboard stay live without hammering the API server. Open the dashboard for health, problem pods and recent changes, or browse resources.

Multiple clusters

Keep as many clusters as you like and switch between them from a single window. Each cluster keeps its own namespace filter and view state.

Troubleshooting

Symptom	Likely cause
Connection test times out	The API server is not reachable from your computer: VPN, firewall or proxy
x509: certificate signed by unknown authority	The kubeconfig lacks the cluster CA, or a corporate proxy re-signs TLS
Unauthorized or Forbidden	Expired token or missing RBAC permissions for your user
A sign-in dialog appears	The cluster needs interactive sign-in (OIDC, AKS, EKS, GKE or an exec plugin). Follow the dialog; see Connecting to Kubernetes
An exec plugin fails	The plugin command is not installed or not on the PATH seen by the app (see Desktop edition)

Using the Web edition? The kubeconfig rules differ: see Connecting to Kubernetes and the Web quick start.