Kubelings ☸️

Master Kubernetes from scratch through small, interactive, hands-on terminal exercises.

Inspired by the pedagogical brilliance of rustlings, ziglings, and raylings, Kubelings guides engineers through self-paced, iterative exercises. You will fix broken YAML manifests, construct multi-container sidecars, mount storage volumes, write RBAC authorization rules, solve scheduling constraints, build custom Python Kubernetes operators, and troubleshoot production cluster incidents.

Pedagogical Philosophy

Learning Kubernetes from static documentation or raw copy-pasted Helm charts is difficult because feedback is slow and error messages are cryptic. Kubelings solves this through guided, test-driven micro-learning:

1. Active Debugging & Iteration: Every exercise starts in a broken or incomplete state containing a # I AM NOT DONE marker. You read the problem description, inspect the failure, and edit the code until it passes.
2. Instant Feedback Loop: An automated watcher observes file modifications in real time, executing in-memory schema validation and spec checks in < 30ms.
3. Dual-Mode Learning (Offline & Live Cluster):
   • Offline Mode: Zero cluster setup required. Exercises validate Kubernetes object specs, API constraints, and controller behaviors in-memory.
   • Live Cluster Mode: Seamlessly connect to kind, minikube, k3d, or remote clusters. Exercises provision temporary ephemeral namespaces and verify live reconciliations.
4. Progressive Hints: When stuck, multi-tiered hints (kubelings hint) nudge you in the right direction without spoiling the answer.

Architecture

                                  +-----------------------+
                                  |     User Terminal     |
                                  +-----------+-----------+
                                              |
                                              v
                                  +-----------------------+
                                  |  Kubelings CLI (Typer)|
                                  +-----------+-----------+
                                              |
                     +------------------------+------------------------+
                     |                                                 |
                     v                                                 v
         +-----------------------+                         +-----------------------+
         |  File Watcher Engine  |                         | Rich UI & Diagnostics |
         |      (watchdog)       |                         |    (syntax / tables)  |
         +-----------+-----------+                         +-----------------------+
                     |
                     v
         +-----------------------+
         |  Curriculum Manifest  |  (13 Chapters / 62 Exercises)
         +-----------+-----------+
                     |
                     v
         +-----------------------+
         |   Exercise Runner     |
         +-----------+-----------+
                     |
        +------------+------------+
        |                         |
        v                         v
+----------------+       +-------------------+
| Offline Schema |       | Live Cluster      |
| Validator &    |  OR   | Adapter & Ephem.  |
| Spec Evaluator |       | Namespaces (kind) |
+----------------+       +-------------------+

Quickstart & Installation

Prerequisites

• Python >= 3.10
• uv (recommended) or pip
• Optional (for live cluster exercises): kubectl and a local cluster (kind, minikube, or k3d)

Running Instantly (No Clone Needed)

You can run Kubelings anywhere using uvx or pipx:

# Initialize exercises in your current folder
uvx kubelings init

# Start the interactive watch mode
uvx kubelings watch

Or install globally:

pipx install kubelings
kubelings init
kubelings watch

Local Development Installation

Clone the repository and install dependencies in editable mode:

Using uv (Fastest)

git clone https://github.com/dnf0/kubelings.git
cd kubelings
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

Using Standard pip

git clone https://github.com/dnf0/kubelings.git
cd kubelings
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Verify your installation:

kubelings --help

CLI Commands & Usage Guide

1. Watch Mode (Recommended)

Launch the interactive watch loop to monitor your exercise solutions in real time:

kubelings watch

Optionally, resume from a specific exercise:

kubelings watch --start sched01

Workflow:

1. Open the indicated file in exercises/<chapter>/<exercise>.py.
2. Read the instructions, comments, and task requirements.
3. Fix the YAML manifest or Python logic.
4. Delete the # I AM NOT DONE comment at the top of the file and save.
5. kubelings validates your solution and automatically advances!

2. Run a Single Exercise

Execute and evaluate a single exercise directly:

kubelings run pods01

3. Progressive Hints

Get step-by-step tips for any exercise:

kubelings hint pods01

To display a specific hint tier:

kubelings hint pods01 --hint-num 2

4. List All Chapters & Exercises

Browse the entire curriculum syllabus, descriptions, and exercise paths:

kubelings list

5. Verify Curriculum Progress

Display a rich summary table showing the pass/fail status of all 62 exercises:

kubelings verify

6. Cluster Connectivity Status

Check whether kubelings is running in offline validation mode or connected to a live Kubernetes cluster:

kubelings cluster

7. Initialize Exercises in Any Workspace

If running kubelings via pipx or uvx in a new directory, scaffold the curriculum exercises:

kubelings init

8. Reset an Exercise

Restore any exercise back to its clean starter template:

kubelings reset pods01

9. Version

Display the installed version of Kubelings:

kubelings version

Curriculum & Syllabus

Kubelings covers 13 structured chapters with 62 practical exercises:

Contributing

We welcome contributions, new exercises, bug fixes, and documentation improvements! Please check out CONTRIBUTING.md for local development setup, exercise authoring guidelines, and test instructions.

License

Kubelings is distributed under the terms of the Apache-2.0 license.