feat(operator): self-register and manage the host cluster (#5237)

* feat(operator): self-register and manage the host cluster

The operator now registers the cluster it runs ON as a Cluster resource
named "host" (labelled ksail.io/host-cluster) in its own namespace, so the
hub itself appears in the cluster list and its workloads can be browsed,
scaled, restarted, and reconciled through the dashboard — following the
pattern of Rancher's "local" cluster, Argo CD's "in-cluster" destination,
and Headlamp's in-cluster "main" context.

- A leader-gated startup runnable ensures the registration exists
  (idempotent; a same-named unlabelled cluster is never adopted).
- The reconciler skips provisioning/drift/components and the teardown
  finalizer for host-labelled clusters: it only observes status (endpoint,
  node readiness) through the operator's own credentials and reports
  Ready; ComponentsReady is Unknown (reason HostCluster). Deleting a
  host-labelled resource never invokes a provisioner.
- The resource browser resolves the host cluster to an in-cluster dynamic
  client instead of a vcluster kubeconfig Secret.
- The REST API rejects create/update/delete of the host registration with
  403 (kubectl remains the escape hatch; CR deletion only deregisters).
- The chart gains hostCluster.enabled (default true), the POD_NAMESPACE
  downward-API env, and host-browse RBAC (nodes/events read, metrics API,
  GitOps CRs read+patch).
- The UI badges the host cluster and hides edit/delete for it; the
  Overview no longer backfills create-form defaults into its empty spec.

Verified end-to-end against a throwaway Kind cluster: self-registration,
Ready status with live node counts, node browsing, and 403 lifecycle
guards.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* chore: Apply megalinter fixes

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: devantler <26203420+devantler@users.noreply.github.com>

Author: devantler

charts/ksail-operator/README.md

@@ -12,6 +12,7 @@ The operator reconciles `Cluster` resources (`ksail.io/v1alpha1`) so you can pro
 - **REST API** — served by the operator and consumed by the UI (toggle with `api.bindPort`).
 - **Web UI** _(optional)_ — a dashboard that talks to the REST API (`ui.enabled`).
 - **OIDC auth** _(optional)_ — app-driven OIDC login that protects the REST API and UI (`auth.oidc.enabled`).
+- **Host cluster registration** — the operator self-registers the cluster it runs on as a `Cluster` resource named `host` (labelled `ksail.io/host-cluster`) in the release namespace, so the hub itself appears in the cluster list and its workloads can be browsed in the UI — like Rancher's `local` cluster or Argo CD's `in-cluster` destination. The operator never provisions, updates, or deletes the underlying cluster for this entry, and the API rejects lifecycle mutations on it. Disable with `hostCluster.enabled=false`.
 
 > **Note:** The REST API is unauthenticated by default. Enable OIDC (`auth.oidc.enabled=true`) to require sign-in, or set `api.bindPort=0` to disable the API entirely when you don't need the UI.
 
@@ -135,6 +136,12 @@ Register the redirect URL with your provider, and point `ksail.local` at your In
 |----------------|--------------------------------------------------------------------------------------------|---------|
 | `api.bindPort` | Port the operator REST API listens on (consumed by the UI). Set to `0` to disable the API. | `8080`  |
 
+### Host cluster
+
+| Key                   | Description                                                                                                            | Default |
+|-----------------------|------------------------------------------------------------------------------------------------------------------------|---------|
+| `hostCluster.enabled` | Self-register the cluster the operator runs on as a `Cluster` resource named `host` so it appears in the cluster list. | `true`  |
+
 ### Web UI
 
 | Key                      | Description                                                               | Default                                                       |

charts/ksail-operator/templates/deployment.yaml

@@ -39,14 +39,20 @@ spec:
             {{- if .Values.ui.readOnly }}
             - --read-only
             {{- end }}
+            - --host-cluster={{ .Values.hostCluster.enabled }}
             {{- if .Values.auth.oidc.enabled }}
             - --oidc-issuer-url={{ .Values.auth.oidc.issuerURL }}
             - --oidc-client-id={{ .Values.auth.oidc.clientID }}
             - --oidc-redirect-url={{ include "ksail-operator.oidc.redirectURL" . }}
             - --oidc-scopes={{ .Values.auth.oidc.scopes }}
             {{- end }}
-          {{- if .Values.auth.oidc.enabled }}
           env:
+            # POD_NAMESPACE tells the operator which namespace to register the host cluster in.
+            - name: POD_NAMESPACE
+              valueFrom:
+                fieldRef:
+                  fieldPath: metadata.namespace
+            {{- if .Values.auth.oidc.enabled }}
             - name: KSAIL_OPERATOR_OIDC_CLIENT_SECRET
               valueFrom:
                 secretKeyRef:
@@ -57,7 +63,7 @@ spec:
                 secretKeyRef:
                   name: {{ include "ksail-operator.oidc.secretName" . }}
                   key: session-secret
-          {{- end }}
+            {{- end }}
           ports:
             {{- if .Values.api.bindPort }}
             - name: api

charts/ksail-operator/templates/rbac.yaml

@@ -68,6 +68,30 @@ rules:
     resources: ["roles", "rolebindings", "clusterroles", "clusterrolebindings"]
     verbs:
       ["get", "list", "watch", "create", "update", "patch", "delete", "deletecollection", "bind", "escalate"]
+{{- if .Values.hostCluster.enabled }}
+  # Host cluster browsing (hostCluster.enabled): the dashboard reads the hub itself through the
+  # operator's ServiceAccount. The workload kinds above already carry read/write verbs; these add
+  # the read-only kinds the resource browser needs (nodes, events), the metrics API powering the
+  # Overview's usage gauges, and the GitOps CRs (patched to trigger reconciles).
+  - apiGroups: [""]
+    resources: ["nodes", "events"]
+    verbs: ["get", "list", "watch"]
+  - apiGroups: ["metrics.k8s.io"]
+    resources: ["nodes", "pods"]
+    verbs: ["get", "list"]
+  - apiGroups:
+      - kustomize.toolkit.fluxcd.io
+      - helm.toolkit.fluxcd.io
+      - source.toolkit.fluxcd.io
+      - argoproj.io
+    resources:
+      - kustomizations
+      - helmreleases
+      - gitrepositories
+      - ocirepositories
+      - applications
+    verbs: ["get", "list", "watch", "patch"]
+{{- end }}
 {{- end }}
 ---
 apiVersion: rbac.authorization.k8s.io/v1

charts/ksail-operator/values.yaml

@@ -32,6 +32,15 @@ api:
   # Port the operator REST API listens on (consumed by the UI). Set to 0 to disable the API.
   bindPort: 8080
 
+# hostCluster self-registers the cluster the operator runs on as a Cluster resource (named "host",
+# labelled ksail.io/host-cluster, in the release namespace), so the hub itself appears in the
+# cluster list and its workloads can be browsed through the operator's ServiceAccount — like
+# Rancher's "local" cluster or Argo CD's "in-cluster" destination. The operator never provisions,
+# updates, or deletes the underlying cluster for this entry, and the API rejects lifecycle
+# mutations on it (kubectl-deleting the resource merely deregisters it until the next restart).
+hostCluster:
+  enabled: true
+
 # ui is the web dashboard. It is embedded in the operator binary and served by the operator itself
 # on the API port (api.bindPort) — same origin as the REST API, so there is no separate UI
 # container and no reverse proxy. Reach it via the ingress below or by port-forwarding the operator

docs/src/content/docs/cli-flags/operator/operator-root.mdx

@@ -19,6 +19,7 @@ Flags:
       --api-bind-address string            Address the REST API binds to (empty disables it, e.g. ":8080")
       --dev-logging                        Emit human-readable console logs instead of structured JSON (for local development)
       --health-probe-bind-address string   Address the health and readiness probes bind to (default ":8081")
+      --host-cluster                       Register the cluster the operator runs on as a Cluster resource (named "host") so it appears in the cluster list (default true)
       --leader-elect                       Enable leader election to ensure only one active operator instance
       --metrics-bind-address string        Address the metrics endpoint binds to ("0" disables it) (default "0")
       --oidc-client-id string              OIDC client ID (the client secret is read from KSAIL_OPERATOR_OIDC_CLIENT_SECRET)

internal/controller/cluster_controller.go

@@ -135,6 +135,11 @@ type ClusterReconciler struct {
 	// disables runtime status reporting (endpoint/nodes stay empty).
 	ObserveStatus StatusObserver
 
+	// ObserveHostStatus gathers runtime status for the self-registered host cluster (the cluster the
+	// operator runs on) through the operator's own credentials. Optional; nil disables runtime status
+	// reporting for the host cluster.
+	ObserveHostStatus StatusObserver
+
 	// InstallComponents installs the cluster's components into the provisioned child cluster.
 	// Optional; nil disables component installation.
 	InstallComponents ComponentInstaller
@@ -173,6 +178,14 @@ func (r *ClusterReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ct
 		return r.reconcileDelete(ctx, &cluster)
 	}
 
+	// The host cluster (the operator's self-registration of the cluster it runs on) is never
+	// provisioned or torn down, so it gets no finalizer and a status-only reconcile.
+	if cluster.IsHostCluster() {
+		log.Info("reconciling host cluster")
+
+		return r.reconcileHost(ctx, &cluster)
+	}
+
 	if controllerutil.AddFinalizer(&cluster, FinalizerName) {
 		updateErr := r.Update(ctx, &cluster)
 		if updateErr != nil {
@@ -264,6 +277,37 @@ func (r *ClusterReconciler) reconcileNormal(
 	return ctrl.Result{RequeueAfter: r.readyRequeue()}, nil
 }
 
+// reconcileHost reconciles the self-registered host cluster. The underlying cluster — the one the
+// operator runs on — already exists and is owned by whoever provisioned it, so there is nothing to
+// create, update, or delete: reconciliation only observes runtime status (node readiness, endpoint)
+// through the operator's own credentials and reports it. Component installation is intentionally
+// skipped; the host cluster's components are not the operator's to manage.
+func (r *ClusterReconciler) reconcileHost(
+	ctx context.Context,
+	cluster *v1alpha1.Cluster,
+) (ctrl.Result, error) {
+	before := cluster.Status.DeepCopy()
+
+	r.observeStatusWith(ctx, r.ObserveHostStatus, cluster)
+
+	apimeta.SetStatusCondition(&cluster.Status.Conditions, metav1.Condition{
+		Type:               v1alpha1.ConditionComponentsReady,
+		Status:             metav1.ConditionUnknown,
+		ObservedGeneration: cluster.Generation,
+		Reason:             "HostCluster",
+		Message:            "components on the host cluster are not managed by the operator",
+	})
+
+	r.markReady(cluster)
+
+	statusErr := r.updateStatusIfChanged(ctx, cluster, before)
+	if statusErr != nil {
+		return ctrl.Result{}, statusErr
+	}
+
+	return ctrl.Result{RequeueAfter: r.readyRequeue()}, nil
+}
+
 // reconcileComponents installs the cluster's components when they are not already reconciled for the
 // current generation, recording the outcome in the ComponentsReady condition. Best-effort: failures
 // are reported via the condition (not the reconcile error) and return false so the reconcile
@@ -335,14 +379,25 @@ func componentsUpToDate(cluster *v1alpha1.Cluster) bool {
 // optional StatusObserver. It is best-effort: observation errors are logged and partial results
 // applied, since a not-yet-reachable child cluster is expected shortly after provisioning.
 func (r *ClusterReconciler) observeStatus(ctx context.Context, cluster *v1alpha1.Cluster) {
-	if r.ObserveStatus == nil {
+	r.observeStatusWith(ctx, r.ObserveStatus, cluster)
+}
+
+// observeStatusWith applies the given observer's results to the cluster status. Shared by the
+// child-cluster path (ObserveStatus) and the host-cluster path (ObserveHostStatus); a nil observer
+// disables observation.
+func (r *ClusterReconciler) observeStatusWith(
+	ctx context.Context,
+	observer StatusObserver,
+	cluster *v1alpha1.Cluster,
+) {
+	if observer == nil {
 		return
 	}
 
-	observed, err := r.ObserveStatus(ctx, r.reader(), cluster)
+	observed, err := observer(ctx, r.reader(), cluster)
 	if err != nil {
 		logf.FromContext(ctx).
-			Info("observe child cluster status (best-effort)", "error", err.Error())
+			Info("observe cluster status (best-effort)", "error", err.Error())
 	}
 
 	if observed.Endpoint != "" {
@@ -368,6 +423,21 @@ func (r *ClusterReconciler) reconcileDelete(
 		return ctrl.Result{}, nil
 	}
 
+	// Deleting the host registration must never destroy anything: the underlying cluster is the one
+	// the operator runs on. The host path adds no finalizer, but a user may have labelled a cluster
+	// that already carried one — remove it without invoking the provisioner (conservative: the
+	// underlying cluster is orphaned, not destroyed).
+	if cluster.IsHostCluster() {
+		controllerutil.RemoveFinalizer(cluster, FinalizerName)
+
+		err := r.Update(ctx, cluster)
+		if err != nil {
+			return ctrl.Result{}, fmt.Errorf("remove finalizer: %w", err)
+		}
+
+		return ctrl.Result{}, nil
+	}
+
 	r.markProgressing(cluster, v1alpha1.ClusterPhaseDeleting, "Deleting", "Deleting cluster")
 	// Status update is best-effort during deletion; ignore conflicts on a terminating object.
 	_ = r.updateStatus(ctx, cluster)

internal/controller/host_cluster_test.go

@@ -0,0 +1,143 @@
+package controller_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/devantler-tech/ksail/v7/internal/controller"
+	"github.com/devantler-tech/ksail/v7/pkg/apis/cluster/v1alpha1"
+	clusterprovisioner "github.com/devantler-tech/ksail/v7/pkg/svc/provisioner/cluster"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	apimeta "k8s.io/apimachinery/pkg/api/meta"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/types"
+	ctrl "sigs.k8s.io/controller-runtime"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+)
+
+const (
+	hostName      = "host"
+	hostNamespace = "default"
+)
+
+// newHostCluster returns a host-labelled Cluster, mirroring the operator's self-registration of the
+// cluster it runs on (empty spec, host-cluster label).
+func newHostCluster(withFinalizer bool) *v1alpha1.Cluster {
+	cluster := &v1alpha1.Cluster{
+		ObjectMeta: metav1.ObjectMeta{
+			Name:       hostName,
+			Namespace:  hostNamespace,
+			Generation: 1,
+			Labels:     map[string]string{v1alpha1.HostClusterLabel: "true"},
+		},
+	}
+	if withFinalizer {
+		cluster.Finalizers = []string{controller.FinalizerName}
+	}
+
+	return cluster
+}
+
+func hostRequest() ctrl.Request {
+	return ctrl.Request{
+		NamespacedName: types.NamespacedName{Name: hostName, Namespace: hostNamespace},
+	}
+}
+
+// newHostReconciler builds a reconciler whose provisioner builder fails the reconcile if invoked —
+// the host path must never touch a provisioner — and whose host observer reports fixed status.
+func newHostReconciler(
+	t *testing.T,
+	fakeClient client.Client,
+) *controller.ClusterReconciler {
+	t.Helper()
+
+	return &controller.ClusterReconciler{
+		Client: fakeClient,
+		Scheme: newScheme(t),
+		NewProvisioner: func(
+			_ context.Context,
+			_ *v1alpha1.Cluster,
+		) (clusterprovisioner.Provisioner, error) {
+			return nil, errBoom
+		},
+		ObserveHostStatus: func(
+			_ context.Context,
+			_ client.Reader,
+			_ *v1alpha1.Cluster,
+		) (controller.ObservedStatus, error) {
+			return controller.ObservedStatus{
+				Endpoint:      "https://10.96.0.1:443",
+				NodesReady:    2,
+				NodesTotal:    3,
+				NodesObserved: true,
+			}, nil
+		},
+	}
+}
+
+func TestReconcile_HostClusterReportsReadyWithoutProvisioner(t *testing.T) {
+	t.Parallel()
+
+	fakeClient := newFakeClient(newScheme(t), newHostCluster(false))
+	reconciler := newHostReconciler(t, fakeClient)
+
+	res, err := reconciler.Reconcile(context.Background(), hostRequest())
+	require.NoError(t, err, "the host path must not build a provisioner")
+	assert.Positive(t, res.RequeueAfter, "the host cluster should be re-observed periodically")
+
+	var got v1alpha1.Cluster
+
+	require.NoError(t, fakeClient.Get(context.Background(), hostRequest().NamespacedName, &got))
+	assert.Equal(t, v1alpha1.ClusterPhaseReady, got.Status.Phase)
+	assert.Empty(t, got.Finalizers, "the host cluster must not get the teardown finalizer")
+	assert.Equal(t, "https://10.96.0.1:443", got.Status.Endpoint)
+	assert.Equal(t, int32(2), got.Status.NodesReady)
+	assert.Equal(t, int32(3), got.Status.NodesTotal)
+
+	ready := apimeta.FindStatusCondition(got.Status.Conditions, v1alpha1.ConditionReady)
+	require.NotNil(t, ready)
+	assert.Equal(t, metav1.ConditionTrue, ready.Status)
+
+	components := apimeta.FindStatusCondition(
+		got.Status.Conditions,
+		v1alpha1.ConditionComponentsReady,
+	)
+	require.NotNil(t, components)
+	assert.Equal(t, metav1.ConditionUnknown, components.Status)
+	assert.Equal(t, "HostCluster", components.Reason)
+}
+
+func TestReconcile_HostClusterDeleteSkipsProvisioner(t *testing.T) {
+	t.Parallel()
+
+	scheme := newScheme(t)
+	// A user may have labelled an existing cluster that already carried the finalizer; deletion must
+	// remove the finalizer without ever invoking the provisioner.
+	cluster := newHostCluster(true)
+	fakeClient := newFakeClient(scheme, cluster)
+	prov := &fakeProvisioner{exists: true}
+	reconciler := newReconciler(scheme, fakeClient, prov)
+
+	require.NoError(t, fakeClient.Delete(context.Background(), cluster))
+
+	_, err := reconciler.Reconcile(context.Background(), hostRequest())
+	require.NoError(t, err)
+	assert.Equal(
+		t,
+		0,
+		prov.deleteCalls,
+		"deleting the host registration must not tear anything down",
+	)
+
+	var got v1alpha1.Cluster
+
+	getErr := fakeClient.Get(context.Background(), hostRequest().NamespacedName, &got)
+	assert.True(
+		t,
+		apierrors.IsNotFound(getErr),
+		"the registration should be gone after finalizer removal",
+	)
+}

pkg/apis/cluster/v1alpha1/labels.go

@@ -4,3 +4,17 @@ package v1alpha1
 // Cluster resource. The operator only ever deletes namespaces carrying this label, so namespaces
 // that already existed (e.g. "default" or user-managed namespaces) are never removed.
 const ManagedNamespaceLabel = "ksail.io/managed-namespace"
+
+// HostClusterLabel marks the Cluster resource the operator self-registers to represent the cluster
+// it runs ON (the hub), following the pattern of Rancher's "local" cluster and Argo CD's
+// "in-cluster" destination. The label is reserved: the operator never provisions, updates, or
+// deletes the underlying cluster for a resource carrying it — it only observes status and serves
+// resource browsing through its own in-cluster credentials — and the REST API rejects lifecycle
+// mutations on it.
+const HostClusterLabel = "ksail.io/host-cluster"
+
+// IsHostCluster reports whether this Cluster resource is the operator's self-registration of the
+// cluster it runs on (see HostClusterLabel).
+func (c *Cluster) IsHostCluster() bool {
+	return c.Labels[HostClusterLabel] == "true"
+}