Small, Hardened Images

Chiseled images are Ubuntu images cut down to the files a .NET process needs. There is no shell, no package manager and no apt, and the image starts as the non-root app user (UID 1654) without a USER line. Fewer packages means fewer CVEs to triage, a smaller pull and nothing for an attacker who gets code execution to work with.

Choosing a variant

aspnet tag	Shell, package manager	ICU and tzdata	Starts as	Choose when
10.0 (noble)	yes	yes	root	you must install OS packages in the final stage
10.0-alpine	yes (apk)	no, invariant mode	root	you want small and accept musl
10.0-noble-chiseled	no	no, invariant mode	app	the API is culture-neutral and UTC-only
10.0-noble-chiseled-extra	no	yes	app	you format for cultures or convert time zones

The same suffixes exist for runtime and runtime-deps; a self-contained or Native AOT app goes on runtime-deps:10.0-noble-chiseled.

Globalization invariant mode

Plain chiseled images set DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=true because they carry no ICU. Every culture then behaves like the invariant culture, string comparison is ordinal, and creating a specific culture such as new CultureInfo("de-DE") throws CultureNotFoundException. Without tzdata, TimeZoneInfo.FindSystemTimeZoneById("Europe/Berlin") throws TimeZoneNotFoundException; UTC still works. Microsoft.Data.SqlClient refuses to run in invariant mode at all. These failures appear on the first request that needs them, not at start-up. Decide per service: an API that stores UTC and returns ISO 8601 JSON is fine on plain chiseled; anything that renders invoices for a locale or computes a warehouse cut-off in local time needs -extra. Set InvariantGlobalization to match the image in Directory.Build.props, so the test projects get it too and tests on a laptop fail the same way production would. Set only in the API's .csproj, it lands in the API's runtimeconfig.json, while the test host runs with the test project's own runtimeconfig and keeps ICU.

Living without a shell

• No RUN in the final stage. Create directories and set permissions in the build stage, then COPY --chown.
• No HEALTHCHECK CMD curl. Kubernetes httpGet probes are made by the kubelet, so no binary is needed inside.
• No kubectl exec -- sh. Attach an ephemeral debug container with kubectl debug --target; it shares the process namespace.
• A preStop exec of sleep fails because there is no sleep binary; use the native sleep action.

Pinning and scanning

A tag such as 10.0-noble-chiseled moves: Microsoft re-publishes it for .NET patches and Ubuntu fixes. Pin by digest (@sha256:...) so a build is reproducible, and let Renovate or Dependabot open a pull request when the digest changes so the update is tested rather than silent. Scan the final image, not the SDK stage, in CI with Trivy or Docker Scout and fail on fixable High and Critical findings. Rebuild on a schedule: an image built six months ago carries six months of unpatched libraries even if your code did not change.

# syntax=docker/dockerfile:1
# CI passes a digest-pinned reference:
#   --build-arg RUNTIME_IMAGE=mcr.microsoft.com/dotnet/aspnet:10.0-noble-chiseled-extra@sha256:<digest>
ARG RUNTIME_IMAGE=mcr.microsoft.com/dotnet/aspnet:10.0-noble-chiseled-extra

FROM --platform=$BUILDPLATFORM mcr.microsoft.com/dotnet/sdk:10.0 AS build
ARG TARGETARCH
WORKDIR /src
COPY Directory.Build.props Directory.Packages.props ./
COPY src/Orders.Api/Orders.Api.csproj src/Orders.Api/
RUN dotnet restore src/Orders.Api/Orders.Api.csproj -a $TARGETARCH
COPY src/ src/
RUN dotnet publish src/Orders.Api/Orders.Api.csproj -a $TARGETARCH --no-restore \
        -c Release -o /app/publish
# The final image has no shell, so prepare writable folders here.
RUN mkdir -p /staging/invoice-exports

FROM ${RUNTIME_IMAGE} AS final
WORKDIR /app
COPY --from=build /app/publish .
COPY --from=build --chown=1654:1654 /staging/invoice-exports /var/lib/orders/invoice-exports
# Chiseled images already start as app; stating it keeps policy linters quiet.
USER $APP_UID
ENTRYPOINT ["./Orders.Api"]

using System.Globalization;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

// Fail at start-up, not on the first invoice, when the image lacks ICU or tzdata.
var problems = new List<string>();
try
{
    var german = CultureInfo.GetCultureInfo("de-DE");
    app.Logger.LogInformation("Invoice total renders as {Total}", 1234.5m.ToString("C", german));
}
catch (CultureNotFoundException)
{
    problems.Add("de-DE culture unavailable: globalization invariant mode (no ICU in the image)");
}

try
{
    var berlin = TimeZoneInfo.FindSystemTimeZoneById("Europe/Berlin");
    var local = TimeZoneInfo.ConvertTimeFromUtc(DateTime.UtcNow, berlin);
    app.Logger.LogInformation("Warehouse local time {LocalTime}", local);
}
catch (TimeZoneNotFoundException)
{
    problems.Add("Europe/Berlin not found: no tzdata in the image");
}

if (problems.Count > 0)
{
    foreach (var problem in problems) app.Logger.LogCritical("{Problem}", problem);
    app.Logger.LogCritical("Use the -noble-chiseled-extra base image");
    return 1;
}

app.MapGet("/invoices/{id:int}/total", (int id) =>
    Results.Ok(new { id, total = 1234.5m.ToString("C", CultureInfo.GetCultureInfo("de-DE")) }));

await app.RunAsync();
return 0;

# Resolve the digest the tag points to today, then pin it in CI's --build-arg
docker buildx imagetools inspect mcr.microsoft.com/dotnet/aspnet:10.0-noble-chiseled-extra

# Fail the pipeline on fixable high and critical CVEs in the final image
trivy image --severity HIGH,CRITICAL --ignore-unfixed --exit-code 1 \
  registry.example.com/shop/orders-api:1.4.0

# There is no shell to exec into:
docker run --rm --entrypoint sh registry.example.com/shop/orders-api:1.4.0
# exec: "sh": executable file not found in $PATH

# Attach a debug container that shares the API container's process namespace
kubectl debug -it orders-api-7c9f6d8b5-xk2lp --image=busybox:1.36 --target=orders-api -- sh
# inside: ps, ls /proc/1/root/app, wget -qO- localhost:8080/health/ready

<!-- Directory.Build.props at the repository root: applies to the API and its test projects -->
<Project>

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <!-- Deployed on aspnet:10.0-noble-chiseled (no ICU): behave the same everywhere -->
    <InvariantGlobalization>true</InvariantGlobalization>
  </PropertyGroup>

</Project>