New tagging scheme for .NET Monitor, Aspire Dashboard, and samples

[lbussell]

Architecture-specific tags for .NET Monitor, Aspire Dashboard, and sample images will be undocumented going forwards, and will no longer be published starting with .NET 10 (and .NET Aspire Dashboard 9.0). This set of images is colloquially known as appliance images.

Undocumented tags are still available and still receive updates according to our Image Update Policy, but they are not listed in our supported tags tables and are not visible on MAR.

Background

Currently, choosing a .NET image can be intimidating or confusing due to the quantity of tags available. We want to make sure that each individual tag has a good reason to exist.

.NET appliance images are primarily intended to be used as-is, without modification. At the same time, architecture-specific tags are primarily useful for base images (like the .NET Runtime images) in order to reference a specific target platform from a Dockerfile. Since appliance-style images are not typically modified or extended using a Dockerfile, architecture-specific tags provide little value in this scenario.

We think that by undocumenting and eventually removing architecture-specific tags for .NET appliance images, we can provide an improved user experience for selecting tags, while making sure that users can still reference specific platforms if necessary.

For more background and justification, see #5946.

Affected tags

Tags in the following repos and formats will be undocumented:

.NET Monitor

• <Major>.<Minor>.<Patch>-<OS>-<Arch> (e.g. 8.0.5-ubuntu-chiseled-amd64)
• <Major>.<Minor>-<OS>-<Arch> (e.g. 8.0-ubuntu-chiseled-amd64)
• <Major>-<OS>-<Arch> (e.g. 8-ubuntu-chiseled-amd64)
• <Major>.<Minor>.<Patch>-<Arch> (e.g. 9.0.0-amd64)
• <Major>.<Minor>-<Arch> (e.g. 9.0-amd64)
• <Major>-<Arch> (e.g. 9-amd64)

Note

This change does not affect the monitor/base repo, since those images are built to be extended.

.NET Aspire Dashboard

• <Major>.<Minor>.<Patch>-<Arch> (e.g. 8.2.1-amd64)
• <Major>.<Minor>-<Arch> (e.g. 8.2-amd64)
• <Major>-<Arch> (e.g. 8-amd64)

.NET Samples

• dotnetapp-<Version>-<OS>-<arch> (e.g. dotnetapp-8.0-alpine-amd64)
• dotnetapp-chiseled-<Version>-<arch> (e.g. dotnetapp-chiseled-8.0-amd64)
• aspnetapp-<Version>-<OS>-<arch> (e.g. aspnetapp-8.0-alpine-amd64)
• aspnetapp-chiseled-<Version>-<arch> (e.g. aspnetapp-chiseled-8.0-amd64)

Recommended action

When selecting tags for .NET appliance images, prefer using the multi-platform tags wherever possible:

• mcr.microsoft.com/dotnet/monitor:9
• mcr.microsoft.com/dotnet/monitor:9.0
• mcr.microsoft.com/dotnet/monitor:9.0.X
• mcr.microsoft.com/dotnet/aspire-dashboard:8
• mcr.microsoft.com/dotnet/aspire-dashboard:8.2
• mcr.microsoft.com/dotnet/aspire-dashboard:8.2.1

If you rely on using an architecture-specific variant of a .NET appliance image, specify the build/runtime platform using Docker instead:

• docker run: Use the --platform option
• docker build: Use the --platform option
• Docker Compose: Use the platform attribute
• Dockerfile: Use the --platform flag

You can also pin your image reference to an architecture-specific image digest (the "Name" entries below):

$ docker buildx imagetools inspect mcr.microsoft.com/dotnet/monitor:9.0.0-rc.1
Name:      mcr.microsoft.com/dotnet/monitor:9.0.0-rc.1
MediaType: application/vnd.docker.distribution.manifest.list.v2+json
Digest:    sha256:ee8c80eebd8e6a881c3fbbe2ce1f4c18660a59a8a5d5319b682c70f6bc0bfd7c

Manifests:
  Name:      mcr.microsoft.com/dotnet/monitor:9.0.0-rc.1@sha256:7b0a6171fa4a8618e509b707250925e2e30b7717582a595590c45a273caa8d3d
  MediaType: application/vnd.docker.distribution.manifest.v2+json
  Platform:  linux/amd64

  Name:      mcr.microsoft.com/dotnet/monitor:9.0.0-rc.1@sha256:79ec0b008d5ef0235ac8ce8275d34f09396bb6e02eb7204f62db994ae6ce1a7d
  MediaType: application/vnd.docker.distribution.manifest.v2+json
  Platform:  linux/arm64

Finally, the architecture-specific .NET appliance image tags still exist for .NET 9 and Aspire Dashboard 8.
However, please note that we plan to remove these architecture-specific tags for .NET 10 and Aspire Dashboard 9.0. If you have any feedback on this change, please reply directly to this discussion announcement.