Skip to content

Realm

A realm is the outermost layer of the Kukeon hierarchy. It is the tenant boundary: everything a realm owns is invisible from another realm, by construction.

What a realm is, on disk and in the kernel

Creating a realm materializes three things on the host:

  1. A containerd namespace — all containers the realm runs live in a dedicated containerd namespace, named kukeon-<realm> by default. Images pulled into one realm are not visible from another.
  2. A cgroup subtree — /sys/fs/cgroup/kukeon/<realm> — used as the root for every space and stack inside the realm. This gives you a single place to attach quotas or account usage across the realm.
  3. Metadata at /opt/kukeon/<realm>/realm.yaml (under the run path, which is configurable via --run-path). This is the authoritative record that the realm exists; the daemon reconciles state from it.

Realm spec

apiVersion: v1beta1
kind: Realm
metadata:
  name: main
  labels: {}
spec:
  namespace: kukeon-main
  registryCredentials: [] # optional, per-registry

The full schema is in Manifest Reference → Realm.

Key fields:

  • metadata.name — the realm's name, used everywhere as the realmId.
  • spec.namespace — the containerd namespace. Defaults to the realm name (or kukeon-<name> when bootstrapped by kuke init); you can set it explicitly.
  • spec.registryCredentials — a list of registry logins for images this realm pulls. Scoped to the realm: two realms can use the same image reference with different credentials.

Realms and containerd namespaces

Every containerd operation Kukeon performs is scoped to a namespace. If you want to inspect what a realm sees, use ctr with the same namespace:

# List images in the `main` realm
sudo ctr -n kukeon-main images ls

# List running tasks (containers) in the `main` realm
sudo ctr -n kukeon-main tasks ls

Inspecting a different namespace (or no namespace) will not show anything Kukeon created for main. This is the main mechanism that gives realms their tenancy guarantee.

Why you might want more than one realm

  • Environments — dev, staging, prod as three realms on the same host.
  • Tenants — one realm per user or project on a shared host.
  • Registry credentials — different teams pull from different private registries.
  • Accounting — one cgroup subtree per realm makes it easy to bill or enforce quotas.

Operations

# Create
sudo kuke create realm mytenant --namespace kukeon-mytenant

# Get (list)
sudo kuke get realms

# Get (single, as YAML)
sudo kuke get realm mytenant -o yaml

# Delete (with --cascade to remove children)
sudo kuke delete realm mytenant --cascade

See CLI Reference → create, get, delete.