Skip to main content

Azure Deployment Guide for .NET Aspire

This comprehensive guide covers deploying your .NET Aspire application to Azure Container Apps using the Azure Developer CLI (azd).

Table of contents​

  1. Prerequisites
  2. Initial setup
  3. Environment configuration
  4. Development deployment
  5. Production deployment
  6. CI/CD pipeline setup
  7. Monitoring and troubleshooting
  8. Security best practices
  9. Cost optimization
  10. Maintenance and updates

Prerequisites​

Required software​

  1. .NET 9.0 SDK (already installed)

    dotnet --version  # Should show 9.0.x

  2. Azure Developer CLI (azd)

    # macOS (using Homebrew)
    brew tap azure/azd && brew install azd

    # Verify installation
    azd version

  3. Docker Desktop

  4. Azure CLI (optional but recommended)

    # macOS
    brew install azure-cli

    # Verify installation
    az --version

Azure account requirements​

  • Azure Subscription with appropriate permissions
  • Owner or Contributor role on the subscription
  • User Access Administrator role (for managed identity assignments)

Initial setup​

1. Authenticate with Azure​

# Login to Azure
azd auth login

# Verify authentication
azd auth show

2. Verify project structure​

Your project should already have the required azure.yaml file:

name: mind-or-machine
services:  
  app:
    language: dotnet
    project: ./MindOrMachine.AppHost/MindOrMachine.AppHost.csproj
    host: containerapp

Environment configuration​

1. Create development environment​

# Create a development environment
azd env new dev

# This will prompt for:
# - Environment name: dev
# - Azure subscription selection
# - Azure region selection (recommend: East US 2 or West US 2)

2. Create production environment​

# Create a production environment
azd env new prod --subscription "Your Production Subscription" --location eastus2

3. List and switch environments​

# List all environments
azd env list

# Switch to specific environment
azd env select dev

4. Configure environment variables​

# Set environment-specific variables
azd env set ENVIRONMENT_NAME dev
azd env set ASPNETCORE_ENVIRONMENT Production  # For prod environment

# For production, set additional variables
azd env select prod
azd env set ENVIRONMENT_NAME prod
azd env set ASPNETCORE_ENVIRONMENT Production
azd env set GAME_MAX_PLAYERS 100
azd env set GAME_DEFAULT_TIME_PER_QUESTION 20

Development deployment​

1. Quick deployment (all-in-one)​

# Switch to development environment
azd env select dev

# Deploy everything with a single command
azd up

# This will:
# 1. Package your application into containers
# 2. Provision Azure resources (Resource Group, Container Registry, Container Apps Environment, etc.)
# 3. Deploy your application to Azure Container Apps

2. Step-by-step deployment​

# Step 1: Package the application
azd package

# Step 2: Provision Azure infrastructure
azd provision

# Step 3: Deploy the application
azd deploy

3. Deploy application updates only​

# When you make code changes, deploy only the updated services
azd deploy

# Deploy specific service only
azd deploy app

4. Update infrastructure only​

# When you change the AppHost configuration or add new services
azd provision

Production deployment​

1. Generate infrastructure files​

For production deployments, it's recommended to generate and review the infrastructure files:

# Enable infrastructure generation
azd config set alpha.infraSynth on

# Generate Bicep files for review
azd infra gen

This creates:

  • infra/main.bicep - Main deployment template
  • infra/main.parameters.json - Parameters file
  • infra/resources.bicep - Shared resources
  • Service-specific manifests/containerApp.tmpl.yaml files

2. Review generated infrastructure​

Examine the generated files in the infra/ directory:

# Review the main Bicep file
cat infra/main.bicep

# Review parameters
cat infra/main.parameters.json

# Review shared resources
cat infra/resources.bicep

3. Production environment setup​

# Switch to production environment
azd env select prod

