Getting started

Installation

KubeCell installs in a fixed order. Deviating from it is the most common cause of confusing failures, so treat this page as a checklist rather than a menu.

Prerequisites

Both clusters must be reachable from your workstation, able to pull the controller image, and running the pinned versions. Host nodes need profile and TopoLVM topology labels — labels do not survive a node rebuild, so re-apply them after any reinstall.

# Pinned combination (do not replace silently)#   host K3s      v1.36.3+k3s1#   K3k           v1.2.0#   child K3s     v1.34.2+k3s1#   OCM Hub       v1.3.1# Host nodes carry the profile label and TopoLVM topology labelskubectl label node<node> hardware.kubecell.io/profile=<profile>kubectl label node<node> topology.topolvm.io/node=<node>kubectl label node<node> topology.kubernetes.io/zone=<node># Both clusters must be able to pull the controller image.# Configure K3s registries.yaml mirrors first and verify with a small image.

Installation order

1. Apply CRDs. Install the four KubeCell CRDs from the release bundle. This is the only step that must happen before anything else.
2. Install the OCM Hub. The management controller writes ManifestWork objects into the hub, so the hub must exist and be pinned to the bundle version.
3. Install the management chart. Deploys the controller, webhook, RBAC, and the optional Kite dashboard. Requires both --apply and --confirm.
4. Join the host. Run the locked clusteradm join command on the host. The ManagedCluster name must equal the future Cell name.
5. Approve the ManagedCluster. clusteradm accept is a mandatory manual safety gate. KubeCell never auto-approves a host.
6. Install the host chart and baseline. The host chart installs the webhook; the installer installs the pinned baseline: K3k, TopoLVM, Traefik, Device Plugin.
7. Generate the Cell and verify. host --step=cell produces the Cell from live discovery. Apply it, then confirm joined, fresh lease, and fresh inventory.
8. Create class, plan, and child. Draft a quota tier with suggest-class, then follow the first VirtualCluster guide.

Management plane

The management cluster is a single-node K3s that holds desired state and observations only. It runs no tenant workloads. Its K3s version may differ from the hosts.

# 1. CRDskubectl apply-f kubecell-release/manifests/crds# 2. OCM Hub (pinned version from the bundle)go run ./cmd/kubecell-installer management \  --bundle ./kubecell-release --apply --confirm# 3. Verify the management planekubectl-n open-cluster-management get podskubectl-n kubecell-system get deploy

Host onboarding

Joining is a two-step operation with a manual approval in between. The approval exists so a compromised or misconfigured host cannot register itself into your fleet unnoticed.

# Run against the host clusterexport KUBECONFIG=<host-kubeconfig>KUBECONFIG=$KUBECONFIG clusteradm join \  --hub-token "$(clusteradm get token)" \  --hub-apiserver https://hub.example.com:6443 \  --cluster-name <cell-name> --wait

# Run against the management clusterexport KUBECONFIG=<hub-kubeconfig>KUBECONFIG=$KUBECONFIG clusteradm accept --clusters <cell-name> --wait

kubectl create ns kubecell-system   # namespaceCreate is false, create it firsthelm install kubecell-host ./charts/kubecell-host \  --namespace kubecell-system \  --set image.repository=<controller-repo> \  --set image.tag=<tag> --set image.pullPolicy=IfNotPresent

The installer then installs the host baseline at pinned versions, idempotently: K3k, TopoLVM, Traefik, the vendor Device Plugin, and profile labels. The controller never installs these itself.

Generate the Cell

Do not hand-write a Cell from memory. Generate it from live host discovery so the machine profile matches reality, then apply it.

go run ./cmd/kubecell-installer host --step=cell --cell <cell-name> \  --kubeconfig <host-kubeconfig> | grep -v '^#' > cell.yamlkubectl apply-n kubecell-system -f cell.yaml

kubectl-n kubecell-system get cell,vnclass,vcp,vc# Cell readiness: joined, fresh lease, fresh inventorykubectl-n kubecell-system get cell cell1 \  -o jsonpath='{.status.phase}{"\t"}{.status.managedCluster.leaseFresh}{"\n"}'

Optional: Kite dashboard

The kubecell-management chart bundles the kite-org dashboard as a conditional dependency (kite.enabled, on by default). It runs single-node with sqlite, exposes a NodePort Service, and uses a dedicated ServiceAccount. Pass the initial superuser password at install time; never commit it.

Uninstall and boundaries

• The installer only touches the selected KubeCell release. OCM Hub, ManagedCluster, and klusterlet follow the OCM lifecycle and are out of Helm uninstall scope.
• Uninstalling a Helm release is not the same as uninstalling OCM. Remove registrations deliberately.
• Deleting a VirtualCluster is safe and finalizer-scoped; deleting the management plane while child clusters exist is not a supported cleanup path.

Next: host onboarding in four commands or create your first VirtualCluster.