Docker Machine Windows 10 Hyper-V Troubleshooting Tips

This blog post is a set of areas to look out for in case you are having issues with Docker Machine on Windows 10 , specifically when straight forward stuff like standard Docker Machine commands for creating, removing are failing.

I have a Windows 10 machine and my experience with native Docker on Windows 10 has been positive. I was happy with the fact that I no longer needed to install VirtualBox and instead the Hyper-V manager with Windows 10 did all the VM stuff behind the scenes.

Recently, I wanted to prepare for a talk on Docker Swarm and my requirement was to setup things on my local machine (Windows 10) itself. I did not want to go to a Cloud Provider to provision multiple hosts, though that is the thing that one might be better off doing but still I wanted to make all this work on my local Windows 10 laptop running Docker Native for Windows.

So, what I wanted to do was the following:

• Setup multiple Docker Machine hosts.
• Then try out the Docker Swarm mode and demonstrate multiple features like Swarm Manager node, worker nodes, Rolling update, scaling, services and more.

But the first thing was to setup multiple Docker machine hosts and here is where there are a few things to keep in mind.

For those of you, who used the Docker Toolbox on Windows earlier without Windows 10, the way to create the Docker Machine was the following command:

docker-machine create --driver virtualbox <machine-name>

Now, we do not have any VirtualBox setup on Windows 10 with native Docker for Windows and we wan’t to avoid that.

So it seems straightforward that all we need to do is use the driver for HyperV and we should be all set. The command goes something like this:

docker-machine create --driver hyperv <machine-name>

But this resulted in an error message that went like this:

Error creating machine: exit status 1

This resulted in a journey that led to the following things to check up on to ensure that your Docker Machine is able to create the machines successfully and in good state for you to try out Docker Swarm.

The points are listed in no particular order of importance.

Run as Administrator

Couple of things to keep in mind here:

• Ensure that you have Administrator rights on your computer. This will help a lot.
• We usually run these commands from the Command Prompt or the Powershell Window. Just ensure that you are running them as administrator. You can do then by going to Start → type cmd (or command) and then Ctrl+Shift+Enter or the screen as shown below

This will avoid errors like the one below:

Error creating machine: Error with pre-create check: Hyper-v commands have to be run as an Administrator

Get familiar with Hyper-V — just a bit

You need to understand that Microsoft Hyper-V is the hypervisor behind the scenes. In simple terms, not sure if this is the right way to put it, but it’s doing the work of VirtualBox for us.

From the Start → Run menu, type Hyper-V…. and you should see the application listed below:

Launch it. In my case, I have the barebones Docker for Windows installed and you can see the MobyLinuxVM setup in that. The screenshot is shown below:

I have shut down the Docker daemon and hence the state is Off.

I suggest that you try out a few clicks here and check out the Hyper-V settings. A sample screenshot is shown below. This will help you understand where the Virtual Hard Disks, Machines, etc are getting saved.

Click Virtual Switch manager and you should see the familiar DockerNAT that is created for you.

You will see an additional switch that I have created “External Virtual Switch”. More on that later.

Then click on the MobyLinuxVM and check out its Settings in the right pane. You will see different values like Memory allocated to the VM, etc.

So the first one that you should keep in mind is that if our Docker Machine command to create a machine succeeded, you should see additional entries over here in the list of VMs, in addition to the MobyLinuxVM that is handled by Docker for Windows native.

Use Windows Event Viewer

So I made sure that I had Administrator Access and launched the Command Terminal as an Administrator too. And tried out the same command to create my manager Docker host:

docker-machine create --driver hyperv manager1

It moved forward with some messages and started failing at creating the VHD. The error message was the same i.e. exit status 1.

Whenever you want to see what has caused the error, try the Event Viewer in Windows. It will have some details — if we get lucky.

To run the Event Viewer in windows, click on Start and Event Viewer as shown below:

The logs for Hyper-V are present in Applications and Service Logs → Microsoft → Windows

