Deploy to Azure Container Apps using the Azure Developer CLI

The Azure Developer CLI (azd) supports deploying both Azure Container Apps and Azure Container App Jobs. For Azure Container Apps, azd offers two deployment strategies:

• Image-based strategy. Separates container app configuration updates from image deployments.
• Revision-based strategy. Combines both into a single deployment and supports advanced rollout patterns.

The following sections explain both strategies, along with how to deploy Container App Jobs.

Image-based deployment strategy

In this strategy, the container app configuration is created and updated during azd provision, while the container image is updated during azd deploy.

• The container app definition (resources, environment variables, health probes, and so on) resides in a Bicep module applied during provisioning.
• Only the container image reference (containers[0].image) changes during deployment.

Revision behavior

Each change to the app configuration or image triggers a new revision:

Each revision allocates additional replicas in the Container Apps environment, which might temporarily increase resource usage and cost.

Configure image-based deployments

To ensure that azd provision updates an existing container app without overwriting the latest deployed image, perform an upsert operation. This pattern is implemented by the AVM container-app-upsert module and consists of two steps:

1. In your main.parameters.json, define a parameter that references the azd-provided variable SERVICE_{NAME}_RESOURCE_EXISTS. This variable gets set automatically by azd at provision time to indicate whether the resource already exists.

   {
     "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
     "contentVersion": "1.0.0.0",
     "parameters": {
       "environmentName": {
         "value": "${AZURE_ENV_NAME}"
       },
       "location": {
         "value": "${AZURE_LOCATION}"
       },
       // ... other parameters
       "apiExists": {
         "value": "${SERVICE_API_RESOURCE_EXISTS}"
       }
     }
   }
   

2. In your Bicep file, reference the exists parameter to control whether the container app should be created or updated. The container-app-upsert module encapsulates this logic internally.

   @description('Indicates whether the container app resource already exists.')
   param apiExists bool
   
   module api 'br/public:avm/ptn/azd/container-app-upsert:0.1.2' = {
     name: 'api'
     params: {
       name: 'my-api'
       location: location
       containerAppsEnvironmentName: containerAppsEnvironment.name
       containerRegistryName: containerRegistry.name
       imageName: !empty(apiImageName) ? apiImageName : ''
       exists: apiExists
       env: [
         {
           name: 'MONGODB_CONNECTION_STRING'
           value: mongodb.outputs.connectionString
         }
       ]
       targetPort: 3100
     }
   }
   

   This approach allows azd provision to upsert (update if exists, create if not) the container app resource safely without manual checks.

   Tip

   Keep the apiVersion in azure.yaml aligned with the Bicep module's apiVersion for Microsoft.App/containerApps to avoid mismatches.

Revision-based deployment strategy

In this strategy, both the container app definition and image are deployed together during azd deploy.

• The container app configuration resides in a dedicated Bicep module applied during deployment.

• Changes to environment variables, images, resources, and load-balancing settings are rolled out as a single revision.

  Tip

  This strategy supports blue-green, canary, and other advanced rollout patterns.

Configure revision-based deployments

1. Define the container app deployment by creating an infra file for your service, such as infra/api.bicep. You can define your container app by using the AVM-based module or by defining the resource directly:

   • AVM module
   • Direct bicep resource

   @description('Unique environment name used for resource naming.')
   param environmentName string
   
   @description('Primary location for all resources.')
   param location string
   
   param containerRegistryName string
   param containerAppsEnvironmentName string
   param imageName string
   param identityId string
   
   resource containerRegistry 'Microsoft.ContainerRegistry/registries@2023-01-01-preview' existing = {
     name: containerRegistryName
   }
   
   resource containerAppsEnvironment 'Microsoft.App/managedEnvironments@2022-03-01' existing = {
     name: containerAppsEnvironmentName
   }
   
   module api 'br/public:avm/res/app/container-app:0.8.0' = {
     name: 'api'
     params: {
       name: 'api'
       ingressTargetPort: 80
       scaleMinReplicas: 1
       scaleMaxReplicas: 10
       containers: [
         {
           name: 'main'
           image: imageName
           resources: {
             cpu: json('0.5')
             memory: '1.0Gi'
           }
         }
       ]
       managedIdentities: {
         systemAssigned: false
         userAssignedResourceIds: [identityId]
       }
       registries: [
         {
           server: containerRegistry.properties.loginServer
           identity: identityId
         }
       ]
       environmentResourceId: containerAppsEnvironment.id
       location: location
       tags: {
         'azd-env-name': environmentName
         'azd-service-name': 'api'
       }
     }
   }
   

