Getting started with Docker and Kubernetes on Windows 10

December 2020

TL;DR : In this article you learn how to install the necessary tools to run Docker & Kubernetes on Windows 10: Docker for Windows, Minikube, Kind, and K3s. You'll also learn which setup is the best with regards to your machine.

How to install Kubernetes and Docker on Windows 10

Docker and Kubernetes are two popular tools to run containers at scale.

So what's the problem with getting both of these tools on Windows?

Containers come in two flavours: Windows and Linux containers.

However, the majority of the time, when people say containers, they refer to Linux containers.

Unfortunately, you can't run Linux containers on a Windows host or vice versa.

That's because containers expect to use the kernel of the operating system they're designed for.

A Linux executable expects a Linux host, and there's no way to run it on Windows!

But there's a workaround.

You could create a Virtual Machine that runs Linux on your Windows host.

This will let every Linux application or executable run inside a container in the virtual machine.

So how do we choose the right Virtual Machine?

It depends on your hardware and operating system.

There are several options available.

Today, you're going to determine which combination is best for you and get up to speed on how to install it.

Specifically, we're going to look whether you should install Docker through Docker for Windows or Minikube AND whether you should use Minikube, Kind, or K3s for Kubernetes.

Table of contents:

The challenge with running Linux containers on Windows 10
What options you have to run containers on Windows 10?
Installing Docker for Windows With WSL 2 or Hyper-V
What options do you have for installing Kubernetes on Windows 10?
Installing Kubernetes on Windows 10 with Minikube
Installing Kubernetes on Windows 10 with Kind
Installing Kubernetes on Windows 10 with K3s
Appendix 1: Installing WSL 2
Appendix 2: Installing Chocolatey

The challenge with running Linux containers on Windows 10

Containers are processes that are isolated from the rest of the operating system but still use their resources.

Imagine clicking on an icon on your desktop and launching an application — the application runs unrestricted and can use as many CPU and memory as needed.

If you execute the same application but within a container, not only you can define how much memory and CPU it will use at most, but you can also restrict access to the filesystem, network, etc.

Containers use the underlying operating system to offer a restricted view of the resources available.

If your operating system is Windows, you can isolate Windows applications in containers.

The same is the case for Linux.

However, if you want to run Linux containers on Windows, you can't unless you run a Linux host.

You have a few options when it comes to running Linux on your computer, but it all boils down to running a virtual machine.

Here's a quick summary:

Let's have a look in detail.

What options you have to run containers on Windows 10?

Docker is a tool designed to run containers.

It can run both Windows and Linux containers, but in this guide, you will focus primarily on Linux containers.

When Docker for Windows was released, it supported Hyper-V as its virtualization technology.

In other words, every Linux container that you created ran inside a virtual machine in Hyper-V.

Hyper-V is a Type-1 hypervisor and thus provides excellent performance for running virtual machines on Windows.

Then in May 2019, Windows Subsystem for Linux 2 (WSL 2) was announced.

WSL 2 runs a Hyper-V virtual machine with Linux inside — just like Docker does.

Why is WSL 2 a big deal?

WSL 2 runs on top of the Windows Hypervisor (Hyper-V), which is a bare-metal hypervisor.

You can expect the best type of performance from this hypervisor.

WSL 2 also supports memory reclaim, and this means that the system uses only the right amount of RAM required for running the Linux kernel.

And best of all, WSL 2 offers deep integration with the rest of the Windows host.

You can navigate and copy files across the virtual machine as if it were natively on Windows.

For more information on WSL 2, you should check out this deep dive by Microsoft themselves.

Wouldn't it be great if you could use WSL2 to run your Docker containers?

If you're running WSL 2, Docker for Windows integrates with it automatically, and it leverages the existing WSL 2 virtual machine to run your containerised applications.

If your Windows 10 build is higher than 19018, you should be easily able to install it.

You can check your build version with the following command:

—

□

𝖷

PowerShell

Get-ComputerInfo OsName,OsVersion,OsBuildNumber
OsName                      OsVersion  OsBuildNumber
------                      ---------  -------------
Microsoft Windows 10 Pro    10.0.19041 19041

You can follow the instructions on how to install WSL 2 here.

In case you don't have access to WSL 2, that's where things get a bit tricky.

Without WSL 2, your second best option for running Linux containers on Windows is using Docker for Desktop with Hyper-V.

In other words, rather then reutilising the Hyper-V virtual machine created by WSL 2, Docker for Windows creates a brand new virtual machine.

Unfortunately, not all Windows versions ship with Hyper-V.

Hyper-V is unavailable on Windows 10 Home, but ships with the Windows 10 Pro and Enterprise editions.

You can check if your computer supports Hyper-V with the following command:

—

□

𝖷

PowerShell

Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V
FeatureName      : Microsoft-Hyper-V
DisplayName      : Hyper-V Platform
RestartRequired  : Possible
State            : Enabled