# Set production-specific environment variables
azd env set AZURE_ENV_NAME prod
azd env set ASPNETCORE_ENVIRONMENT Production
azd env set GAME_EXPIRY_HOURS 24
azd env set JWT_ACCESS_TOKEN_EXPIRY_MINUTES 60

# Deploy to production
azd up

4. Production configuration best practices​

Create a production configuration checklist:

Resource configuration​

  • Container Apps Environment: Use dedicated environment for production
  • Azure Container Registry: Enable admin user for container image pulls
  • Cosmos DB: Configure for production workloads with appropriate RU/s
  • Application Insights: Enable for monitoring and diagnostics
  • Key Vault: Store sensitive configuration

Security configuration​

warning

The examples below show setting sensitive values directly. In production, use Azure Key Vault to store secrets and reference them in your application instead of setting them as environment variables.

# Set security-related environment variables (use Key Vault for production - see Security Best Practices section)
azd env set JWT_KEY "your-production-jwt-key-256-bits"
azd env set COSMOS_KEY "retrieved-from-azure-portal"
azd env set CORS_ALLOWED_ORIGINS "https://yourdomain.com"

CI/CD pipeline setup​

1. GitHub Actions pipeline​

# Configure GitHub Actions pipeline
azd pipeline config

# Select GitHub when prompted
# Follow the prompts to:
# 1. Authenticate with GitHub
# 2. Select repository
# 3. Configure environments (dev, prod)

This creates .github/workflows/azure-dev.yml with:

  • Automated deployment on push to main
  • Environment-specific deployments
  • Security best practices

2. Azure DevOps pipeline​

# Configure Azure DevOps pipeline
azd pipeline config

# Select Azure DevOps when prompted
# Follow the prompts to configure the pipeline

3. Pipeline configuration best practices​

Environment-specific deployments​

  • Development: Deploy on every push to develop branch
  • Production: Deploy only on push to main branch with manual approval

Security configuration​

  • Store secrets in GitHub Secrets or Azure Key Vault
  • Use managed identities for Azure resource access
  • Enable branch protection rules

Monitoring and troubleshooting​

1. View deployment status​

# Show current deployment information
azd show

# Monitor deployment progress
azd monitor

2. Access application logs​

# Stream logs from Container Apps
azd monitor --logs

# Open Application Insights in browser
azd monitor --overview

3. Common troubleshooting steps​

Container start failures​

  1. Check container logs in Azure Portal
  2. Verify environment variables are set correctly
  3. Ensure container registry authentication is working

Connection issues​

  1. Verify service discovery configuration
  2. Check if all required ports are exposed
  3. Validate network configuration

Database connection issues​

  1. Verify Cosmos DB connection strings
  2. Check if managed identity has proper permissions
  3. Validate container app can reach Cosmos DB endpoint

4. Debug commands​

# Get detailed environment information
azd env get-values

# Refresh environment from Azure
azd env refresh

# View resource group in Azure Portal
azd show  # Click the portal link

Security best practices​

1. Network security​

Container Apps environment​

  • Use internal ingress for internal services
  • Configure custom domains with SSL certificates
  • Implement proper CORS policies

Network isolation​

# Configure virtual network integration (if needed)
# This requires custom Bicep configuration

2. Identity and access management​

Managed identity configuration​

  • System-assigned managed identities are enabled by default
  • Configure Key Vault access for sensitive configuration
  • Use managed identity for Cosmos DB access

Authentication configuration​

# Set JWT configuration for production
azd env set JWT_ISSUER "https://api.yourdomain.com"
azd env set JWT_AUDIENCE "mindormachine-api"
azd env set JWT_ACCESS_TOKEN_EXPIRY_MINUTES 60

3. Data protection​

Secrets management​

For production deployments, store sensitive configuration in Azure Key Vault:

  1. Create a Key Vault in your Azure subscription
  2. Add secrets to Key Vault (JWT keys, connection strings, API keys)
  3. Grant access to your Container App's managed identity
  4. Reference secrets in your application using Azure Key Vault configuration provider
