K8sQuest: Hands-On Kubernetes Troubleshooting on a Local Cluster

What K8sQuest Teaches Through Kubernetes Repairs

K8sQuest is designed for people learning Kubernetes through failure and diagnosis rather than memorizing isolated commands. Its premise is straightforward: each mission introduces a broken state, and the learner investigates that state with kubectl until the system behaves correctly. The README describes 50 progressive challenges across five worlds, beginning with foundational Pods and continuing into Deployments, Services, networking, storage, and debugging.

The format targets a specific kind of learner. A new Kubernetes user can follow a mission briefing, inspect resources from another terminal, and apply a correction without first designing a cluster or deploying an application from scratch. More experienced users may find the scenario structure useful for a bounded exercise around a resource type, although the README presents the project as beginner-friendly.

K8sQuest does not simulate Kubernetes in a browser. The repository description specifies a local cluster through kind or k3d, and the README calls it a local learning platform. Commands therefore act on actual Kubernetes resources. A mission can teach command vocabulary used in operations, but it cannot by itself reproduce managed control planes, cloud identity, external load balancers, or provider-specific storage.

The five worlds make progression visible rather than leaving the learner with an unstructured command playground. Mission briefings state difficulty, estimated time, and concepts. Hints unlock progressively, solutions are available as `solution.yaml` files, and post-mission debriefs explain the Kubernetes mental model behind the repair. This is a guided troubleshooting course wrapped in a game rather than an ordinary cluster sandbox.

The K8sQuest Mission, Engine, and World Layout

The repository layout exposes K8sQuest as a shell-driven application with a Python engine and data-driven mission directories. `install.sh` is the setup entry point, while `play.sh` starts the interactive session. Under `engine/`, `reset.py` accepts a level identifier, which indicates that challenge reset logic is handled separately from the play loop. The `worlds/` directory contains mission organization, and `rbac/` holds Kubernetes authorization resources.

The documented play flow uses two terminals. The first runs `./play.sh` and displays the mission briefing plus game actions. The second is reserved for kubectl investigation and repair. Keeping the game process alive while issuing Kubernetes commands avoids confusing the interactive terminal with the command terminal. After changing resources, the learner returns to the first terminal and runs `check` or `validate`.

Python dependencies are limited in `requirements.txt` to `rich>=13.0.0` and `pyyaml>=6.0`. The shell scripts can therefore orchestrate the session while Python handles terminal presentation, mission handling, or YAML parsing. The README does not expose internal function boundaries, so it does not justify assigning those jobs to particular modules.

A `Dockerfile` provides another execution path. It uses `python:3.11-slim`, installs `kubectl`, copies `engine/`, `worlds/`, and `progress.json`, sets `K8SQUEST_WEB=true`, and starts `engine/engine.py`. The top-level repository listing does not separately show `progress.json`, while the Dockerfile expects it. The repository does not state when that file is created, so image builders should verify that initialization detail before treating the image as standalone.

Installing K8sQuest on Linux, macOS, or Windows

Before installation, have Docker Desktop running and confirm access to `kubectl`, `kind`, `bash`, `python3` version 3.9 or later, and `jq`. The README describes `jq` as necessary for advanced content. On Windows, run the project from Git Bash rather than PowerShell or CMD.

After cloning the repository, installation uses a documented script. This block retrieves the source and enters its directory:

git clone https://github.com/Manoj-engineer/k8squest.git
cd k8squest

The reader should now be in the repository root, where `install.sh`, `play.sh`, `requirements.txt`, and `worlds/` are located.

Run the installer next:

./install.sh

The README does not enumerate every action performed by `install.sh`. It therefore does not support a claim that the script creates the cluster, installs operating-system packages, or completes every dependency check. Any failure should be checked against the stated prerequisites.

On Windows, the documented sequence is the same once Git Bash is open and Docker Desktop is fully running:

./install.sh
./play.sh

Those commands install the project and start the game. If Bash reports `docker: command not found`, the README identifies Docker Desktop startup as the first check. If `bash: command not found` appears, use Git Bash. A `TypeError: 'type' object is not subscriptable` indicates Python 3.8 or older, while K8sQuest requires Python 3.9 or newer.

Running the First Pod Troubleshooting Mission

Start K8sQuest from the repository root:

./play.sh

The first terminal should display an interactive mission briefing. Read its difficulty, time estimate, and concept description before changing anything. Leave this terminal running because it owns the game session.

Open a second Bash terminal, enter the same `k8squest` directory, and use kubectl to inspect the exercise. The README does not provide a fixed first-mission command or expected resource name, so the active mission briefing and mission files are the sources for the specific resources to inspect.

