Announcement: New approach for differentiating .NET 8+ images

[richlander]

We are defining a (subtly different) approach to the various kinds of images we ship, for .NET 8+. In short, some images will be "batteries included", others will be as small as possible, and another set will be "choose your own adventure". This model can be thought of as "opinionated" or pragmatic differentiation.

This new plan aims to resolve the following issues:

• Native AOT supports a smaller set of dependencies (with the potential for smaller images).
• Native AOT build-time dependencies (clang, ...) add significant complexity and build cost to app Dockerfiles, particularly for cross-compiling.
• Native AOT isn't convenient to use with SDK container builds.
• Chiseled images are more difficult to compose, such that we should provide images for common scenarios.
• Globalization support in our images is inconsistent.

Related issues:

• Provide base image for Native AOT #4748 (comment)
• Consider an icu version of aot-deps #4804
• https://github.com/dotnet/dotnet-docker/issues?q=is%3Aissue+tzdata
• Container offering for supporting Native AOT scenarios #4129

Batteries included

The "batteries included" plan is really "globalization included". Up until now, we installed icu in some images, but never tzdata. That doesn't make much sense, since ICU is huge, and tzdata is relatively small, yet they both power .NET globalization/world APIs.

Ubuntu and Debian images will have ICU and tzdata installed. The practical impact of this is that Ubuntu images will get 1.2MB larger. Debian base images already contain tzdata so our Debian images won't change.

Alpine images have always been focused on size. We do not plan to change that (beyond some opt-in options discuss later).

Changes:

• Add tzdata to runtime-deps:8.0-jammy (used by runtime, aspnet, and sdk images with the same tag).
• Add tzdata to runtime-deps:8.0-bookworm-slim (used by runtime, aspnet, and sdk images with the same tag).

Note: Adding tzdata to Debian Bookworm images should have no practical effect, unless there is an update to tzdata (that is not yet included in Debian) at which point .NET images will now include a newer tzdata (and the size will increase commensurately).

Some packages will still be optional, such as Kerberos, LDAP, and msquic. They are only required by niche scenarios.

As small as possible

Alpine, Mariner distroless, and Ubuntu Chiseled images are all focused on size. These images do not and will not include ICU or tzdata. That's the status-quo, so no change. This also means that these images only work with apps that are configured for globalization invariant mode.

Notes:

• SDK images are not produced for distroless or chiseled image types.
• Composite images are our smallest aspnet offering for CoreCLR.

Changes:

• No changes.

Choose your own adventure

We've come to realize that the runtime-deps images we provide have significant value, particularly since they include a standard user and port definitions. They are convenient to use for self-contained and native AOT scenarios. However, solely providing runtime-deps images that are needed by the runtime and sdk images we ship isn't sufficient to enable all the scenarios one can imagine or generate optimal images.

This need primarily only applies to native AOT and the distroless/chiseled image types.

For each variant, we will provide three image variants (all in runtime-deps), using chiseled images as an example:

• 8.0-jammy-chiseled -- "as small as possible" images for CoreCLR (no tzdata or icu)
• 8.0-jammy-chiseled-aot -- "as small as possible" images for native AOT (no tzdata, icu, or stdc++)
• 8.0-jammy-chiseled-extra -- "batteries included" image for both CoreCLR and native AOT (includes tzdata, icu, and stdc++)

In terms of scenarios:

• The 8.0-jammy-chiseled images will be the base for runtime and aspnet repo images (of the same tag).
• Native AOT apps can use the 8.0-jammy-chiseled-aot image, by default, since it is optimized for size.
• Native AOT apps and CoreCLR self-contained/single file apps that require globalization functionality can use 8.0-jammy-chiseled-extra.

Alpine and Mariner images will use the same scheme.

We don't plan to offer runtime and aspnet images based on 8.0-jammy-chiseled-extra. We will re-consider that if there is sufficient demand.

Debian and Ubuntu (non-chiseled) runtime-deps images will not have multiple variants.

Changes:

• Add aot and extra variants for 8.0-alpine, 8.0-cbl-mariner2.0-distroless, 8.0-jammy-chiseled.

Building native AOT container images

We will publish -aot SDK images (in the sdk repo) that enable building native aot apps. They will be created for distros with matching runtime-deps:*-aot images. These images are very large, about twice the size of regular SDK images.

AOT images will be published for:

• Alpine
• Mariner
• Ubuntu

This approach will enable a developer to write Dockerfiles that are very similar to the model used for CoreCLR. It will also enable an easy path to using SDK container builds with native AOT.

Changes:

• Add -aot sdk variant for 8.0-alpine, 8.0-cblmariner2.0, and 8.0-jammy

[jsheetzmt]

Hi @richlander,

We don't plan to offer runtime and aspnet images based on 8.0-jammy-chiseled-extra. We will re-consider that if there is sufficient demand.

