The container images in this repository are provided for building .NET source and testing the resultant binaries. The images are built with OS base images and must be updated per the OS lifecycle. This document describes the required patterns.
The images are a mix of Microsoft- and community-supported images.
The build images are built with Azure Linux, supporting both glibc and musl build flavors. They are built for x64 only, per Linux build methodology. Microsoft designates the set of images it used for its official build per The Official Runtime Docker Images.
Build images are uniquely created for each new .NET version with the latest Azure Linux available at that time. The image tags include both the given .NET and Azure Linux versions. The tag may also contain a target OS and architecture.
The Azure Linux lifecycle is shorter than the .NET LTS lifecycle. It is expected that build images will need to be (initially) created with Azure Linux n and then replaced with Azure Linux n+1 mid-way through the .NET version lifecycle. They may also need to be updated if the target OS is EOL.
Build images are deleted after a .NET version is no longer supported. It is possible that images will be required for a while after the published EOL date.
Examples:
Test images are produced for the supported Linux distros listed in Supported OS Versions files. In some cases, a compatible derivative will be used. Images are built for a variety of architectures based on need. They are shared across .NET versions.
Test images should be deleted after:
- The underlying OS is EOL.
- Test images for a new version are available.
- All references to the old OS versions have been replaced by a newer in-support version
Examples:
Test images should be be built according to established patterns:
- dotnet-buildtools-prereqs-docker #1147
- dotnet-buildtools-prereqs-docker #1142
- dotnet-buildtools-prereqs-docker #1070
Note: this content should be moved to another location as it is not lifecycle related.
Build and test images are referenced in repo infra files, across a variety of main and release/* branches. Updating these references is a multi-step detail-oriented task. It is a pain, but necessary.
Two types of tag styles are available: distro version-specific and floating.
Distro version-specific tags include the distro's version (e.g. alpine-3.21-helix-amd64).
Repos that are susceptible to breaking changes in the distro should use these tags.
dotnet/runtime is an example of such a repo.
Note
There are plans to automate the creation of PRs to update image references to new distro versions as they become available.
Floating tags have no distro version indicated in the name and are scoped to a .NET version (e.g. alpine-net9.0-helix-amd64).
It is routinely updated to reference a new version as the distro's and .NET's lifecycles progress.
Floating tags are beneficial for repos that are not susceptible to breaking changes that occur from new distro versions because the source that references the tag doesn't need to be updated in order to make use of the new version. These tags are provided on an as-needed basis. If a new floating tag is desired, log an issue requesting it.
The maintainers of this repo follow a workflow before a floating tag gets moved to a newer distro version:
- First, version-specific tags for the new distro version are provided.
- After a one month evaluation period, the new distro version is ready to be rolled out to floating tags according to the schedule, assuming there are no issues found.
- For the .NET version currently in development, the floating tag is moved to reference the new distro version as soon as the evaluation period has been met.
- For servicing versions of .NET, the floating tag is moved to reference the new distro version one month after the in-development .NET version has been updated. This is done as soon as the branch is open for a servicing release.
Floating tags are scoped to a specific .NET version.
This ensures they are stable as the release moves to maintenance phase, not getting bumped to a newer distro version during that phase.
This time period starts 6 months before the EOL date of the .NET version.
In other words, for the last 6 months of servicing for that .NET version, the floating tag is guaranteed to not be moved to a new distro version.
Repos consuming these tags should reference the .NET version associated with the release branch (e.g. sources in the release/9.0 branch should reference the net9.0 tag).
Once the .NET version is EOL, the floating tag associated with that .NET version is no longer maintained.
At times, it may be necessary to use a pinned image reference for build reliability.
This is done by appending the digest of the specific image that is needed (e.g. mcr.microsoft.com/dotnet-buildtools/prereqs:<tag-name>@sha256:56feee03d202e008a98f3c92784f79f3f0b3a512074f7f8ee2b1ba4ca4c08c6e).
If the reference was pinned in response to a break that occurred, a tracking issue should be created (before the PR is merged) so that we remember to resolve the underlying issue and update the image reference back to the original value.
The following locations are examples of infra that gets updated when new images are available.
Community images are constructed per the needs of the given community.