# Configure Key Vault name in environment
azd env set KEYVAULT_NAME "your-keyvault-name"

# Example: Referencing Key Vault secrets in appsettings.json
# "KeyVaultName": "your-keyvault-name"
# Then access via configuration: Configuration["KeyVaultName"]

In your .NET application, install the Azure.Extensions.AspNetCore.Configuration.Secrets package and configure it to read from Key Vault.

Data encryption​

  • Cosmos DB encryption at rest (enabled by default)
  • SSL/TLS for data in transit (enabled by default)

Cost optimization​

1. Environment management​

# Scale down development environment when not in use
azd env select dev
azd down  # Tears down all resources

# Recreate when needed
azd up

2. Resource optimization​

Container Apps scaling​

  • Configure appropriate min/max replicas
  • Use consumption-based scaling rules
  • Monitor resource usage and adjust accordingly

Cosmos DB optimization​

  • Use autoscale for variable workloads
  • Monitor Request Units (RU/s) consumption
  • Implement efficient querying patterns

3. Cost monitoring​

# Monitor costs in Azure Portal
# Set up cost alerts and budgets
# Review cost analysis regularly

Maintenance and updates​

1. Application updates​

# Deploy code changes
azd deploy

# Deploy infrastructure changes
azd provision

# Full deployment (code + infrastructure)
azd up

2. Environment maintenance​

# Update environment variables
azd env set NEW_SETTING "value"

# Refresh environment from Azure
azd env refresh

# Clean up resources
azd down --force  # Use with caution

3. Backup and recovery​

Cosmos DB backup​

  • Automatic backups are enabled by default
  • Configure point-in-time restore if needed
  • Test recovery procedures regularly

Application configuration backup​

  • Export environment variables: azd env get-values --output json > backup.json
  • Store infrastructure files in source control
  • Document manual configuration steps

Additional resources​

Official documentation​

Useful commands reference​

# Environment Management
azd env new <name>                    # Create new environment
azd env select <name>                 # Switch environment
azd env list                          # List environments
azd env set <key> <value>            # Set environment variable
azd env get-values                    # Show all variables

# Deployment Commands
azd up                               # Full deployment
azd provision                        # Infrastructure only
azd deploy                           # Application only
azd package                          # Package application

# Monitoring and Troubleshooting
azd show                             # Show deployment info
azd monitor                          # Open monitoring dashboard
azd monitor --logs                   # Stream application logs

# Infrastructure Management
azd infra gen                        # Generate Bicep files
azd down                             # Delete all resources
azd down --force                     # Delete without confirmation

# Pipeline Configuration
azd pipeline config                  # Set up CI/CD pipeline

Environment variables reference​

# Core Azure Variables (set automatically)
AZURE_ENV_NAME                      # Environment name
AZURE_LOCATION                      # Azure region
AZURE_SUBSCRIPTION_ID               # Subscription ID

# Application-Specific Variables
ASPNETCORE_ENVIRONMENT              # ASP.NET Core environment
GAME_MAX_PLAYERS                    # Maximum players per game
GAME_DEFAULT_TIME_PER_QUESTION      # Default question time
GAME_EXPIRY_HOURS                   # Game session expiry
JWT_KEY                             # JWT signing key
JWT_ISSUER                          # JWT token issuer
JWT_ACCESS_TOKEN_EXPIRY_MINUTES     # JWT token expiry

Quick start checklist​

For first-time deployment:

  • Install prerequisites (azd, Docker Desktop)
  • Run azd auth login
  • Run azd env new dev
  • Run azd up
  • Verify deployment in Azure Portal
  • Test application endpoints
  • Set up production environment
  • Configure CI/CD pipeline
  • Implement monitoring and alerts

This guide provides everything you need to successfully deploy your Aspire application to Azure. Follow the steps sequentially for your first deployment, then use the specific sections for ongoing maintenance and updates.