If you have Hyper-V, but it is disabled, you can enable it with: Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All.

If your computer supports Hyper-V but not WSL 2, you can jump to the next chapter to install Docker for Windows on Hyper-V.

If your Windows installation doesn't have WSL 2 or Hyper-V, you can't install Docker for Windows unless you upgrade.

Installing Docker for Windows with WSL 2 or Hyper-V

Instead of downloading the binary and manually insert environment variables, this guide uses Chocolatey the Windows package manager to install Docker for Windows.

You can follow the instructions on how to install Chocolatey here.

With Chocolatey, you can install Docker for Windows with:

—

□

𝖷

PowerShell

choco install docker-desktop -y
Installing the following packages:
docker-desktop
By installing you accept licenses for the packages.
# truncated output
Installing docker-desktop...
docker-desktop has been installed.

Once the installation is over, you can search in the Windows menu for Docker by typing its name.

If it's there, restart your PC for the changes to take effect because, without it, it won't run.

After the restart, you might see the following error:

This error arises when virtualization is disabled in the BIOS.

The easiest way to find this setting in your BIOS is to Google the query "enable virtualization in bios + laptop name/motherboard name".

There's a high chance you can find a tutorial specific to your machine that shows you all the steps to accomplish the task.

Once you make the changes, restart your machine and Docker should now work.

To confirm if it works, open PowerShell as an administrator and type:

—

□

𝖷

PowerShell

docker ps
CONTAINER ID   IMAGE   COMMAND   CREATED   STATUS   PORTS   NAMES

You can verify that Docker is installed correctly with the following command:

—

□

𝖷

PowerShell

docker run hello-world
Hello from Docker!
This message shows that your installation appears to be working correctly.

Excellent, now that you've installed Docker for Windows, you're ready to install Kubernetes.

What options do you have for installing Kubernetes on Windows 10?

Similar to Docker, Kubernetes has constraints that you need to watch out for.

Kubernetes can run Windows and Linux containers.

However, you can only run Windows containers on Windows nodes and Linux containers on Linux nodes.

And there's a further constraint: the Kubernetes control plane can only run on a Linux node.

In other words, Kubernetes will have to run inside a Linux virtual machine to operate correctly on Windows.

Here you have the same choice of virtual machines as you had with Docker:

You can run Kubernetes in WSL 2.
If your Windows version supports it, you can use Hyper-V to create a virtual machine or
You can create a virtual machine using VirtualBox.

But choosing a virtual machine is only part of the challenge.

There are several tools designed to run a Kubernetes cluster locally.

In this guide, you will cover Minikube, Kind and K3s.

But how do you decide which method to install with?

Well, it depends on your use case.

Are you getting started with Kubernetes and you need a fully working environment in no time? If so, Minikube will work just right.
If you're extending Kubernetes or you need to test Kubernetes using clusters larger than a single node, Kind is the way to go.
If you have a low spec machine or want something that uses fewer resources, K3s is what you need.

After that, you need to look at your hardware capabilities.

The methods we're going to look at demand anywhere from 2GB to up to 8GB of RAM.

To be specific, Minikube needs 2GB, Kind needs 8GB and K3s requires 2GB.

In most cases, your hardware will easily be able to support all three methods.

Once you know which methods your system is capable of running, you can look at your use case and choose your preferred method.

	WSL 2	Hyper-V	VirtualBox
Minikube	✅	✅	✅
KinD	✅	✅
K3s	✅	✅	✅

Click here to learn how to install Minikube
Click here to learn how to install Kind
Click here to learn how to install K3s

Installing Kubernetes on Windows 10 with Minikube

Minikube is one of the most developer-friendly local Kubernetes cluster that you can install.

If you haven't done so, install Chocolatey — the Windows package manager.

You can find the instructions here.

Open PowerShell as an administrator and execute:

—

□

𝖷

PowerShell

choco install minikube -y
Installing the following packages:
minikube
By installing you accept licenses for the packages.
# truncated output
minikube package files install completed. Performing other installation steps.
The install of minikube was successful.

Once the installation is complete, you can launch a local cluster with:

—

□

𝖷

PowerShell

minikube start
👍  Starting control plane node minikube in cluster minikube
🐳  Preparing Kubernetes v1.25.2 ...
🔎  Verifying Kubernetes components...
🌟  Enabled addons: default-storageclass, storage-provisioner
🏄  Done! kubectl is now configured to use "minikube" by default

Minikube follows the same logic as Docker for Windows.

If WSL 2 has been installed, it will be used by default.

If WSL 2 isn't available, Minikube will try to use the same Hyper-V virtual machine created by Docker for Windows.

You can also create a separate Hyper-V virtual machine with :

—

□

𝖷

PowerShell

minikube start --driver=hyperv

