[Breaking change]: Default ASP.NET Core port changed to 8080 in container images

[mthalman]

Description

The default ASP.NET Core port configured in .NET container images has been updated from port 80 to 8080.

Coinciding with this change of the port is an update to use the new ASPNETCORE_HTTP_PORTS environment variable instead of ASPNETCORE_URLS.

Read more about this change at "Secure your .NET cloud apps with rootless Linux Containers".

Version

.NET 8 Preview 1

Previous behavior

Prior to .NET 8, you could run a container expecting port 80 to be the default port and be able to access the running app.

For example, running the following command would allow you to access the app locally at port 9999, which is mapped to port 80 in the container:

docker run --rm -it -p 9999:80 <my-app>

New behavior

Starting with .NET 8, if a user attempts to map to port 80 in the container without explicitly setting the ASP.NET Core port used in the container, any attempt made to connect to that mapped port will fail.

For example, if a user was to run the following command, they would be unable to connect to the application locally using port 9999.

docker run --rm -it -p 9999:80 <my-app>

Instead, the command, would need to be changed to use port 8080 within the container:

docker run --rm -it -p 9999:8080 <my-app>

Type of breaking change

• Binary incompatible: Existing binaries may encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.
• Source incompatible: When recompiled using the new SDK or component or to target the new runtime, existing source code may require source changes to compile successfully.
• Behavioral change: Existing binaries may behave differently at run time.

Reason for change

The change to the port number was made because of the need to provide a good usability experience when switching to a non-root user. Running as a non-root user requires the use of a non-privileged port in some environments. But port 80, the previous default port, is a privileged port. So the default is now updated to port 8080 which is a non-privileged port.

Recommended action

Users have two options to respond to this breaking change:

• Recommended: Explicitly set the ASPNETCORE_HTTP_PORTS/ASPNETCORE_HTTPS_PORTS/ASPNETCORE_URLS environment variable(s) to the desired port. Example: docker run --rm -it -p 9999:80 -e ASPNETCORE_HTTP_PORTS=80 <my-app>
• Update existing commands and configuration that rely on the expected default port of port 80 to reference port 8080 instead. Example: docker run --rm -it -p 9999:8080 <my-app>

Feature area

Deployment

Affected APIs

No response

---

Associated WorkItem - 118218

[gewarren]

@mthalman @richlander Do you think these container image breaking changes should be under deployment, or should we create a new category called containers or Docker or something like that?

https://learn.microsoft.com/en-us/dotnet/core/compatibility/8.0#deployment

[mthalman]

A new containers category would be great. I only chose deployment because that was the closest related thing.