Cluster Registration
Register existing Kubernetes clusters with Bosca by uploading a kubeconfig. Credentials are encrypted at rest; the studio never sees the raw kubeconfig after registration.
Overview
Bosca Kubernetes manages existing clusters — it doesn't provision them. You bring a cluster that's already running (EKS, GKE, AKS, bare-metal kubeadm, kind, k3s, etc.) and hand Bosca a kubeconfig with sufficient permissions. From that point on, every read, mutation, and stream against that cluster routes through the controller.
Registering a Cluster
Navigate to Kubernetes → Settings → Registered Clusters and click Register cluster. The form asks for:
| Field | Purpose |
|---|---|
| Name | Display name shown in the cluster switcher and detail pages. Pick something operators recognize (e.g. prod-us-east-1). |
| Provider | Free-form label such as EKS, GKE, AKS, kind, or bare-metal. Used in lists and grouping; no semantic effect. |
| Region | Region or zone string (e.g. us-east-1, europe-west2-a, local). Display only. |
| Environment | One of PRODUCTION, STAGING, DEVELOPMENT. Destructive operations against PRODUCTION clusters require extra confirmation in the studio. |
| Kubeconfig | The full kubeconfig YAML. Bosca encrypts and stores it; you can rotate it later via rotateKubeconfig without re-registering. |
Kubeconfig Storage
Kubeconfigs are encrypted at rest with the platform's standard security.encryption.key using the same encryption service that protects every other Bosca credential. The encrypted blob lives in the kubernetes.cluster_credential Postgres table; the raw kubeconfig never touches the controller's filesystem, never appears in environment variables, and never gets logged.
When the controller needs to talk to a cluster, it decrypts the kubeconfig in-memory and writes it to a private temp file with 0600 permissions just for the duration of the operation (typically a single Helm subprocess or a fabric8 client construction). The temp file is deleted in finally, regardless of success.
Kubeconfig Permissions
Bosca Kubernetes is an admin-class tool — the studio's pages assume the kubeconfig has sufficient permissions to read every resource in every namespace and to mutate workloads. Recommend a kubeconfig backed by:
- A dedicated ServiceAccount bound to
cluster-admin(typical), or - A scoped ClusterRole with at minimum
get/list/watchon all core resources, plus the verbs your operators actually use (create/update/deleteon workloads, Secrets, ConfigMaps, etc.) and read on every CRD installed in the cluster.
Multi-Cluster Selection
Every page in the subsystem reads the active cluster from the page-header switcher. The selection is persisted to localStorage under the key k8s.cluster, so it survives reloads. Switching clusters tears down active subscriptions (pod log streams, helm release watches, event streams) and re-subscribes against the new target.
Cluster Health Probing
The controller runs a periodic ClusterHealthProbe against every registered cluster — a single kubectl api-resources-equivalent request that updates the cluster's last_seen_at and health columns. If the probe fails consistently, the cluster's health badge transitions to warn or error in the studio so operators notice before they try to use a broken cluster. Failures don't auto-deregister the cluster — health is informational.
Updating and Removing Clusters
Cluster metadata (name, environment) can be edited inline from the registered clusters page. Rotating the kubeconfig uses a separate mutation so the encrypted blob is replaced atomically — operators don't need to re-register if they rotate a ServiceAccount token. Deregistering a cluster removes the row and the encrypted credential from Bosca, but does not modify the cluster itself.