Customize .NET Aspire Azure deployments

2025-06-26

The Azure Developer CLI (azd) provides a powerful feature called infrastructure generation that allows you to generate and customize the underlying infrastructure code for your .NET Aspire applications. This capability is essential for production scenarios where you need fine-grained control over Azure resources, security configurations, and deployment patterns.

This article covers how to use azd infra gen to:

Generate Bicep infrastructure files from your .NET Aspire app model.
Customize generated infrastructure for production requirements.
Apply security best practices to generated resources.
Manage infrastructure as code with proper version control.

Prerequisites

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

.NET 8.0 or .NET 9.0.
- Starting with .NET 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 .NET Aspire plugin (Optional)

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

You will also need to have the Azure Developer CLI installed locally.

How infrastructure generation works

Infrastructure generation in azd transforms your .NET Aspire app model into concrete Azure infrastructure definitions using Bicep templates. This process bridges the gap between the development-time orchestration in .NET Aspire and the production infrastructure required in Azure.

When you run azd infra gen, the CLI:

Analyzes your .NET Aspire AppHost project.
Identifies all resources and their dependencies.
Generates corresponding Azure resource definitions in Bicep.
Creates supporting configuration files for deployment.

Use infrastructure generation

Call the generate infrastructure command on your .NET Aspire solution:

azd infra gen

This command creates an infra folder in your AppHost project directory with the following structure:

└───📂 infra
     ├─── abbreviations.json   # Azure resource naming conventions  
     ├─── main.bicep           # Main infrastructure entry point
     ├─── main.parameters.json # Parameter values for deployment
     └─── resources.bicep      # Resource definitions

Production considerations

The generated infrastructure provides a solid foundation for your deployment, but production environments require additional configuration for security, scalability, and maintainability. This section covers the key areas you should customize when preparing for production deployment.

Security configurations

When preparing for production deployments, review and enhance the generated infrastructure with appropriate security controls:

Network isolation:

// Example: Configure Container Apps Environment with network restrictions
resource containerAppsEnvironment 'Microsoft.App/managedEnvironments@2023-05-01' = {
  name: environmentName
  location: location
  properties: {
    vnetConfiguration: {
      infrastructureSubnetId: subnetId
      internal: true
    }
    workloadProfiles: [
      {
        name: 'Consumption'
        workloadProfileType: 'Consumption'
      }
    ]
  }
}

Identity and access management:

// Example: Configure managed identity with least privilege access
resource managedIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = {
  name: identityName
  location: location
}

// Assign specific roles rather than broad permissions
resource acrPullRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  scope: containerRegistry
  name: guid(containerRegistry.id, managedIdentity.id, 'AcrPull')
  properties: {
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '7f951dda-4ed3-4680-a7ca-43fe172d538d') // AcrPull
    principalId: managedIdentity.properties.principalId
    principalType: 'ServicePrincipal'
  }
}

Resource sizing and scaling

Review generated resource configurations for production requirements:

// Example: Configure appropriate resource limits
resource containerApp 'Microsoft.App/containerApps@2023-05-01' = {
  name: appName
  location: location
  properties: {
    configuration: {
      ingress: {
        external: true
        targetPort: 8080
        allowInsecure: false // Ensure HTTPS only
      }
    }
    template: {
      containers: [
        {
          name: containerName
          image: image
          resources: {
            cpu: json('1.0')      // Adjust based on load requirements
            memory: '2.0Gi'       // Adjust based on memory needs
          }
        }
      ]
      scale: {
        minReplicas: 2          // Ensure availability
        maxReplicas: 10         // Control costs
        rules: [
          {
            name: 'http-requests'
            http: {
              metadata: {
                concurrentRequests: '100'
              }
            }
          }
        ]
      }
    }
  }
}

Environment-specific configurations

Use parameters to manage environment-specific settings:

@description('Environment name (dev, staging, prod)')
param environmentType string = 'dev'

@description('Application tier configuration')
var tierConfigurations = {
  dev: {
    skuName: 'Consumption'
    replicas: 1
  }
  staging: {
    skuName: 'Dedicated'
    replicas: 2
  }
  prod: {
    skuName: 'Dedicated'
    replicas: 3
  }
}

var currentTier = tierConfigurations[environmentType]

Iterative customization workflow

After generating initial infrastructure, establish a workflow for ongoing customization:

Make infrastructure changes to the generated Bicep files.
Test deployments in development environments.
Version control your infrastructure changes.
Document customizations for team collaboration.

Important

Running azd infra gen again will regenerate files and may overwrite your customizations. Always version control your changes and be prepared to re-apply customizations after regeneration.

Advanced customization patterns

Custom resource definitions

Extend generated infrastructure with additional Azure resources:

// Add Application Insights for monitoring
resource applicationInsights 'Microsoft.Insights/components@2020-02-02' = {
  name: '${resourceBaseName}-ai'
  location: location
  kind: 'web'
  properties: {
    Application_Type: 'web'
    Flow_Type: 'Redfield'
    Request_Source: 'IbizaWebAppExtensionCreate'
    WorkspaceResourceId: logAnalyticsWorkspace.id
  }
}

// Configure container apps to use Application Insights
resource containerApp 'Microsoft.App/containerApps@2023-05-01' = {
  // ... other properties
  properties: {
    template: {
      containers: [
        {
          // ... other container properties
          env: [
            {
              name: 'APPLICATIONINSIGHTS_CONNECTION_STRING'
              value: applicationInsights.properties.ConnectionString
            }
          ]
        }
      ]
    }
  }
}

Infrastructure validation

Add validation rules to ensure proper resource configuration:

@description('Validates that environment type is supported')
@allowed(['dev', 'staging', 'prod'])
param environmentType string

@description('Validates location is in allowed regions')
@allowed(['eastus', 'westus2', 'northeurope'])
param location string

Best practices

Version control: Always commit generated infrastructure files to source control.
Environment separation: Use separate resource groups and naming conventions for different environments.
Security scanning: Implement automated security scanning of Bicep templates.
Cost monitoring: Set up budget alerts and resource tags for cost tracking.
Documentation: Maintain documentation of customizations and their rationale.