Board: imageless Kubernetes

The goal is to show a pod that names a FloxHub environment instead of a built image, how a containerd shim realizes it on the node, and what changes in the deploy and rollback loop.

This page is drawn from https://flox.dev/docs/imageless-kubernetes/intro, https://flox.dev/docs/imageless-kubernetes/tech, https://flox.dev/docs/imageless-kubernetes/config, https://flox.dev/docs/imageless-kubernetes/install/self-managed, https://flox.dev/docs/imageless-kubernetes/install/eks, https://flox.dev/docs/imageless-kubernetes/install/troubleshooting, https://flox.dev/docs/imageless-kubernetes/examples/gitlab-ci, https://flox.dev/kubernetes/ and https://flox.dev/blog/kubernetes-uncontained-explained-unlocking-faster-more-reproducible-deployments-on-k8s/.

Whiteboard outcome

When you are done, the board shows FloxHub on the left, a pod spec with a flox.dev/environment annotation and runtimeClassName: flox, a node with a Flox containerd shim, and a rollback arrow that points at an earlier generation.

Before you draw: three questions

1. Which cluster: Amazon EKS, a self-managed cluster, K3s? (The docs cover EKS and self-managed; https://flox.dev/docs/imageless-kubernetes/intro.)
2. How long does the image pipeline take today, and how many registries are involved?
3. Do the environments live on FloxHub already, public or private?

Draw it in 8 steps

1. On the left, draw FloxHub with an environment myorg/myenv at generation N. Say: “Imageless Kubernetes is a new way to run Kubernetes backed by Flox environments rather than container images”, and the environment must be pushed to FloxHub (https://flox.dev/docs/imageless-kubernetes/intro).
2. Draw a pod spec in the middle with two lines circled. Annotation flox.dev/environment names the environment, and runtimeClassName: flox selects the Flox backend (https://flox.dev/docs/imageless-kubernetes/intro). Say: “Kubernetes stays Kubernetes”, with a different runtime handler and one annotation (https://flox.dev/blog/kubernetes-uncontained-explained-unlocking-faster-more-reproducible-deployments-on-k8s/).
3. Write the stub image under the spec. The pod uses flox/empty:1.0.0, a “dummy container” that exists because the pod spec requires an image (https://flox.dev/docs/imageless-kubernetes/intro). The blog sizes it at 49 bytes (https://flox.dev/blog/kubernetes-uncontained-explained-unlocking-faster-more-reproducible-deployments-on-k8s/).
4. Draw a node box with a small box “containerd-shim-flox-v2”. Say: it wraps containerd-shim-runc-v2, intercepts the container config, and pulls the environment to the node so it can be mounted into the container (https://flox.dev/docs/imageless-kubernetes/tech).
5. Draw an arrow from FloxHub to the shim labeled pull env, fetch missing packages. Say: the shim fetches only packages not already in the node’s immutable store, so most bytes are reused from the node-local cache (https://flox.dev/blog/kubernetes-uncontained-explained-unlocking-faster-more-reproducible-deployments-on-k8s/). The vendor page claims “50% Faster provisioning”; it is a marketing figure with no method shown [verify] (https://flox.dev/kubernetes/).
6. Draw the update loop under it. flox install -r myorg/myenv somepackage, then flox push -r myorg/myenv, then redeploy. Say: “No need to rebuild an image” (https://flox.dev/docs/imageless-kubernetes/intro). FloxHub then gives a package list, env vars, startup scripts and “An audit trail of what changes were made to the environment and by whom” (https://flox.dev/docs/imageless-kubernetes/intro).
7. Draw a dotted rollback arrow. The blog describes rollback as a one-line change in the pod template to a prior generation (https://flox.dev/blog/kubernetes-uncontained-explained-unlocking-faster-more-reproducible-deployments-on-k8s/). Generations are version numbers of a FloxHub environment (https://flox.dev/docs/concepts/generations).
8. At the bottom, write the rule: Push the environment, not the payload. The pod names it; the node realizes it. (https://flox.dev/docs/imageless-kubernetes/intro, https://flox.dev/kubernetes/)

flowchart LR
  FH[FloxHub<br/>myorg/myenv<br/>generation N]
  subgraph K[Kubernetes cluster]
    P[Pod<br/>runtimeClassName flox<br/>annotation flox.dev/environment]
    subgraph N[Node]
      SH[containerd-shim-flox-v2]
      ST[Node-local store]
    end
  end
  FH -->|pull env| SH
  SH --> ST
  P -->|CRI| SH
  O[Operator<br/>flox install then flox push] --> FH

What can go wrong

• Pods stuck in ContainerCreating. A message like no runtime for "flox" is configured means the shim install was disrupted, often a competing imported containerd config, more likely when the NVIDIA Container Toolkit is on the same node (https://flox.dev/docs/imageless-kubernetes/install/troubleshooting).
• Missing annotation. In the GitLab example, the annotation is required and pods fail to start without it (https://flox.dev/docs/imageless-kubernetes/examples/gitlab-ci).
• Private environments. Create a Kubernetes secret from flox auth token and mount it at /var/run/secrets/flox.dev. User tokens expire one month after issue; the docs point to service accounts for organization-owned tokens (https://flox.dev/docs/imageless-kubernetes/config).
• Telemetry. The shim and in-container activation send telemetry and Sentry error reports that can include hostnames; there is an annotation to disable metrics (https://flox.dev/docs/imageless-kubernetes/config, https://flox.dev/docs/imageless-kubernetes/intro).
• Node requirements. Self-managed clusters need containerd 1.7 or later, Flox on every node, and the shim registered with containerd and Kubernetes (https://flox.dev/docs/imageless-kubernetes/install/self-managed). On EKS the docs recommend a new node group (https://flox.dev/docs/imageless-kubernetes/install/eks).

What they will ask