The intended sequence is investigation, repair, then validation. Use pod status, logs, events, and kubectl inspection commands appropriate to the mission. Apply the correction from the second terminal, then return to the K8sQuest terminal. The available game actions are:

check
guide
hints
solution
validate
skip
quit

`check` watches resource status for changes, while `validate` tests the attempted repair. `hints` reveals progressively fuller assistance. `solution` opens the mission's `solution.yaml`, and `skip` advances without awarding XP.

The README marks `guide` as “Coming soon,” so it should not be treated as a reliable first-use feature. Progress is saved automatically, including on exit. The repository includes `reset.py`, and the Dockerfile references `progress.json`, but the README does not document a portable export or synchronization process.

After success, K8sQuest presents a debrief covering what failed, why the repair worked, related production incident examples, interview questions, and relevant kubectl commands. That explanation is a major reason to complete a mission instead of immediately using `solution` or `skip`.

Safety Guards and the Local Cluster Boundary

K8sQuest enables several safety guards by default. According to the README, it prevents deletion of critical namespaces such as `kube-system` and `default`, blocks destructive cluster-wide operations, limits access to the `k8squest` namespace through RBAC, and asks for confirmation before risky operations. The `rbac/` directory supports that claim, while `docs/SAFETY.md` is the documented location for a fuller explanation.

These controls reduce the consequence of beginner mistakes, but they are not a substitute for understanding cluster administration. The README describes namespace and operation restrictions. It does not claim that every destructive action is harmless. Because missions alter a real local cluster, Docker isolation and the configured RBAC boundary remain part of the trust model.

The intended scope is local practice without a cloud account or usage cost. That makes repeated exercise practical, but it narrows the systems involved. The README does not document exercises for cloud IAM, managed database services, public DNS, cloud load balancers, or provider-specific volume behavior. Those subjects should not be inferred from the Kubernetes topics named in the mission list.

K8sQuest is also an educational game with validation and progress logic, not a general incident-response console. Its `check` command evaluates mission resources, and its debriefs explain intended lessons. It should not replace production change controls, observability, incident runbooks, or post-incident review.

Resetting Missions and Managing K8sQuest Progress

A stuck or spoiled mission can be reset without restarting the entire learning path. Activate the Python virtual environment and call the reset script with a level identifier. This recreates the first Pods level:

source venv/bin/activate
python3 engine/reset.py level-1-pods

The level name is part of the command interface, so an incorrect name may fail or target nothing. The README also gives identifiers for rollout, endpoints, volume permissions, and node affinity examples in later worlds.

Progress is tracked with XP, levels, and achievements, and the README says it is auto-saved. Resetting a level is therefore distinct from deleting all progress. The repository does not document a global progress-deletion command, a portable export format, or synchronization across machines.

There are no GitHub releases, so the repository metadata does not provide a release-based upgrade path. The last push was on 2026-09-21. Before updating, inspect or preserve generated progress state, then review changes to `install.sh`, `engine/`, `worlds/`, and the Kubernetes manifests in `rbac/`.

The Apache-2.0 license covers the project under its terms. That is a licensing classification, not legal advice. Organizations distributing a customized course should review the license text and any separate policies for cluster infrastructure and generated training content.

K8sQuest Compared with a Manual kind Practice Cluster

The closest practical alternative is a manually assembled kind cluster containing deliberately broken manifests. That approach gives an experienced Kubernetes user direct control over every object, script, and expected outcome. It can also cover organization-specific scenarios that K8sQuest does not claim to include.

K8sQuest's difference is preparation and feedback. According to the README, it supplies 50 ordered missions, mission briefings, progressive hints, validation, debriefs, XP, achievements, automatic saves, and level resets. A manual cluster can offer these features, but the user must build the exercise structure and success criteria. K8sQuest packages them around a local cluster and a multi-terminal workflow.

That structure is also a constraint. The mission framework determines which resources, faults, and concepts are available. Users cannot assume that every Kubernetes failure mode is represented, especially provider integrations or custom controllers. The manual kind alternative is better for bespoke curriculum work, while K8sQuest is more immediately usable for its documented progression through Pods, Deployments, Services, networking, storage, and debugging.

K8sQuest is not suitable for production clusters, cloud billing evaluation, or certification preparation. The README does not claim certification alignment. Its boundary is the fixed mission catalog plus the infrastructure required to run a real Kubernetes cluster locally.

Editorial conclusion

K8sQuest suits learners who want to repair Kubernetes resources through kubectl without paying for a cloud cluster. It is a poor fit for production debugging, organization-specific incident exercises, or users who cannot run Docker Desktop and the required command-line tools. Verify first that every prerequisite is available, that the local cluster workflow starts correctly on the intended operating system, and that the mission catalog matches the Kubernetes failures you need to practice.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Manoj-engineer/k8squest on GitHub
4. README