Cluster Registration

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 required kubeconfig shape
• what happens with one context vs. many contexts
• authentication expectations
• how to verify that registration worked
• discovering clusters through the UI or API
• removing stale clusters

What “registration” means in Console

The console discovers clusters from your kubeconfig.

• One working context → the console has one cluster target to query
• Multiple working contexts → the console can fan out across multiple cluster targets
• No working contexts → no clusters appear, or some cluster-backed features fail

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.

Required kubeconfig format

Your kubeconfig must contain the standard Kubernetes sections:

• clusters
• users
• contexts
• current-context

A 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-cluster

The console does not require a KubeStellar-specific kubeconfig extension. It expects the same file format that kubectl and client-go use.

Registration flow

1. Make sure the kubeconfig already works with kubectl

Before opening the console, confirm the contexts you want to use are valid:

kubectl config get-contexts
kubectl --context=dev-cluster get namespaces

If kubectl cannot reach the cluster, the console will not be able to use that context either.

2. Put every target cluster in the kubeconfig the console will read

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/config

3. Start the console in the mode you are using

• Local / source / curl install: start the console normally; it reads your kubeconfig automatically
• Helm / in-cluster install: run kc-agent on your workstation so browser-driven cluster actions can use your local kubeconfig

See Installation, Local Setup, and Troubleshooting for the deployment-specific details.

4. Verify the clusters appear

After startup:

1. Open the console
2. Go to cluster-aware dashboards such as Clusters
3. Confirm the clusters from your kubeconfig are visible and returning data

If a context is present in kubeconfig but unreachable, you may see partial data or connection errors instead of a clean registration.

Single-context vs. multi-context behavior

Single-context kubeconfig

If your kubeconfig contains one usable context, the console behaves like a single-cluster install. This is the simplest way to validate that registration is working.

Multi-context kubeconfig

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:

• Use clear, stable context names so operators can tell clusters apart
• Regularly review and remove stale contexts (see Removing stale clusters)
• Test each context individually with kubectl --context=...

Authentication expectations

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 ones that work with kubectl, including:

• bearer tokens
• client certificates
• exec-based auth plugins
• cloud-provider generated kubeconfigs

The important requirement is that authentication must work non-interactively on the machine running the console components that read kubeconfig.

That means:

• if an exec plugin is required, its binary must already be installed
• if a token is expired, renew it before opening the console
• if access depends on VPN or network reachability, that path must already be up
• if a context prompts for interactive login every time, fix that first in your normal kubectl workflow

Discovering clusters

Via the UI

The console provides a dedicated Clusters dashboard that displays all discovered clusters with live health information:

1. Open the console
2. Navigate to Clusters in the main menu
3. View all clusters from your kubeconfig with:
   • Health status (healthy, unhealthy, or initializing)
   • Node count
   • Pod count
   • Connection status

Via the API

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 once.

These APIs are available through the standard REST interface and require authentication (if enabled).

Removing stale clusters

When to remove a cluster

Over time, you may need to clean up stale cluster contexts from your kubeconfig:

• Clusters that are no longer in use
• Temporary dev/test clusters that have been decommissioned
• Duplicate contexts pointing to the same physical cluster
• Expired credentials that can no longer be renewed

How to remove a cluster

Via the UI

The console supports cluster removal through the Clusters page:

1. Navigate to Clusters
2. Identify the cluster you want to remove
3. Click the remove or delete option (if available in your UI)
4. Confirm the removal

Via the API (kc-agent required)

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:

• The context must exist in your kubeconfig
• You cannot remove the currently active context (set via current-context)
• If the cluster or user credentials are not referenced by any other context, they are also removed from the kubeconfig
• This operation modifies your local kubeconfig file

Via kubectl

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 one 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.

Troubleshooting cluster registration

No clusters appear

Check these first:

kubectl config get-contexts
kubectl config current-context
kubectl --context=<context-name> get namespaces

If those commands fail, fix the kubeconfig before troubleshooting the console.

Some clusters appear, but not all

Usually one or more contexts are stale, expired, or depend on auth plugins that are not available on the current machine.

Helm install shows “Agent Not Connected”

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.

Hosted demo cannot see my clusters

That is expected. The hosted demo is intentionally read-only and does not connect to your local kubeconfig.

Removing stale or unreachable clusters

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:

1. Open the Clusters dashboard
2. The unreachable cluster will appear with an “Unreachable” status or warning indicator
3. Click the cluster card and select the Remove Cluster button
4. Confirm the removal in the dialog

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 only 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.

Related docs

• Quick Start
• Installation
• Local Setup
• Architecture
• Security Model
• Troubleshooting