KWOK

KWOK creates ultra-fast simulated Kubernetes clusters for control-plane-level testing. This guide walks you through creating your first KWOK cluster, understanding when to use it, and exploring common use cases.

What is KWOK?

KWOK (Kubernetes WithOut Kubelet) is a toolkit that enables simulating thousands of Kubernetes nodes and pods without running actual containers. KSail uses kwokctl’s Docker runtime to run etcd, kube-apiserver, and the kwok-controller as Docker containers. Nodes and pods are simulated at the API level — they appear Ready and Running but consume no compute resources.

When to Use KWOK

Use case	Notes
Control-plane testing	Validates API operations, RBAC, and admission webhook configuration. Webhook objects are accepted by the API server, but in-cluster webhook execution is not supported — no real pod serves the endpoint.
CI/CD speed	Clusters start in seconds with minimal resource usage.
Scale testing	Simulate thousands of nodes/pods without real infrastructure.
Tooling validation	Test kubectl, Helm, and GitOps workflows against a real API server.

Consider other distributions when you need real containers (Vanilla, K3s), production-grade immutable infrastructure (Talos), or isolated virtual clusters (VCluster).

Quick Start

1. Initialize a KWOK Project

Create a new KWOK configuration:

mkdir my-kwok-cluster
cd my-kwok-cluster

ksail cluster init \
  --name dev-cluster \
  --distribution KWOK \
  --gitops-engine ArgoCD

This generates:

• ksail.yaml — KSail cluster configuration
• kwok/ — KWOK kustomize configuration directory:
  • kustomization.yaml — Kustomize entrypoint referencing simulation CRDs
  • simulation.yaml — ClusterLogs, ClusterExec, ClusterAttach, ClusterPortForward CRDs
  • node-not-ready.yaml — CEL-based node NotReady chaos stage (opt-in)
  • pod-failure.yaml — CEL-based pod failure chaos stage (opt-in)
• k8s/kustomization.yaml — Directory for Kubernetes manifests

2. Create the Cluster

ksail cluster create

KSail creates Docker containers for the control plane (etcd, kube-apiserver, kwok-controller), configures simulation CRDs, and sets up kubectl automatically.

3. Verify the Cluster

# Check cluster info
ksail cluster info

# List running containers
docker ps | grep kwok

# Test kubectl access
kubectl get nodes
kubectl get pods --all-namespaces

4. Deploy an Application

# Create a deployment — pods are simulated as Running
kubectl create deployment nginx --image=nginx:1.25
kubectl get pods -w  # Pods transition to Running via KWOK Stage simulation

# Logs work via ClusterLogs CRD
kubectl logs deploy/nginx

5. Clean Up

ksail cluster delete

Configuration

For general KSail YAML options, see the Configuration Reference. KSail scaffolds a kwok/ kustomize directory (shown in Quick Start) that KWOK’s config loader assembles automatically.

The kustomization.yaml references simulation.yaml by default. Chaos stages are included as commented-out resources — uncomment them to enable:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - simulation.yaml
  # Uncomment to enable chaos simulation stages (KWOK v0.7.0+ CEL support):
  # - node-not-ready.yaml
  # - pod-failure.yaml

Simulation CRDs

The simulation.yaml file contains four Cluster-level CRDs that KWOK does not provide by default:

CRD	Enables
ClusterLogs	kubectl logs to return configurable output
ClusterExec	kubectl exec to run commands
ClusterAttach	kubectl attach
ClusterPortForward	kubectl port-forward

See the KWOK documentation for all available CRDs and configuration options.

CEL Chaos Stages (KWOK v0.7.0+)

KSail includes two example chaos stages that use KWOK v0.7.0 CEL expression support for conditional node and pod simulation. These stages use label-based selectors with CEL expressions instead of the older JQ-based syntax.

Node NotReady (node-not-ready.yaml) — Transitions nodes to NotReady status when labeled:

# Enable the stage by uncommenting it in kwok/kustomization.yaml, then:
kubectl label node <name> node-not-ready.stage.kwok.x-k8s.io=true

Pod Failure (pod-failure.yaml) — Fails running pods when labeled:

# Enable the stage by uncommenting it in kwok/kustomization.yaml, then:
kubectl label pod <name> pod-failure.stage.kwok.x-k8s.io=true

You can create additional custom stages by adding YAML files to the kwok/ directory and referencing them in kustomization.yaml. See the KWOK Stages Configuration documentation for the full Stage API.

Unsupported Components

The following components are not installed on KWOK clusters because they require real container execution:

Component	Reason
CNI (Cilium, Calico)	KWOK has no real network dataplane. spec.cluster.cni has no effect.
CSI (Local Path Provisioner)	Requires real container execution; would never become truly ready.
cert-manager	Webhook pods must serve real TLS endpoints.
Flux	Simulated flux-operator pod never registers Flux CRDs; use ArgoCD instead.
Policy engines (Kyverno, Gatekeeper)	Register global MutatingWebhookConfigurations whose endpoints are never served, breaking subsequent Helm installs.

KSail emits a warning and skips each of these when spec.cluster.distribution: KWOK is set. For a full compatibility overview, see the Support Matrix.

Note

ksail workload reconcile is skipped for KWOK — GitOps controllers are simulated as Running but cannot actually sync resources.

Troubleshooting

Cluster Won’t Start

Symptom: ksail cluster create fails.

docker ps          # Docker must be running
docker info        # Ensure Docker daemon is healthy

kubectl Commands Fail

Symptom: kubectl get nodes returns connection errors.

kubectl config current-context    # Should show kwok-<cluster-name>
kubectl config use-context kwok-dev-cluster  # Switch if needed

Pods Not Transitioning to Running

Symptom: Pods stay in Pending state.

This typically means KWOK’s Stage configurations are missing. Ensure the kwok/ directory is present or recreate the cluster:

ksail cluster delete
ksail cluster init --distribution KWOK
ksail cluster create