Publishing .NET Core images to Microsoft Container Registry (MCR)

Microsoft teams are now publishing container images to the Microsoft Container Registry. There are two primary reasons for this change:

• Syndicate Microsoft-provided container images to multiple registries, like Docker Hub and Red Hat.
• Use Microsoft Azure as a global CDN for delivering Microsoft-provided container images.

You will use and see MCR as a storage back-end for Microsoft images. The primary way you learn about Microsoft container images and tags will be through a registry, which for most users will continue to be Docker Hub. Most of the experience you've had browsing for .NET Core container images will continue unchanged with this new model. The Docker Hub URLs you've used for Microsoft repos will continue to work, and forward to updated locations on Docker Hub. Existing Docker Hub will images will be maintained as-is.

See .NET Core Container Images now Published to Microsoft Container Registry for the most updated information on our use of MCR.

Starting with .NET Core nightly repo

On the .NET team, we started our transition to MCR with the .NET Core "nightly" repo. dotnet-nightly is now hosted on MCR and syndicated to Docker Hub. We started with the nightly repo in order to discover and fix any challenges we found with this new model before we move our higher-traffic primary container repository.

We will start publishing dotnet to MCR a bit later, in either February or March. This issue will be updated when that happens.

Repo Split

The .NET Core repo currently includes 4 major categories of tags:

• sdk
• aspnetcore-runtime
• runtime
• runtime-deps

Providing all of the tags in one place has helped with discoverability but made for a repo with an enormous README that can be challenging to navigate and consume. It is large enough that we exceeded Docker Hub README limits and had to artificially make it smaller.

Going forward, we will provide a repo for each of the tag categories listed above. We'll also provide a "product repo" that will hierarchicaly group all of our repos together. This will satisfy discoverability needs so that it will be easy to find the tags you want.

You can already see this experience with microsoft-dotnet-core-nightly. There are now multiple repos for our nightly builds:

• .NET Core Nightly product repo
• .NET Core SDK Nightly repo
• .NET Core ASP.NET Core Nightly repo
• .NET Core Runtime Nightly repo
• .NET Core Runtime-deps Nightly repo

The same split will exist for the non-nightly stable repo (currently hosted at microsoft/dotnet) when we start publishing it to MCR and syndicating it back to DockerHub.

Changes to registry URL

The biggest change is that your Dockerfiles need to be updated to point to the MCR registry in order get access to new .NET Core container tags. The same change is required for scripts or human operations that pull images via docker pull.

The following example shows the registry path, repo and tag for the .NET Core 2.2 "Nightly" SDK on MCR:

mcr.microsoft.com/dotnet/core-nightly/sdk:2.2

As comparison, the following repo and tag have been used to date for the .NET Core 2.2 "Nightly" SDK on Docker Hub:

microsoft/dotnet-nightly:2.2-sdk

The new repo URL is provided at each of the news repos. For example, the new .NET Core SDK "nightly" repo provides a box on the right where you can copy and paste the correct MCR-based repo syntax that you can use for docker pull or in FROM statements in your Dockerfiles.

Servicing existing Docker Hub tags

We will continue to service existing non-version-specific or floating tags on Docker Hub while the associated .NET Core version is supported. For example the microsoft/dotnet:2.1-sdk tag is a floating tag that will continue to be serviced for the lifetime of .NET Core 2.1. You can continue using floating tags without issue.

If you use non-floating tags, like microsoft/dotnet:2.1.504-sdk-alpine, then you will need to update your Dockerfile to use a new non-floating tag. No new non-floating tags will be published to microsoft/dotnet and microsoft/dotnet-nightly after we fully transition to MCR.

.NET Core 3.0 Preview 3 and later will only be made available on MCR.

Microsoft is a Verified Publisher

Until now, Microsoft-provided container images were considered "community images". As part of this change, we are re-classifying Microsoft as a "verified publisher" on Docker Hub. This designation should make it clearer that .NET and other Microsoft-provided images are coming from a verified source. There clearly was that expectation previously, but Docker is now making that clearer in the Docker Hub pages they host for Microsoft.

We will provide official vulnerability scanning Microsoft-provided images as a second phase of this transition.