After a while, you'll either have a successful installation or be presented with some error.

In most cases, if following the instruction doesn't help, you should try to delete the cluster with:

—

□

𝖷

PowerShell

minikube delete
🔥  Deleting "minikube" ...
💀  Removed all traces of the "minikube" cluster.

And create a new one with:

—

□

𝖷

PowerShell

minikube start --v=7

The --v=7 flag increases the logging level, and you should be able to spot the error in the terminal output.

Once the command completes successfully, you can test the setup with:

—

□

𝖷

PowerShell

kubectl get nodes
NAME       STATUS   ROLES    AGE   VERSION
minikube   Ready    master   13d   v1.19.4

Congrats you have a fully working Kubernetes cluster!

Installing Kubernetes on Windows 10 - Kind

Kind is short for Kubernetes in Docker.

As the name suggests, you need to have a working installation of Docker before you can use KinD.

You can refer to instructions at the top of this article on the best option to install Docker on your machine.

Once Docker is installed, you should install kubectl next.

Kubectl is a command-line interface that assists in handling Kubernetes clusters.

In most cases, it should easily be installed through Chocolatey with:

The steps to install Chocolatey are described here.

—

□

𝖷

PowerShell

choco install kubernetes-cli -y
Installing the following packages:
kubernetes-cli
By installing you accept licenses for the packages.
# truncated output
The install of kubernetes-cli was successful.

If that doesn't work, you can do it manually as well.

You can follow the instructions on the official homepage.

Now you will use choco to install Kind.

—

□

𝖷

PowerShell

choco install kind -y
Installing the following packages:
kind
By installing you accept licenses for the packages.
# truncated output
The install of kind was successful.

If you hadn't installed Docker till now, the above command should install it automatically.

Note: If you have WSL 2 installed, it will automatically be used.

Let's test it:

—

□

𝖷

PowerShell

kind create cluster
Creating cluster "kind" ...
 ✓ Ensuring node image (kindest/node:v1.19.1) 🖼
 ✓ Preparing nodes 📦
 ✓ Writing configuration 📜
 ✓ Starting control-plane 🕹️
 ✓ Installing CNI 🔌
 ✓ Installing StorageClass 💾
Set kubectl context to "kind-kind"
You can now use your cluster with:

kubectl cluster-info --context kind-kind

Have a nice day! 👋

The command could take a while (5 minutes+ and if your RAM is 8GB, you'll see some slowdown as well).

To check if we were successful, type:

—

□

𝖷

PowerShell

kubectl cluster-info --context kind-kind
Kubernetes control plane is running at https://127.0.0.1:58120
CoreDNS is running at https://127.0.0.1:58120/api/…

To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.

Excellent, your cluster is ready!

Installing Kubernetes on Windows 10 - K3s

K3s is a minimal distribution of Kubernetes.

You can install K3s on:

WSL 2
Hyper-V or VirtualBox virtual machines.

You should pick the WSL 2 installation method if your computer supports it.

Using K3s with WSL 2

Now install K3s from this Github repository.

Open the WSL 2 shell and execute the following commands:

—

□

𝖷

PowerShell

chmod +x k3s
sudo ./k3s server

If you encounter problems, you might find it worth your time to check out this discussion).

If your computer doesn't support WSL 2, you can try MultiPass.

Using K3s with MultiPass

MultiPass is a tool that creates and manages virtual machines that are based on Ubuntu.

You can download MultiPass with Chocolatey with:

—

□

𝖷

PowerShell

choco install multipass -y
Installing the following packages:
multipass
By installing you accept licenses for the packages.
# truncated output
The install of multipass was successful.

Once downloaded, run the executable file and choose installation options.

During the installation, you'll be asked if you want to use Hyper-V or VirtualBox.

If you have Hyper-V, go for it.

Otherwise, stick to VirtualBox.

To launch a node with Multipass, open PowerShell and execute:

—

□

𝖷

PowerShell

multipass launch -n node1
Launched: node1

Here you created a node with default configurations of 1GB RAM and one CPU named node1.

To verify if the node exists, you can execute:

—

□

𝖷

PowerShell

multipass list
Name                    State             IPv4             Image
node1                   Running           172.25.60.186    Ubuntu 20.04 LTS

Sometimes you might not see an IP address assigned to your virtual machine.

There are a couple of reasons why you might encounter errors with the above command:

Encountering a mistake because of VirtualBox or Hyper-V.
Having a public network enabled.
Having corrupted IP addresses.

Encountering an error because of VirtualBox or Hyper-V

Although Hyper-V is recommended, there's a chance it just might not work on your system.

In that case, you should try changing your hypervisor.

To change to Hyper-V, type:

—

□

𝖷

PowerShell

multipass set local.driver=hyperv

To change to VirtualBox, type:

—

□

𝖷

PowerShell

