KWOK: Simulating Thousands of Kubernetes Nodes Without Kubelet

The Problem: Testing Kubernetes at Scale Without Hardware

Kubernetes controllers and operators often fail in production because they were tested against a handful of nodes. Spinning up a real cluster with hundreds of nodes requires cloud instances or a large physical lab, which is slow and expensive. KWOK solves this by simulating nodes and pods at the API level, so you can create thousands of nodes in seconds on a laptop. The intended users are developers of controllers, scheduler plugins, or custom resource controllers who need to observe behavior under scale without the overhead of real kubelets. It is not for testing node-level components like CNI or kube-proxy, because those are not simulated.

How KWOK Works: Simulating Lifecycle Without Kubelet

KWOK provides two tools: kwok and kwokctl. The core tool, kwok, acts as a fake kubelet. It watches Kubernetes API resources and updates the status of nodes and pods to mimic real behavior. For example, when you create a pod, kwok sets its phase to Running and updates conditions. When you delete a node, it removes the node object. The key mechanism is that all state changes are written directly to the API server, so any client that uses the Kubernetes API sees a consistent view. kwokctl is a CLI that manages clusters, creating and deleting them almost instantly. It can run kwok in a container or binary, and it sets up the necessary components like etcd and the API server. The README states that KWOK can reliably maintain 1k nodes and 100k pods, and create 20 nodes or pods per second.

Getting Started: Commands and Configuration

The README points to the project website for detailed instructions, but the basic flow is to install kwokctl and use it to create a cluster. For example, you would run something like `kwokctl create cluster --name test` to start a cluster with simulated nodes. Then you can use `kubectl` to interact with it. The README mentions that you can run KWOK using pre-built images if Docker or Nerdctl is installed, or use binaries for all platforms. Configuration is done through flags or a config file, allowing you to set node types, labels, taints, capacities, and conditions. For pod behaviors, you can configure status transitions. The exact commands are not in the README, so you would need to consult the website or the CLI help for specifics. But the core idea is that you create a cluster, then create nodes and pods, and they get simulated automatically.

Key Capabilities: What You Can Test

The flexibility of KWOK is its main strength. You can define different node types with custom labels, taints, and capacities. This is useful for testing node selectors, affinity rules, or taint-based eviction. You can also configure pod behaviors, such as setting different statuses, to test edge cases. For example, you can make a pod fail or stay in Pending. This allows you to test how your controller reacts to various states. The compatibility with Kubernetes API means you can use kubectl, helm, or any other client. The README specifically mentions that KWOK works with any tools that are compliant with Kubernetes APIs. This makes it easy to integrate into existing workflows.

Limitations: Where Simulation Falls Short

The biggest limitation is that KWOK does not run actual containers. It only simulates the API objects. So you cannot test container runtime interactions, image pulls, or actual application behavior. If you need to verify that your deployment actually runs, KWOK is the wrong tool. Also, the simulation is only as accurate as the configuration. If you do not set the right conditions, the simulated nodes may not behave like real ones. For example, node pressure eviction is not automatically simulated; you have to configure it. Another limitation is that the README claims reliability for 1k nodes and 100k pods, but that is a specific scenario. If you need more, you may hit performance issues. The project is under active development, so APIs may change between releases.

Alternatives: Real Clusters and Other Simulators

The main alternative is to use a real cluster, either on cloud providers like EKS or GKE, or local solutions like kind or minikube. Kind runs real nodes in Docker containers, so it provides actual kubelets and container runtimes. This is better for testing node-level behavior, but it is limited to a few nodes per machine. For scale, you would need a cloud provider, which costs money and takes time. Another alternative is kube-scheduler-simulator, which simulates the scheduler only, not the entire cluster. That tool focuses on testing scheduling algorithms without the overhead of nodes. The difference is that KWOK simulates the full node and pod lifecycle, while the scheduler simulator only handles the scheduling decisions. If you need to test controllers that watch node status, KWOK is more appropriate. If you only care about scheduling, the simulator might be lighter.

Maintenance and Upgrade Cost

The project has a recent release schedule, with v0.8.0 in June 2026, v0.7.0 in May 2025, and v0.6.1 in October 2024. This indicates active maintenance. The license is Apache-2.0, which is permissive and allows commercial use without copyleft obligations. However, as a subproject of Kubernetes SIGs, it follows Kubernetes community standards. Upgrading between versions may require changes to your configuration or cluster creation commands, as the CLI and API evolve. The README does not provide a migration guide, so you should check the release notes on GitHub for breaking changes. Since it is a simulation tool, the cost of upgrading is low if you only use it for testing, but you need to ensure your test scripts remain compatible.

Editorial conclusion

Adopt KWOK if you need to test Kubernetes controllers, schedulers, or API clients against large clusters without spending on real hardware. Avoid it if you need to validate kubelet-specific behavior like container runtime interactions or node pressure eviction, since those are simulated. Before adopting, verify that the simulated node and pod statuses match your use case, and check the compatibility of your tooling with the fake nodes. The project is under active development with recent releases, but you should pin a version and review the changelog for breaking changes.

Official sources

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