Workik.

.NET 8 to .NET 10 Migration: An Enterprise Upgrade Guide

.NET 10 Docker Images and CI/CD Pipelines

Move .NET 8 Docker images to .NET 10 on Ubuntu 24.04, keep the non-root app user, publish containers from the SDK and update GitHub Actions.

Moving your applications to .NET 10 LTS (Long Term Support) requires updating how you build, package, and run containers in your CI/CD (Continuous Integration and Continuous Delivery) pipelines. Larkfield Insurance runs Larkfield.Claims.Api and Larkfield.Billing.Worker as container images, built through GitHub Actions. In .NET 10, Microsoft changed the base Linux distribution for container images, expanded container publishing options in the .NET SDK (Software Development Kit), and updated CI tooling requirements.

Previous lesson: Upgrade EF Core 8 to EF Core 10 | Next lesson: Test, Roll Out and Stay Current on .NET


Base Image Changes: Ubuntu Replaces Debian

Starting with .NET 10, default Linux image tags without a specific distribution name in their tag use Ubuntu 24.04 (Noble Numbat). In .NET 9 and earlier releases, these default tags pulled Debian Linux images.

An image reference such as mcr.microsoft.com/dotnet/aspnet:10.0 or mcr.microsoft.com/dotnet/sdk:10.0 now resolves to an Ubuntu 24.04 base. Debian-based images are not provided by Microsoft for .NET 10. If your organization requires Debian for compliance or security policy reasons, your team must build and maintain those base images internally.

You can still use explicit tags if you prefer pinned OS (Operating System) versions, such as mcr.microsoft.com/dotnet/aspnet:10.0-noble. Alpine-based images also remain available for teams that prioritize smaller image footprints.

Common Mistake: Assuming package names in apt-get commands remain identical when upgrading to .NET 10 images. Debian and Ubuntu often diverge on package versions, names, and repository availability. Always test custom package installations against Ubuntu 24.04 before pushing to production.


Updating Dockerfiles for Larkfield Services

In .NET 8, Microsoft introduced non-root user support with the default app user and changed the default HTTP port for ASP.NET Core images to 8080. Larkfield Insurance already adopted these changes during their .NET 8 rollout.

When upgrading Larkfield.Claims.Api to .NET 10, you only need to increment the image version tags from 8.0 to 10.0, provided you do not rely on Debian-specific OS packages.

Before (.NET 8)

dockerfile
Copy

After (.NET 10)

dockerfile
Copy

Because USER app runs with user ID 1654, ensure any mounted storage volumes or file system paths created inside the container grant read and write access to that user account.

Pro Tip: If you must install native utilities such as curl for container health checks, switch to USER root temporarily to run apt-get, then switch back to USER app before defining the entry point.


SDK Container Publishing Without Dockerfiles

The .NET SDK can build container images directly from your project files, without a Dockerfile. By default it loads the image into your local Docker daemon, and it can also push straight to a registry.

In .NET 8, console applications and worker services like Larkfield.Billing.Worker required setting <EnableSdkContainerSupport>true</EnableSdkContainerSupport> explicitly in the project file. In .NET 10, console projects support container publishing out of the box without this flag.

You can configure container properties directly inside Larkfield.Billing.Worker.csproj:

After (.NET 10)

xml
Copy

The new <ContainerImageFormat> property in .NET 10 lets you choose the Docker or OCI (Open Container Initiative) image format explicitly, instead of the format the SDK would otherwise pick. Choose OCI if your registry or security tooling expects OCI manifests.

To build the image, run the publish command using the container target:

bash
Copy

Pro Tip: SDK container publishing automatically applies the non-root app user and chooses the correct base image tag based on your target framework moniker and project type.


Updating CI/CD Pipelines in GitHub Actions

Your CI/CD pipelines need the .NET 10 SDK installed to compile projects, run tests, and publish build artifacts. When using GitHub Actions, update your pipeline definitions to use actions/setup-dotnet@v4.

You can configure the SDK version in two ways: by specifying the version channel explicitly or by pointing directly to your repository global.json file.

Using global.json ensures that your build agents and local developer environments use the exact same SDK patch band.

After (.NET 10)

yaml
Copy

If your repository does not use a global.json file, pin the major and minor band directly in the action configuration:

yaml
Copy

If you manage self-hosted runners or private build agents, install the .NET 10 SDK package on those host machines before triggering migrated pipelines.


Hosting Runtimes and Infrastructure Alignment

Updating container images and build pipelines only covers the delivery side of your systems. Your target compute environments must also support .NET 10.

Review the following areas before rolling out your container images:

  1. Kubernetes and Container Platforms: If your deployment manifests define security contexts, ensure runAsNonRoot: true and runAsUser: 1654 are compatible with your cluster admission controllers. Verify that your ingress controllers route traffic to container port 8080 rather than the older port 80 standard.
  2. PaaS Hosting Runtimes: If you deploy applications without containers to managed services like Azure App Service, update the application stack configuration to .NET 10 in your infrastructure templates before deploying the application code.
  3. OpenSSL Requirements: .NET 10 requires OpenSSL 1.1.1 or later on Linux distributions. Ubuntu 24.04 ships with OpenSSL 3 by default, which satisfies this requirement, but custom lightweight runtime images must ensure this library is installed.

Try This: Verify the operating system and user context of your built .NET 10 container by running an interactive shell inspection:

bash
Copy

The output confirms that the operating system is Ubuntu 24.04 LTS and the user context resolves properly.


Try It Yourself

Update a Dockerfile and verify image compatibility for a .NET 10 deployment:

  1. Create a minimal Dockerfile for Larkfield.Claims.Api targeting mcr.microsoft.com/dotnet/aspnet:10.0.
  2. Inspect the base image using docker run to verify that Ubuntu 24.04 is the underlying OS distribution.
  3. Update a GitHub Actions workflow configuration to set the .NET SDK version using either dotnet-version: '10.0.x' or global-json-file: global.json.
  4. Run dotnet publish /t:PublishContainer on a console or worker service project to build an image without a Dockerfile.

In the next lesson, Test, Roll Out and Stay Current on .NET, you will establish verification strategies, plan staged production deployments, and configure long-term patch routines.

Was this lesson helpful?