Set Up Your Environment

Requirements

Your container runtime must have access to at least:

Resource	Minimum
CPU	4 cores
RAM	10 GiB
Storage	40 GiB

Note

Windows (WSL): WSL only accesses 50% of host RAM by default. You’ll need a machine with at least 8 CPU cores and 20 GiB RAM. Adjust limits with a .wslconfig file.

---

Install Required Tools

macOS

1. Install Docker Desktop

   Download and install Docker Desktop for Mac. Start it and confirm it’s running before continuing.

   Note

   Docker Desktop requires a paid subscription for companies with 250+ employees or $10M+ revenue. Colima is a free alternative.

2. Install Homebrew

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

3. Install k3d

   k3d runs a lightweight Kubernetes cluster inside Docker.

   brew install k3d

Linux

1. Install Docker Engine

   Install Docker Engine for your distribution, or Docker Desktop for Linux.

   Note

   Docker Desktop requires a paid subscription for companies with 250+ employees or $10M+ revenue. Docker Engine is a free alternative.

2. Install Homebrew

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

   Add brew to your PATH (the installer prints the exact command for your shell):

   (echo; echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"') >> ~/.bashrc

   Install required dependencies:

   sudo apt-get install build-essential && brew install gcc

3. Install k3d

   brew install k3d

Windows (WSL)

Danger

Requires Windows 10 version 2004 (Build 19041+) or Windows 11. For older builds, follow the manual WSL installation guide.

1. Install WSL

   Open PowerShell as Administrator and run:

   wsl --install

   This installs WSL 2 with Ubuntu. Restart when prompted, then open Ubuntu and set a username and password.

   Update packages:

   sudo apt update && sudo apt upgrade

   Danger

   Istio requires Linux kernel 6.6.x or later on WSL. Update with:

   wsl --update --pre-release

2. Install a container runtime

   Option A: Docker Desktop for Windows — integrates automatically with WSL 2. In Docker Desktop settings, enable Use the WSL 2 based engine.

   Note

   Docker Desktop requires a paid subscription for companies with 250+ employees or $10M+ revenue.

   Option B: Docker Engine — install directly inside your WSL Ubuntu distribution as a free alternative.

3. Install Homebrew and k3d in your WSL terminal

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   brew install k3d

Troubleshooting WSL

• Ubuntu won’t start: Enable virtualization in your BIOS.
• Missing Windows features: Search “Turn Windows features on or off” → enable Virtual Machine Platform and Windows Subsystem for Linux.
• WSL running as version 1: Check with wsl -l -v. Upgrade with wsl --set-version <distro> 2.
• Running Windows in a VM: Enable nested virtualization in both the host BIOS and hypervisor.

---

Verify

Confirm your tools are installed and working:

docker info   # Docker is running
k3d version   # k3d is installed

Both commands should return version output without errors.

Note

kubectl is not required at this stage. Once UDS CLI is installed in the next step, you can use uds zarf tools kubectl as a built-in alternative.