Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update selecting tags documentation #6109

Merged
merged 10 commits into from
Dec 12, 2024
Merged

Update selecting tags documentation #6109

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
956ccf8
Update Windows multiplatform callout
lbussell Dec 10, 2024
5e4cee4
Simplify repos list to refer to other existing repo lists
lbussell Dec 10, 2024
5822d96
Add default linux tags section
lbussell Dec 10, 2024
9bcc607
Update selecting tags documentation
lbussell Dec 11, 2024
3be9609
Fix azure linux link
lbussell Dec 11, 2024
64f8b8e
Remove alpine linux link
lbussell Dec 11, 2024
57ed406
Add package format
lbussell Dec 11, 2024
1369c1e
Add a second table to distro descriptions, remove bullets
lbussell Dec 11, 2024
0dbc85d
Add back docker issue link
lbussell Dec 12, 2024
78ed435
Merge remote-tracking branch 'upstream/main' into selecting-tags
lbussell Dec 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 16 additions & 12 deletions documentation/supported-tags.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,18 +52,22 @@ They include:
- Debian, unless specified (like `8.0-alpine`).
- All [supported architectures](supported-platforms.md#architectures).

> [!NOTE]
> Since .NET 8, these multi-platform tags **specifically exclude all Windows versions** due to `containerd`'s platform matching algorithm for Windows hosts.

Please see [#4492 (Switch multi-platform tags to Linux only)](https://github.com/dotnet/dotnet-docker/issues/4492) for more context.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The link to this issue is removed. I think it would be useful to keep this so that the community can easily find the context on why this decision was made for the .NET images.

If you are using Windows, you will need to explicitly specify an OS Version with a single-platform tag like so:

```Dockerfile
FROM mcr.microsoft.com/dotnet/sdk:8.0-nanoserver-ltsc2022
FROM mcr.microsoft.com/dotnet/sdk:8.0-nanoserver-1809
FROM mcr.microsoft.com/dotnet/sdk:8.0-windowsservercore-ltsc2019
FROM mcr.microsoft.com/dotnet/sdk:8.0-windowsservercore-ltsc2022
```
> [!WARNING]
> These multi-platform tags **specifically exclude all Windows versions** due
> to `containerd`'s platform matching algorithm for Windows hosts. See
> [containerd/containerd#6508](https://github.com/containerd/containerd/issues/6508)
> and [dotnet/dotnet-docker#4492](https://github.com/dotnet/dotnet-docker/issues/4492)
> for more context.
>
> If you are using Windows, you will need to explicitly specify an OS Version
> with a single-platform tag like so:
>
> ```Dockerfile
> FROM mcr.microsoft.com/dotnet/sdk:8.0-nanoserver-ltsc2022
> FROM mcr.microsoft.com/dotnet/sdk:8.0-nanoserver-1809
> FROM mcr.microsoft.com/dotnet/sdk:8.0-windowsservercore-ltsc2019
> FROM mcr.microsoft.com/dotnet/sdk:8.0-windowsservercore-ltsc2022
> ```

### `<Major.Minor.Patch .NET Version>-<OS version>`

Expand Down
1 change: 0 additions & 1 deletion documentation/vulnerability-reporting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -327,7 +327,6 @@ Those are unrelated packages that happen to contain the same name as the vulnera
We can't take any action if a fixed version of the package isn't available from the package repository of the Linux distro version.
Sometimes fixes aren't ever made available because they are low severity or not applicable in container environments.
Questions on this matter should be directed to the relevant Linux distro.
If you're not already using [Alpine Linux](../samples/selecting-tags.md#alpine), you may want to consider using it instead because of its security focus and low number of vulnerabilities.

### L. Is the package in the Linux distro base image?

Expand Down
119 changes: 90 additions & 29 deletions samples/selecting-tags.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,27 +6,42 @@ You can use the referenced images and tags with the docker CLI, for example with

## .NET Docker repos

There are multiple [.NET Docker repos](../README.md) that expose various layers of the .NET platform.
There are multiple [.NET Docker repos](../README.md) that expose various layers
of the .NET platform. They can be found under [Featured Repos](/README.md#featured-repos).
Other repos, including preview (nightly) .NET images, can be found under
[Related Repos](/README.md#related-repositories).

* [dotnet/runtime-deps](../README.runtime-deps.md) -- Linux-only images that contains the native dependencies of .NET. Best used for self-contained applications.
* [dotnet/runtime](../README.runtime.md) -- Images that contains the .NET runtime. Best used for console applications. On Linux, depends on the `runtime-deps` image.
* [dotnet/aspnet](../README.aspnet.md) -- Images that contains the ASP.NET Core runtime. Best used for web applications and services. Depends on the `runtime` image.
* [dotnet/sdk](../README.sdk.md) -- An image that contains the .NET SDK (which includes tools and all runtimes). Best used for building and testing applications. Depends on [buildpack-deps](https://hub.docker.com/_/buildpack-deps) for Debian and Ubuntu, on [dotnet/aspnet](../README.aspnet.md) for Alpine and on [windows/nanoserver](https://mcr.microsoft.com/en-us/product/windows/nanoserver/about) for Windows.
## Default Linux tags

The repos above are commonly used on the command line and in Dockerfiles. There are two more repos that may be useful to you:
The `runtime-deps`, `runtime`, `aspnet`, and `sdk` repos provide version-only
manifest list tags. These tags can sometimes be referred to as "convenience
tags".

* [dotnet/nightly](https://github.com/dotnet/dotnet-docker/blob/nightly/README.md) -- A duplicate structure of repos which contain the latest pre-released versions of .NET. (which are not supported in production).
* [dotnet/samples](../README.samples.md) -- A set of samples that demonstrate .NET being used in console and web scenarios.
* `9.0`
* `9.0.X`
* `latest`

For .NET 8 and .NET 9, these tags refer to Debian 12 (Bookworm). All three
of the above tags will provide a Debian image.

> [!CAUTION]
> For .NET 10 and subsequent releases, [these tags will refer to Ubuntu 24.04
> ("Noble")](https://github.com/dotnet/dotnet-docker/discussions/5709).

These convenience tags don't support Windows. See the [Multi-Platform
Tags](/documentation/supported-tags.md#multi-platform-tags) documentation for
more info.

## Targeting a specific operating system

If you want a specific operating system image, you should use a specific operating system tag. We publish images for [Alpine](#alpine), [Debian](#debian), [Ubuntu](#ubuntu), [Windows Nano Server](#nano-server), and [Windows Server Core](#windows-server-core).
If you want a specific operating system image, you should use a specific operating system tag. We publish images for [Alpine](#alpine-linux), [Azure Linux](#azure-linux), [Debian](#debian), [Ubuntu](#ubuntu), [Windows Nano Server](#nano-server), and [Windows Server Core](#windows-server-core).

The following tags demonstrate the pattern used to describe each operating system (using .NET 9.0 as the example):

* `9.0-alpine` (Latest Alpine)
* `9.0-noble` (Ubuntu 24.04)
* `9.0-azurelinux3.0` (Azure Linux 3.0)
* `9.0-bookworm-slim` (Debian 12)
* `9.0-noble` (Ubuntu 24.04)
* `9.0-nanoserver-ltsc2022` (Nano Server LTSC 2022)
* `9.0-nanoserver-1809` (Nano Server, version 1809)
* `9.0-windowsservercore-ltsc2022` (Windows Server Core LTSC 2022)
Expand All @@ -40,25 +55,71 @@ docker pull mcr.microsoft.com/dotnet/runtime:9.0-alpine

### Linux

#### [Debian](https://www.debian.org)

* When targeting Linux containers, Debian is the default Linux distro for all tags that do not specify an OS. For example, `latest`, `9.0`, and `9.0.0` will all provide a Debian image.
* Very stable.

#### [Ubuntu](https://ubuntu.com)

* Shares Debian's codebase.
* Feature-rich.
* Less stable compared to Debian.

#### [Alpine](https://www.alpinelinux.org)

* Security-oriented and lightweight.
* Uses [musl instead of glibc](https://wiki.musl-libc.org/functional-differences-from-glibc.html) which may have incompatibility with your software.

<a name="alpine-globalization">Globalization Support</a>:

By default, the `icu-libs` package is not included and the [globalization invariant mode](https://github.com/dotnet/runtime/blob/main/docs/design/features/globalization-invariant-mode.md) is enabled. You can opt into globalization support by [following the pattern shown in the sample Dockerfile](https://github.com/dotnet/dotnet-docker/blob/main/samples/dotnetapp/Dockerfile.alpine-icu).
#### [Alpine Linux](https://alpinelinux.org/)

| | |
|-----------------|--------------------------------------------------------------------|
| Releases | [Every 6 months](https://alpinelinux.org/releases/) |
| Security | [Alpine Linux Security Tracker](https://security.alpinelinux.org/) |
| Support | [Alpine Linux Community](https://alpinelinux.org/community/) |
| Package format | `.apk` |
| Package manager | `apk` |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it be more useful to describe package type rather than package manager for each of these?


| Supported .NET Features | |
|-------------------------|----------------------------|
| [Globalization] | Invariant mode by default.<br>Globalization supported with `-extra` image variant. |
| [Distroless Images] | Yes |

#### [Azure Linux](https://github.com/microsoft/azurelinux)

| | |
|-----------------|--------------------------------------------------------------------------------------------|
| Releases | Approximately every 2 years |
| Security | [Azure Linux Vulnerability Data](https://github.com/microsoft/AzureLinuxVulnerabilityData) |
| Support | [Azure Linux GitHub repo](https://github.com/microsoft/azurelinux/issues) |
| Package format | `.rpm` |
| Package manager | `tdnf` |

| Supported .NET Features | |
|-------------------------|---------------------------------|
| [Globalization] | Yes, for non-distroless images.<br>Globalization supported in distroless images with `-extra` image variant. |
| [Distroless Images] | No |

#### [Debian](https://www.debian.org/)

* Stability-focused, extensive package repository.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Describing this as stability-focused (and Ubuntu as "user-friendly") and having it limited to just that distro may be controversial.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah. There were already "opinions" in this doc and others. I would probably just prefer to remove all such opinions from our docs and only report facts. Users can make their own judgement.

* Full featured .NET images including many packages.

| | |
|-----------------|-----------------------------------------------------------------|
| Releases | [Approximately every 2 years](https://www.debian.org/releases/) |
| Security | [Debian Security Information](https://www.debian.org/security/) |
| Support | [Debian User Support](https://www.debian.org/support) |
| Package format | `.deb` |
| Package manager | `apt`/ `dpkg` |

| Supported .NET Features | |
|-------------------------|-----|
| [Globalization] | Yes |
| [Distroless Images] | No |

#### [Ubuntu](https://ubuntu.com/)

| | |
|-----------------|----------------------------------------------------------------------|
| Releases | [LTS releases every 2 years](https://ubuntu.com/about/release-cycle) |
| Security | [Ubuntu Security Information](https://ubuntu.com/security/cves) |
| Support | [Ubuntu support](https://ubuntu.com/support)<br> [Launchpad](https://bugs.launchpad.net/ubuntu)<br> [Discourse](https://discourse.ubuntu.com/) |
| Package format | `.deb` |
| Package manager | `apt`/ `dpkg` |

| Supported .NET Features | |
|-------------------------|------------------------------------------------------------|
| [Globalization] | Yes, for non-Chiseled images.<br>Globalization supported in Chiseled images with `-extra` image variant. |
| [Distroless Images] | Yes - [Ubuntu Chiseled](/documentation/ubuntu-chiseled.md) |

[Globalization]: ./enable-globalization.md
[Distroless Images]: /documentation/distroless.md

### Windows

Expand Down
Loading