Pre-announcement: dotnet/samples breaking changes (port 8080, ...)

[richlander]

We will be updating our dotnet/samples container images to .NET 8 as part of the .NET 8 RC1 release (September 12). They will be updated to take advantage of several new features, some of which are breaking changes. We know that these images are used for testing by some organizations. You may need to make changes to the way you use these images.

Our samples have always been intended as best-practice demonstrations of using .NET in containers. Our adoption of both breaking changes and opt-in features may be a useful guide for your own container images.

Note: The remainder of this announcement is worded in the past tense, as if the changes have already been made, to avoid needing to change the tense later.

Related announcements:

• https://devblogs.microsoft.com/dotnet/securing-containers-with-rootless/
• https://devblogs.microsoft.com/dotnet/running-nonroot-kubernetes-with-dotnet/
• Add non-root user support #4397
• Update non-root UID to avoid warning in Debian #4715
• Breaking change: Multi-platform .NET 8 tags no longer support Windows containers #4549
• Switch multi-platform tags to Linux only #4492

Use port 8080

This change is breaking.

aspnetapp images have been updated to use port 8080.

Port 8080 is the new default for all .NET 8 container images. It was chosen to enable one-line configuration of non-root images. With earlier versions, .NET container images are configured to listen on port 80.

You can launch the images with the following pattern, mapping container port 8080. Port 8000 is used as the host port throughout.

docker run --rm -it -p 8000:8080 mcr.microsoft.com/dotnet/samples:aspnetapp

You can switch back to port 80 with an environment variable:

docker run --rm -it -p 8000:80 -e ASPNETCORE_HTTP_PORTS=80 -u root mcr.microsoft.com/dotnet/samples:aspnetapp

root or another privileged user is typically needed to use a port below 1024, however, this rule is not uniformally enforced. That's why the -u argument is used when switching back to port 80.

The following environment variables can be used to configure ports.

Supported with .NET 8+:

ASPNETCORE_HTTP_PORTS=80

Supported with all .NET versions:

ASPNETCORE_URLS=http://+:80 

Note: ASPNETCORE_URLS overrides ASPNETCORE_HTTP_PORTS.

You can see these environment variables used in our .NET 8 and .NET 6 Dockerfiles, respectively.

Non-root hosting

This change is opt-in, but is (potentially) breaking.

The samples have been updated to use the new app user. This change is a defense-in-depth measure that makes hosting container images more secure.

Any use of root-requiring commands will break, by definition of using a non-root user.

The container images use the USER instruction to set the user.

USER $APP_UID

You can see the USER setting demonstrated in our images.

$ docker run --rm --entrypoint whoami mcr.microsoft.com/dotnet/samples:aspnetapp
app
$ docker inspect mcr.microsoft.com/dotnet/samples:aspnetapp | grep User
            "User": "",
            "User": "1654",

We recommend specifying the user as a UID instead of by name if you want to use the Kubernetes runAsNonRoot capability. We have defined the APP_UID environment variable to store the correct value (which we recently changed).

The user can be changed via Docker CLI -u argument or the Kubernetes runAsUser field.

Windows images use version-specific tags

This change is breaking.

Windows images are now provided with version-specific tags instead of via multi-platform manifest tags. We concluded that Windows images work best when version-specific tags are used, so are excluslively offering Windows images with that model.

The following examples demonstrate valid tag patterns for Windows with .NET 8+.

• mcr.microsoft.com/dotnet/samples:aspnetapp-nanoserver-ltsc2022
• mcr.microsoft.com/dotnet/samples:aspnetapp-windowsservercore-ltsc2022
• mcr.microsoft.com/dotnet/samples:aspnetapp-windowsservercore-ltsc2019

Linux images can still be pulled with the more convenient tag: mcr.microsoft.com/dotnet/samples:aspnetapp.

This same change applies to version tags in the runtime, aspnet, and sdk repos. Previously, Windows images could be pulled with a version tag, like 6.0. That will not work with the 8.0 tag. Similar tags as are used with the samples must be used with .NET 8+ images.

Use Chiseled images

This change is opt-in and (potentially) breaking.

The samples have been updated to use Chiseled base images. This change significantly limits what the samples images can do (in a good way).

Chiseled images are a defense-in-depth measure, by virtue of only including the minimum packages necessary. These images do not include a shell (like bash), a package manager (like apt), or tools (like curl). The images are also significantly smaller.

We announced Chiseled images about a year ago. They are shipping as a supported offering, with .NET 8. We recently added the ability to scan Ubuntu Chiseled images.

Use composite ready-to-run images

This change is opt-in and (potentially) breaking.

The samples have been updated to use a base image that includes composite ready-to-run images. These ready-to-run images are smaller, making the container images smaller.

Composite ready-to-run images are a more customizable form of ahead-of-time compilation for CoreCLR-based apps. We've configured ready-to-run image generation to be more frugal, valuing container image size above other metrics. However, startup performance is still very good (and likely measureably better when including registry pull cost).

The composite images are not compatible with apps that use NuGet packages that include binaries that are included in .NET, like for example System.Reflection.Metadata.