KWOK: simulated Kubernetes nodes without a kubelet

What KWOK replaces, and who needs that

A normal Kubernetes cluster needs a control plane and a kubelet on every node. The kubelet is what registers a node, reports its capacity, admits pods, and moves them through their lifecycle. If you want to test a scheduler policy, a controller that reacts to node conditions, or a dashboard that renders a hundred nodes, you usually have to pay for real machines or wait for a provisioner. KWOK removes the kubelet from the picture. The README describes it as a toolkit that sets up a cluster of thousands of Nodes in seconds, with all Nodes simulated to behave like real ones, and states the approach has a low resource footprint that fits on a laptop.

The project ships two tools. The kwok binary is the component that simulates the lifecycle of fake nodes, pods, and other Kubernetes API resources. The kwokctl CLI creates and manages clusters whose nodes are simulated by kwok. That split matters when you decide how to adopt it: kwok can be pointed at an existing cluster, while kwokctl is the path for a self-contained test environment.

The audience is narrow and specific. People writing controllers against the Kubernetes API, people testing scheduling behaviour at scale, and people who need a reproducible cluster for CI without a cloud bill. The README's own claim is that KWOK works with any client compliant with Kubernetes APIs, naming kubectl, helm, and kui. That compatibility is the whole point: from the client's side, the cluster looks ordinary.

How the simulation actually works

The mechanism is a set of controllers that watch the Kubernetes API and write status back, in place of a kubelet doing it. The repository layout shows this clearly. There is a stages/ directory at the top level alongside cmd/, pkg/, kustomize/, and charts/. Stages are the configuration unit for the simulation: they describe how a resource should move from one state to the next. The demo directory contains files such as stages-pod-fast.demo and container-failure.demo, which suggests stages can be tuned for speed or made to emulate failure paths.

Because the simulated node never runs a container, the behaviour you observe is only as good as the stage definitions you feed it. Node conditions, pod phases, and container statuses are produced by these rules rather than by a runtime. That is a design trade-off worth naming: you get determinism and speed, and you give up fidelity to whatever a real kubelet would have done under the same load.

The dependency list in go.mod reinforces the shape of the project. It imports k8s.io/client-go, k8s.io/apiserver, and k8s.io/cri-api, so the simulation speaks the same API machinery as the rest of Kubernetes, and there is CRI-related surface for the parts of the demo suite that emulate exec, attach, logs, and port-forward. The demo directory lists all four of those as recorded demo files, which tells you the project intends the fake cluster to be usable interactively, not just as a data fixture.

Scale numbers in the README are worth quoting exactly, because they are the reason to consider this at all: the project states it can reliably maintain 1k nodes and 100k pods, and can create 20 nodes or pods per second. Those are the project's own figures, not measurements performed here.

Installing kwokctl and creating your first simulated cluster

The README points at the project website for installation detail and says pre-built images let you run it once Docker or Nerdctl is installed, with binaries also available for all platforms. The repository has a charts/ directory and a kustomize/ directory, so Helm and Kustomize are both plausible deployment paths, and the Makefile defines a BINARY variable set to kwok kwokctl, which is the list of binaries the build produces.

If you build from source, the Makefile is the entry point. The version is derived by the hack/get-version.sh script, and the supported Kubernetes releases come from supported_releases.txt.

git clone https://github.com/kubernetes-sigs/kwok
cd kwok
make build

After that, the two binaries land in the build output. The first real use is creating a cluster whose nodes kwok simulates:

kwokctl create cluster
kubectl get nodes

The README's framing is that clusters and nodes are created and deleted almost instantly, without waiting for boot or provisioning, so the node list should populate without the usual registration delay. To scale it up, the project documents managing nodes and pods through the kwokctl path rather than by hand-writing Node objects.

kwokctl scale node --replicas 100
kubectl get nodes

Check the flags against the version you installed before relying on them in a script. This article covers v0.8.0, released on 2026-06-23, and CLI surfaces do move between releases.

