|
| 1 | +--- |
| 2 | +title: Azure Container Apps Deployment Strategies using the Azure Developer CLI |
| 3 | +description: Learn about Azure Container Apps deployment strategies using the Azure Developer CLI. |
| 4 | +author: alexwolfmsft |
| 5 | +ms.author: alexwolf |
| 6 | +ms.date: 07/15/2025 |
| 7 | +ms.service: azure-dev-cli |
| 8 | +ms.topic: how-to |
| 9 | +ms.custom: devx-track-`azd`evcli |
| 10 | +--- |
| 11 | + |
| 12 | +# Azure Container Apps deployment strategies using the Azure Developer CLI |
| 13 | + |
| 14 | +The Azure Developer CLI (`azd`) provides multiple strategies to provision and deploy applications to [Azure Container Apps](/azure/container-apps/overview). This document outlines these strategies, including when to use them and how they work. |
| 15 | + |
| 16 | +## Container app upsert strategy |
| 17 | + |
| 18 | +The `container-app-upsert` strategy is a Bicep-based approach for creating or updating Azure Container Apps. It's a flexible option that works well for many types of container applications. |
| 19 | + |
| 20 | +### How it works |
| 21 | + |
| 22 | +The `container-app-upsert` strategy: |
| 23 | + |
| 24 | +1. Uses a Bicep module (`container-app-upsert.bicep`) that detects whether a Container App already exists. |
| 25 | +2. If the Container App exists, it updates the existing app while preserving its current container image if no new image is specified. |
| 26 | +3. If the Container App doesn't exist, it creates a new one with the specified parameters. |
| 27 | + |
| 28 | +This approach is commonly used in `azd` templates, such as the Todo application templates (nodejs-mongo-aca, python-mongo-aca, etc.). |
| 29 | + |
| 30 | +### When to use it |
| 31 | + |
| 32 | +Use the `container-app-upsert` strategy when: |
| 33 | + |
| 34 | +- You want the ability to incrementally update your Container App without replacing it entirely. |
| 35 | +- You need to preserve certain settings during updates. |
| 36 | +- You're working with standard container applications that aren't based on the .NET Aspire framework. |
| 37 | +- You want a pattern that supports composability across multiple services. |
| 38 | + |
| 39 | +### Example |
| 40 | + |
| 41 | +Here's how to use the `container-app-upsert` strategy in your Bicep files: |
| 42 | + |
| 43 | +```bicep |
| 44 | +module api 'br/public:avm/ptn/azd/container-app-upsert:0.1.2' = { |
| 45 | + name: 'api' |
| 46 | + params: { |
| 47 | + name: 'my-api' |
| 48 | + location: location |
| 49 | + containerAppsEnvironmentName: containerAppsEnvironment.name |
| 50 | + containerRegistryName: containerRegistry.name |
| 51 | + imageName: !empty(apiImageName) ? apiImageName : '' |
| 52 | + exists: apiExists |
| 53 | + env: [ |
| 54 | + { |
| 55 | + name: 'MONGODB_CONNECTION_STRING' |
| 56 | + value: mongodb.outputs.connectionString |
| 57 | + } |
| 58 | + ] |
| 59 | + targetPort: 3100 |
| 60 | + } |
| 61 | +} |
| 62 | +``` |
| 63 | + |
| 64 | +In this example: |
| 65 | + |
| 66 | +- The `exists` parameter determines whether to update an existing app or create a new one. |
| 67 | +- The `imageName` uses the `!empty()` function to conditionally specify a new image or keep the existing one. |
| 68 | +- Application settings are provided via the `env` parameter. |
| 69 | + |
| 70 | +## Delay deployment strategy with .NET Aspire |
| 71 | + |
| 72 | +The `delay-deployment` strategy is specifically designed for .NET Aspire applications. It postpones full container app creation until deployment time, allowing for more flexibility with .NET Aspire's orchestration model. |
| 73 | + |
| 74 | +### How it works |
| 75 | + |
| 76 | +The `delay-deployment` strategy: |
| 77 | + |
| 78 | +1. Delays full provisioning of container resources until deployment time. |
| 79 | +2. Uses the .NET Aspire manifest to define container apps and their configurations. |
| 80 | +3. Supports two deployment approaches based on the manifest: |
| 81 | + - Bicep-based deployment (when the manifest includes a deployment configuration). |
| 82 | + - YAML-based deployment (direct Container Apps YAML deployment). |
| 83 | +4. Handles special features like service binding and configuration sharing across Aspire components. |
| 84 | + |
| 85 | +When using .NET Aspire with `azd`, the Aspire project generates a manifest that `azd` uses during deployment. This approach allows for better integration with .NET Aspire's application model. |
| 86 | + |
| 87 | +### When to use it |
| 88 | + |
| 89 | +Use the `delay-deployment` strategy when: |
| 90 | + |
| 91 | +- Working with .NET Aspire applications. |
| 92 | +- Your application has complex service relationships defined in the Aspire manifest. |
| 93 | +- You need integration with .NET Aspire's resource binding model. |
| 94 | +- You want to leverage .NET Aspire's application hosting capabilities. |
| 95 | + |
| 96 | +### Example |
| 97 | + |
| 98 | +For .NET Aspire applications, `azd` automatically uses the delay-deployment strategy when you specify `"containerapp-dotnet"` as the host type. Typically, this is handled automatically when importing a .NET Aspire project. |
| 99 | + |
| 100 | +When working with a .NET Aspire application: |
| 101 | + |
| 102 | +1. Initialize your `azd` project with a .NET Aspire application: |
| 103 | + |
| 104 | + ```bash |
| 105 | + # This is typically done automatically by `azd` init for .NET Aspire projects |
| 106 | + azd init |
| 107 | + ``` |
| 108 | + |
| 109 | +1. During provisioning, `azd` sets up the necessary Azure resources but delays full Container App configuration. |
| 110 | + |
| 111 | +1. During deployment, `azd` will: |
| 112 | + |
| 113 | + - Build and publish the container images. |
| 114 | + - Apply the .NET Aspire manifest with proper configuration. |
| 115 | + - Configure service bindings between components. |
| 116 | + |
| 117 | +The delay-deployment strategy is primarily managed internally by `azd` based on the .NET Aspire application structure. |
| 118 | + |
| 119 | +## Choosing the right strategy |
| 120 | + |
| 121 | +| Feature | container-app-upsert | delay-deployment (.NET Aspire) | |
| 122 | +|------------------------|------------------------------|-------------------------------| |
| 123 | +| Application type | Any containerized application| .NET Aspire applications | |
| 124 | +| Configuration source | Bicep parameters | .NET Aspire manifest | |
| 125 | +| Deployment timing | All configuration during provisioning | Container App specifics during deployment | |
| 126 | +| Service binding | Manual configuration | Integrated with Aspire binding model | |
| 127 | +| Best for | General container applications | .NET microservices orchestrated with Aspire | |
| 128 | + |
| 129 | +## Additional resources |
| 130 | + |
| 131 | +- [Azure Container Apps Overview](/azure/container-apps/overview) |
| 132 | +- [Azure Container Apps Bicep Reference](/azure/templates/microsoft.app/containerapps) |
| 133 | +- [.NET Aspire Overview](/dotnet/aspire/get-started/aspire-overview) |
| 134 | +- [Todo Application Templates](https://github.com/Azure-Samples/todo-nodejs-mongo) (using container-app-upsert) |
0 commit comments