.NET 8.0 Container Images Now Available

[lbussell]

.NET 8.0 Container Images GA

.NET 8.0 is now generally available.

New Features for .NET Container Images

Non-Root User Included By Default

The .NET Linux container images include a new non-root user named app with the UID 1654.
The UID is provided in an environment variable, $APP_UID.
You can opt into this new user by adding the line USER $APP_UID to your Dockerfile.

Important

The name of this user may conflict with an existing user defined by your application's Dockerfile.

Ubuntu Chiseled Images

Ubuntu Chiseled is Ubuntu's take on "distroless" container images.
The Ubuntu Chiseled .NET images include the minimum set of libraries necessary to run .NET applications.
For more information, see the Ubuntu Chiseled .NET Containers documentation.

ASP.NET Core Composite Images

Compared to the default ASP.NET Core images, ASP.NET Core composite images provide a smaller image size on disk as well as performance improvements for framework-dependent ASP.NET Core apps by performing some cross-assembly optimizations and between the .NET and ASP.NET Core runtimes.
For more information, see Add Dockerfiles for Linux .NET Composite Images.

(Preview) Native AOT Images

The aot images provide an optimized deployment size for Native AOT compiled .NET apps.
Native AOT has the lowest size, startup time, and memory footprint of all .NET deployment models.
aot image variants are only available for our size-focused runtime-deps images: Alpine and Ubuntu Chiseled.
They also require the use of the aot SDK image which include extra libraries needed for Native AOT compilation.
See more info about the Native AOT images in the Image Variants documentation.

New approach for differentiating .NET 8+ images

We are defining a different approach to the kinds of images we ship for .NET 8+.

Ubuntu, Debian, Windows Server Core, and Nano Server images are full-featured and include ICU libraries and time zone information (e.g. tzdata in Linux) by default.
These images are intended to satisfy the most common use cases of .NET developers.

Alpine and Ubuntu Chiseled .NET images are focused on size.
By default, these images do not include icu or tzdata, meaning that these images only work with apps that are configured for globalization-invariant mode.
Apps that require globalization support can use the new extra image variant of the dotnet/runtime-deps images. Because this is only available with runtime-deps images, it requires a self-contained deployment of the application.
Alpine and Chiseled images also come in extra, composite, and aot variants.

Please see the Image Variants documentation for more info. A sample image size report is provided to assist in choosing the correct .NET image variant for your application.

Breaking Changes

For a general list of breaking changes in .NET 8.0, please see "Breaking changes in .NET 8".
Below is the list of breaking changes for .NET container images only.

Default ASP.NET Core port changed to 8080

The default ASP.NET Core port configured in .NET container images has been updated from port 80 to 8080.
This change was made to provide a good usability experience when using a non-root user.
Running as a non-root user requires the use of a non-privileged port.
Since port 80, the previous default port, is a privileged port, the default was updated to port 8080, which is a non-privileged port.

We also added the new ASPNETCORE_HTTP_PORTS environment variable as a simpler alternative to ASPNETCORE_URLS. The new variable expects a semicolon delimited list of ports numbers, while the older variable expects a more complicated syntax.

Multi-platform container tags are Linux-only

This change was made because of usability issues related to the platform-matching algorithm for containerd when used in conjunction with Windows desktop OS versions. Please see #4492 for more context.
This change aligns .NET's Windows container images with the method of tagging that's used for the actual base Windows Server container images.

Update your tag usage to indicate which Windows version you're targeting.
Instead of using an image name like mcr.microsoft.com/dotnet/aspnet:8.0, you'll now need to use something like one of the following:

• mcr.microsoft.com/dotnet/aspnet:8.0-nanoserver-1809
• mcr.microsoft.com/dotnet/aspnet:8.0-nanoserver-ltsc2022
• mcr.microsoft.com/dotnet/aspnet:8.0-windowsservercore-ltsc2019
• mcr.microsoft.com/dotnet/aspnet:8.0-windowsservercore-ltsc2022

ca-certificates, krb5-libs, and libintl packages removed from Alpine images

These packages were removed from our Alpine Linux images since they are focused on deployment size, and also to align Alpine with the packages offered in the Ubuntu Chiseled containers. ca-certificates are provided by ca-certificates-bundle in Alpine Linux. If you need globalization support for your .NET app you can make one of the following changes:

• Use the new extra version of the Alpine runtime-deps image, which includes ICU and Time Zone data libraries
• Use one of our full-featured distro images - Ubuntu or Debian

Please see "Announcement: New approach for differentiating .NET 8+ images" for more info.

Debian container images upgraded to Debian 12

The default Linux distro for .NET container images is Debian.
In .NET 8, the Debian version has been upgraded to Debian 12 (Bookworm).
As a result of upgraded package versions, this new version of Debian may have changes in it that break your application.
The most notable change is the upgrade of Open SSL from 1.1 to 3.0.

[mu88]

@lbussell just out of curiosity: why was the user ID of the app user changed from 64198 (as stated in this blog post) to 1654? Was there a technical reason?

[akoken]

It likely exceeded the UID_MAX value designated for Debian Bookwarm, which is typically set to 60000.

[mu88]

Thx for the explanation!

[mthalman]

@richlander - Would it be worthwhile to update the blog post to the GA version instead of preview (and subsequently update the port)?