Skip to content

Document Linux container host kernel compatibility #7424

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

Merged
lbussell merged 1 commit into from
Oct 20, 2026
Merged

Document Linux container host kernel compatibility #7424

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
6 changes: 6 additions & 0 deletions documentation/supported-platforms.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion samples/selecting-tags.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Loading