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:
Details
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:
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.