Microsoft Artifact Registry · logical architecture
bub.im · cheatsheet
Microsoft Artifact Registry · logical architecture
How MAR, also known as MCR, is put together: an anonymous OCI registry split into a discovery endpoint and a content delivery endpoint, fronted by Azure Traffic Manager and Azure Front Door. Written for anyone who has to allow it through a firewall or an enclave boundary.
01
What it is
One service, two names. MAR is the current product name, MCR is the original name and still the hostname everyone types.
| Term | Meaning |
|---|---|
| MAR | Microsoft Artifact Registry. The current name of the service. |
| MCR | Microsoft Container Registry. The original name, kept in the hostnames mcr.microsoft.com and *.data.mcr.microsoft.com. |
| Standard | An implementation of the OCI Distribution Specification. It serves container images, Helm charts and other OCI artifacts. |
| Publisher | Microsoft and Azure only. Third parties cannot publish into it. |
| Access model | Anonymous read over HTTPS on port 443. No credentials are needed to pull. |
| Discovery | The MAR catalog UI, plus listings syndicated to other catalogs such as Docker Hub and Azure Marketplace. The pull source is always mcr.microsoft.com, whichever catalog you browsed. |
| Mirrors | None official. Microsoft does not provide or endorse mirrors and warns that they may serve altered content.supply chain |
02
Logical architecture
Five layers, top to bottom. Solid arrows are the pull path, the dashed arrow is the redirect the client follows, and the dashed boxes are internals that Microsoft does not document publicly.
| Step | Where | What happens |
|---|---|---|
| 1 | Client to DNS | The client resolves mcr.microsoft.com. Azure Traffic Manager answers with a registry region close to the client. |
| 2 | Client to registry | The client requests the manifest and, from it, learns the digests of the layers it needs. |
| 3 | Registry to client | For layer blobs the registry sends the client to the data endpoint. The client follows the redirect, the registry does not proxy the bytes. |
| 4 | Client to edge | The client downloads the blob from a regional data host behind Azure Front Door. |
| 5 | Edge to origin | On a cache miss the edge fetches the blob from the origin store and caches it for later pulls. |
03
Layers and components
Only the client facing layers are documented by Microsoft. The origin and publishing layers are inferred from the public behaviour, so treat them as a model rather than a specification.
| Layer | Component | Role |
|---|---|---|
| Clients | Runtimes, orchestrators, CI, CLIs | Speak the standard registry protocol. Nothing MAR specific is required on the client. |
| Global routing | Azure Traffic Manager | DNS based routing for the registry endpoint. This is why the registry IP addresses change by client location. |
| Edge | Azure Front Door | Documented entry point of MAR and the CDN behind the data endpoint. Explains the service tag pair in section 07. |
| Discovery plane | Registry endpoint | Manifests, tags, catalog UI. Load balanced across the nine public regions, giving consistent content addressable artifacts. |
| Delivery plane | Data endpoint | Layer bytes only. Regional CDN endpoints, added and moved by Microsoft for performance. |
| Origin | Artifact store | Not publicly documented.inferred |
| Publishing | Microsoft pipelines | Not publicly documented. The only visible fact is that no third party can publish.inferred |
| Sovereign instance | China region | Separate hostnames, same design. Not reachable through the global names in a useful way. |
04
Observing the pull flow
Each command exercises one hop of the diagram. Run them from a host that is allowed to reach MAR, and replace the placeholders.
# hop 1 and 2: resolve the registry endpoint and probe the API root $ dig +short mcr.microsoft.com $ curl -sI https://mcr.microsoft.com/v2/ # hop 2: list tags for a repository $ curl -s https://mcr.microsoft.com/v2/dotnet/runtime/tags/list # hop 2: fetch the manifest and note the layer digests $ skopeo inspect --raw docker://mcr.microsoft.com/dotnet/runtime:8.0 # hop 3: request one blob without following the redirect, read the Location header $ curl -s -o /dev/null -D - https://mcr.microsoft.com/v2/dotnet/runtime/blobs/sha256:<layer-digest> # hop 4: the host named in Location is the regional data endpoint $ dig +short <host-from-location>
noteThe Location header is the fastest way to learn which data host your site actually uses. Record it, but write the firewall rule against the wildcard, not against that one host.
05
Official endpoints
| FQDN | Purpose | Notes |
|---|---|---|
| mcr.microsoft.com | Registry endpoint and catalog UI | HTTPS. Global name, resolved through Azure Traffic Manager. |
| *.data.mcr.microsoft.com | Data endpoint | HTTPS. Wildcard covers every regional host, for example westeurope.data.mcr.microsoft.com.use this |
| mcr.azure.cn | Registry endpoint, China | Counterpart of mcr.microsoft.com. |
| *.data.mcr.azure.cn | Data endpoint, China | Counterpart of *.data.mcr.microsoft.com. |
Public regions of the registry endpoint:
| Area | Locations |
|---|---|
| Asia | Asia East, Asia South East |
| Europe | Europe North, Europe West |
| United States | US Central, US East, US West, US West 2, US West-Central |
| China | China East 3, China North 3, served by the China hostnames above |
06
What it hosts
Common namespaces under mcr.microsoft.com. The catalog UI is the authoritative list.
| Category | Path prefix | Examples |
|---|---|---|
| Runtimes and SDKs | dotnet/ | .NET runtime, ASP.NET, SDK images |
| Windows base images | windows/ | nanoserver, servercore, server |
| Data services | mssql/ | SQL Server images |
| Azure services | azure-functions/, azure-cognitive-services/ | Functions base images, on premises AI service containers |
| Developer tooling | devcontainers/, playwright | Dev container images, browser test images |
| OCI artifacts | bicep/ | Public Bicep modules and other non image artifacts |
07
Firewall and proxy rules
Microsoft asks for the two FQDNs and advises against region specific rules, because the regional data hosts are added and moved over time.
| Method | Rule | Comment |
|---|---|---|
| FQDN allow list | mcr.microsoft.com and *.data.mcr.microsoft.com | Preferred. Stable across regional changes. Needs a firewall or proxy that can filter by name or SNI. |
| Azure service tags | MicrosoftContainerRegistry and AzureFrontDoor.FirstParty | Enable both. Only works inside Azure NSG and Azure Firewall rules. |
| IP allow list | Not recommended | Traffic Manager and Front Door use shared, changing addresses, and Microsoft does not publish a fixed list for MAR.brittle |
| Region specific host | A single <region>.data.mcr.microsoft.com | Works today, breaks when Microsoft moves the region.avoid |
| TLS | HTTPS on 443 only | No plain HTTP is needed. TLS inspection is optional and can break some clients. |
A minimal Squid rule for a single build subnet:
# squid.conf
acl build_hosts src 10.20.30.0/24
acl mar_sites dstdomain mcr.microsoft.com .data.mcr.microsoft.com
http_access allow build_hosts mar_sites
http_access deny all
08
Using it from a protected enclave
| Pattern | Description | Fit |
|---|---|---|
| Ingest and mirror | One controlled host, outside or on the edge of the enclave, pulls from MAR. Images are scanned, pinned by digest and imported into your own private registry. Workloads inside pull only from that registry. | Strict enclavespreferred |
| Scoped egress | FQDN rule for the two names, limited to build agents or the container host subnet, logged and alerted. | Moderate enclaves |
| Open egress | Whole enclave allowed to reach the names or a wider Microsoft wildcard. | Not advisedscope creep |
# import into an Azure Container Registry you control $ az acr import --name <acr> --source mcr.microsoft.com/dotnet/runtime:8.0 --image dotnet/runtime:8.0 # or copy to any internal registry, then record the digest $ skopeo copy docker://mcr.microsoft.com/dotnet/runtime:8.0 docker://registry.internal/dotnet/runtime:8.0 $ skopeo inspect --format '{{.Digest}}' docker://registry.internal/dotnet/runtime:8.0
mirrorsMicrosoft states that it offers no official mirrors and does not endorse third party ones. An internal registry that you populate yourself, and verify by digest, is a different thing from a third party mirror, but the point still applies: content is only as trustworthy as the ingest step.
09
Sources and limits
Verified against Microsoft documentation on 2026-09-29. Live traffic was not captured, because the authoring workspace could not reach MAR, so the redirect behaviour in step 3 follows the documented two endpoint model.
| Topic | Reference |
|---|---|
| Firewall rules and service tags | microsoft/containerregistry · client-firewall-rules.md |
| Endpoints, regions, mirrors | microsoft/containerregistry · mcr-endpoints-guidance.md |
| Catalog syndication | Azure Blog · Microsoft syndicates container catalog |
| Catalog UI | mcr.microsoft.com/en-us/catalog |
0 comments