1. Setup
The lab exercises require the installation and configuration of a few tools. This page will help you get started.
Local Installation
The exercises assume a UNIX environment and are tested on macOS and on Windows with WSL 2 (Ubuntu).
- macOS: the instructions use Homebrew. Run all commands in a terminal.
- Windows: install the Windows Subsystem for Linux as described below. Run all commands of this training inside the WSL terminal, not in PowerShell or the Command Prompt, unless stated otherwise.
Requirements
- Administrator rights. On a company laptop, your IT department may have to install WSL and Docker Desktop for you
- At least 8 GB of RAM (16 GB recommended) and 20 GB of free disk space
- In a company network, access to Docker Hub, GitHub (
github.com,ghcr.io),registry.k8s.io,mirror.gcr.ioand PyPI. Ask your IT department to allow them in the proxy or firewall
CPU architecture
The Linux / WSL commands on this page download amd64 binaries. On a Windows machine with an ARM processor,
replace amd64 with arm64.
Windows Subsystem for Linux (Windows only)
Open PowerShell as Administrator, install WSL with the default Ubuntu distribution and restart your machine:
After the restart, open Ubuntu from the Start menu and create your Linux user and password.
Verify that Ubuntu runs on WSL version 2 (in PowerShell):
The VERSION column must show 2. If it shows 1, convert it: wsl --set-version Ubuntu 2.
Details: https://learn.microsoft.com/en-us/windows/wsl/install
Keep your files in WSL
Store the lab files in your Linux home directory (~/), not under /mnt/c/. Accessing the Windows file system
from WSL is significantly slower.
CLI Tools
Docker
k3d runs the Kubernetes nodes as Docker containers, and Docker builds the container image of the app you deploy later in this training.
- macOS: install Docker Desktop, then start it from the Applications folder:
- Windows (WSL): install
Docker Desktop for Windows on the Windows side,
start it and connect it to WSL:
- Settings > General: make sure Use WSL 2 based engine is selected
- Settings > Resources > WSL Integration: enable the integration for Ubuntu
- Select Apply and reopen your WSL terminal
- All platforms: https://docs.docker.com/get-started/get-docker/
Docker Desktop license
Docker Desktop is free for personal use, education, non-commercial open source projects and small businesses
(fewer than 250 employees and less than USD 10 million annual revenue). Larger organizations need a paid
subscription. Free alternatives are Colima on macOS (start it with 4 GB of
memory: colima start --memory 4) and Docker Engine installed directly inside WSL (see below).
Verify the daemon is running:
You should see system-wide information about the Docker installation with no errors.
Common errors
The command 'docker' could not be found in this WSL 2 distro: (WSL) the WSL integration for Ubuntu is not enabled in Docker Desktop (Settings > Resources > WSL Integration).Cannot connect to the Docker daemon: Docker Desktop is not running, or (Docker Engine in WSL) the service is stopped:sudo systemctl start docker.permission denied while trying to connect to the Docker daemon socket: (Docker Engine in WSL) your user is not in thedockergroup: runsudo usermod -aG docker $USERand reopen the terminal.
Pull a test image to make sure Docker can download images. In company networks, a proxy can block this:
The output ends with:
Pull fails or hangs
A proxy or firewall blocks the download. Ask your IT department for the proxy settings and add them in Docker Desktop (macOS and Windows) under Settings > Resources > Proxies. With Docker Engine in WSL, add them as described in Daemon proxy configuration.
Test Docker in WSL (Windows only)
Make sure a port that a container publishes in WSL is reachable from Windows. In the WSL terminal, run:
Open http://localhost:8080 in your Windows browser. You should see the Welcome to nginx! page. Stop the container afterwards:
k3s and k3d
k3s is a lightweight, certified Kubernetes distribution and runs the Kubernetes cluster you work with in this training. k3s only runs on Linux, so we use k3d to run k3s inside Docker containers, on macOS and WSL alike. There is no separate k3s installation: k3d pulls the k3s container image when you create a cluster.
- macOS:
- Linux / WSL:
- All platforms: https://k3d.io
Verify the installation. The k3d version must be v5.9 or newer:
kubectl
kubectl is the command-line client of Kubernetes. Every lab uses it to talk to your cluster.
- macOS:
- Linux / WSL:
- All platforms: https://kubernetes.io/docs/tasks/tools/
Verify the installation. The client version must be v1.35 or newer:
Optional, highly recommended!
Command Completion
Command completion lets the Tab key complete commands, resource types and names. This saves a lot of typing, e.g. for long Pod names. To enable it:
- macOS (default shell: zsh):
- Linux / WSL (default shell: bash):
Verify the completion: type kubectl vers and press Tab. It completes to kubectl version.
Alias k for kubectl
You will type kubectl a lot. Defining the short alias k for it is common practice among Kubernetes users, and you
will come across commands like k get pods in many blog posts, examples and talks. This training always writes out
the full kubectl command, so you can follow it either way.
- macOS (default shell: zsh):
- Linux / WSL (default shell: bash):
If you enabled the command completion in bash, enable it for k as well (zsh does this automatically):
Verify the alias:
Colored Output
kubectl prints its output without colors. The wrapper kubecolor adds them, which
makes long outputs easier to read. Install it and use it in place of kubectl:
- macOS:
- Linux / WSL:
If you enabled the command completion in zsh, keep it working with kubecolor (bash needs nothing extra):
Verify it: kubectl version --client now prints colored output and an additional line Kubecolor Version. If your
terminal has a light background, add export KUBECOLOR_PRESET=light to your shell configuration as well.
Helm
Helm installs and packages applications for Kubernetes. You use it from chapter 4 on.
- macOS:
- Linux / WSL:
- All platforms: https://helm.sh/docs/intro/install/
Verify the installation. The version must start with v4:
IDE
Install PyCharm (recommended) or Visual Studio Code. Both have strong Python and Kubernetes support.
On Windows, install the IDE on the Windows side and configure it so that its terminal opens a WSL shell. Every command in this training must run in WSL.
Create the directory for your lab files (on Windows, in the WSL terminal):
PyCharm (recommended)
- macOS:
- Windows: download and install from https://www.jetbrains.com/pycharm/download
PyCharm’s core features are free. Since version 2025.1, Community and Professional are a single product; the Pro features come with a 30-day trial.
- Install the Kubernetes plugin via Settings > Plugins
Windows: open the terminal in WSL
- Open Settings > Tools > Terminal
- Set Shell path to
wsl.exe - Open a new terminal tab (View > Tool Windows > Terminal) and verify that it runs in WSL:The output must be
Ubuntu.
Open the lab directory with File > Open: ~/labs on macOS, \\wsl.localhost\Ubuntu\home\<your-user>\labs on
Windows.
Visual Studio Code
- macOS:
- Windows: download and install from https://code.visualstudio.com/download and keep Add to PATH selected, so that you can start VS Code from WSL
Windows: open the terminal in WSL
- Install the WSL extension (
ms-vscode-remote.remote-wsl) - In the WSL terminal, open the lab directory:
- The status bar shows WSL: Ubuntu in the bottom-left corner. Terminal > New Terminal now opens a WSL
shell. Verify it:The output must be
Ubuntu.
Install the following extensions. On Windows, install them while VS Code is connected to WSL, when the Extensions view shows Install in WSL: Ubuntu:
- Python (
ms-python.python) - Kubernetes (
ms-kubernetes-tools.vscode-kubernetes-tools)
Verify the Setup
Create a throwaway cluster to check that all tools work together:
Creating the cluster takes about 15 seconds, or a bit longer the first time, because k3d downloads the k3s image.
The two --disable flags keep the cluster minimal: k3s is started without its built-in Ingress controller
(Traefik) and without its built-in load balancer (ServiceLB).
List the nodes of the cluster:
You should see one node with the status Ready. If it isn’t Ready yet, wait a moment and repeat the command.
k3d added the context k3d-setup-test to your kubeconfig (~/.kube/config) and switched kubectl to it.
k3s runs its own components as Pods, and the nodes download their images themselves. List them to check that the cluster can download images:
After about 40 seconds, all three Pods are 1/1 and Running. If they aren’t yet, wait a moment and repeat the
command. If they stay in ContainerCreating or show ErrImagePull or ImagePullBackOff, the nodes can’t download
images, usually because of a proxy. Let your trainer know before the training.
Delete the cluster again: