Windows container version compatibility

Windows Server 2016 and Windows 10 Anniversary Update (both version 14393) were the first Windows releases that could build and run Windows Server containers. Containers built using these versions can run on newer releases, but there are a few things you need to know before you start.

As we’ve been improving the Windows container features, we’ve had to make some changes that can affect compatibility. Older containers will run the same on newer hosts with Hyper-V isolation, and will use the same (older) kernel version. However, if you want to run a container based on a newer Windows build, it can only run on the newer host build.

Windows Server host OS compatibility

• Windows Server, version 20H2
• Windows Server, version 2004
• Windows Server, version 1909
• Windows Server, version 1903
• Windows Server 2019
• Windows Server 2016

Container base image OS version	Supports Hyper-V isolation	Supports process isolation
Windows Server, version 20H2	вњ”	вњ”
Windows Server, version 2004	вњ”	вќЊ
Windows Server, version 1909	вњ”	вќЊ
Windows Server, version 1903	вњ”	вќЊ
Windows Server 2019	вњ”	вќЊ
Windows Server 2016	вњ”	вќЊ

Container base image OS version	Supports Hyper-V isolation	Supports process isolation
Windows Server, version 20H2	вќЊ	вќЊ
Windows Server, version 2004	вњ”	вњ”
Windows Server, version 1909	вњ”	вќЊ
Windows Server, version 1903	вњ”	вќЊ
Windows Server 2019	вњ”	вќЊ
Windows Server 2016	вњ”	вќЊ

Container base image OS version	Supports Hyper-V isolation	Supports process isolation
Windows Server, version 20H2	вќЊ	вќЊ
Windows Server, version 2004	вќЊ	вќЊ
Windows Server, version 1909	вњ”	вњ”
Windows Server, version 1903	вњ”	вќЊ
Windows Server 2019	вњ”	вќЊ
Windows Server 2016	вњ”	вќЊ

Container base image OS version	Supports Hyper-V isolation	Supports process isolation
Windows Server, version 20H2	вќЊ	вќЊ
Windows Server, version 2004	вќЊ	вќЊ
Windows Server, version 1909	вќЊ	вќЊ
Windows Server, version 1903	вњ”	вњ”
Windows Server 2019	вњ”	вќЊ
Windows Server 2016	вњ”	вќЊ

Container base image OS version	Supports Hyper-V isolation	Supports process isolation
Windows Server, version 20H2	вќЊ	вќЊ
Windows Server, version 2004	вќЊ	вќЊ
Windows Server, version 1909	вќЊ	вќЊ
Windows Server, version 1903	вќЊ	вќЊ
Windows Server 2019	вњ”	вњ”
Windows Server 2016	вњ”	вќЊ

Container base image OS version	Supports Hyper-V isolation	Supports process isolation
Windows Server, version 20H2	вќЊ	вќЊ
Windows Server, version 2004	вќЊ	вќЊ
Windows Server, version 1909	вќЊ	вќЊ
Windows Server, version 1903	вќЊ	вќЊ
Windows Server 2019	вќЊ	вќЊ
Windows Server 2016	вњ”	вњ”

Windows 10 host OS compatibility

• Windows 10, version 20H2
• Windows 10, version 2004
• Windows 10, version 1909
• Windows 10, version 1903
• Windows 10, version 1809

Container base image OS version	Supports Hyper-V isolation	Supports process isolation
Windows Server, version 20H2	вњ”	вњ”
Windows Server, version 2004	вњ”	вќЊ
Windows Server, version 1909	вњ”	вќЊ
Windows Server, version 1903	вњ”	вќЊ
Windows Server 2019	вњ”	вќЊ
Windows Server 2016	вњ”	вќЊ

Container base image OS version	Supports Hyper-V isolation	Supports process isolation
Windows Server, version 20H2	вќЊ	вќЊ
Windows Server, version 2004	вњ”	вњ”
Windows Server, version 1909	вњ”	вќЊ
Windows Server, version 1903	вњ”	вќЊ
Windows Server 2019	вњ”	вќЊ
Windows Server 2016	вњ”	вќЊ

Container base image OS version	Supports Hyper-V isolation	Supports process isolation
Windows Server, version 20H2	вќЊ	вќЊ
Windows Server, version 2004	вќЊ	вќЊ
Windows Server, version 1909	вњ”	вќЊ
Windows Server, version 1903	вњ”	вќЊ
Windows Server 2019	вњ”	вќЊ
Windows Server 2016	вњ”	вќЊ

Container base image OS version	Supports Hyper-V isolation	Supports process isolation
Windows Server, version 20H2	вќЊ	вќЊ
Windows Server, version 2004	вќЊ	вќЊ
Windows Server, version 1909	вќЊ	вќЊ
Windows Server, version 1903	вњ”	вќЊ
Windows Server 2019	вњ”	вќЊ
Windows Server 2016	вњ”	вќЊ