multipass set local.driver=virtualbox

When you perform either change, be sure to reboot your system.

Having a public network enabled

MultiPass can give errors on a public network.

Type the following command to get information on your network:

—

□

𝖷

PowerShell

Get-NetConnectionProfile
Name             : Network
InterfaceAlias   : Ethernet
InterfaceIndex   : 6
NetworkCategory  : Public
IPv4Connectivity : Internet
IPv6Connectivity : NoTraffic

The NetworkCategory variable will tell you if your network is set to public or private.

The output will also give you an InterfaceIndex variable.

You'll have that to change the network category to Private.

To change your network profile, execute:

—

□

𝖷

PowerShell

Set-NetConnectionProfile -InterfaceIndex 'your number' -NetworkCategory Private

Having corrupted IP addresses

When you execute multipass list and see a dash in the IP address column like below:

—

□

𝖷

PowerShell

multipass list
Name                    State             IPv4             Image
node1                   Running           N/A              Ubuntu 20.04 LTS

It means that your node isn't assigned any IP address.

To fix that you need open a file called hosts.ics which can be located in either path:

C:\Windows\System32\drivers\etc\hosts.ics
C:\Windows\System32\drivers\hosts.ics

Retrieve the content of the file and check if your machine has an IP address assigned to it.

—

□

𝖷

cat C:\Windows\System32\drivers\etc\hosts.ics
172.25.48.1 learnk8s.mshome.net
172.25.60.186 node1.mshome.net

If you see anything other than an IP address like random numbers, you need to do the following:

Uninstall Multipass.
Delete hosts.ics.
Reboot.
Reinstall Multipass.
Rerun the launch command.

When your launch fails for whatever reason, you'll be unable to create another node of the same name without clearing the list.

Before debugging, do this:

—

□

𝖷

PowerShell

multipass delete --purge --all

Just keep in mind that this command deletes all instances.

Installing K3s on the node

Now you will install K3s on this node with the following command:

—

□

𝖷

PowerShell

multipass exec node1 -- bash -c "curl -sfL https://get.k3s.io | sh -"

After a little wait you should be able to see your cluster in action with:

—

□

𝖷

PowerShell

multipass exec node1 -- sudo kubectl get nodes
NAME       STATUS   ROLES    AGE   VERSION
node1      Ready    master   13d   v1.19.4+k3s1

Congratulations, you installed K3s!

Appendix 1: Installing WSL 2

There are two ways you can install WSL 2: simplified and manual install.

To use the simplified install method, you need to be a member of the Windows Insider Program and have the preview build of Windows 10 (build 20262 or higher).

Then open PowerShell as an admin and type:

—

□

𝖷

PowerShell

wsl --install

After the installation, you'll need to restart your machine.

For a manual installation, perform the following steps:

Enable WSL through the PowerShell as an administrator with:

—

□

𝖷

PowerShell

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
Deployment Image Servicing and Management tool
Version: 10.0.19041.572

Image Version: 10.0.19041.685

Enabling feature(s)
[==========================100.0%==========================]
The operation completed successfully.

Now, enable the 'Virtual Machine Platform' setting through:

—

□

𝖷

PowerShell

Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform -NoRestart
Path          :
Online        : True
RestartNeeded : False

Reboot your system for the changes to take effect.

Set WSL 2 as the default version with:

—

□

𝖷

PowerShel

wsl --set-default-version 2

Next thing you need is a Linux distro.

You can get them from the Microsoft Store.

If you are not sure, select Ubuntu as the Linux distro.

It might take a while to complete the installation, but once it is successful, you can test with:

—

□

𝖷

PowerShell

wsl --list --verbose
  NAME                   STATE           VERSION
* ubuntu-20.10           Running         2

As a safety measure, we'll need to explicitly limit how much resource allowance we give to WSL 2.

Simply go to C:\users\your profile and create a .wslconfig file.

Here's what its contents should be:

.wslconfig

[wsl2]
memory=4GB
processors=3

Open PowerShell as an administrator and execute:

—

□

𝖷

PowerShell

Restart-Service LxssManager

To restart WSL 2 for the configurations to take place.

Appendix 2: Installing Chocolatey

Installing binaries on Windows could take some time.

You have to visit a website, hope that the download URL is still valid, search for the download page, select the right version, download it, install it, and finally add it to your path.

It's doable, but I'm sure you would rather spend time doing more coding than chasing and installing executables from the internet.

Enter Chocolatey.

Chocolatey is a package manager for Windows.

You tell it what executables you wish to install, and Chocolatey installs them on your behalf.

You're outsourcing all the hard work of provisioning software to Chocolatey.

Installing Chocolatey is easy.

You can find the full instructions on the official website.

To verify the installation, type:

—

□

𝖷

PowerShell

choco -v
0.10.15

Now you can use choco install <name> to install any executable you wish.