Azure Container Registry 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.

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:

Aspire CLI

Aspire CLI — Додати пакет Aspire.Hosting.Azure.ContainerRegistry

aspire add azure-containerregistry

Aspire CLI інтерактивний; оберіть відповідний результат пошуку:

Aspire CLI — Приклад виводу

Select an integration to add:

> azure-containerregistry (Aspire.Hosting.Azure.ContainerRegistry)
> Other results listed as selectable options...

Заувага

Якщо лише один результат — він вибирається автоматично. Потрібно підтвердити версію.

apphost.cs (C# file-based app)

C# — AppHost.cs

#:package Aspire.Hosting.Azure.ContainerRegistry@*

PackageReference (*.csproj)

XML — Додати посилання на пакет Aspire.Hosting.Azure.ContainerRegistry

<PackageReference Include="Aspire.Hosting.Azure.ContainerRegistry" Version="*" />

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:

C# — AppHost.cs

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.

For more information, see Configure Azure Container Apps environments.

Обережно

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:

:::code source=“snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/Program.Existing.cs” id=“existing”:::

C# — AppHost.cs

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.

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 , 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:

my-acr.module.bicep

@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:

env.module.bicep

@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.