Configure Azure Container Apps environments

The Aspire AppHost simplifies infrastructure provisioning by generating code to create Azure resources for your applications. This approach lets you model and configure deployment-related aspects directly in your AppHost, reducing the need to rely on tools like Bicep. These aspects include configuring ACA environments, which provide a serverless platform for running containerized applications.

Using the Aspire.Hosting.Azure.AppContainers integration, you can deploy compute resources to Azure Container Apps by adding an ACA environment with AddAzureContainerAppEnvironment. Use PublishAsAzureContainerApp only when you want to customize the generated Container App resource for a project, container, or executable — it does not create the ACA environment. Add an ACA environment first, then use the callback to customize the generated Container App resource.

By using the Azure.Provisioning APIs (explained in Customize Azure resources), you can configure and customize ACA environments along with related resources, such as container registries and file share volumes. Any available deployment setting can be configured. For more information on the available settings, see Microsoft.App managedEnvironments.

Note

When deployed resources use volumes or bind mounts, Aspire provisions Azure Storage file shares and managed environment storage entries for the ACA environment. Both mount types are translated to Azure Files-backed mounts during deployment, so local host bind-mount semantics don’t carry over to Azure Container Apps.

Note

When Aspire configures a managed identity for a resource deployed to Azure Container Apps, it automatically sets the AZURE_TOKEN_CREDENTIALS environment variable to ManagedIdentityCredential. This ensures that DefaultAzureCredential uses only ManagedIdentityCredential for authentication, following Azure SDK best practices. If you need to use a different credential type, remove this environment variable by customizing the generated Container App with PublishAsAzureContainerApp. For more information, see DefaultAzureCredential behavior in Azure deployments.

Add an ACA environment

The AzureContainerAppEnvironmentResource type models an ACA environment resource. When you call the AddAzureContainerAppEnvironment method, it creates an instance of this type (wrapped in the IResourceBuilder<AzureContainerAppEnvironmentResource>).

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var acaEnv = builder.AddAzureContainerAppEnvironment("aca-env");

// Omitted for brevity...

builder.Build().Run();

TypeScript

TypeScript — apphost.ts

import { createBuilder } from './.modules/aspire.js';

const builder = await createBuilder();

const acaEnv = await builder.addAzureContainerAppEnvironment("aca-env");

// Omitted for brevity...

By default, calling this API to add an ACA environment generates the following provisioning Bicep module:

aca-env.module.bicep

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param userPrincipalId string

param tags object = { }

resource aca_env_mi 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = {
  name: take('aca_env_mi-${uniqueString(resourceGroup().id)}', 128)
  location: location
  tags: tags
}

resource aca_env_acr 'Microsoft.ContainerRegistry/registries@2023-07-01' = {
  name: take('acaenvacr${uniqueString(resourceGroup().id)}', 50)
  location: location
  sku: {
    name: 'Basic'
  }
  tags: tags
}

resource aca_env_acr_aca_env_mi_AcrPull 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(aca_env_acr.id, aca_env_mi.id, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '7f951dda-4ed3-4680-a7ca-43fe172d538d'))
  properties: {
    principalId: aca_env_mi.properties.principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '7f951dda-4ed3-4680-a7ca-43fe172d538d')
    principalType: 'ServicePrincipal'
  }
  scope: aca_env_acr
}

resource aca_env_law 'Microsoft.OperationalInsights/workspaces@2023-09-01' = {
  name: take('acaenvlaw-${uniqueString(resourceGroup().id)}', 63)
  location: location
  properties: {
    sku: {
      name: 'PerGB2018'
    }
  }
  tags: tags
}