Inside that, I found the error details buried inside the following section:

The Admin section showed a series of errors and the details were:

This message seems to indicate some sort of rights issue. But it looks like there is some long standing bug somewhere here, as far as my search on the Internet could help. And the solution was not very encouraging to me. All it needed was a restart of the Hyper-V Virtual Machine Management service as shown in the next section.

Restart Hyper-V Virtualization Service

Go to Windows and restart this service if you see the above error message in your Event Viewer log. It worked for me.

Hyper-V External Virtual Switch

OK. The Docker Machine create machine command:

docker-machine create --driver hyperv manager1

moved forward now but tripped out on getting the IP Address and SSH.

(manager1) Creating SSH key…
(manager1) Creating VM…
(manager1) Using switch “DockerNAT”
(manager1) Creating VHD
(manager1) Starting VM…
(manager1) Waiting for host to start…
 Waiting for machine to be running, this may take a few minutes…
Detecting operating system of created instance…
Waiting for SSH to be available…

A few searches later, it led to the following link and then to the official docs for Microsoft Hyper-V driver (Lesson of the day: RTFM)

The documentation says and which I produce below:

You will need an existing virtual switch to use the driver.

What this means is that we have to use the Docker Machine create command as follows:

docker-machine create --driver hyperv --hyperv-virtual-switch "<<Your-External-Switch-Name>>" manager1

Now, we do we get or create this external switch? What is this switch? Well, its the networking part of the puzzle for your Docker machine, such that it can use your existing LAN or Wireless connection. That is the easiest way that I can explain but it should become clear in a moment.

Remember, I told you to get familiar with the Hyper-V application. Well, go ahead and launch it again. You should see the screen as shown below:

Now, go ahead and click on Virtual Switch Manager from the Actions list on the right.

That is where you will need to define your External Switch. Click on that.

Click on new virtual network switch on the left and select External for the type of virtual switch. Then click on Create Virtual Switch button.

This will bring up the switch properties where you should give it a name and select the correct network connection to use. In my case, I have both the LAN and the Wireless. So select the correct one.

Then click on Apply. It will apply the settings.

Once it is applied, I suggest that you go to your Windows Network and Sharing Center.

Click on change Adapter settings and you should be able to see all the new switch that you created along with DockerNAT too. Just ensure that your new switch is enabled and connected. This is important.

Now, when creating the docker machine, you will need to give the name of the External Switch, which is then provided to the Hyper-V driver.

The final command that worked for me is given below:

docker-machine create — driver hyperv — hyperv-virtual-switch 
"External Virtual Switch" manager1

Note: The “External Virtual Switch” is the name of my switch. It could be different in your case.

This succeeds finally. You can then create the multiple Docker machines that you want for your Swarm.

Once the machines are successfully created, you can check two things:

• Execute the docker-machine ls command to see your machines.
• Go to Hyper-V and see the multiple Hyper-V VMs. In my case, I had the following:

Regenerating Certs

Occasionally, when you do a docker-machine ls, you might run into a message in the output, mentioning that the certificates were generated for a particular IP and now it is different. I guess as it switches networks and gets an IP, this can happen.

In these situations, I have simply gone ahead with the regenerte-certs command for docker-machine:

$ docker-machine regenerate-certs <machine-name>

Removing Zombie Docker Machines

Another issue I have run into at times is that there was some issue or the other creating the Docker machine. As a result of that, the docker machine is listed when you execute the ls command but you are not able to remove it via the following command:

$ docker-machine rm <machine-name>

In such cases, I have used the ( — force) flag as shown below:

$ docker-machine --force rm <machine-name>

In Summary

Hope this troubleshooting guide helps you in overcoming some of the issues that you might face while creating / managing Docker Machines on your Windows 10 box.

If you have any suggestions/corrections — please let me know. I am not an expert in Windows 10 or Hyper-V and the above is more of a trial and error and dogged persistence to get it to work. :-)