Request for Feedback: Extensibility Refactor Impact on Acquisition

[jander-msft]

tl;dr

1. The acquisition of the .NET Tool package (e.g. dotnet tool install dotnet-monitor) and its feature set are not impacted.
2. The tool archives will be split into the core tool and each extension.
3. The acquisition of the .NET Monitor Docker image (e.g. docker pull mcr.microsoft.com/dotnet/monitor) and its feature set are not impacted.
4. The Docker images are split into a base image (contains core .NET Monitor tool) and an extending image (base image + extensions)

Overview

For .NET Monitor 8, the team is refactoring the tool to allow certain features to be extensible (namely, custom egress providers). The extensibility model allows extensions authors to provide additional functionality that is not directly built into the tool. The motivations for this are:

1. Allow tool consumers to author and install extensions for the tool without having to customize the tool source code and build it themselves.
2. Allow tool consumers to exclude functionality that would never be used. For example, you may use AWS services exclusively and are not interested in the Azure Blob storage extension.

The existing acquisition mechanisms and the feature sets offered by those existing assets (namely, the .NET Tool package and the Docker images) will be preserved.

Existing Egress Providers

As part of this offering, the Azure Blob storage and S3 storage egress providers will be refactored out of the core of the .NET Monitor tool into their own extension packages. The Azure Blob storage egress provider has shipped in the tool since the tool's inception, whereas the S3 storage egress provider is new to .NET Monitor 8. These were refactored out of the tool to allow for custom selection of which ones are installed as well as to flex the extensibility model to make sure it works.

Impact on the .NET Tool Package

While the cloud storage egress providers have been refactored into their own extension packages, the .NET tool offering bundles the extensions within the NuGet package to maintain the existing capabilities. This effectively preserves the functional behavior of the .NET Tool package. Going forward, its our intent to ship all extensions maintained as part of the .NET Monitor project within the .NET Tool package. Think of it as the "everything-but-the-kitchen-sink" package.

We view the .NET Tool package as a convenience for acquiring .NET Monitor on any platform with all of the default capabilities, so long as you have an applicable .NET SDK to acquire the package. If a user needs a more sculpted installation (specific platform, specific TFM, specific extensions), that is the purpose of the archive packages.

Impact on the Archives

The 8.0 archive packages (*.tar.gz and *.zip) for the .NET Monitor tool will NOT contain the extensions. The extensions themselves will be their own archive packages. These packages can be overlayed on top of the expanded .NET Monitor tool archive such that the extensions are extracted into the correct locations so that users do not have to understand the tool layout. An example layering would be:

dotnet_monitor_version=<version>
mkdir -p /app

curl -fSL --output dotnet-monitor.tar.gz https://dotnetcli.azureedge.net/dotnet/diagnostics/monitor/$dotnet_monitor_version/dotnet-monitor-$dotnet_monitor_version-linux-x64.tar.gz
tar -oxzf dotnet-monitor.tar.gz -C /app
rm dotnet-monitor.tar.gz

curl -fSL --output dotnet-monitor-egress-azureblobstorage.tar.gz https://dotnetcli.azureedge.net/dotnet/diagnostics/monitor/$dotnet_monitor_version/dotnet-monitor-egress-azureblobstorage-$dotnet_monitor_version-linux-x64.tar.gz
tar -oxzf dotnet-monitor-egress-azureblobstorage.tar.gz -C /app
rm dotnet-monitor-egress-azureblobstorage.tar.gz

curl -fSL --output dotnet-monitor-egress-s3storage.tar.gz https://dotnetcli.azureedge.net/dotnet/diagnostics/monitor/$dotnet_monitor_version/dotnet-monitor-egress-s3storage-$dotnet_monitor_version-linux-x64.tar.gz
tar -oxzf dotnet-monitor-egress-s3storage.tar.gz -C /app
rm dotnet-monitor-egress-s3storage.tar.gz

Note that all packages are extracted into the /app directory without having to understand the structure of where extensions are located. The above example provides the same functionality found in the .NET Tool package, except it is sculpted to only run on an ASP.NET 8.0 shared installation on Linux x64 platforms.

Impact on the Docker Images

