Skip to content

containerd namespaces

Kukeon doesn't run its own container runtime. It drives containerd, and every containerd operation it performs is scoped to a containerd namespace.

The mapping

Realm containerd namespace
main kukeon-main
kukeon-system kukeon-system
mytenant kukeon-mytenant (or whatever spec.namespace says)

By default, each realm's namespace is kukeon-<realm-name>. The realm manifest can override this via spec.namespace.

Why this matters

Containerd namespaces are the tenancy boundary. They scope:

  • Images — an image pulled into kukeon-main is not visible from kukeon-mytenant; each realm maintains its own image cache.
  • Containers — a container running in kukeon-main can only be listed, stopped, or inspected by a client scoped to kukeon-main.
  • Tasks — running tasks are namespaced too.
  • Snapshots and content — the underlying layer store is shared, but the references are namespaced.

This is also what lets Kukeon coexist with Docker or nerdctl on the same host. They use their own namespaces (moby, default, etc.) and never see Kukeon's.

Inspecting state with ctr

Anything Kukeon does through containerd is visible to ctr, the low-level containerd CLI:

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

# Containers in the main realm
sudo ctr -n kukeon-main containers ls

# Running tasks (the equivalent of `docker ps`) in the main realm
sudo ctr -n kukeon-main tasks ls

# Attach to a task's stdout (useful for debugging)
sudo ctr -n kukeon-main tasks attach <container-id>

If ctr -n <ns> images ls returns empty, the image was never imported into that namespace. A common cause is importing into default instead of the realm's namespace. See Build from source for the correct way to import.

The system namespace

kuke init creates a second realm, kukeon-system, with containerd namespace kukeon-system (or kuke-system.kukeon.io in older layouts). That's where the kukeond image lives. See System realm.

  • Realm — the Kukeon-level tenant boundary
  • System realm — the dedicated realm for kukeond