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.io and 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:

wsl --install

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):

wsl -l -v

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:
    brew install --cask docker-desktop
  • Windows (WSL): install Docker Desktop for Windows on the Windows side, start it and connect it to WSL:
    1. Settings > General: make sure Use WSL 2 based engine is selected
    2. Settings > Resources > WSL Integration: enable the integration for Ubuntu
    3. 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).

Alternative for WSL: Docker Engine without Docker Desktop

Use either Docker Desktop with WSL integration or Docker Engine inside WSL, never both. If Docker Desktop is installed, disable its WSL integration first.

Don’t install the snap package (sudo snap install docker) that Ubuntu suggests when docker is missing: it doesn’t create the docker group, so the usermod command below fails.

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER   # allows running docker without sudo
sudo systemctl enable --now docker

On WSL, the script warns that it detected WSL and waits 20 seconds. Let it continue.

Close and reopen the WSL terminal so the new group membership takes effect.

The Docker service requires systemd, which is enabled by default for Ubuntu installed with wsl --install. Details: https://docs.docker.com/engine/install/ubuntu/

Verify the daemon is running:

docker info

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 the docker group: run sudo usermod -aG docker $USER and reopen the terminal.

Pull a test image to make sure Docker can download images. In company networks, a proxy can block this:

docker pull nginx:1.29

The output ends with:

Status: Downloaded newer image for nginx:1.29
docker.io/library/nginx:1.29
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:

docker run -d --rm --name wsl-test -p 8080:80 nginx:1.29

Open http://localhost:8080 in your Windows browser. You should see the Welcome to nginx! page. Stop the container afterwards:

docker stop wsl-test

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:
    brew install k3d
  • Linux / WSL:
    curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash
  • All platforms: https://k3d.io

Verify the installation. The k3d version must be v5.9 or newer:

k3d version

kubectl

kubectl is the command-line client of Kubernetes. Every lab uses it to talk to your cluster.

  • macOS:
    brew install kubectl
  • Linux / WSL:
    curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
    sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
    rm kubectl
  • All platforms: https://kubernetes.io/docs/tasks/tools/

Verify the installation. The client version must be v1.35 or newer:

kubectl version --client
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):
    echo 'autoload -Uz compinit && compinit' >> ~/.zshrc
    echo 'source <(kubectl completion zsh)' >> ~/.zshrc
    source ~/.zshrc
  • Linux / WSL (default shell: bash):
    sudo apt install -y bash-completion
    echo 'source <(kubectl completion bash)' >> ~/.bashrc
    source ~/.bashrc

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):
    echo 'alias k=kubectl' >> ~/.zshrc
    source ~/.zshrc
  • Linux / WSL (default shell: bash):
    echo 'alias k=kubectl' >> ~/.bashrc
    source ~/.bashrc

If you enabled the command completion in bash, enable it for k as well (zsh does this automatically):

echo 'complete -o default -F __start_kubectl k' >> ~/.bashrc
source ~/.bashrc

Verify the alias:

k version --client
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:
    brew install kubecolor
    echo 'alias kubectl=kubecolor' >> ~/.zshrc
    source ~/.zshrc
  • Linux / WSL:
    curl -fsSLO https://github.com/kubecolor/kubecolor/releases/download/v0.8.0/kubecolor_0.8.0_linux_amd64.deb
    sudo apt install -y ./kubecolor_0.8.0_linux_amd64.deb
    rm kubecolor_0.8.0_linux_amd64.deb
    echo 'alias kubectl=kubecolor' >> ~/.bashrc
    source ~/.bashrc

If you enabled the command completion in zsh, keep it working with kubecolor (bash needs nothing extra):

echo 'compdef kubecolor=kubectl' >> ~/.zshrc
source ~/.zshrc

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:
    brew install helm
  • Linux / WSL:
    curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-4
    chmod 700 get_helm.sh
    ./get_helm.sh
    rm get_helm.sh
  • All platforms: https://helm.sh/docs/intro/install/

Verify the installation. The version must start with v4:

helm version

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):

mkdir -p ~/labs

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.

  1. Install the Kubernetes plugin via Settings > Plugins

Windows: open the terminal in WSL

  1. Open Settings > Tools > Terminal
  2. Set Shell path to wsl.exe
  3. Open a new terminal tab (View > Tool Windows > Terminal) and verify that it runs in WSL:
    echo $WSL_DISTRO_NAME
    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

Windows: open the terminal in WSL

  1. Install the WSL extension (ms-vscode-remote.remote-wsl)
  2. In the WSL terminal, open the lab directory:
    cd ~/labs
    code .
  3. The status bar shows WSL: Ubuntu in the bottom-left corner. Terminal > New Terminal now opens a WSL shell. Verify it:
    echo $WSL_DISTRO_NAME
    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:

  1. Python (ms-python.python)
  2. Kubernetes (ms-kubernetes-tools.vscode-kubernetes-tools)

Verify the Setup

Create a throwaway cluster to check that all tools work together:

k3d cluster create setup-test \
  --k3s-arg "--disable=traefik@server:*" \
  --k3s-arg "--disable=servicelb@server:*"

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:

kubectl get nodes
NAME                      STATUS   ROLES           AGE   VERSION
k3d-setup-test-server-0   Ready    control-plane   9s    v1.35.5+k3s1

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:

kubectl get pods -A
NAMESPACE     NAME                                      READY   STATUS    RESTARTS   AGE
kube-system   coredns-8db54c48d-ffgqq                   1/1     Running   0          35s
kube-system   local-path-provisioner-5d9d9885bc-2w8zp   1/1     Running   0          35s
kube-system   metrics-server-786d997795-pdg5c           1/1     Running   0          35s

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:

k3d cluster delete setup-test