Windows Docker Tag Scheme Changed

# 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](https://docs.microsoft.com/en-us/windows-server/get-started/get-started-with-1709) and [Windows Server 2016](https://docs.microsoft.com/en-us/windows-server/get-started/server-basics).

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

- Tag names will better describe [Windows Release Channels](https://docs.microsoft.com/en-us/windows-server/get-started/semi-annual-channel-overview).
- 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](https://hub.docker.com/r/microsoft/aspnet/)
* [microsoft/aspnetcore](https://hub.docker.com/r/microsoft/aspnetcore/)
* [microsoft/aspnetcore-build](https://hub.docker.com/r/microsoft/aspnetcore-build/)
* [microsoft/dotnet](https://hub.docker.com/r/microsoft/dotnet/)
* [microsoft/dotnet-framework](https://hub.docker.com/r/microsoft/dotnet-framework/)
* [microsoft/wcf](https://hub.docker.com/r/microsoft/wcf/)

## Discussion

Please share your thoughts on this change and see what others are saying at:

* [dotnet/dotnet-docker #331](https://github.com/dotnet/dotnet-docker/issues/331)
* [Microsoft/dotnet-framework-docker #40](https://github.com/Microsoft/dotnet-framework-docker/issues/40)

## Details

* [dotnet/dotnet-docker #329](https://github.com/dotnet/dotnet-docker/pull/329)
* [Microsoft/dotnet-framework-docker #39](https://github.com/Microsoft/dotnet-framework-docker/pull/39)
* [dotnet/announcements #37](https://github.com/dotnet/announcements/issues/37)
* [dotnet/announcements #36](https://github.com/dotnet/announcements/issues/36)

With the release of [Windows Server 1709](https://blogs.technet.microsoft.com/windowsserver/2017/10/17/windows-server-version-1709-available-for-download/), 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](https://hub.docker.com/r/microsoft/nanoserver/tags/) and [microsoft/windowsservercore](https://hub.docker.com/r/microsoft/windowsservercore/tags/):

* 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](https://docs.microsoft.com/en-us/windows-server/get-started/semi-annual-channel-overview) 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 Nano 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](https://hub.docker.com/r/microsoft/aspnet/)
* [microsoft/aspnetcore](https://hub.docker.com/r/microsoft/aspnetcore/)
* [microsoft/aspnetcore-build](https://hub.docker.com/r/microsoft/aspnetcore-build/)
* [microsoft/dotnet](https://hub.docker.com/r/microsoft/dotnet/)
* [microsoft/dotnet-framework](https://hub.docker.com/r/microsoft/dotnet-framework/)
* [microsoft/wcf](https://hub.docker.com/r/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.

```Dockerfile
FROM microsoft/dotnet-framework@sha256:bf8b882633fda16586b69c6f3937f9ccb176ff0c1c77542e175af38d9ee6714e
```

You can determine an image digest with various Docker commands.

Image digests are displayed with every pull.

``` console
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.

```console
$ 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`.

``` console
$ 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.