resource aca_env 'Microsoft.App/managedEnvironments@2024-03-01' = {
  name: take('acaenv${uniqueString(resourceGroup().id)}', 24)
  location: location
  properties: {
    appLogsConfiguration: {
      destination: 'log-analytics'
      logAnalyticsConfiguration: {
        customerId: aca_env_law.properties.customerId
        sharedKey: aca_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: aca_env
}

resource aca_env_Contributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(aca_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: aca_env
}

output MANAGED_IDENTITY_NAME string = aca_env_mi.name

output MANAGED_IDENTITY_PRINCIPAL_ID string = aca_env_mi.properties.principalId

output AZURE_LOG_ANALYTICS_WORKSPACE_NAME string = aca_env_law.name

output AZURE_LOG_ANALYTICS_WORKSPACE_ID string = aca_env_law.id

output AZURE_CONTAINER_REGISTRY_NAME string = aca_env_acr.name

output AZURE_CONTAINER_REGISTRY_ENDPOINT string = aca_env_acr.properties.loginServer

output AZURE_CONTAINER_REGISTRY_MANAGED_IDENTITY_ID string = aca_env_mi.id

output AZURE_CONTAINER_APPS_ENVIRONMENT_NAME string = aca_env.name

output AZURE_CONTAINER_APPS_ENVIRONMENT_ID string = aca_env.id

output AZURE_CONTAINER_APPS_ENVIRONMENT_DEFAULT_DOMAIN string = aca_env.properties.defaultDomain

This module configures:

• A user-assigned managed identity for the ACA environment.
• An Azure Container Registry (ACR) for the ACA environment.
• A Log Analytics workspace for the ACA environment.
• An Azure Container Apps environment.
• The Aspire dashboard for the ACA environment.
• A role assignment for the user principal ID to the ACA environment.
• Various outputs for the ACA environment.

Using the acaEnv variable, you can chain a call to the ConfigureInfrastructure API to customize the ACA environment to your liking. For more information, see Configure infrastructure.

Use PublishAsAzureContainerApp

The following PublishAsAzureContainerApp overloads let you customize the generated Container App resource for a project, container, or executable:

• AzureContainerAppProjectExtensions.PublishAsAzureContainerApp
• AzureContainerAppContainerExtensions.PublishAsAzureContainerApp
• AzureContainerAppExecutableExtensions.PublishAsAzureContainerApp

The callback receives an AzureResourceInfrastructure instance and the strongly-typed ContainerApp resource. This lets you set any property that Azure Container Apps supports — such as scaling rules, ingress settings, or environment variables — before the Bicep is generated.

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

builder.AddAzureContainerAppEnvironment("aca-env");

builder.AddProject<Projects.ApiService>("api")
    .PublishAsAzureContainerApp((infrastructure, containerApp) =>
    {
        containerApp.Template.Value!.Scale = new ContainerAppScale
        {
            MinReplicas = 1,
            MaxReplicas = 10
        };
    });

builder.Build().Run();

TypeScript

Note

The PublishAsAzureContainerApp callback receives strongly-typed Azure SDK types from the Azure.Provisioning.AppContainers package — such as ContainerApp, ContainerAppScale, and ContainerAppIngressConfiguration — which are C#-specific and have no TypeScript equivalents. To customize a deployed Container App from a TypeScript AppHost, use configureInfrastructure with a raw Bicep override, or apply the customizations via the Azure portal or a separate Bicep/ARM template.

Handle naming conventions

By default, AddAzureContainerAppEnvironment uses a different Azure resource naming scheme than the Azure Developer CLI (azd). If you’re upgrading an existing deployment that previously used azd, you might see duplicate Azure resources. To avoid this issue, call the WithAzdResourceNaming method to revert to the naming convention used by azd:

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var acaEnv = builder.AddAzureContainerAppEnvironment("aca-env")
    .WithAzdResourceNaming();

// Omitted for brevity...

builder.Build().Run();

TypeScript

TypeScript — apphost.ts

import { createBuilder } from './.modules/aspire.js';

const builder = await createBuilder();

const acaEnv = await builder.addAzureContainerAppEnvironment("aca-env");
await acaEnv.withAzdResourceNaming();

// Omitted for brevity...

Calling this API ensures your existing Azure resources remain consistent and prevents duplication.

Customize provisioning infrastructure

All Azure resources are subclasses of the AzureProvisioningResource type. This enables customization of the generated Bicep by providing a fluent API to configure the Azure resources — using the ConfigureInfrastructure API:

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var acaEnv = builder.AddAzureContainerAppEnvironment("aca-env");

acaEnv.ConfigureInfrastructure(infra =>
{
    var resources = infra.GetProvisionableResources();
    var containerEnvironment = resources.OfType<ContainerAppManagedEnvironment>().FirstOrDefault();

    containerEnvironment.Tags.Add("ExampleKey", "Example value");
});

builder.Build().Run();

TypeScript

Note

ConfigureInfrastructure uses strongly-typed Azure SDK types from the Azure.Provisioning.AppContainers package — such as ContainerAppManagedEnvironment — which are C#-specific and have no TypeScript equivalents. Infrastructure customization of this kind is only available from a C# AppHost. For more information, see Customize Azure resources.

The preceding C# code:

• Chains a call to the ConfigureInfrastructure API:
  • The infra parameter is an instance of the AzureResourceInfrastructure type.
  • The provisionable resources are retrieved by calling the GetProvisionableResources method.
  • The single ContainerAppManagedEnvironment resource is retrieved.
  • A tag is added to the Azure Container Apps environment resource with a key of ExampleKey and a value of Example value.

See also

• Azure integrations overview
• Deploy to Azure Container Apps
• Customize Azure resources
• Azure Container Apps documentation
• Container Apps pricing