Container base image OS version	Supports Hyper-V isolation	Supports process isolation
Windows Server, version 20H2	вќЊ	вќЊ
Windows Server, version 2004	вќЊ	вќЊ
Windows Server, version 1909	вќЊ	вќЊ
Windows Server, version 1903	вќЊ	вќЊ
Windows Server 2019	вњ”	вќЊ
Windows Server 2016	вњ”	вќЊ

Matching container host version with container image versions

Windows Server containers

Because Windows Server containers and the underlying host share a single kernel, the container’s base image OS version must match that of the host. If the versions are different, the container may start, but full functionally isn’t guaranteed. The Windows operating system has four levels of versioning: major, minor, build and revision. For example, version 10.0.14393.103 would have a major version of 10, a minor version of 0, a build number of 14393, and a revision number of 103. The build number only changes when new versions of the OS are published, such as version 1709, 1903, and so on. The revision number is updated as Windows updates are applied.

Build number (new release of Windows)

Windows Server containers are blocked from starting when the build number between the container host and the container image are different. For example, when the container host is version 10.0.14393.* (Windows Server 2016) and container image is version 10.0.16299.* (Windows Server version 1709), the container won’t start.

Revision number (patching)

Windows Server containers currently don’t support scenarios where Windows Server 2016-based containers run in a system where the revision numbers of the container host and the container image are different. For example, if the container host is version 10.0.14393.1914 (Windows Server 2016 with KB4051033 applied) and the container image is version 10.0.14393.1944 (Windows Server 2016 with KB4053579 applied), then the image might not start.

However, for hosts or images using Windows Server version 1809 and later, this rule doesn’t apply, and the host and container image don’t need to have matching revisions.

We recommend you keep your systems (host and container) up-to-date with the latest patches and updates to stay secure.

You might encounter issues when using Windows Server containers with the February 11, 2020 security update release (also called «2B») or later monthly security update releases. See this article for more details.

We strongly recommend you update both your host and containers with the latest patches and updates to stay secure and compatible. For important guidance for how to update Windows containers, see Update Windows Server containers.

Practical application

Example 1: The container host is running Windows Server 2016 with KB4041691 applied. Any Windows Server container deployed to this host must be based on the version 10.0.14393.1770 container base images. If you apply KB4053579 to the host container, you must also update the images to make sure the host container supports them.

Example 2: The container host is running Windows Server version 1809 with KB4534273 applied. Any Windows Server container deployed to this host must be based on a Windows Server version 1809 (10.0.17763) container base image, but doesn’t need to match the host KB. If KB4534273 is applied to the host, the container images will still be supported, but we recommend you update them to address any potential security issues.

Querying version

Method 1: Introduced in version 1709, the cmd prompt and ver command now return the revision details.

Method 2: Query the following registry key: HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion

To check what version your base image uses, review the tags on the Docker hub or the image hash table provided in the image description. The Windows 10 update history page lists when each build and revision was released.

Hyper-V isolation for containers

You can run Windows containers with or without Hyper-V isolation. Hyper-V isolation creates a secure boundary around the container with an optimized VM. Unlike standard Windows containers that share the kernel between containers and the host, each Hyper-V isolated container has its own instance of the Windows kernel. This means you can have different OS versions in the container host and image (for more information, see the following compatibility matrix).

To run a container with Hyper-V isolation, simply add the tag —isolation=hyperv to your docker run command.

Errors from mismatched versions

If you try to run an unsupported combination, you’ll get the following error:

There are three ways you can resolve this error:

• Rebuild the container based on the correct version of mcr.microsoft.com/microsoft-windows-nanoserver or mcr.microsoft.com/windows/servercore
• If the host is newer, run docker run —isolation=hyperv .
• Try running the container on a different host with the same Windows version

Choose which container OS version to use

As of April 16, 2019, the «latest» tag is no longer published or maintained for the Windows base OS container images. Please declare a specific tag when pulling or referencing images from these repos.

You must know which version you need to use for your container. For example, if you want Windows Server version 1809 as your container OS and want to have the latest patches for it, you should use the tag 1809 when specifying which version of the base OS container images you want, like so:

However, if you want a specific patch of Windows Server version 1809, you can specify the KB number in the tag. For example, to get a Nano Server base OS container image from Windows Server version 1809 with the KB4493509 applied to it, you would specify it like so:

You can also specify the exact patches you need with the schema we have used previously, by specifying the OS version in the tag:

The Server Core base images based on Windows Server 2019 and Windows Server 2016 are Long-Term Servicing Channel (LTSC) releases. If you for instance want Windows Server 2019 as your Server Core image’s container OS and want to have the latest patches for it, you can specify LTSC releases like so:

Matching versions using Docker Swarm

Docker Swarm doesn’t currently have a built-in way to match the version of Windows that a container uses to a host with the same version. If you update the service to use a newer container, it will run successfully.

If you need to run multiple versions of Windows for a long period of time, there are two approaches you can take: either configure the Windows hosts to always use Hyper-V isolation or use label constraints.

Finding a service that won’t start

If a service won’t start, you’ll see that the MODE is replicated but REPLICAS will get stuck at 0. To see if the OS version is the problem, run the following commands:

Run docker service ls to find the service name:

Run docker service ps (service name) to get the status and latest attempts:

If you see starting container failed: . , you can see the full error with docker service ps —no-trunc (container name):

This is the same error as CreateContainer: failure in a Windows system call: The operating system of the container does not match the operating system of the host. (0xc0370101) .

Fix — Update the service to use a matching version

There are two considerations for Docker Swarm. In the case where you have a compose file that has a service that uses an image you didn’t create, you’ll want to update the reference accordingly. For example:

The other consideration is if the image you are pointing to is one that you’ve created yourself (for example, contoso/myimage):

In this case, you should use the method described in Errors from mismatched versions to modify that dockerfile instead of the docker-compose line.

Mitigation — Use Hyper-V isolation with Docker Swarm

There is a proposal to support using Hyper-V isolation on a per-container basis, but the code is not done yet. You can follow progress on GitHub. Until that’s done, the hosts would need to be configured to always run with Hyper-V isolation.

This requires changing the Docker service configuration, then restarting the Docker engine.

Add a line with «exec-opts»:[«isolation=hyperv»]

The daemon.json file does not exist by default. If you find that this is the case when you peek into the directory, you must create the file. Then you’ll want to copy in the following:

Close and save the file, then restart the docker engine by running the following cmdlets in PowerShell:

After you’ve restarted the service, launch your containers. Once they’re running, you can verify the isolation level of a container by inspecting the container with the following cmdlet:

It will return either «process» or «hyperv». If you have modified and set your daemon.json as described above, it should show the latter.

Mitigation — Use labels and constraints

Here’s how to use labels and constraints to match versions:

Add labels to each node.

On each node, add two labels: OS and OsVersion . This assumes you’re running locally but could be modified to set them on a remote host instead.

Afterwards, you can check those by running the docker node inspect command, which should show the newly added labels:

Add a service constraint.

Now that you’ve labeled each node, you can update constraints that determine placement of services. In the following example, replace «contoso_service» with the name of your actual service:

This enforces and limits where a node may run.

To learn more about how to use service constraints, check out the service create reference.

Matching versions using Kubernetes

The same issue described in Matching versions using Docker Swarm can happen when pods are scheduled in Kubernetes. This issue can be avoided with similar strategies:

• Rebuild the container based on the same OS version in development and production. To learn how, see Choose which container OS version to use.
• Use node labels and nodeSelectors to make sure pods are scheduled on compatible nodes if both Windows Server 2016 and Windows Server version 1709 nodes are in the same cluster
• Use separate clusters based on OS version

Finding pods failed on OS mismatch

In this case, a deployment included a pod that was scheduled on a node with a mismatched OS version, and without Hyper-V isolation enabled.

The same error is shown in the events listed with kubectl describe pod

. After several attempts, the pod status will probably be CrashLoopBackOff .

Mitigation — using node labels and nodeSelector

Run kubectl get node to get a list of all nodes. After that, you can run kubectl describe node (node name) to get more details.

In the following example, two Windows nodes are running different versions:

Let’s use this example to show how to match the versions:

Take note of each node name and Kernel Version from the system info.

In our example, the info will look like this:

Name	Version
38519acs9010	14393.1715.amd64fre.rs1_release_inmarket.170906-1810
38519acs9011	16299.0.amd64fre.rs3_release.170922-1354

Add a label to each node called beta.kubernetes.io/osbuild . Windows Server 2016 needs both major and minor versions (14393.1715 in this example) to be supported without Hyper-V isolation. Windows Server version 1709 only needs the major version (16299 in this example) to match.

In this example, the command to add the labels looks like this:

Check the labels are there by running kubectl get nodes —show-labels.

In this example, the output will look like this:

Add node selectors to deployments. In this example case, we’ll add a nodeSelector to the container spec with beta.kubernetes.io/os = windows and beta.kubernetes.io/osbuild = 14393.* or 16299 to match the base OS used by the container.

Here’s a full example for running a container built for Windows Server 2016:

The pod can now start with the updated deployment. The node selectors are also shown in kubectl describe pod

, so you can run that command to verify they were added.