Skip to main content

Deploying to Azure

Microsoft provides first-party support for deploying Aspire applications to Azure through the Azure Developer CLI (azd). The azd CLI has been specifically enhanced to make Aspire development and deployment to Azure a friction-free experience.

Prerequisites​

Before deploying to Azure, ensure you have:

  • Azure Developer CLI (azd): Install azd
  • Azure subscription: An active Azure subscription
  • Docker: Docker Desktop or Podman for container builds
  • Azure CLI: Logged in via az login (as configured in the Azure Setup section)

Understanding Azure Container Apps​

Azure Container Apps is a fully managed environment that enables you to run microservices and containerized applications on a serverless platform. When you deploy an Aspire project to Azure, each project and containerized resource becomes an Azure Container App.

Key benefits:

  • Serverless scaling: Automatically scales based on HTTP traffic, events, or CPU/memory load
  • Microservices support: Built-in service discovery and communication
  • Integrated observability: Logs, metrics, and distributed tracing
  • Managed infrastructure: No Kubernetes cluster management required

The Deployment Process​

Step 1: Initialize Your Project​

From your AppHost project directory (or the solution root), run:

azd init

This command:

  1. Scans your directory structure to detect the Aspire AppHost project
  2. Analyzes your application to understand its structure
  3. Prompts you for an environment name (e.g., dev, staging, production)
  4. Creates an azure.yaml file and .azure directory with configuration

Example output:

Initializing an app to run on Azure (azd init)

? How do you want to initialize your app?
  > Use code in the current directory

? Select the language or framework you are working with:
  > .NET Aspire

? Select Azure location:
  > (Europe) North Europe

Step 2: Deploy to Azure​

Once initialized, deploy your entire application stack with a single command:

azd up

This command combines several operations:

  1. Provision (azd provision):

    • Starts your AppHost with a special command to generate the Aspire manifest
    • Converts the manifest to Azure Bicep infrastructure-as-code
    • Creates Azure resources:
      • Resource Group
      • Container Registry (for your container images)
      • Container Apps Environment
      • Container Apps (one per service)
      • Managed resources (Azure Cosmos DB, Azure Cache for Redis, Azure Service Bus, etc.)
      • Log Analytics workspace (for observability)

  2. Deploy (azd deploy):

    • Builds Docker images for your .NET projects
    • Pushes images to Azure Container Registry
    • Deploys container images to Azure Container Apps
    • Configures environment variables and service connections

This process takes 10-15 minutes on first deployment.

Step 3: Access Your Application​

After deployment completes, azd will display:

  • Endpoint URLs: Public URLs for your services
  • Azure Portal links: Direct links to view resources
  • Dashboard URL: If you've enabled the Aspire Dashboard
SUCCESS: Your application was deployed to Azure in 12 minutes 34 seconds.
You can view the resources created under the resource group rg-cloud-native-workshop-dev in the Azure Portal:
https://portal.azure.com/#@/resource/subscriptions/.../resourceGroups/rg-cloud-native-workshop-dev

View Aspire Dashboard: https://dashboard.xxxxx.northeurope.azurecontainerapps.io
API Endpoint: https://dometrain-api.xxxxx.northeurope.azurecontainerapps.io

Managing Your Deployment​

Updating Your Application​

After making code changes, redeploy with:

azd deploy

This skips infrastructure provisioning and only rebuilds/redeploys your code, making it much faster than azd up.

Provisioning Infrastructure Only​

To update Azure resources without deploying code:

azd provision

Monitoring and Logs​

View logs for a specific service:

azd logs --service dometrain-api

Stream logs in real-time:

azd logs --service dometrain-api --follow

Opening the Azure Portal​

Quickly open your resource group in the Azure Portal:

azd show

Cleaning Up Resources​

warning

This will permanently delete all Azure resources created for this environment.

When you're done testing, remove all Azure resources to avoid ongoing charges:

azd down

This command:

  • Deletes all Azure resources in the resource group
  • Removes the resource group itself
  • Does NOT delete your local source code or configuration

Example output:

? Total resources to delete: 15, are you sure you want to continue? (y/N) y

SUCCESS: Your application was removed from Azure in 2 minutes 15 seconds.

How azd Works with Aspire​

The Azure Developer CLI has special Aspire integration:

  1. Manifest Generation: When azd detects an Aspire AppHost, it runs the AppHost with --publisher manifest to generate the manifest.json file

  2. Bicep Translation: azd reads the manifest and generates Azure Bicep infrastructure code in-memory (not saved to disk by default)

  3. Resource Mapping: Aspire resources are mapped to Azure services:

    • .AddPostgres() → Azure Container App (PostgreSQL container) or Azure Database for PostgreSQL
    • .AddRedis() → Azure Cache for Redis (or container)
    • .AddRabbitMQ() → Azure Service Bus (or container)
    • .AddAzureCosmosDB() → Azure Cosmos DB account
    • .AddProject<T>() → Azure Container App

  4. Service Connections: References created with .WithReference() become environment variables and managed identities

Environment Configuration​

The azure.yaml file created by azd init defines your application structure. You can customize:

  • Service names
  • Azure regions
  • Resource naming
  • Environment-specific variables

Example azure.yaml:

name: cloud-native-workshop
services:
  dometrain-api:
    project: ./src/Dometrain.Monolith.Api
    language: dotnet
    host: containerapp

Best Practices​

  1. Use separate environments: Create different azd environments for dev, staging, and production:

    azd env new staging
    azd env new production

  2. Secure secrets: Use Azure Key Vault for sensitive configuration (azd automatically provisions this)

  3. Monitor costs: Check Azure Cost Management regularly, especially with Cosmos DB and Azure Cache for Redis

  4. Clean up dev resources: Run azd down when you're done with development environments

  5. Use managed identities: Aspire automatically configures managed identities for service-to-service authentication

Troubleshooting​

Build failures: Ensure Docker is running and you can build containers locally first

Deployment timeout: The first deployment takes 10-15 minutes. Be patient!

Resource quotas: Some Azure subscriptions have limits on Container Apps or Cosmos DB accounts

Authentication errors: Verify az login is using the correct subscription:

az account show
az account set --subscription <subscription-id>

Next Steps​

Once deployed, you can:

  • View your application in the Azure Portal
  • Set up CI/CD with GitHub Actions (azd supports this!)
  • Configure custom domains and SSL certificates
  • Enable autoscaling based on load
  • Set up Azure Monitor alerts

For more advanced deployment scenarios, see the Azure Developer CLI documentation.