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.
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. 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: brew install --cask docker-desktop, then start Docker Desktop from the Applications folder
  • 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 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.

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

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.

Test Docker in WSL (Windows only)

Run the following checks in the WSL terminal to make sure Docker works from inside WSL.

Check that the Docker CLI reaches the Docker daemon. The output must contain both a Client and a Server section:

docker version

Run a test container. You should see the message Hello from Docker!:

docker run --rm hello-world

Publish a port from a container and reach it from Windows:

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

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

docker stop wsl-test
Common errors
  • The command 'docker' could not be found in this WSL 2 distro — 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.

k3s and k3d

k3s is a lightweight, certified Kubernetes distribution — 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:

k3d version

The output shows the k3d version and the k3s version it deploys by default.

kubectl

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

kubectl version --client
Optional: alias k for kubectl

You will type kubectl a lot. Defining the short alias k for it is common practice among Kubernetes users — you will come across commands like k get pods in many blog posts, examples and talks. The alias is optional: this training always writes out the full kubectl command.

  • macOS (default shell: zsh):
    echo 'alias k=kubectl' >> ~/.zshrc
source ~/.zshrc
  • Linux / WSL (default shell: bash):
    echo 'alias k=kubectl' >> ~/.bashrc
source ~/.bashrc

Verify the alias:

k version --client

Helm

  • 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

yq

yq is a lightweight command-line YAML processor used to inspect and manipulate Kubernetes manifests and Helm values files.

  • macOS: brew install yq
  • Linux / WSL:
    sudo curl -fsSL -o /usr/local/bin/yq https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64
sudo chmod +x /usr/local/bin/yq
    Do not use apt install yq — the Debian package is no longer maintained.
  • All platforms: https://github.com/mikefarah/yq

Verify the installation:

yq --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.

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 your project from the WSL file system: File → Open and select the folder under \\wsl.localhost\Ubuntu\home\<your-user>\.

Visual Studio Code

Windows: open the terminal in WSL

  1. Install the WSL extension (ms-vscode-remote.remote-wsl)
  2. In the WSL terminal, change into your project directory and open it with:
    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 — 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:*"
kubectl get nodes

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

You should see one node with the status Ready. k3d added the context k3d-setup-test to your kubeconfig (~/.kube/config) and switched kubectl to it.

Delete the cluster again:

k3d cluster delete setup-test