WSL2: Seamlessly Install Ubuntu OS, Docker, and Kubernetes on Windows for a Development Environment

Updates:

• In the troubleshooting section, I have added how to enable connection from your Windows server to an Ingress deployment running on WSL.
• Adding Helm installation

Introduction — What is WSL

WSL (Windows Subsystem for Linux) is a tool that allows you to run a Linux operating system, such as Ubuntu, directly on your Windows computer without the need for a full Linux installation or using virtual machine applications like Oracle VirtualBox or VMware Player where you can install any Operating System. It allows you to execute Linux commands and run Linux-based programs within Windows, making developing or running Linux-specific software much easier.

As a DevOps professional working with a Windows laptop (due to company policy), WSL has been a lifesaver. I can run essential tools like Docker, Ansible, Terraform, and more on a Linux environment (as they are intended to be used), while having access to the files managed by my Windows system.

Blog Goals

In this blog, we will cover the following items:

1. Install WSL (Windows Subsystem for Linux) on Windows

We will follow the steps to set up WSL on your Windows operating system.

2. Upload a Public Certificate

In organizations using VPNs like Palo Alto, WSL may be unable to integrate with external sites due to missing certificates. We will cover how to upload a public certificate to solve this.

3. Install Docker & Docker Compose

Since Docker Desktop requires a license in enterprise environments, we will show how to install and run Docker directly in WSL. This is also a great opportunity to learn Docker CLI commands.

4. Install Minikube

Minikube is an alternative to a full Kubernetes cluster that can run on your WSL setup. We will guide you through the installation process.

5. Install kubectl

Kubectl is the Kubernetes command-line tool used to interact with your Kubernetes cluster. In this section, we will walk through the installation process and verify that it works with the install Kubernetes cluster installed with the minikube.

6. Install Helm

Helm is an open-source package manager for Kubernetes. It simplifies the management, deployment, and scaling of applications on Kubernetes clusters by using pre-configured application templates called charts. With Helm, you can package applications, share them through repositories, and manage their lifecycle, including upgrades, rollbacks, and uninstalls, all through a user-friendly CLI. Helm enables you to streamline Kubernetes operations, making it easier to deploy complex applications consistently across multiple environments.

7. Install Ansible

Ansible is an open-source IT automation tool . It allows you to define, deploy, and manage configurations for infrastructure components such as servers, applications, networks, and more in a declarative, human-readable YAML syntax. With Ansible, you can automate tasks like provisioning, configuration management, application deployment, and orchestration across various platforms.

8. Install Terraform

Terraform is an open-source Infrastructure as Code (IaC) tool created by HashiCorp. Terraform enables you to define, provision, and automate clouded service infrastructure such as virtual machines, storage, networking, and many other infrastructure components across various platforms.

9. Connect Visual Studio (vs code) to your WSL server

Visual Studio Code (VS Code) is a free, open-source code editor developed by Microsoft. It’s a lightweight yet powerful tool designed for developers to write, debug, and manage code across a wide variety of programming languages and frameworks.

Install WSL

Run the following steps to install WSL on your Windows operating system

1. Open Powershell terminal as admin and run wsl — -install

WSL installation using powershell

This command installs the following Windows components

• Virtual Machine Platform
• Windows Subsystem For Linux

If for any reason the installation using the PowerShell terminal fails, you can install these components from “Turn Windows feature on or off” — You can access this option by searching for Turn Windows features on or off from windows command line

Enable windows components

2. Reboot the Windows Operating system

