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  |  (23 Chapters / 102 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 102 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

VS Code & Cursor Extension 💻

Kubelings provides an official extension for Visual Studio Code and Cursor that turns your editor into a fully integrated Kubernetes learning IDE.

✨ Extension Features

• 📚 Activity Bar Curriculum Tree View: Browse all 23 chapters and 102 exercises directly from the sidebar with real-time pass/fail status and chapter completion counters.
• 📊 Status Bar Progress Indicator: Persistent status bar item showing your total completion percentage, current progress, and next active exercise. Click to jump straight to the exercise.
• ⚡ On-Save Diagnostics: Automatic in-editor validation whenever you save an exercise manifest (exercises/**/*.py), surfacing schema errors, missing attributes, or remaining # I AM NOT DONE markers.
• 💡 Code Actions & Quick Fixes: Lightbulb quick fixes directly on errors to:
  • Reveal Hint: Display progressive hints in the editor without spoiling the answer.
  • Compare with Reference Solution: Instantly open a side-by-side diff comparing your exercise code against the official reference solution.
• 🔍 Solution Diffing: Interactive diff viewer (kubelings.showSolutionDiff) for visual code comparison.
• 💻 Integrated Terminal Watch Mode: Launch kubelings watch into a dedicated integrated terminal with a single click.

📦 Extension Installation

Via Command Line (VSIX)

# For VS Code
code --install-extension dist/kubelings-vscode.vsix

# For Cursor
cursor --install-extension dist/kubelings-vscode.vsix

Via Editor UI (VSIX)

1. Open the Extensions view (Ctrl+Shift+X / Cmd+Shift+X).
2. Click the ... (Views and More Actions) menu in the top-right corner of the Extensions pane.
3. Select Install from VSIX... and choose dist/kubelings-vscode.vsix (available from the repository root after make vscode-package or downloaded from GitHub Releases).

Curriculum & Syllabus

Kubelings covers 23 structured chapters with 102 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.