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 & Interactive Hotkeys: An automated watcher observes file modifications in real time (< 30ms). Press h to reveal progressive hints, r to force a rerun, l to list exercises, or q to quit.
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 |
         |      (watchfiles)     |                         |    (syntax / tables)  |
         +-----------+-----------+                         +-----------------------+
                     |
                     v
         +-----------------------+
                      |
                      v
          +-----------------------+
          |  Curriculum Manifest  |  (18 Chapters / 82 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

Interactive Learning Commands

1. Watch Mode (kubelings watch)

Start the interactive development loop. Whenever you save a file in exercises/, Kubelings immediately evaluates your changes.

kubelings watch

Interactive Hotkeys:

• h : Reveal progressive hint tier
• r : Force rerun current exercise
• l : List curriculum exercises
• q : Exit watcher

2. Interactive Terminal TUI Dashboard (kubelings tui / kubelings dashboard)

Explore the curriculum, browse code, and trigger evaluations inside a split-pane full-screen terminal interface:

kubelings tui
# or
kubelings dashboard

3. Resource Relationship Topology Visualizer (kubelings tree)

Render an architectural relationship topology tree of Kubernetes workloads, services, endpoints, volumes, and network policies:

kubelings tree pods01
# or inspect an external manifest
kubelings tree deployment.yaml

4. Universal Manifest Linter (kubelings lint)

Audit any Kubernetes manifest against security standards, reliability probes, and schema best practices:

kubelings lint exercises/01_pods/pods01.py
# or lint production manifests
kubelings lint manifests/production/

5. Run a Single Exercise

Execute and evaluate a single exercise directly:

kubelings run pods01

6. Progressive Hints

Get step-by-step tips for any exercise:

kubelings hint pods01

7. List All Chapters & Exercises

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

kubelings list

8. Verify Curriculum Progress

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

kubelings verify

9. Test Reference Solutions

Run built-in self-testing across reference solutions:

kubelings test

10. Cluster Connectivity Status

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

kubelings cluster

Curriculum & Syllabus

Kubelings covers 20 structured chapters with 90 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.