From a6a0d5c19d0b233dd1df1764079c7c7fab7d85d1 Mon Sep 17 00:00:00 2001 From: Logan Bussell Date: Mon, 19 Oct 2026 20:17:22 -0700 Subject: [PATCH] Document Linux container host kernel and runtime compatibility Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 83fcc6a2-5ca9-42a0-b926-a670570cd7ad --- documentation/supported-platforms.md | 6 ++++++ samples/selecting-tags.md | 2 +- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/documentation/supported-platforms.md b/documentation/supported-platforms.md index bd01fb44e2..f5a444f3df 100644 --- a/documentation/supported-platforms.md +++ b/documentation/supported-platforms.md @@ -31,6 +31,12 @@ We publish .NET container images for the following versions of each Linux distro Pre-release versions of the above distros will be published in the [nightly repositories](https://github.com/dotnet/dotnet-docker/blob/nightly/README.md), pending the availability of pre-release base images. +#### Host Compatibility + +Linux containers share the host's kernel and container runtime. Newer container base images may use system calls that older Linux kernels or outdated container runtime seccomp profiles do not support. Running newer images on an old or end-of-life host OS can cause operations inside the container to fail with errors such as `Operation not permitted` (`EPERM`) or `Function not implemented` (`ENOSYS`). + +If you encounter these errors, upgrade the host kernel and container runtime, or pin to a tag for an older supported OS version. + #### FedRAMP Compliance For [.NET appliance images](./supported-tags.md#net-appliance-images) based on Azure Linux, base image OS upgrades will be delayed until the new version of Azure Linux has FedRAMP approval. diff --git a/samples/selecting-tags.md b/samples/selecting-tags.md index 413d44becd..5ab1b4ca05 100644 --- a/samples/selecting-tags.md +++ b/samples/selecting-tags.md @@ -172,4 +172,4 @@ Each container image is generated for a specific processor architecture and oper For multi-stage Dockerfiles, there are typically at least two tags referenced, an SDK and a runtime tag. It is fine to use a multi-platform tag for the SDK. That's the pattern used for .NET samples. You will pull an SDK image that works on your machine. It is important to define a .NET runtime (`runtime-deps`, `runtime`, or `aspnet`) that matches your production environment. -Linux containers are flexible. As long as the processor architecture matches, you can run Alpine, Azure Linux, and Ubuntu images in environments that support Linux containers and meet the images' kernel requirements. [Windows images are more restricted](https://docs.microsoft.com/virtualization/windowscontainers/deploy-containers/version-compatibility). You cannot load containers for newer Windows versions on older hosts. For the best experience, the Windows container version should match the host Windows version. +Linux containers are flexible. As long as the processor architecture matches, you can run Alpine, Azure Linux, and Ubuntu images in environments that support Linux containers and [meet the images' kernel requirements](/documentation/supported-platforms.md#host-compatibility). [Windows images are more restricted](https://docs.microsoft.com/virtualization/windowscontainers/deploy-containers/version-compatibility). You cannot load containers for newer Windows versions on older hosts. For the best experience, the Windows container version should match the host Windows version.