Guides

API reference

KubeCell owns exactly four CRDs under kubecell.io/v1alpha1. All of them are desired-state or preflight APIs. Fields with a single safe value are platform constants and intentionally absent.

Kind	Scope	Short name	Owner
Cell	Namespaced	cell	Platform
VirtualNodeClass	Cluster-scoped	vnclass	Platform
VirtualClusterPlan	Namespaced	vcp	Tenant / platform
VirtualCluster	Namespaced	vc	Tenant / platform

Namespace

Cells must live in the same namespace as the controller, by convention kubecell-system.

Cell

The unit of physical capacity: one OCM ManagedCluster bound to one machine profile.

spec

Field	Type	Required	Notes
managedClusterRef.name	string	Yes	Bound OCM ManagedCluster name. Immutable once any VirtualCluster resolves the Cell.
machineProfile.name	string	Yes	Profile name; the placement selector. Immutable once resolved.
machineProfile.devices[]	array	No	Inline accelerator contract. A single machine profile per Cell, not a list of profiles.
machineProfile.devices[].name	string	Yes	Stable identifier inside KubeCell, referenced by entitlement checks.
machineProfile.devices[].resourceName	string	Yes	Exact host extended-resource key; must match character-for-character everywhere.

status (read-only)

Field	Type	Required	Notes
observedGeneration	int64	—	Observed metadata.generation; distinguishes stale from fresh.
phase	enum	—	Pending \| Provisioning \| Ready \| Degraded \| Deleting \| Failed.
conditions[]	[]Condition	—	Joined, Available, ProviderReady, InventoryFresh, CapabilityMismatch, and others.
managedCluster{name,uid,joined,available,leaseFresh,leaseRenewTime}	object	—	OCM observation plus the decisive Lease freshness signal.
provider{k3kVersion,namespaceReady,k3kCRDsReady,controllerReady,cniReady,topolvmReady}	object	—	Decomposition of host-baseline readiness.
nodes[]{name,profile,ready,labelHash,capacity,allocatable,activeRequested,pendingRequested,readinessReasons,observedAt}	array	—	Per-node inventory and placement inputs.
inventory{<resource>{capacity,allocatable,requested,pending,availableEstimate}}	map	—	Aggregated headroom per resource.
storageInventory{provisioner,allocatedPV,perNode,freeCapacity,freeCapacityKnown,freeCapacitySource,fresh,observedAt}	object	—	TopoLVM free space must come from lvmd; inferring from PV capacity is forbidden.
nodePorts{allocated,observedAt,fresh}	object	—	Allocated NodePorts for child APIs.

cell-full.yaml

apiVersion: kubecell.io/v1alpha1kind: Cellmetadata:  name: cell1  namespace: kubecell-systemspec:  managedClusterRef:    name: cell1  machineProfile:    name: ascend-910b    devices:    - name: ascend      resourceName: huawei.com/Ascend910status:  observedGeneration: 1  phase: Ready  managedCluster:    name: cell1    uid: "b3f1..."        # compared at UID level on deletion    joined: true    available: true       # not trustworthy alone    leaseFresh: true      # the true liveness criterion  provider:    k3kVersion: v1.2.0    namespaceReady: true    k3kCRDsReady: true    controllerReady: true    cniReady: true    topolvmReady: true

VirtualNodeClass

Cluster-scoped quota tier: one name, one entitlement, one storage class.

Field	Type	Required	Notes
entitlement.workloadHard	map[string]Quantity	Yes	Hard requests/limits applied as a ResourceQuota in the host namespace.
storageClassName	string	Yes	Storage class used for child data volumes and child PVCs (typically topolvm-provisioner).

virtualnodeclass-full.yaml

apiVersion: kubecell.io/v1alpha1kind: VirtualNodeClassmetadata:  name: ascend-910b-smallspec:  entitlement:    workloadHard:      requests.cpu: "4"      limits.cpu: "4"      requests.memory: 8Gi      limits.memory: 8Gi      requests.huawei.com/Ascend910: "2"      limits.huawei.com/Ascend910: "2"  storageClassName: topolvm-provisioner

VirtualClusterPlan

Side-effect-free preflight. The spec is isomorphic to a VirtualCluster so an accepted plan can be turned into a creation request without rewriting anything.

Field	Type	Required	Notes
cellRef.name	string	Yes	Target Cell.
classRef.name	string	Yes	Target quota tier.
status.decision	enum	—	Accepted \| Rejected \| Unknown. Evaluated once; never refreshed periodically.
status.expiresAt	time	—	When the conclusion becomes void.
status.checks[]	array	—	Per-resource findings, including the reason for Rejected.

Not a reservation

Acceptance never reserves capacity. The controller re-runs the same evaluation at real creation time and blocks on a non-accepted conclusion, writing the report to VirtualCluster.status.feasibilityChecks.

VirtualCluster

The child cluster instance: key fields immutable, rich status.

spec

Field	Type	Required	Notes
cellRef.name	string	Yes	Target Cell; immutable after creation.
classRef.name	string	Yes	Quota tier; immutable after creation.

status (read-only)

Field	Type	Required	Notes
observedGeneration	int64	—	Generation the status reflects.
phase	enum	—	Pending \| Provisioning \| Ready \| Degraded \| Deleting \| Failed.
resolved	object	—	Immutable resolution snapshot: the sole basis for steady-state rendering.
feasibilityChecks[]	array	—	Recheck report written at creation time.
endpoint{address,port}	object	—	Discovered child API address and NodePort.
credential.secretName	string	—	Secret containing the admin kubeconfig (kubeconfig.yaml key).
host.quotaUsed	object	—	Quota accounting observed on the host side.
conditions[]	[]Condition	—	Standard condition table.

virtualcluster-status.yaml

apiVersion: kubecell.io/v1alpha1kind: VirtualClustermetadata:  name: child-dev  namespace: kubecell-systemspec:  cellRef: {name: cell1}  classRef: {name: ascend-910b-small}status:  phase: Ready  endpoint:    address: 10.0.12.7    port: 31234  credential:    secretName: kubecell-child-dev-<uid>-admin-kubeconfig  host:    quotaUsed:      requests.cpu: "400m"      requests.huawei.com/Ascend910: "2"

Phases and conditions

Phase	Meaning
Pending	Accepted, waiting for the controller to begin rendering.
Provisioning	Works are being applied on the host; child cluster not yet Ready.
Ready	Child API reachable, kubeconfig published, quota and policy in place.
Degraded	The Cell lost liveness (stale lease) or a required inventory source is unavailable.
Deleting	Finalizer cleanup in progress by UID.
Failed	A terminal error that requires operator action; re-applying does not bypass it.

Joined / Available — OCM conditions. Available alone is not trustworthy.
ProviderReady — host baseline decomposed into K3k, CNI, and TopoLVM readiness.
InventoryFresh — inventory and storage observations are recent and from a live source.
CapabilityMismatch — declared device capacity exceeds observed allocatable.

See also: technical-design.md for the authoritative field-by-field design and validation rules.

Day-2 operations

Security & isolation