diff --git a/docs/azure/container-registry-integration.md b/docs/azure/container-registry-integration.md new file mode 100644 index 0000000000..3bd988eb1e --- /dev/null +++ b/docs/azure/container-registry-integration.md @@ -0,0 +1,114 @@ +--- +title: Azure Container Registry integration (Preview) +description: Learn how to integrate Azure Container Registry with .NET Aspire for secure container image management. +ms.date: 05/09/2025 +--- + +# .NET Aspire Azure Container Registry integration (Preview) + +[!INCLUDE [includes-hosting](../includes/includes-hosting.md)] + +> [!IMPORTANT] +> The .NET Aspire Azure Functions integration is currently in preview and is subject to change. + +[Azure Container Registry (ACR)](/azure/container-registry) is a managed Docker container registry service that simplifies the storage, management, and deployment of container images. The .NET Aspire integration allows you to provision or reference an existing Azure Container Registry and seamlessly integrate it with your app's compute environments. + +## Overview + +.NET 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 Azure Container Registry integration is part of the .NET Aspire hosting model. It allows you to define and manage your app's resources in a declarative manner. The integration is available in the [📦 Aspire.Hosting.Azure.ContainerRegistry](https://www.nuget.org/packages/Aspire.Hosting.Azure.ContainerRegistry) NuGet package. + +### [.NET CLI](#tab/dotnet-cli) + +```dotnetcli +dotnet add package Aspire.Hosting.Azure.ContainerRegistry +``` + +### [PackageReference](#tab/package-reference) + +```xml + +``` + +--- + +For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-package) or [Manage package dependencies in .NET applications](/dotnet/core/tools/dependencies). + +### 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: + +:::code source="snippets/acr//AspireAcr.AppHost/AspireAcr.AppHost/Program.cs"::: + +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](configure-aca-environments.md). + +> [!IMPORTANT] +> When you call `AddAzureContainerRegistry` or `AddAzureContainerAppEnvironment`, they implicitly call the idempotent —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](local-provisioning.md#configuration). + +#### Provisioning-generated Bicep + +If you're new to [Bicep](/azure/azure-resource-manager/bicep/overview), it's a domain-specific language for defining Azure resources. With .NET 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: + +:::code language="bicep" source="snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/my-acr.module.bicep"::: + +The preceding Bicep provisions an Azure Container Registry resource. Additionally, the added Azure Container App environment resource is also generated: + +:::code language="bicep" source="snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/env.module.bicep"::: + +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. + +### Reference an existing container registry + +To reference an existing Azure Container Registry, use the method with the registry name and resource group: + +:::code source="snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/Program.Existing.cs" id="existing"::: + +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. + +```csharp +builder.AddProject("api", "../Api/Api.csproj") + .WithRoleAssignments(acr, ContainerRegistryBuiltInRole.AcrPush); +``` + +## See also + +- [Azure Container Registry documentation](/azure/container-registry) +- [.NET Aspire Azure integrations overview](integrations-overview.md) diff --git a/docs/azure/integrations-overview.md b/docs/azure/integrations-overview.md index 85bfae3535..5d1bceebf5 100644 --- a/docs/azure/integrations-overview.md +++ b/docs/azure/integrations-overview.md @@ -1,7 +1,7 @@ --- title: Azure integrations overview description: Overview of the Azure integrations available in the .NET Aspire. -ms.date: 04/10/2025 +ms.date: 05/09/2025 uid: dotnet/aspire/integrations/azure-overview --- @@ -323,6 +323,9 @@ The preceding code: To configure the Azure Container App environment, see [Configure Azure Container Apps environments](configure-aca-environments.md). For more information, see and . +> [!TIP] +> If you're working with Azure Container Apps, you might also be interested in the [.NET Aspire Azure Container Registry integration](container-registry-integration.md). + ## Infrastructure as code The Azure SDK for .NET provides the [📦 Azure.Provisioning](https://www.nuget.org/packages/Azure.Provisioning) NuGet package and a suite of service-specific [Azure provisioning packages](https://www.nuget.org/packages?q=owner%3A+azure-sdk+description%3A+declarative+resource+provisioning&sortby=relevance). These Azure provisioning libraries make it easy to declaratively specify Azure infrastructure natively in .NET. Their APIs enable you to write object-oriented infrastructure in C#, resulting in Bicep. [Bicep is a domain-specific language (DSL)](/azure/azure-resource-manager/bicep/overview) for deploying Azure resources declaratively. diff --git a/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/AspireAcr.AppHost.csproj b/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/AspireAcr.AppHost.csproj new file mode 100644 index 0000000000..20092aa8d7 --- /dev/null +++ b/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/AspireAcr.AppHost.csproj @@ -0,0 +1,20 @@ + + + + + + Exe + net9.0 + enable + enable + true + 4a4b5271-16e5-49fd-a7a1-ff2849aefc25 + + + + + + + + + diff --git a/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/Program.Existing.cs b/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/Program.Existing.cs new file mode 100644 index 0000000000..88e3440599 --- /dev/null +++ b/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/Program.Existing.cs @@ -0,0 +1,24 @@ +using Azure.Provisioning.ContainerRegistry; + +internal static partial class Program +{ + internal static void ReferenceExisting(string[] args) + { + // + 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(); + // + } +} \ No newline at end of file diff --git a/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/Program.cs b/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/Program.cs new file mode 100644 index 0000000000..9c1f2a4314 --- /dev/null +++ b/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/Program.cs @@ -0,0 +1,12 @@ +using Azure.Provisioning.ContainerRegistry; + +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(); diff --git a/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/Properties/launchSettings.json b/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/Properties/launchSettings.json new file mode 100644 index 0000000000..4bdb81f981 --- /dev/null +++ b/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/Properties/launchSettings.json @@ -0,0 +1,35 @@ +{ + "$schema": "https://json.schemastore.org/launchsettings.json", + "profiles": { + "https": { + "commandName": "Project", + "dotnetRunMessages": true, + "launchBrowser": true, + "applicationUrl": "https://localhost:17190;http://localhost:15027", + "environmentVariables": { + "ASPNETCORE_ENVIRONMENT": "Development", + "DOTNET_ENVIRONMENT": "Development", + "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "https://localhost:21284", + "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:22130" + } + }, + "http": { + "commandName": "Project", + "dotnetRunMessages": true, + "launchBrowser": true, + "applicationUrl": "http://localhost:15027", + "environmentVariables": { + "ASPNETCORE_ENVIRONMENT": "Development", + "DOTNET_ENVIRONMENT": "Development", + "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "http://localhost:19098", + "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "http://localhost:20225" + } + }, + "generate-manifest": { + "commandName": "Project", + "launchBrowser": false, + "dotnetRunMessages": true, + "commandLineArgs": "--publisher manifest --output-path aspire-manifest.json", + } + } +} diff --git a/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/api-identity.module.bicep b/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/api-identity.module.bicep new file mode 100644 index 0000000000..0ff5902d5b --- /dev/null +++ b/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/api-identity.module.bicep @@ -0,0 +1,15 @@ +@description('The location for the resource(s) to be deployed.') +param location string = resourceGroup().location + +resource api_identity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = { + name: take('api_identity-${uniqueString(resourceGroup().id)}', 128) + location: location +} + +output id string = api_identity.id + +output clientId string = api_identity.properties.clientId + +output principalId string = api_identity.properties.principalId + +output principalName string = api_identity.name \ No newline at end of file diff --git a/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/api-roles-my-acr.module.bicep b/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/api-roles-my-acr.module.bicep new file mode 100644 index 0000000000..0c3c78e2f7 --- /dev/null +++ b/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/api-roles-my-acr.module.bicep @@ -0,0 +1,20 @@ +@description('The location for the resource(s) to be deployed.') +param location string = resourceGroup().location + +param my_acr_outputs_name string + +param principalId string + +resource my_acr 'Microsoft.ContainerRegistry/registries@2023-07-01' existing = { + name: my_acr_outputs_name +} + +resource my_acr_AcrPush 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(my_acr.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '8311e382-0749-4cb8-b61a-304f252e45ec')) + properties: { + principalId: principalId + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '8311e382-0749-4cb8-b61a-304f252e45ec') + principalType: 'ServicePrincipal' + } + scope: my_acr +} \ No newline at end of file diff --git a/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/api.module.bicep b/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/api.module.bicep new file mode 100644 index 0000000000..7ca43d4278 --- /dev/null +++ b/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/api.module.bicep @@ -0,0 +1,84 @@ +@description('The location for the resource(s) to be deployed.') +param location string = resourceGroup().location + +param api_identity_outputs_id string + +param api_identity_outputs_clientid string + +param api_containerport string + +param env_outputs_azure_container_apps_environment_default_domain string + +param env_outputs_azure_container_apps_environment_id string + +param env_outputs_azure_container_registry_endpoint string + +param env_outputs_azure_container_registry_managed_identity_id string + +param api_containerimage string + +resource api 'Microsoft.App/containerApps@2024-03-01' = { + name: 'api' + location: location + properties: { + configuration: { + activeRevisionsMode: 'Single' + ingress: { + external: false + targetPort: api_containerport + transport: 'http' + } + registries: [ + { + server: env_outputs_azure_container_registry_endpoint + identity: env_outputs_azure_container_registry_managed_identity_id + } + ] + } + environmentId: env_outputs_azure_container_apps_environment_id + template: { + containers: [ + { + image: api_containerimage + name: 'api' + env: [ + { + name: 'OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EXCEPTION_LOG_ATTRIBUTES' + value: 'true' + } + { + name: 'OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EVENT_LOG_ATTRIBUTES' + value: 'true' + } + { + name: 'OTEL_DOTNET_EXPERIMENTAL_OTLP_RETRY' + value: 'in_memory' + } + { + name: 'ASPNETCORE_FORWARDEDHEADERS_ENABLED' + value: 'true' + } + { + name: 'HTTP_PORTS' + value: api_containerport + } + { + name: 'AZURE_CLIENT_ID' + value: api_identity_outputs_clientid + } + ] + } + ] + scale: { + minReplicas: 1 + } + } + } + identity: { + type: 'UserAssigned' + userAssignedIdentities: { + '${api_identity_outputs_id}': { } + '${env_outputs_azure_container_registry_managed_identity_id}': { } + } + } +} \ No newline at end of file diff --git a/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/aspire-manifest.json b/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/aspire-manifest.json new file mode 100644 index 0000000000..53644a4020 --- /dev/null +++ b/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/aspire-manifest.json @@ -0,0 +1,66 @@ +{ + "$schema": "https://json.schemastore.org/aspire-8.0.json", + "resources": { + "my-acr": { + "type": "azure.bicep.v0", + "path": "my-acr.module.bicep" + }, + "env": { + "type": "azure.bicep.v0", + "path": "env.module.bicep", + "params": { + "my_acr_outputs_name": "{my-acr.outputs.name}", + "userPrincipalId": "" + } + }, + "api": { + "type": "project.v1", + "path": "../Api/Api.csproj", + "deployment": { + "type": "azure.bicep.v0", + "path": "api.module.bicep", + "params": { + "api_identity_outputs_id": "{api-identity.outputs.id}", + "api_identity_outputs_clientid": "{api-identity.outputs.clientId}", + "api_containerport": "{api.containerPort}", + "env_outputs_azure_container_apps_environment_default_domain": "{env.outputs.AZURE_CONTAINER_APPS_ENVIRONMENT_DEFAULT_DOMAIN}", + "env_outputs_azure_container_apps_environment_id": "{env.outputs.AZURE_CONTAINER_APPS_ENVIRONMENT_ID}", + "env_outputs_azure_container_registry_endpoint": "{env.outputs.AZURE_CONTAINER_REGISTRY_ENDPOINT}", + "env_outputs_azure_container_registry_managed_identity_id": "{env.outputs.AZURE_CONTAINER_REGISTRY_MANAGED_IDENTITY_ID}", + "api_containerimage": "{api.containerImage}" + } + }, + "env": { + "OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EXCEPTION_LOG_ATTRIBUTES": "true", + "OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EVENT_LOG_ATTRIBUTES": "true", + "OTEL_DOTNET_EXPERIMENTAL_OTLP_RETRY": "in_memory", + "ASPNETCORE_FORWARDEDHEADERS_ENABLED": "true", + "HTTP_PORTS": "{api.bindings.http.targetPort}" + }, + "bindings": { + "http": { + "scheme": "http", + "protocol": "tcp", + "transport": "http" + }, + "https": { + "scheme": "https", + "protocol": "tcp", + "transport": "http" + } + } + }, + "api-identity": { + "type": "azure.bicep.v0", + "path": "api-identity.module.bicep" + }, + "api-roles-my-acr": { + "type": "azure.bicep.v0", + "path": "api-roles-my-acr.module.bicep", + "params": { + "my_acr_outputs_name": "{my-acr.outputs.name}", + "principalId": "{api-identity.outputs.principalId}" + } + } + } +} \ No newline at end of file diff --git a/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/env.module.bicep b/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/env.module.bicep new file mode 100644 index 0000000000..496963df9b --- /dev/null +++ b/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/env.module.bicep @@ -0,0 +1,97 @@ +@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 \ No newline at end of file diff --git a/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/my-acr.module.bicep b/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/my-acr.module.bicep new file mode 100644 index 0000000000..72427e348a --- /dev/null +++ b/docs/azure/snippets/acr/AspireAcr.AppHost/AspireAcr.AppHost/my-acr.module.bicep @@ -0,0 +1,17 @@ +@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 \ No newline at end of file diff --git a/docs/toc.yml b/docs/toc.yml index 00f18a9103..8f950b4999 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -170,6 +170,9 @@ items: href: caching/azure-cache-for-redis-distributed-caching-integration.md - name: Azure Cache for Redis output caching href: caching/azure-cache-for-redis-output-caching-integration.md + - name: Azure Container Registry (Preview) + displayName: container registry,acr + href: azure/container-registry-integration.md - name: Azure Cosmos DB displayName: cosmos db,database href: database/azure-cosmos-db-integration.md