Cell manifest

apiVersion: v1beta1
kind: Cell
metadata:
  name: hello-world
  labels: {}
spec:
  id: hello-world
  realmId: default
  spaceId: default
  stackId: default
  rootContainerId: web       # optional; defaults to the first container
  containers:
    - id: web
      image: docker.io/library/busybox:latest
      command: /bin/sh
      args:
        - -c
        - "exec busybox httpd -f -v -p 8080 -h /www"
status:
  state: Ready
  cgroupPath: /kukeon/default/default/default/hello-world
  containers:
    - id: web
      state: Ready
      ...

See Concepts → Cell for what a cell is.

spec

Field	Type	Required	Description
id	string	yes	Cell identifier (matches metadata.name)
realmId	string	yes	Realm that owns the cell
spaceId	string	yes	Space that owns the cell
stackId	string	yes	Stack that owns the cell
rootContainerId	string	no	Identifier of the container that owns the cell's network namespace. Defaults to the first container in containers if unset.
containers	array	yes	Container specs (see Container manifest for fields)
nestedCgroupRuntime	bool	no	Opt-in: delegate the full host-available cgroup-v2 controller set on the cell's cgroup.subtree_control, instead of the default kukeon resource subset (cpu, memory, io, pids). Set this when the cell hosts a nested runtime that itself manages cgroups (e.g. a kukeond cell run as a nested kukeon workload). Defaults to false.

The root container

Exactly one container in the cell must be the root — it owns the network namespace, and every other container joins it.

• If rootContainerId is set, that container is the root. Its spec.root field (if present) is implied.
• If rootContainerId is empty, the container with spec.root: true is used.
• If neither is set, the first container in containers is the root.

Nested cgroup runtimes

By default a cell's cgroup.subtree_control is populated with the kukeon resource controllers (cpu, memory, io, pids) — enough for per-container resource accounting and limits to work for the runc task cgroups runc nests under the cell.

When a cell is itself going to manage further nested cgroups (the canonical case being a kukeond instance running inside a kukeon cell), set spec.nestedCgroupRuntime: true. Kukeon then enables every controller the host root cgroup advertises (cgroup.controllers) on the cell's subtree — so the nested runtime can in turn enable the controllers it needs on its own children.

This is opt-in because the default subset minimises the controller surface enabled per cell on hosts that may have many cells.

status

Field	Type	Description
state	Pending, Ready, Stopped, Failed, Unknown	Lifecycle state
cgroupPath	string	Absolute cgroup path
subtreeControllers	array of string	Cgroup-v2 controller set actually delegated on this cell's cgroup.subtree_control after the host-root filter. For a nestedCgroupRuntime: true cell this is the full host-available set; otherwise the kukeon resource subset (cpu, memory, io, pids).
containers	array of ContainerStatus	Per-container status snapshot
createdAt	RFC3339 timestamp	Wall-clock time of the first persist for this cell. Set once and never moves.
updatedAt	RFC3339 timestamp	Wall-clock time of the most recent persist.
readyAt	RFC3339 timestamp	Wall-clock time of the first State==Ready persist. Set-once.
reason	string	Short reason code summarizing why state is in its current value.
message	string	Human-readable detail backing reason; especially valuable on state: Failed.
cgroupReady	bool	Whether cgroupPath actually exists on the host filesystem as of the last status write.

Minimal

apiVersion: v1beta1
kind: Cell
metadata:
  name: hello-world
spec:
  id: hello-world
  realmId: default
  spaceId: default
  stackId: default
  containers:
    - id: web
      image: docker.io/library/busybox:latest
      command: /bin/sh
      args:
        - -c
        - "exec busybox httpd -f -v -p 8080 -h /www"

See Tutorials → Hello-world cell for a complete worked example.