The .NET Monitor images use the .NET Monitor archive described in the previous section and would require a similar overlaying technique to achieve parity with prior versions. However, it may be advantageous to separate the installtion of the .NET Monitor archive into a base image and install the extension archives in an extending image. The former image provides the .NET Monitor tool installation as a standalone image to allow anyone to extend it as they need without having to configure the standard environment variables, application root, and command line entrypoint. The latter image would become the mcr.microsoft.com/dotnet/monitor image. This is a similar technique employed by the runtime-deps -> runtime -> aspnetcore -> sdk layering in the https://github.com/dotnet/dotnet-docker GitHub repository.

Base Image (published as mcr.microsoft.com/dotnet/monitor/base):

ARG REPO=mcr.microsoft.com/dotnet/aspnet

# Installer image
FROM amd64/buildpack-deps:jammy-curl AS installer

# Retrieve .NET Monitor
RUN dotnet_monitor_version=<version> \
    && curl -fSL --output dotnet-monitor.tar.gz https://dotnetcli.azureedge.net/dotnet/diagnostics/monitor/$dotnet_monitor_version/dotnet-monitor-$dotnet_monitor_version-linux-x64.tar.gz \
    && dotnet_monitor_sha512='<sha512>' \
    && echo "$dotnet_monitor_sha512  dotnet-monitor.tar.gz" | sha512sum -c - \
    && mkdir -p /app \
    && tar -oxzf dotnet-monitor.tar.gz -C /app \
    && rm dotnet-monitor.tar.gz


# .NET Monitor base image
FROM $REPO:8.0.0-preview-jammy-chiseled-amd64

WORKDIR /app
COPY --from=installer /app .

ENV \
    # Unset ASPNETCORE_HTTP_PORTS from aspnet base image
    ASPNETCORE_HTTP_PORTS= \
    # Disable debugger and profiler diagnostics to avoid diagnosing self.
    COMPlus_EnableDiagnostics=0 \
    # Default Filter
    DefaultProcess__Filters__0__Key=ProcessId \
    DefaultProcess__Filters__0__Value=1 \
    # Remove Unix Domain Socket before starting diagnostic port server
    DiagnosticPort__DeleteEndpointOnStartup=true \
    # Server GC mode
    DOTNET_gcServer=1 \
    # Logging: JSON format so that analytic platforms can get discrete entry information
    Logging__Console__FormatterName=json \
    # Logging: Use round-trip date/time format without timezone information (always logged in UTC)
    Logging__Console__FormatterOptions__TimestampFormat=yyyy'-'MM'-'dd'T'HH':'mm':'ss'.'fffffff'Z' \
    # Logging: Write timestamps using UTC offset (+0:00)
    Logging__Console__FormatterOptions__UseUtcTimestamp=true \
    # Add dotnet-monitor path to front of PATH for easier, prioritized execution
    PATH="/app:${PATH}"

ENTRYPOINT [ "dotnet-monitor" ]
CMD [ "collect", "--urls", "https://+:52323", "--metricUrls", "http://+:52325" ]

Extending Image (published as mcr.microsoft.com/dotnet/monitor):

ARG REPO=mcr.microsoft.com/dotnet/monitor/base

# Installer image
FROM amd64/buildpack-deps:jammy-curl AS installer

# Retrieve .NET Monitor extensions
RUN dotnet_monitor_extension_version=<version> \
    && curl -fSL --output dotnet-monitor-egress-azureblobstorage.tar.gz https://dotnetcli.azureedge.net/dotnet/diagnostics/monitor-extensions/$dotnet_monitor_extension_version/dotnet-monitor-egress-azureblobstorage-$dotnet_monitor_extension_version-linux-x64.tar.gz \
    && dotnet_monitor_egress_azureblobstorage_sha512='<sha512>' \
    && echo "$dotnet_monitor_egress_azureblobstorage_sha512  dotnet-monitor-egress-azureblobstorage.tar.gz" | sha512sum -c - \
    && tar -oxzf dotnet-monitor-egress-azureblobstorage.tar.gz -C /app \
    && rm dotnet-monitor-egress-azureblobstorage.tar.gz \
    && curl -fSL --output dotnet-monitor-egress-s3storage.tar.gz https://dotnetcli.azureedge.net/dotnet/diagnostics/monitor-extensions/$dotnet_monitor_extension_version/dotnet-monitor-egress-s3storage-$dotnet_monitor_extension_version-linux-x64.tar.gz \
    && dotnet_monitor_egress_s3storage_sha512='<sha512>' \
    && echo "$dotnet_monitor_egress_s3storage_sha512  dotnet-monitor-egress-s3storage.tar.gz" | sha512sum -c - \
    && tar -oxzf dotnet-monitor-egress-s3storage.tar.gz -C /app \
    && rm dotnet-monitor-egress-s3storage.tar.gz