We are hoping to switch over to chiseled images for our ASP.NET Core APIs to get smaller images that we are hosting in Azure Container Apps. Our APIs use Microsoft.Data.SqlClient, which has a dependency on ICU. See here.

It would be awesome if chiseled aspnet images are also published with a "batteries included" variant.

[akoken]

I think there is no ideal solution right now. Until then, you can use this workaround.

[Kerwood]

We are en the same boat. We would like to switch to chiseled but have a lot of applications with a dependency to tzdata.

[mu88]

Today I switched two of my ASP.NET Core apps to chiseled containers and immediately stumbled over this issue. Therefore, it would be great if Microsoft could provide the base image mcr.microsoft.com/dotnet/aspnet:8.0-jammy-chiseled-extra including globalization so that the following error no longer occurs:

Unhandled exception. System.Globalization.CultureNotFoundException: Only the invariant culture is supported in globalization-invariant mode. See https://aka.ms/GlobalizationInvariantMode for more information. (Parameter 'name')
en is an invalid culture identifier.
   at System.Globalization.CultureInfo..ctor(String name, Boolean useUserOverride)
   at Microsoft.AspNetCore.Builder.RequestLocalizationOptions.SetDefaultCulture(String defaultCulture)
   at Program.<>c.<<Main>$>b__0_3(RequestLocalizationOptions localizationOptions) in C:\Users\myUser\Documents\Development\GitHub\ThisIsYourLife\src\WebApp\Program.cs:line 52
   at Microsoft.AspNetCore.Builder.ApplicationBuilderExtensions.UseRequestLocalization(IApplicationBuilder app, Action`1 optionsAction)

[jdoneil7]

Lending my support for this, as we are in the same situation with ASP.NET Core applications with a dependency on SqlClient.

[johnnyreilly]

These are now available, see: #5092

and: https://github.com/dotnet/dotnet-docker/blob/main/documentation/ubuntu-chiseled.md#how-do-i-use-globalization-with-chiseled-images

[logicaloud]

I'd like to join in hoping for a "batteries included" option.

In microservices scenarios or for pod compositions where multiple dotnet based containers work together, a single shared framework container may have a larger size than an AOT container, but because the base image layer (i.e., "aspnet-jammy-chiseled-extra") can be shared between the various containers, this will probably still have a smaller overhead than several AOT based containers. As such, if the objective is to enable small deployment sizes, then having a "batteries included" image would be a great option.

Edit: I'd like to add that AOT is not always an option, a shared framework deployment may be a requirement for many apps.

[logicaloud]

There is now another open issue where comments are encouraged to express support for a chiseled ASPNET images with ICU/TZDATA included (see note in https://devblogs.microsoft.com/dotnet/announcing-dotnet-chiseled-containers/). If anyone would like to add their voice, then please head over to #5014.

[Kerwood]

We are hoping to switch over to chiseled images for our ASP.NET Core APIs to get smaller images that we are hosting in Azure Container Apps. Our APIs use Microsoft.Data.SqlClient, which has a dependency on ICU. See here.

It would be awesome if chiseled aspnet images are also published with a "batteries included" variant.

Yes, we need that. Show some support for the the -extra variant here: #5021

[voroninp]

ASP.NET Core Composite images provide a smaller size on disk while keeping the performance of the default ReadyToRun (R2R) setting. The caveat is that the composite images have tighter version coupling. This means the final app run on them cannot use handpicked custom versions of the framework and/or ASP.NET assemblies that are built into the composite binary.

How do I get the list of bundled assemblies and their versions?

[richlander]

richlander/container-workshop#7

[j-aho]

@richlander sorry for kind of hijacking this thread, but does this mean that we won't have new versions of mcr.microsoft.com/dotnet/sdk seems to not have any of the 8.0.30x versions (stuck at 8.0.203)?

[mthalman]

There are 8.0.3xx versions of the SDK image available. I'm assuming you're asking because these aren't listed on the Docker Hub page. There's been an ongoing issue of our content not being replicated to Docker Hub which is why it's out of date; this is being worked on. For now, you can see the latest supported tags either at the MAR portal or here in this repo.

[j-aho]

Thanks for the reply, we run into an incident a few weeks ago where a build machine had 8.0.300 installed from microsoft repository, in a build there was a step where build was done on the host and then started a docker to continue with a publish and copy that to a final image, but then we got dotnet version incompatibility (the build is fixed now to be done inside the docker image), where we only got 8.0.206 as the latest version of dotnet container image, after that I was trying to track the dockerhub page.

We still don't seem to be able to access the 8.0.300 image (not that we need it anymore), getting a HTTP 429 response "invalid character 'R' looking for beginning of value: "Ref A: DE7FC6D3DF2F471B90096CB27177C66F Ref B: DB3EDGE1718 Ref C: 2024-06-04T13:50:39Z", not sure about that and I guess out of topic here. Pulling the 8.0.301 seems to work as expected.