Skip to content

Deploy Container Apps with the Azure Developer CLI (azd)

The Azure Developer CLI (azd) is an open-source, developer-focused command-line tool that turns a template into a running Azure application. It combines infrastructure as code, application build/deploy, and optional CI/CD wiring behind a small set of workflow commands, so you can go from an empty folder to a deployed Container App with azd up.

This page explains when to use azd for Azure Container Apps, how it relates to the CLI and Bicep workflows already covered in this guide, and how to structure azure.yaml for a Container Apps service.

Prerequisites

  • Azure Developer CLI installed:

    # macOS
brew install azure/azd/azd

# Linux
curl -fsSL https://aka.ms/install-azd.sh | bash

# Windows
winget install microsoft.azd

  • An Azure subscription with permission to create resource groups and Container Apps resources.

  • Docker (optional) — only needed for local container builds. azd can also build container images remotely via Azure Container Registry.

Authentication

azd uses its own credential flow — run azd auth login before azd up. The Azure CLI (az login) is used separately for the verification commands below. Install the Azure CLI if you plan to run those az containerapp checks.

When to Use

Scenario Recommended Method
Go from template to running app in one command azd up
Repeatable app + infrastructure lifecycle for a whole project azd (provision + deploy together)
Fine-grained control of a single app or hotfix az containerapp up / az containerapp update (see Deployment Workflows)
Production baseline with governance and review Bicep / ARM via az deployment group create
Team-wide standard release automation CI/CD pipeline (GitHub Actions)

azd complements, not replaces, the CLI and Bicep

azd orchestrates the same underlying building blocks this guide already covers — Bicep or Terraform for infrastructure and container image build/deploy for the app. Use azd when you want a single, opinionated workflow across both; use the raw CLI or az deployment group create when you need precise, resource-level control.

azd Workflow

azd maps a small set of commands to the stages of a deployment lifecycle. azd up is a convenience command that runs package, provision, and deploy together.

flowchart TD
    A[azd init<br/>select or scaffold template] --> B[azd up]
    B --> C[Package<br/>build container image]
    C --> D[Provision<br/>Bicep or Terraform IaC]
    D --> E[Deploy<br/>push app to Container Apps]
    E --> F[Running Container App]
    F --> G{Change type?}
    G -->|App code| H[azd deploy]
    G -->|Infrastructure| I[azd provision]
    H --> F
    I --> F
Command Purpose
azd init Initialize a project from an existing template or scaffold azure.yaml for your code.
azd up Package, provision, and deploy in a single command.
azd provision Apply infrastructure changes (Bicep/Terraform) only.
azd deploy Build and deploy application code only, without re-provisioning.
azd down Tear down the provisioned Azure resources.

Procedure

1. Initialize from a template

Start from an existing template that already contains Container Apps infrastructure, or run azd init in your own repository to scaffold azure.yaml.

azd init --template hello-azd
Command Why it is used
azd init --template ... Initializes a project from an azd template that includes IaC, app code, and configuration.

2. Define the Container Apps service in azure.yaml

azure.yaml at the project root tells azd how to build and deploy each service. For a Container App, set host: containerapp and provide either project (build the image from source) or image (deploy a prebuilt image) — not both.

name: my-aca-app
metadata:
  template: my-aca-app@0.0.1
infra:
  provider: bicep
services:
  api:
    project: ./src/api
    language: js
    host: containerapp
    docker:
      path: ./Dockerfile

Deploy from a prebuilt image instead of building from source:

services:
  api:
    image: myregistry.azurecr.io/myapp:latest
    host: containerapp

project vs image for containerapp

When host is containerapp, you must set exactly one of project or image. project builds the container image from source (locally with Docker, or remotely via Azure Container Registry with docker.remoteBuild: true). image deploys an existing image without a build step.

The infra.provider field defaults to bicep. Set it to terraform to provision with Terraform instead:

infra:
  provider: terraform

3. Provision and deploy

Run a single command to build the image, provision the Container Apps environment and app, and deploy your code:

azd up
Command Why it is used
azd up Packages the app, provisions Azure infrastructure, and deploys the container app in one step.

azd prompts for an environment name, target subscription, and Azure region on first run. These values are stored per environment so subsequent runs are non-interactive.

4. Iterate

Redeploy only the application after code changes, without re-running infrastructure provisioning:

azd deploy

Apply infrastructure changes (for example, a modified Bicep module) without rebuilding the app:

azd provision

Verification

Confirm the deployment succeeded and the app is reachable:

# List azd environment values, including the resource group and endpoints
azd env get-values

# Confirm the container app and its running revision
az containerapp show \
  --name "$APP_NAME" \
  --resource-group "$RG" \
  --query "properties.runningStatus" \
  --output tsv

# Confirm the ingress FQDN and open it
az containerapp show \
  --name "$APP_NAME" \
  --resource-group "$RG" \
  --query "properties.configuration.ingress.fqdn" \
  --output tsv
Command Why it is used
azd env get-values Prints the environment outputs (resource group, service endpoints) captured after provisioning.
az containerapp show ... Verifies the deployed container app's running status and ingress endpoint.

Expected result: azd up reports a successful deployment with the service endpoint URL, and the az containerapp show calls return a running status and a resolvable FQDN.

Rollback / Troubleshooting

  • Roll back application code: azd deployments create new Container Apps revisions. To roll back, shift traffic to the previous stable revision as described in Deployment Workflows, or redeploy a known-good image.

  • Tear down everything: Run azd down to delete the resources azd provisioned for the current environment.

    azd down --purge
    Command Why it is used
    azd down --purge Deletes the provisioned resources and purges soft-deletable resources for the environment.

  • Provisioning failures: When azd up fails during the provision stage, the error surfaces the underlying Bicep or Terraform deployment error. Re-run azd provision after fixing the template, or inspect the deployment in the resource group.

  • Image build failures: If a local Docker build fails, set docker.remoteBuild: true on the service to build the image remotely in Azure Container Registry.

See Also

Sources