2. Provide parameters at deploy time by creating a parameters file (e.g. api.parameters.json):

   {
     "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
     "contentVersion": "1.0.0.0",
     "parameters": {
       "environmentName": { "value": "${AZURE_ENV_NAME}" },
       "location": { "value": "${AZURE_LOCATION}" },
       "containerRegistryName": { "value": "${AZURE_CONTAINER_REGISTRY_NAME}" },
       "containerAppsEnvironmentName": { "value": "${AZURE_CONTAINER_ENVIRONMENT_NAME}" },
       "imageName": { "value": "${SERVICE_API_IMAGE_NAME}" },
       "identityId": { "value": "${SERVICE_API_IDENTITY_ID}" }
     }
   }
   

   Note

   SERVICE_API_IMAGE_NAME is dynamically set during deploy and isn't part of the provision outputs.

   When you run azd deploy, the container app revision is applied using the resource definition above.

   Tip

   Pass any additional outputs from azd provision as parameters to azd deploy if your container app references other provisioned resources.

Comparison summary

Deploy Container App Jobs

In addition to Container Apps, azd supports deploying Azure Container App Jobs (Microsoft.App/jobs). Container App Jobs are designed for tasks that run to completion, such as batch processing, scheduled tasks, or event-driven work.

How it works

When azd discovers a job resource tagged with azd-service-name, it:

1. Builds and pushes the Docker image to Azure Container Registry (same as Container Apps).
2. Updates the job's container image by calling the Container App Jobs API instead of the Container Apps API.
3. Returns empty endpoints, because jobs have no ingress.

Configure a Container App Job deployment

1. Define the azure.yaml file for your job service. Use host: containerapp and language: docker:

   name: myapp
   services:
     job:
       host: containerapp
       language: docker
       project: ./src/job
       docker:
         path: ./Dockerfile
         context: .
   

2. Create a Bicep module that provisions a Microsoft.App/jobs resource. Tag the resource with azd-service-name so azd can discover it. The parameters and existing resource references (container registry, managed environment, identity) follow the same pattern as the Container Apps examples above:

   resource job 'Microsoft.App/jobs@2025-02-02-preview' = {
     name: 'job'
     location: location
     tags: {
       'azd-env-name': environmentName
       'azd-service-name': 'job'
     }
     properties: {
       environmentId: containerAppsEnvironment.id
       configuration: {
         replicaTimeout: 300
         replicaRetryLimit: 1
         triggerType: 'Manual'
         registries: [
           {
             server: containerRegistry.properties.loginServer
             identity: identityId
           }
         ]
       }
       template: {
         containers: [
           {
             image: imageName
             name: 'main'
             resources: {
               cpu: json('0.5')
               memory: '1.0Gi'
             }
           }
         ]
       }
     }
     identity: {
       type: 'UserAssigned'
       userAssignedIdentities: {
         '${identityId}': {}
       }
     }
   }
   

   Important

   The azd-service-name tag value must match the service name in your azure.yaml file. This tag is how azd associates the provisioned resource with your service.

3. Run azd up to provision and deploy. The CLI automatically detects that the tagged resource is a Container App Job and handles the deployment accordingly.

Key differences from Container Apps

Additional resources

• Azure Container Apps overview
• Azure Container Apps Jobs overview
• Azure Container Apps Bicep reference
• Azure Container App Jobs Bicep reference
• .NET Aspire overview
• Todo application templates (uses image-based)