Deploy using the Aspire CLI

When you deploy Aspire applications to Azure Container Apps using the aspire deploy command, the platform provides several deployment options and configurations. This guide explains how to use the Aspire CLI to deploy your applications to Azure Container Apps. For general information about deploying Aspire applications, see Aspire deployment overview.

Prerequisites

• Aspire common prerequisites
• The Aspire CLI installed
• An Azure subscription: Create one for free
• Install the Azure CLI

Authenticate with Azure

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

Authenticate with Azure CLI

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

If you don’t already have an Aspire project, create one using the Aspire CLI:

1. Open a terminal or command prompt.

2. Run the following commands to create a new Aspire project:

   Create new Aspire project

   aspire new aspire-starter --name AspireApp

3. Navigate to the project directory:

   Navigate to project directory

   cd AspireApp

For more details on creating projects, see Build your first Aspire project.

Configure for Azure Container Apps

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

Aspire CLI

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

aspire add azure-appcontainers

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

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

Select an integration to add:

> azure-appcontainers (Aspire.Hosting.Azure.AppContainers)
> Other results listed as selectable options...

Заувага

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

apphost.cs (C# file-based app)

C# — AppHost.cs

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

PackageReference (*.csproj)

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

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

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

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

var apiService = builder.AddProject<Projects.AspireDeploy_ApiService>("apiservice")
    .WithHttpHealthCheck("/health");

builder.AddProject<Projects.AspireDeploy_Web>("webfrontend")
    .WithExternalHttpEndpoints()
    .WithHttpHealthCheck("/health")
    .WithReference(apiService)
    .WaitFor(apiService);

builder.Build().Run();

For more information, see Configure Azure Container Apps environments.

Resource naming

Azure Container Apps have specific naming requirements that Aspire handles automatically during deployment. Resource names must be lowercase, alphanumeric, and between 2-32 characters. When you define resources in your AppHost, Aspire generates valid Azure resource names based on your provided names.

Deploy with aspire deploy

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

Deploy to Azure Container Apps

aspire deploy

Порада

The aspire deploy command is interactive by default. To deploy without prompts, set these environment variables first:

• Azure__SubscriptionId: Target Azure subscription ID.
• Azure__Location: Azure region (for example, eastus).
• Azure__ResourceGroup: Resource group name to create or reuse.

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.

Interactive prompts

The deployment process prompts you interactively to select your Azure tenant, subscription, and resource group. Use the Up Arrow ↑ Up Arrow ↑ Up Arrow ↑ and Down Arrow ↓ Down Arrow ↓ Down Arrow ↓ keys to navigate the options, or press the corresponding number key ( 1 1 1 1 1 1 , 2 2 2 2 2 2 , etc.) to jump directly to an option. Press Return Return Enter Enter Enter Enter to confirm your selection.

Tenant and subscription selection

(validate-azure-login) ✓ Azure CLI authentication validated successfully
(fetch-tenant) → Fetching available tenants
(fetch-tenant) ✓ Found 3 available tenant(s)
Select your Azure tenant:
Tenant ID:  Default Directory (yourname.onmicrosoft.com) — xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
(fetch-subscription) → Fetching available subscriptions
(fetch-subscription) ✓ Found 1 available subscription(s)
Select your Azure subscription:
Subscription ID:  Visual Studio Enterprise (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
(fetch-resource-groups) → Fetching resource groups
(fetch-resource-groups) ✓ Found 2 resource group(s)
Select your Azure resource group or enter a new name:
Resource group:  my-resource-group

For more information about the interactive prompts, see Interaction service.

Build and provision

After selections are made, Aspire builds container images and provisions Azure infrastructure in parallel:

Building and provisioning

(build-apiservice) → Starting build-apiservice...
(build-webfrontend) → Starting build-webfrontend...
(build-apiservice) i [INF] Building container image for resource apiservice
(build-webfrontend) i [INF] Building container image for resource webfrontend
(build-webfrontend) i [INF] Building image for webfrontend completed
(build-webfrontend) ✓ build-webfrontend completed successfully
(build-apiservice) i [INF] Building image for apiservice completed
(build-apiservice) ✓ build-apiservice completed successfully
(provision-aspire-env-acr) → Deploying aspire-env-acr
(provision-aspire-env-acr) ✓ Successfully provisioned aspire-env-acr (15.2s)
(provision-aspire-env) → Deploying aspire-env

Push to Container Registry

Once images are built and the Azure Container Registry is provisioned, the CLI authenticates and pushes your images:

Pushing images

(login-to-acr-aspire-env-acr) → Logging in to aspireenvacrabcd1234xyz
(login-to-acr-aspire-env-acr) ✓ Successfully logged in to aspireenvacrabcd1234xyz.azurecr.io (4.6s)
(push-webfrontend) → Pushing webfrontend to aspireenvacrabcd1234xyz
(push-apiservice) → Pushing apiservice to aspireenvacrabcd1234xyz
(push-webfrontend) ✓ Successfully pushed webfrontend to aspireenvacrabcd1234xyz.azurecr.io/webfrontend:aspire-deploy-20260128154830 (78.5s)
(push-apiservice) ✓ Successfully pushed apiservice to aspireenvacrabcd1234xyz.azurecr.io/apiservice:aspire-deploy-20260128154830 (79.7s)

Deployment complete

Upon successful deployment, you’ll see a summary of all steps completed:

Pipeline success

------------------------------------------------------------
✓ 24/24 steps succeeded • Total time: 4m 31s

Steps Summary:
      4m 31s  ✓ pipeline-execution
      3m 24s  ✓ provision-aspire-env
      1m 20s  ✓ push-apiservice
      1m 19s  ✓ push-webfrontend
      27.14s  ✓ create-provisioning-context
      22.62s  ✓ provision-webfrontend-containerapp
      22.29s  ✓ provision-apiservice-containerapp
      15.18s  ✓ provision-aspire-env-acr
      13.18s  ✓ build-apiservice
      13.18s  ✓ build-webfrontend
       4.60s  ✓ login-to-acr-aspire-env-acr
       3.08s  ✓ fetch-tenant
       2.01s  ✓ validate-azure-login
       1.47s  ✓ fetch-resource-groups
       1.08s  ✓ fetch-subscription
      ...

✓ PIPELINE SUCCEEDED
------------------------------------------------------------

Заувага

This is example output; actual resource names and deployment times will vary based on your environment.

For more information, 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 tips for troubleshooting, helping you quickly identify and fix errors.

Authentication issues

If you encounter authentication errors:

Authentication error

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

Unique environment name

// Change the environment name to a unique value
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:

   Bash

   Get application endpoint

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

   PowerShell

   Get application endpoint

   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:

Delete resource group

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

Небезпечно

This command deletes all resources in the resource group, including any resources not created by the Aspire CLI.

• Aspire deployment overview
• Configure Azure Container Apps environments
• aspire deploy command reference