# .NET Monitor image
FROM $REPO:8.0-preview-ubuntu-chiseled-amd64

COPY --from=installer /app .

Note that the base Dockerfile is unchanged from the existing .NET 8 Dockerfile, but building it produces the core .NET Monitor image. The extending Dockerfile takes the core image and layers the extensions on top of it. The extending Dockerfile effectively produces the final public .NET Monitor image with the same capabilities today. The split of the core installation and the extensions allow anyone to use the base image for their own customizations; the extending Dockerfile demonstrates how to easy install extensions on top of the core image and preserves the existing offering of the mcr.microsoft.com/dotnet/monitor image.

[mthalman]

In general, this all sounds good. For the Docker images, my only concern is around the naming of the repos. I'm sure we'll get other opinions on this as naming is always a controversial topic.

Instead of mcr.microsoft.com/dotnet/monitor-base, I'd prefer something like mcr.microsoft.com/dotnet/monitor/base. If we were starting from scratch and didn't have to worry about backwards compatibility for the mcr.microsoft.com/dotnet/monitor repository, I'd then like to have a repo name like mcr.microsoft.com/dotnet/monitor/full for the derived image. But since we're not in situation, I think it makes sense to continue using mcr.microsoft.com/dotnet/monitor for the derived images.

[mthalman]

For the specific point of the repository name, is it allowable to have a /base subpath under mcr.microsoft.com/dotnet/monitor if this one is already in use?

Yes. There's no inherent structure with the slashes from the perspective of the registry.

Additionally, is it possible to publish the same .NET Monitor image to both mcr.microsoft.com/dotnet/monitor and mcr.microsoft.com/dotnet/monitor/full but only advertise the 'full' repository?

Good point. That's certainly an option. The .NET Docker infrastructure has the concept of syndication to publish an image to a different repository with a given tag. So yes, you could syndicate a mcr.microsoft.com/dotnet/monitor/full:8.0 image to mcr.microsoft.com/dotnet/monitor:latest if you wanted.

[jander-msft]

Excellent! I'll update the proposal to use dotnet/monitor/base and dotnet/monitor/full and mention that full will be syndicated to dotnet/monitor for backward compatibility.

[jander-msft]

Upon further discussion, we think that rather than creating a dotnet/monitor/full repository that is syndicated back to the dotnet/monitor repository for the latest tag only that we'll just push directly to the dotnet/monitor repository (no full repository will be created). This will create a least resistance upgrade path from prior versions, especially since we conjecture that a small number of customers will actually use the base image as-is or derive their own image from it. This lowers the cognitive load such that the vast majority of customers don't have to understand what are the difference between base and the hypothetical full images.

[birojnayak]

@jander-msft This make sense as it would give each team lots of independence without impacting the core functionality. Please tag me on the PR's relevant to above change.

[jander-msft]

@birojnayak, this work has largely been completed at this point and will be shipping in the next preview of .NET Monitor 8. It applies only to .NET Monitor 8 (and future versions). You can see example usage of the new base installation and extension packages in the following Dockerfiles:

• Base: https://github.com/dotnet/dotnet-docker/blob/nightly/src/monitor-base/8.0/ubuntu-chiseled/amd64/Dockerfile
• Extensions: https://github.com/dotnet/dotnet-docker/blob/nightly/src/monitor/8.0/ubuntu-chiseled/amd64/Dockerfile

There may be other changes that come along but the core idea is currently in-place.