Azure Container Registry Hosting integration

Azure Container Registry is a managed Docker container registry service that simplifies the storage, management, and deployment of container images. The Aspire integration allows you to provision or reference an existing Azure Container Registry and seamlessly integrate it with your app's compute environments.

Overview

Aspire apps often build and run container images locally but require secure registries for staging and production environments. The Azure Container Registry integration provides the following capabilities:

Provision or reference an existing Azure Container Registry.
Attach the registry to any compute-environment resource (for example, Azure Container Apps, Docker, Kubernetes) to ensure proper credential flow.
Grant fine-grained ACR role assignments to other Azure resources.

Supported scenarios

The Azure Container Registry integration supports the following scenarios:

Provisioning a new registry: Automatically create a new Azure Container Registry for your app.
Referencing an existing registry: Use an existing Azure Container Registry by providing its name and resource group.
Credential management: Automatically flow credentials to compute environments for secure image pulls.
Role assignments: Assign specific roles (for example, AcrPush) to enable services to push images to the registry.
Scheduled image cleanup: Automatically remove old or unused container images on a cron schedule with purge tasks.

Hosting integration

The Aspire Azure Container Registry hosting integration models the container registry as the AzureContainerRegistryResource type. To access this type and APIs for expressing them within your AppHost project, install the 📦 Aspire.Hosting.Azure.ContainerRegistry NuGet package:

Install the NuGet package

dotnet add package Aspire.Hosting.Azure.ContainerRegistry

Provision a new container registry

The following example demonstrates how to provision a new Azure Container Registry and attach it to a container app environment:

var builder = DistributedApplication.CreateBuilder(args);
  
// Add (or reference) the registry
var acr = builder.AddAzureContainerRegistry("my-acr");
  
// Wire an environment to that registry
builder.AddAzureContainerAppEnvironment("env")
       .WithAzureContainerRegistry(acr);
  
builder.Build().Run();

The preceding code:

Creates a new Azure Container Registry named my-acr.
Attaches the registry to an Azure Container Apps environment named env.
Optionally grants the AcrPush role to a project resource named api, allowing it to push images to the registry.

Caution

When you call AddAzureContainerRegistry, it implicitly calls AddAzureProvisioning—which adds support for generating Azure resources dynamically during app startup. The app must configure the appropriate subscription and location. For more information, see Local provisioning: Configuration.

Reference an existing container registry

To reference an existing Azure Container Registry, use the PublishAsExisting method with the registry name and resource group:

var builder = DistributedApplication.CreateBuilder(args);
  
var registryName = builder.AddParameter("registryName");
var rgName = builder.AddParameter("rgName");
  
// Add (or reference) the registry
var acr = builder.AddAzureContainerRegistry("my-acr")
    .PublishAsExisting(registryName, rgName);
  
// Wire an environment to that registry
builder.AddAzureContainerAppEnvironment("env")
    .WithAzureContainerRegistry(acr);
  
builder.Build().Run();

The preceding code:

References an existing Azure Container Registry named my-acr in the specified resource group.
Attaches the registry to an Azure Container Apps environment named env.
Uses parameters to allow for dynamic configuration of the registry name and resource group.
Optionally grants the AcrPush role to a project resource named api, allowing it to push images to the registry.

Access the registry from a compute environment

Compute environments such as AzureContainerAppEnvironment and AzureAppServiceEnvironment automatically provision a default Azure Container Registry. You can also specify an explicit registry with WithAzureContainerRegistry. To get a resource builder for the associated registry, use the GetAzureContainerRegistry method:

var env = builder.AddAzureContainerAppEnvironment("env");
  
// A default registry is auto-provisioned — no need to call
// WithAzureContainerRegistry unless you want a specific one
var registry = env.GetAzureContainerRegistry();

This returns an IResourceBuilder<AzureContainerRegistryResource> that you can use for further configuration, such as adding purge tasks.

Caution

The IAzureContainerRegistry interface is obsolete as of Aspire 13.2. If your code casts a compute environment to IAzureContainerRegistry, migrate to the ContainerRegistry property on IAzureComputeEnvironmentResource instead. For more information, see What's new in Aspire 13.2.

Schedule image cleanup with purge tasks

Over time, container registries accumulate old images that consume storage and increase costs. The WithPurgeTask method adds a scheduled ACR purge task that automatically removes old or unused container images on a cron schedule:

var acr = builder.AddAzureContainerRegistry("my-acr")
    .WithPurgeTask("0 1 * * *", ago: TimeSpan.FromDays(7), keep: 5);

The preceding code creates a purge task that runs daily at 1:00 AM, removing images older than 7 days while keeping the 5 most recent images per repository.

Multiple purge tasks

You can add multiple purge tasks to a single registry, each with different schedules and filters:

var acr = builder.AddAzureContainerRegistry("my-acr")
    .WithPurgeTask("0 1 * * *", filter: "app1:.*", keep: 3)
    .WithPurgeTask("0 2 * * 0", filter: "app2:.*", ago: TimeSpan.FromDays(30), keep: 10);

Each purge task is given a unique name automatically. You can also specify a custom task name with the taskName parameter.

Key features

Automatic credential flow

When you attach an Azure Container Registry to a compute environment, Aspire automatically ensures that the correct credentials are available for secure image pulls.

Fine-grained role assignments

You can assign specific roles to Azure resources to control access to the container registry. For example, the AcrPush role allows a service to push images to the registry.

builder.AddProject("api", "../Api/Api.csproj")
       .WithRoleAssignments(acr, ContainerRegistryBuiltInRole.AcrPush);

Provisioning-generated Bicep

If you're new to Bicep, it's a domain-specific language for defining Azure resources. With Aspire, you don't need to write Bicep by-hand, instead the provisioning APIs generate Bicep for you. When you publish your app, the generated Bicep is output alongside the manifest file. When you add an Azure Container Registry resource, the following Bicep is generated:

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location
  
resource my_acr 'Microsoft.ContainerRegistry/registries@2023-07-01' = {
  name: take('myacr${uniqueString(resourceGroup().id)}', 50)
  location: location
  sku: {
    name: 'Basic'
  }
  tags: {
    'aspire-resource-name': 'my-acr'
  }
}
  
output name string = my_acr.name
  
output loginServer string = my_acr.properties.loginServer

The preceding Bicep provisions an Azure Container Registry resource. Additionally, the added Azure Container App environment resource is also generated:

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location
  
param userPrincipalId string
  
param tags object = { }
  
param my_acr_outputs_name string
  
resource env_mi 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = {
  name: take('env_mi-${uniqueString(resourceGroup().id)}', 128)
  location: location
  tags: tags
}
  
resource my_acr 'Microsoft.ContainerRegistry/registries@2023-07-01' existing = {
  name: my_acr_outputs_name
}
  
resource my_acr_env_mi_AcrPull 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(my_acr.id, env_mi.id, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '7f951dda-4ed3-4680-a7ca-43fe172d538d'))
  properties: {
    principalId: env_mi.properties.principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '7f951dda-4ed3-4680-a7ca-43fe172d538d')
    principalType: 'ServicePrincipal'
  }
  scope: my_acr
}
  
resource env_law 'Microsoft.OperationalInsights/workspaces@2023-09-01' = {
  name: take('envlaw-${uniqueString(resourceGroup().id)}', 63)
  location: location
  properties: {
    sku: {
      name: 'PerGB2018'
    }
  }
  tags: tags
}
  
resource env 'Microsoft.App/managedEnvironments@2024-03-01' = {
  name: take('env${uniqueString(resourceGroup().id)}', 24)
  location: location
  properties: {
    appLogsConfiguration: {
      destination: 'log-analytics'
      logAnalyticsConfiguration: {
        customerId: env_law.properties.customerId
        sharedKey: env_law.listKeys().primarySharedKey
      }
    }
    workloadProfiles: [
      {
        name: 'consumption'
        workloadProfileType: 'Consumption'
      }
    ]
  }
  tags: tags
}
  
resource aspireDashboard 'Microsoft.App/managedEnvironments/dotNetComponents@2024-10-02-preview' = {
  name: 'aspire-dashboard'
  properties: {
    componentType: 'AspireDashboard'
  }
  parent: env
}
  
resource env_Contributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(env.id, userPrincipalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'b24988ac-6180-42a0-ab88-20f7382dd24c'))
  properties: {
    principalId: userPrincipalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'b24988ac-6180-42a0-ab88-20f7382dd24c')
  }
  scope: env
}
  
output MANAGED_IDENTITY_NAME string = env_mi.name
  
output MANAGED_IDENTITY_PRINCIPAL_ID string = env_mi.properties.principalId
  
output AZURE_LOG_ANALYTICS_WORKSPACE_NAME string = env_law.name
  
output AZURE_LOG_ANALYTICS_WORKSPACE_ID string = env_law.id
  
output AZURE_CONTAINER_REGISTRY_NAME string = my_acr_outputs_name
  
output AZURE_CONTAINER_REGISTRY_ENDPOINT string = my_acr.properties.loginServer
  
output AZURE_CONTAINER_REGISTRY_MANAGED_IDENTITY_ID string = env_mi.id
  
output AZURE_CONTAINER_APPS_ENVIRONMENT_NAME string = env.name
  
output AZURE_CONTAINER_APPS_ENVIRONMENT_ID string = env.id
  
output AZURE_CONTAINER_APPS_ENVIRONMENT_DEFAULT_DOMAIN string = env.properties.defaultDomain

The generated Bicep is a starting point and is influenced by changes to the provisioning infrastructure in C#. Customizations to the Bicep file directly are overwritten, so make changes through the C# provisioning APIs to ensure they're reflected in the generated files.