Why container bloat hurts modern microservices
Imagine a microservice that starts in 1.2 seconds, but its Docker image weighs 450 MB. In a Kubernetes cluster with 200 replicas, the time spent pulling the image can add up to dozens of minutes during a rolling update. Reducing image size from hundreds of megabytes to a few megabytes not only speeds up deployments but also cuts bandwidth costs and improves security surface area.
Since .NET 8 introduced Native AOT, developers can compile ahead‑of‑time binaries that contain no JIT, no runtime DLLs, and no unnecessary libraries. Combined with Docker multi‑stage builds, the result is a lean, boot‑fast container that can run in under 100 ms.
Native AOT fundamentals for .NET 8
Native AOT transforms managed C# code into a single native executable. The compiler trims unused IL, removes reflection metadata, and statically links the CoreCLR components that are actually needed. In practice, a simple "Hello World" console app drops from a 70 MB framework‑dependent publish to a 6 MB native binary.
Key constraints to remember: reflection, dynamic code generation, and certain NuGet packages are not supported out of the box. The PublishAot MSBuild flag enables the process, while PublishTrimmed further reduces size by analyzing reachable code paths.
Docker multi‑stage build overview
A multi‑stage Dockerfile separates the build environment from the runtime environment. The first stage uses the full SDK image to compile and publish the app, while the final stage copies only the native binary into a minimal base such as mcr.microsoft.com/dotnet/runtime-deps:8.0-alpine. This approach eliminates the SDK, source files, and intermediate artifacts from the final image.
Because the native binary does not depend on the .NET runtime DLLs, the runtime‑deps base is sufficient. The final image can be as small as 30 MB for a modest API.
Step‑by‑step: Build a .NET 8 AOT Docker image
System requirements: Windows 10 + WSL2 or any Linux distribution with Docker Engine 20.10+, .NET SDK 8.0, and at least 4 GB of RAM.
Follow these commands in a terminal:
dotnet new webapi -n FastApi
cd FastApi
# Enable AOT and trimming
sed -i 's//\n <PublishAot>true<\/PublishAot>\n <PublishTrimmed>true<\/PublishTrimmed>/g' FastApi.csproj
# Create Dockerfile
cat > Dockerfile <<'EOF'
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish -c Release -o /app/publish /p:PublishAot=true /p:PublishTrimmed=true
FROM mcr.microsoft.com/dotnet/runtime-deps:8.0-alpine AS final
WORKDIR /app
COPY --from=build /app/publish/ .
ENTRYPOINT ["./FastApi"]
EOF
# Build the image
docker build -t fastapi:aot .
# Inspect size
docker images fastapi:aot
EOF The dotnet publish command produces a native executable named FastApi. The final docker images output typically shows a size around 32 MB, compared with a 210 MB framework‑dependent image built without AOT.
Real‑world size reduction numbers
A recent internal benchmark at a SaaS company measured three services:
- Service A (ASP.NET Core MVC, .NET 7, no AOT): 215 MB image, 1.8 s cold start.
- Service B (ASP.NET Core Minimal API, .NET 8, AOT disabled): 132 MB image, 1.2 s cold start.
- Service C (Native AOT, .NET 8, multi‑stage): 38 MB image, 0.3 s cold start.
The 82 % reduction in image size translated into a 5‑second saving during a rolling update of 50 replicas, proving that the effort is worthwhile for high‑frequency deployments.
Performance tuning tips for production
1. Explicitly list required runtime features. Use the rd.xml file to preserve reflection for JSON serializers like System.Text.Json. Without it, deserialization may fail at runtime.
2. Enable ReadyToRun (R2R) as a fallback. If a library cannot be AOT‑compiled, the PublishReadyToRun flag still improves startup time while keeping the binary native.
3. Leverage Alpine for the final stage. Alpine’s musl libc is smaller than glibc, but verify that any native dependencies (e.g., libgdiplus) are available, otherwise switch to a Debian‑slim base.
4. Monitor memory consumption. Native AOT eliminates the GC heap overhead of the JIT, but the binary’s static memory allocation may be higher. Use docker stats to ensure the container stays within limits.
Conclusion
Combining .NET 8 Native AOT with Docker multi‑stage builds delivers ultra‑fast, ultra‑small containers that shave seconds off cold starts and dramatically cut bandwidth usage. By following the step‑by‑step guide, applying trimming options, and fine‑tuning runtime features, teams can achieve production‑grade performance without sacrificing the developer experience of C#.
Sources
Microsoft .NET 8 documentation, Docker official best practices, .NET Blog – “Native AOT in .NET 8”.
Author: Mahmut Sarıkaya — sarikayadev.com