Where the simulation stops being useful

The obvious limitation is in the name. Kubernetes WithOut Kubelet means no container is scheduled onto a real runtime, no image is pulled, and no process starts. If your test asserts that a pod actually serves traffic, that a volume mounts, or that a container exits with a particular code because of something it did, KWOK cannot answer that. It can be configured to report a container failure, and the demo directory includes container-failure.demo, but reporting a failure and producing one are different things.

A second boundary is resource accounting. Node capacity and conditions are configuration, not measurement. You can set a node's capacity and taints, and the README lists that flexibility as a feature, but the numbers will not respond to real pressure. A scheduling experiment that depends on genuine resource contention will not reproduce here.

The third is the stage rules themselves. Because pod and node transitions are driven by stage configuration, an incorrect or incomplete stage produces a cluster that looks healthy while behaving nothing like a real one. The README does not document how to validate a custom stage against real cluster behaviour, and it does not describe a rollback path for a stage change that breaks a running simulation. Treat stages as test fixtures that need review, not as configuration you can change casually.

Finally, this is a Kubernetes SIGs project under Apache-2.0. It is a testing and simulation tool, not a production control plane, and nothing in the README suggests otherwise.

KWOK versus kind and envtest

The nearest comparison for most teams is kind, which runs a real Kubernetes control plane and real kubelets inside containers. kind gives you genuine pod scheduling and real container execution, at the cost of a Docker or containerd dependency and a cluster that takes noticeably longer to come up. KWOK inverts that: it starts fast and stays cheap because nothing executes, and it pays for that with fidelity.

Against controller-runtime's envtest, the difference is the API surface. envtest starts etcd and kube-apiserver only, so there are no Nodes at all and anything that depends on node status has to be faked inside the test. KWOK provides the node and pod lifecycle as a first-class feature, which is why it suits scheduler and node-condition work where envtest leaves you writing stubs.

The practical split: reach for kind when the test's correctness depends on a container doing something, and reach for KWOK when the test's correctness depends on the API objects and their transitions. Running both is reasonable. A controller suite can use KWOK for the scale cases and kind for the one integration test that proves the container path works.

Maintenance, releases, and the Apache-2.0 licence

The repository is not archived, and the last push was on 2026-06-23, which is the same day v0.8.0 was released. The release cadence visible here is roughly annual: v0.6.1 on 2024-10-29, v0.7.0 on 2025-05-16, and v0.8.0 on 2026-06-23. That is slow enough that you should not expect a fix for a niche bug on a short timeline, and it is regular enough that pinning to a release and upgrading deliberately is the sane approach.

Upgrade cost is dominated by the stage configuration and the kwokctl CLI surface, not by the Go module. The Makefile reads supported_releases.txt to determine which Kubernetes releases a build supports, and NUMBER_SUPPORTED_KUBE_RELEASES defaults to 1, so a given build targets a narrow band of Kubernetes versions. If your cluster manifests depend on a newer Kubernetes API than the KWOK release supports, you will feel that immediately. Check supported_releases.txt in the tag you plan to use before you write anything against it.

The licence is Apache-2.0, which is the standard permissive licence used across Kubernetes SIGs projects and permits commercial use and modification with the usual notice and patent terms. That is a general description of the licence text, not legal advice; read LICENSE in the repository if the distinction matters to your organisation.

Editorial conclusion

Adopt KWOK if you need a Kubernetes API surface with thousands of Nodes and no kubelet, for scheduler experiments, controller tests, or demos on a laptop, and if you can accept that nothing in the cluster actually runs. Skip it if you need real container runtime behaviour, real pod scheduling outcomes, or metrics emitted by a kubelet, because KWOK simulates the lifecycle rather than executing it. Before committing, verify which Kubernetes releases the supported_releases.txt file in your checkout lists, whether the kwokctl flags you need exist in v0.8.0, and whether the stage configuration you plan to write matches the pod lifecycle you are testing.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes