Windows Docker Tag Scheme Changed

[richlander]

Windows Docker Tag Scheme Changed

.NET Core and .NET Framework Windows container images have been updated to use a new tag naming scheme for Windows container images, for both Windows Server Version 1709 and Windows Server 2016.

You will see the following changes in .NET Docker repos:

• Tag names will better describe Windows Release Channels.
• Only stable tags will be used.
• You will need to use image digests as the identifier for patch releases, as appropriate.

The following tags are examples of the new tag scheme:

• 2.0.0-runtime-nanoserver-1709
• 2.0.0-runtime-nanoserver-sac2016
• 4.7.1-windowsservercore-ltsc2016
• 4.7.1-windowsservercore-1709

This scheme is in use in the following repos:

• microsoft/aspnet
• microsoft/aspnetcore
• microsoft/aspnetcore-build
• microsoft/dotnet
• microsoft/dotnet-framework
• microsoft/wcf

Details

• dotnet/dotnet-docker #329
• Microsoft/dotnet-framework-docker #39
• dotnet/announcements #37
• dotnet/announcements #36

With the release of Windows Server 1709, Windows Server container images adopted stable tags, in addition to the release-specific tags already in use.

The following stable base tags are used in Windows repos, microsoft/nanoserver and microsoft/windowsservercore:

• Windows Server 2016 Server Core - ltsc2016
• Windows Server 2016 Nano Server - sac2016
• Windows Server 1709 Server Core - 1709
• Windows Server 1709 Nano Server - 1709

Notes: The 1709 release is a Semi Annual Channel release, but is missing the sac prefix. Windows Server 2016 Server Core is a Long Term Support Channel release.

Release-specific tags will still be used in Windows repos, which will look like the following examples:

• Windows Server 2016 - 10.0.14393.1770
• Windows Server 1709 - 1709_KB4043961

The following stable base tags will be used in .NET repos:

• Windows Server 2016 Server Core - windowsservercore-ltsc2016
• Windows Server 2016 Nano Server - nanoserver-sac2016
• Windows Server 1709 Server Core - windowsservercore-1709
• Windows Server 1709 Server Core - nanoserver-1709

The following tags are examples of the new tag scheme:

• 2.0.0-runtime-nanoserver-1709
• 2.0.0-runtime-nanoserver-sac2016
• 4.7.1-windowsservercore-ltsc2016
• 4.7.1-windowsservercore-1709

This scheme is in use in the following repos:

• microsoft/aspnet
• microsoft/aspnetcore
• microsoft/aspnetcore-build
• microsoft/dotnet
• microsoft/dotnet-framework
• microsoft/wcf

In cases that an immutable Docker reference is required, you are recommended to use an image digest instead of a tag name. Using an image digest will ensure that docker pull and build always use the same image, even after tags are updated.

The following string is an example of a digest reference:

microsoft/dotnet-framework@sha256:bf8b882633fda16586b69c6f3937f9ccb176ff0c1c77542e175af38d9ee6714e

You can use this string as a parameter to docker pull or docker run. You can also use it with a FROM line to ensure that docker build is consistent, such as with the following.

FROM microsoft/dotnet-framework@sha256:bf8b882633fda16586b69c6f3937f9ccb176ff0c1c77542e175af38d9ee6714e

You can determine an image digest with various Docker commands.

Image digests are displayed with every pull.

C:\>docker pull microsoft/dotnet-framework:4.7.1-windowsservercore-1709
4.7.1-windowsservercore-1709: Pulling from microsoft/dotnet-framework
Digest: sha256:bf8b882633fda16586b69c6f3937f9ccb176ff0c1c77542e175af38d9ee6714e
Status: Image is up to date for microsoft/dotnet-framework:4.7.1-windowsservercore-1709

Image digests are displayed for images with the --digests parameter.

$ docker images --digests
REPOSITORY            TAG                             DIGEST                                                                    IMAGE ID            CREATED             SIZE
microsoft/dotnet      2.0-runtime                     sha256:2e9ae1f83873ffb897f8fb7ada205b67b675a1b2c014d5875a49c050783cc469   c73382e1bbf7        38 hours ago        219MB                        

Image digests are displayed as part of docker inspect.

$ docker inspect microsoft/dotnet:2.0-runtime -f '{{.RepoDigests}}'
[microsoft/dotnet@sha256:2e9ae1f83873ffb897f8fb7ada205b67b675a1b2c014d5875a49c050783cc469]

We recommend that you use stable tags during development and image digests for production. This approach gives you an opportunity to test any image updates before they affect production apps. .NET images are updated each month with security updates. We recommend that you rebuild your images each month with these updates to ensure that applications are secure. You need to re-pull base images in order to update them. Otherwise, docker build is happy to use stale local copies of base images.

If you are not able to update source Dockerfiles regularly, then it may make more sense to reference stable tags. You still need to rebuild and redeploy your images in order to update your applications in production.