Optimize ACA deployment docs workflow and content structure

docs/deployment/azure/aca-deployment-azd-in-depth.md

@@ -202,6 +202,8 @@ The previous command may take some time to execute, but when completed the resou
 
 Although development teams are free to use `azd up` (or `azd provision` and `azd deploy`) commands for their deployments both for development and production purposes, some teams may choose to generate Bicep files that they can review and manage as part of version control (this also allows these Bicep files to be referenced as part of a larger more complex Azure deployment).
 
+For comprehensive guidance on customizing generated infrastructure for production scenarios, see [Customize deployments with infrastructure synthesis](customize-deployments.md).
+
 `azd` includes the ability to output the Bicep it uses for provisioning via following command:
 
 ```azdeveloper

docs/deployment/azure/aca-deployment-visual-studio.md

@@ -1,6 +1,6 @@
 ---
 title: Deploy .NET Aspire projects to Azure Container Apps using Visual Studio
-description: Learn how to use Bicep, the Azure CLI, and Azure Developer CLI to deploy .NET Aspire projects to Azure using Visual Studio.
+description: Learn how to deploy .NET Aspire projects to Azure Container Apps using Visual Studio.
 ms.date: 06/14/2024
 ---
 

docs/deployment/azure/aca-deployment.md

@@ -23,7 +23,7 @@ As an alternative to this tutorial and for a more in-depth guide, see [Deploy a
 
 ## Deploy .NET Aspire projects with `azd`
 
-With .NET Aspire and Azure Container Apps (ACA), you have a great hosting scenario for building out your cloud-native apps with .NET. We built some great new features into the Azure Developer CLI (`azd`) specific for making .NET Aspire development and deployment to Azure a friction-free experience. You can still use the Azure CLI and/or Bicep options when you need a granular level of control over your deployments. But for new projects, you won't find an easier path to success for getting a new microservice topology deployed into the cloud.
+With .NET Aspire and Azure Container Apps (ACA), you have a great hosting scenario for building out your cloud-native apps with .NET. We built some great new features into the Azure Developer CLI (`azd`) specific for making .NET Aspire development and deployment to Azure a friction-free experience. For production scenarios that require granular control over infrastructure, see [Customize deployments with infrastructure synthesis](customize-deployments.md). But for new projects, you won't find an easier path to success for getting a new microservice topology deployed into the cloud.
 
 ## Create a .NET Aspire project
 

docs/deployment/azure/customize-deployments.md

@@ -0,0 +1,262 @@
+---
+title: Customize .NET Aspire deployments with infrastructure synthesis
+description: Learn how to customize Azure deployments using azd infra synth for production scenarios.
+ms.date: 01/08/2025
+ms.custom: devx-track-extended-azdevcli
+---
+
+# Customize .NET Aspire deployments with infrastructure synthesis
+
+The Azure Developer CLI (`azd`) provides a powerful feature called infrastructure synthesis 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 synth` to:
+
+> [!div class="checklist"]
+>
+> - 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
+
+[!INCLUDE [aspire-prereqs](../../includes/aspire-prereqs.md)]
+
+You will also need to have the Azure Developer CLI [installed locally](/azure/developer/azure-developer-cli/install-azd).
+
+## How infrastructure synthesis works
+
+Infrastructure synthesis 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 synth`, the CLI:
+
+1. Analyzes your .NET Aspire app host project
+2. Identifies all resources and their dependencies
+3. Generates corresponding Azure resource definitions in Bicep
+4. Creates supporting configuration files for deployment
+
+## Enable and use infrastructure synthesis
+
+Infrastructure synthesis is currently an alpha feature that must be explicitly enabled:
+
+```azdeveloper
+azd config set alpha.infraSynth on
+```
+
+Once enabled, generate infrastructure files for your .NET Aspire project:
+
+```azdeveloper
+azd infra synth
+```
+
+This command creates an `infra` folder in your app host project directory with the following structure:
+
+```
+infra/
+├── main.bicep              # Main infrastructure entry point
+├── main.parameters.json    # Parameter values for deployment
+├── resources.bicep         # Resource definitions
+└── abbreviations.json      # Azure resource naming conventions
+```
+
+## Production considerations
+
+### Security configurations
+
+When preparing for production deployments, review and enhance the generated infrastructure with appropriate security controls:
+
+**Network isolation:**
+
+```bicep
+// 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:**
+
+```bicep
+// 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:
+
+```bicep
+// 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:
+
+```bicep
+@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:
+
+1. **Make infrastructure changes** to the generated Bicep files
+2. **Test deployments** in development environments
+3. **Version control** your infrastructure changes
+4. **Document customizations** for team collaboration
+
+> [!IMPORTANT]
+> Running `azd infra synth` 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:
+
+```bicep
+// 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:
+
+```bicep
+@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
+
+## Next steps
+
+- [Deploy a .NET Aspire project to Azure Container Apps using azd](aca-deployment.md)
+- [Azure Container Apps with azd (In-depth)](aca-deployment-azd-in-depth.md)
+- [Deploy using azd and CI/CD](aca-deployment-github-actions.md)