In KubeStellar Console, cluster registration is kubeconfig-driven. If the console process (or kc-agent) can read a working kubeconfig context, that cluster becomes available to the console. You can add clusters through the Add Cluster UI dialog, which provides multiple methods: import an existing kubeconfig, connect manually, or use cloud provider quick-connect.
This page covers:
The console discovers clusters from your kubeconfig.
Important: the hosted demo at console.kubestellar.io cannot read your local kubeconfig, so you cannot register real clusters there. Use a local or self-hosted install instead.
Your kubeconfig must contain the standard Kubernetes sections:
clustersuserscontextscurrent-contextA minimal example looks like this:
apiVersion: v1
kind: Config
clusters:
- name: dev-cluster
cluster:
server: https://api.dev.example.com:6443
certificate-authority-data: <base64-ca-data>
users:
- name: dev-user
user:
token: <bearer-token>
contexts:
- name: dev-cluster
context:
cluster: dev-cluster
user: dev-user
current-context: dev-clusterThe console does not require a KubeStellar-specific kubeconfig extension. It expects the same file format that kubectl and client-go use.
Before opening the console, confirm the contexts you want to use are valid:
kubectl config get-contexts
kubectl --context=dev-cluster get namespacesIf kubectl cannot reach the cluster, the console will not be able to use that context either.
For local installs, this is usually ~/.kube/config.
If your clusters are split across multiple files, merge them first:
KUBECONFIG=~/.kube/config:~/.kube/cluster2.yaml:~/.kube/cluster3.yaml \
kubectl config view --flatten > ~/.kube/merged-config
mv ~/.kube/merged-config ~/.kube/configkc-agent on your workstation so browser-driven cluster actions can use your local kubeconfigSee Installation, Local Setup, and Troubleshooting for the deployment-specific details.
After startup:
If a context is present in kubeconfig but unreachable, you may see partial data or connection errors instead of a clean registration.
If your kubeconfig contains usable context, the console behaves like a single-cluster install. This is the simplest way to validate that registration is working.
If your kubeconfig contains multiple usable contexts, the console treats them as multiple cluster targets and queries them in parallel. This is the normal setup for multi-cluster fleet views.
Practical guidance:
kubectl --context=...The console uses the same authentication material your kubeconfig already uses. It does not mint new Kubernetes credentials and it does not send your kubeconfig to GitHub.
Common authentication patterns that work are the same that work with kubectl, including:
The important requirement is that authentication must work non-interactively on the machine running the console components that read kubeconfig.
That means:
kubectl workflowThe console provides a dedicated Clusters dashboard that displays all discovered clusters with live health information:
The console exposes cluster discovery through REST APIs:
GET /api/mcp/clusters
Returns all discovered clusters with cached health information:
{
"clusters": [
{
"name": "dev-cluster",
"healthy": true,
"nodeCount": 3,
"podCount": 42,
"neverConnected": false
},
{
"name": "prod-cluster",
"healthy": true,
"nodeCount": 10,
"podCount": 200
}
],
"source": "k8s"
}GET /api/mcp/clusters/:cluster/health
Returns detailed health data for a specific cluster:
{
"cluster": "dev-cluster",
"healthy": true,
"nodeCount": 3,
"podCount": 42,
"reachable": true,
"lastSeen": "2025-05-06T10:30:00Z"
}GET /api/mcp/clusters/health
Returns health information for all clusters at.
These APIs are available through the standard REST interface and require authentication (if enabled).
Over time, you may need to clean up stale cluster contexts from your kubeconfig:
The console supports cluster removal through the Clusters page:
Use the kubeconfig removal API to programmatically deregister clusters:
POST /kubeconfig/remove
Request body:
{
"context": "cluster-name"
}Example response on success:
{
"ok": true,
"removed": "cluster-name"
}Constraints:
current-context)You can also remove contexts directly using kubectl:
# Remove a specific context
kubectl config delete-context <context-name>
# View the updated list
kubectl config get-contexts
# Optionally reset current-context if it was the you deleted
kubectl config use-context <new-current-context>After removal, the context will no longer appear in the console’s cluster list on the next refresh.
Check these first:
kubectl config get-contexts
kubectl config current-context
kubectl --context=<context-name> get namespacesIf those commands fail, fix the kubeconfig before troubleshooting the console.
Usually or more contexts are stale, expired, or depend on auth plugins that are not available on the current machine.
For Helm deployments, kc-agent runs on your workstation, not inside the cluster. Without it, browser-driven cluster actions cannot use your local kubeconfig. See Troubleshooting.
That is expected. The hosted demo is intentionally read-only and does not connect to your local kubeconfig.
If a cluster in your kubeconfig becomes unreachable (e.g., it was decommissioned, network changed, or credentials expired), you can remove it from the console and clean up your kubeconfig:
This action removes the kubeconfig context from your local kubeconfig file, preventing stale entries from cluttering your cluster list and avoiding repeated connection attempts to unavailable clusters.
Note: This removes the context from the kubeconfig that the console reads. It does not affect the cluster itself. You can also manually edit your kubeconfig to remove contexts — see Multi-context kubeconfig for more guidance.