3. After the reboot, WSL terminal will start automatically, and ask to define username and password (Update the username and password and don't forget it)

Note: Sometimes, due to previous installations, the WSL terminal will not start automatically. If this is the case, run the following steps:

• Open Powershell terminal as admin and run again wsl — -install

• Define username and password

5. Start WSL terminal by running wsl from the Windows command line

6. Run lsb_release -a to confirm that Ubuntu 24.04 release is installed

Verify Ubuntu version

7. Verify that WSL is running with version 2

• Open Powershell terminal as admin and run wsl -l -v
• Verify that the Ubuntu is set to version 2

Verify WSL version

• If version 1 is present, run the following command from the PowerShell terminal wsl — set-default-version 2

You now have Ubuntu 24.04 Operating System running on your Windows operating system.

To navigate to your files located on the Desktop from WSL , run cd /mnt/c/Users/<yout-user-name>/Desktop

Note: /mnt/c -refers to drive C on your windows operating system

Install Public Certificate (Optional)

Organizations that use a VPN solution like Palo Alto, where all internet traffic is routed through the Palo Alto appliance, may require you to upload the appliance’s public certificate to your WSL environment for secure communication. This is typically done to enable secure SSL/TLS connections when WSL accesses the internet through the VPN.

To update the certificate in WSL run the following steps

1. Obtain the Public certificate

• Ask your IT department for your organization’s public certificate.

Alternatively, you can retrieve it yourself:

• Open your web browser.
• Visit a trusted internal or external website.
• Download the certificate that your browser uses for SSL communication (often available in the browser’s developer tools or certificate viewer). This certificate will be your organization’s public certificate

2. Copy the certificate to your workstation system under c:/cert/organization.crt ; you can copy it to any path you wish

3. Open the WSL terminal by running wsl in the Windows command line

4. Navigate to the certificate location by running cd /mnt/c/cert

Note: /mnt/c/ refers to your Windows C drive

5. run ll and verify that you can locate the CRT file

6. Copy the certificate to /usr/local/share/ca-certificates by running

sudo cp organization.crt /usr/local/share/ca-certificates

Note: Due to the fact we are running the command with sudo , you will be asked to write your password

7. Enable the certificate by running the command

sudo update-ca-certificates

8. Verify connectivity to the internet by running apt update

Install Docker

If you are working in a small or enterprise organization, you are legally required to purchase a license to install Docker Desktop on your Windows operating system.

While there are alternatives to Docker Desktop, such as Podman, the best option is to install Docker directly on your WSL2 machine

To install docker and docker-compose on WSL run the following steps

1. Open the WSL terminal by running wsl in the Windows command line
2. Update Ubuntu by running the command

sudo apt-get update

3. Install ca-certificates & curl packages by running the command

sudo apt-get install ca-certificates curl

4. Create /etc/apt/keyrings directory by running the command

sudo install -m 0755 -d /etc/apt/keyrings

5. Download the certificate by running the command

sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc

6. Update file permission by running the command

sudo chmod a+r /etc/apt/keyrings/docker.asc

7. Add docker repo to apt source by running

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

8. update repo by running the command

sudo apt-get update

9. Install Docker and Docker compose by running the command

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

Docker and Docker compose installation

10. To Grant permission to your local user to run docker commands, run the following steps that will add your user to the docker group

• Run whoami
• Grant your user permission by running the command

sudo usermod -aG docker <the-user-name-from-privious-step>

• Shutdown WSL by Opening Powershell terminal as admin and run wsl — -shutdown to restart WSL

Shutdown WSL

Verification

Verify your installation by downloading and running docker image. Run the following steps:

1. open WSL terminal by running wsl in the Windows command line

2. Download and Run docker hello-world by running the command docker run hello-world

docker run hello-world

Install Minikube

Minikube allows you to run a local Kubernetes cluster on WSL for development.

Run the following steps to install minikube on WSL

1. open WSL terminal by running wsl in the Windows command line as a non-root user
2. Install minikube by running the following commands

curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64

sudo install minikube-linux-amd64 /usr/local/bin/minikube

minikube config set driver docker

Install Minikube

3. Shutdown WSL by Opening Powershell terminal as admin and run wsl — -shutdown to restart WSL

Verification

Run the following steps to confirm that minikube was installed

1. open WSL terminal by running wsl in the Windows command line as a non-root user
2. Verify minikube is installed by running the command minikube version
3. Start minikube by running the command minikube start (It might take a minute or two)
4. Verify minikube is running by running the command minikube status

Install kubectl

To interact with the minikube cluster like you are interacting with an ordinary Kubernetes cluster. install and run kubectl

1. open WSL terminal by running wsl in the Windows command line as a non-root user
2. Install kubectl by running the following commands

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

sudo install -o root -g root -m 0755 kubectl /usr/bin/kubectl

kubectl installation

3. Install the kubectl auto-complete feature by running the follwoing commands

sudo apt-get install bash-completion

sudo vi ~/.bashrc

• Add the following line to the end of the file source <(kubectl completion bash)
• Save the file

source ~/.bashrc

4. Restart WSL by running wsl — -shutdown from the PowerShell terminal

Verification

1. open WSL terminal by running wsl in Windows command line as a non-root user
2. Run kubectl get nodes
3. Run kubectl get pod -A

Install Helm

1. open WSL terminal by running wsl in Windows command line as a non-root user
2. Install Helm by running

curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3

chmod 700 get_helm.sh

./get_helm.sh

Verification

1. open WSL terminal by running wsl in Windows command line as a non-root user
2. Run helm version and verify that you can see the version

Install Ansible

1. open WSL terminal by running wsl in Windows command line as a non-root user
2. Install Ansible by running

sudo apt install ansible

Verification

1. open WSL terminal by running wsl in Windows command line as a non-root user
2. Run ansible — -version and verify that you can see the version

Install terraform

1. open WSL terminal by running wsl in Windows command line as a non-root user
2. Install terraform dependencies by running

sudo apt-get install -y gnupg software-properties-common

3. Add GPG key for HashiCorp by running

wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg

4. Add HasgiCorp repository by running

echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list

5. Update the repository by running sudo apt-get update

6. Install Terrform by running sudo apt-get install terraform

Verification

1. open WSL terminal by running wsl in Windows command line as a non-root user
2. Run terraform — -version and verify that you can see the version

Congrats !!!

You now have an Ubuntu Operating System that runs terraform , Ansible , docker and Kubernetes cluster based on minikube distribution

Integrate Visual Studio Code (vs code) with wsl

1. On your window machine install VScode using the following link https://code.visualstudio.com/download
2. Install WSL extension on vs code by running the following steps

• Start vs code application
• Navigate to File → Preferences → Extensions

• In the search line, look for wsl and click Install

vscode — wsl extenation

• Restart the vscode application.

3. To integrate WSl with VS code, run the following steps

• Open WSL terminal by running wsl in the Windows command line as a non-root user
• Navigate to the folder from where you wish to manage your project. In my example /mnt/c/project

• In the WSL terminal type code .

VS code application starts and shows your project folder. Every file that you will create using the vscode application will be created under your c:/project folder.

4. To open the terminal to your wsl from vscode , run the following steps:

• From the bottom right, find the terminal tab — Please note that sometimes it is hidden and you need to expand it
• If the terminal presents a Powershell, click on the + and click the ubuntu 24.04 wsl
• Now you can run all the commands like running it on wsl

Congrats !!!

Now you can manage and run projects like terraform directly from vs code

If you liked this blog don’t forget to clap and follow me on both Medium and Linkedin

www.linkedin.com/in/davidzbeda

Command & Troubleshooting

Command

• minikube start; Starts a Kubernetes cluster with a single node running both the control plane and the worker.
• minikube start — -nodes 3 ; Starts a Kubernetes cluster with 3 nodes.
• minikube stop; Stops the cluster while saving its state. Running minikube start will resume it from the last state.
• minikube delete; Deletes the Kubernetes cluster.
• To restart WSL, Open the PowerShell terminal as admin and run the command wsl — - shutdown

Troubleshooting

After minikube installation, External DNS can not be resolved— run the following steps to resolve this issue

1. sudo vi /etc/wsl.conf

• Add the following content to the file

[network]  
generateResolvConf = false

2. sudo vi /etc/resolv.conf

• Add or update nameserver 8.8.8.8

3. Restart WSL by running wsl — -shutdown from the PowerShell terminal

To add the auto-complete option to kubectl, run the following steps

1. open WSL terminal by running wsl in the Windows command line as a non-root user
2. sudo apt-get install bash-completion
3. sudo vi ~/.bashrc

• Add the following line to the end of the file source <(kubectl completion bash)
• Save the file

5. source ~/.bashrc

6. Restart WSL by running wsl — -shutdown from the PowerShell terminal

chmod command does not update file permission

1. sudo vi /etc/wsl.conf

• Add the following content to the file

[automount]
options = "metadata"

• Save the file

2. Restart WSL by running wsl — -shutdown from the PowerShell terminal

how to work with Ingress in minikube

Since Minikube is running on a virtual IP (you can run minikube ip to see the used ip) that is isolated from your local network and not directly reachable from your host system, you cannot access the Ingress that you define. To make it work, follow these steps:

1. start your minikube cluster by executing the command minikube start

2. Upload your deployment, service, and Ingress to the Kubernetes cluster — helm or yml file using kubectl apply -f command

3. Enabling NGINX Ingress Controller in your Minikube cluster allows you to define Ingress resources for routing external HTTP and HTTPS traffic to services within the cluster by executing the command: minikube addons enable ingress

4. Create a tunnel between Minikube Ingress ports 80 and 443 to your Windows machine. Behind the scenes, this tunnel forwards external traffic from your host machine’s ports 80 and 443 to the Minikube cluster, enabling access to services exposed via Ingress, similar to executing the kubectl port-forward command.) Enable tunnel by executing the command: minikube tunnel

5. Open your browser and navigate to the hostname or IP address specified in your Ingress resource (e.g., http://example.local).

Note:

• If you run minikube delete, you will need to enable the Ingress addon on the new cluster again.
• If you close the WSL terminal session, the tunnel will be closed.