Implementación en Azure Container Apps mediante la CLI para desarrolladores de Azure

La CLI para desarrolladores de Azure (azd) admite la implementación de Azure Container Apps y azure Container App Jobs. Para Azure Container Apps, azd ofrece dos estrategias de implementación:

  • Estrategia basada en imágenes. Separa las actualizaciones de configuración de aplicaciones de contenedor de las implementaciones de imágenes.
  • Estrategia basada en revisiones. Combina ambos en una sola implementación y admite patrones de lanzamiento avanzados.

En las secciones siguientes se explican ambas estrategias, así como la forma de implementar trabajos de aplicaciones de contenedores.

Despliegue en Container Apps Express (versión preliminar)

azdadmite implementaciones basadas en imágenes para Azure Container Apps express (versión preliminar). Usa el host existente containerapp en azure.yaml; no necesita un tipo de host independiente para express:

Importante

La compatibilidad con Container Apps express requiere azd la versión 1.35.0-beta.1 o posterior.

services:
  web:
    host: containerapp
    image: mcr.microsoft.com/azuredocs/containerapps-helloworld:latest
    docker:
      imagePassthrough: true

En la infraestructura, cree un entorno administrado con properties.environmentMode establecido en Express. La aplicación contenedora debe hacer referencia a ese entorno e incluir una azd-service-name etiqueta que coincida con el nombre del servicio en azure.yaml:

resource containerAppsEnvironment 'Microsoft.App/managedEnvironments@2026-07-01' = {
  name: 'cae-${environmentName}'
  location: location
  properties: {
    environmentMode: 'Express'
  }
}

Defina el recurso Microsoft.App/containerApps con environmentId establecido en containerAppsEnvironment.id. Agregue una azd-service-name etiqueta con el valor web para que coincida con el nombre del servicio en azure.yaml.

Durante azd deploy, azd detecta el modo Express del entorno principal y actualiza la imagen del contenedor sin establecer un sufijo de revisión personalizado ni ponderaciones de tráfico. Express realiza automáticamente una actualización progresiva de una sola revisión.

Use la estrategia de implementación basada en imágenes para Express. La estrategia basada en revisiones no adapta su Bicep de despliegue para Express, y Express no admite múltiples revisiones ni la división del tráfico. Antes de definir la infraestructura, revise la disponibilidad actual y las limitaciones de las funciones Express.

Estrategia de implementación basada en imágenes

En esta estrategia, la configuración de la aplicación contenedora se crea y actualiza durante azd provision, mientras que la imagen del contenedor se actualiza durante azd deploy.

  • La definición de la aplicación contenedora (recursos, variables de entorno, sondeos de estado, etc.) reside en un módulo de Bicep aplicado durante el aprovisionamiento.
  • Solo cambia la referencia de imagen de contenedor (containers[0].image) durante la implementación.

Comportamiento de revisión

Cada cambio en la configuración de la aplicación o la imagen desencadena una nueva revisión:

Step Command Aplica cambios a Notas
1 azd provision Variables de entorno, recursos, montajes, sondeos, equilibradores de carga Crea una nueva revisión
2 azd deploy Imagen de contenedor Crea otra revisión

Cada revisión asigna réplicas adicionales en el entorno de Container Apps, lo que podría aumentar temporalmente el uso y el costo de los recursos.

Nota:

Los patrones de despliegue avanzados, como blue-green o canary, no son compatibles con esta estrategia.

Configuración de implementaciones basadas en imágenes

Para asegurarse de que azd provision actualiza una aplicación de contenedor existente sin sobrescribir la imagen implementada más reciente, realice una operación upsert . Este patrón lo implementa el módulo AVM container-app-upsert y consta de dos pasos:

  1. En su main.parameters.json, defina un parámetro que haga referencia a la variable proporcionada por azd SERVICE_{NAME}_RESOURCE_EXISTS. Esta variable se establece automáticamente en azd el momento del aprovisionamiento para indicar si el recurso ya existe.

    {
  "$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. En el archivo de Bicep, haga referencia al exists parámetro para controlar si se debe crear o actualizar la aplicación contenedora. El container-app-upsert módulo encapsula esta lógica internamente.

    @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
  }
}

    Este enfoque permite azd provisionactualizar (actualizar si existe, crear si no) el recurso de la aplicación contenedora de forma segura sin comprobaciones manuales.

    Sugerencia

    Mantén el apiVersion en azure.yaml alineado con el apiVersion del módulo Bicep para Microsoft.App/containerApps a fin de evitar discrepancias.

Estrategia de implementación basada en revisiones

En esta estrategia, la definición de la aplicación contenedora y la imagen se implementan juntas durante azd deploy.

  • La configuración de la aplicación en contenedor reside en un módulo Bicep dedicado que se aplica durante el despliegue.

  • Los cambios en las variables de entorno, las imágenes, los recursos y la configuración de equilibrio de carga se implementan como una sola revisión.

    Sugerencia

    Esta estrategia admite patrones de lanzamiento azul-verde, canario y otros avanzados.

Configuración de implementaciones basadas en revisiones

  1. Defina la implementación de la aplicación contenedora mediante la creación de un archivo de infraestructura para el servicio, como infra/api.bicep. Puede definir la aplicación contenedora mediante el módulo basado en AVM o definiendo el recurso directamente:

    @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. Proporcione parámetros en tiempo de implementación mediante la creación de un archivo de parámetros (por ejemplo, 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}" }
  }
}

    Nota:

    SERVICE_API_IMAGE_NAME se establece dinámicamente durante la implementación y no forma parte de las salidas de aprovisionamiento.

    Al ejecutar azd deploy, la revisión de la aplicación contenedora se aplica mediante la definición de recursos anterior.

    Sugerencia

    Pase las salidas adicionales de azd provision como parámetros a azd deploy si su aplicación contenedora hace referencia a otros recursos aprovisionados.

Resumen de comparación

Aspecto Basado en imágenes Sistema basado en revisiones
Comando de Actualización azd provision + azd deploy Solo azd deploy
Tipo de lanzamiento Dos revisiones Revisión única
Control de implementación Administrado por azd Configurable (azul-verde, canario)
Caso de uso Entornos simples Implementaciones avanzadas
Ubicación de la definición de la aplicación en contenedor Bicep en el momento del aprovisionamiento Bicep en tiempo de implementación

Implementar trabajos de la aplicación en contenedor

Además de Container Apps, azd admite la implementación de trabajos de Azure Container Apps (Microsoft.App/jobs). Los trabajos de la aplicación en contenedor están diseñados para tareas que se ejecutan hasta su finalización, como el procesamiento por lotes, las tareas programadas o el trabajo impulsado por eventos.

Nota:

Los trabajos de la aplicación en contenedor utilizan la misma host: containerapp configuración en azure.yaml. No se requiere ningún tipo de host nuevo. La plantilla de Bicep determina si azd aprovisiona una Aplicación de Contenedor o una Tarea de Aplicación de Contenedor según el tipo de recurso que defina.

Cómo funciona

Cuando azd detecta un recurso de trabajo etiquetado con azd-service-name, es:

  1. Compila e inserta la imagen de Docker en Azure Container Registry (igual que Container Apps).
  2. Actualiza la imagen del contenedor del trabajo llamando a la API de Container App Jobs en lugar de a la API de Container Apps.
  3. Devuelve puntos de conexión vacíos, ya que los trabajos no tienen ingreso.

Configurar una implementación de Container App Job

  1. Define el archivo azure.yaml para tu servicio de trabajo. Use host: containerapp y language: docker:

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

  2. Cree un módulo de Bicep que aprovisione un recurso Microsoft.App/jobs. Etiquete el recurso con azd-service-name para azd que pueda detectarlo. Los parámetros y las referencias de recursos existentes (registro de contenedor, entorno administrado, identidad) siguen el mismo patrón que los ejemplos anteriores de Container Apps:

    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}': {}
    }
  }
}

    Importante

    El azd-service-name valor de etiqueta debe coincidir con el nombre del servicio en el azure.yaml archivo. Esta etiqueta es cómo azd asocia el recurso aprovisionado con el servicio.

  3. Ejecute azd up para aprovisionar e implementar. La CLI detecta automáticamente que el recurso etiquetado es un Container App Job y gestiona la implementación en consecuencia.

Diferencias clave de Container Apps

Aspecto Aplicaciones de contenedores Container App Jobs
Tipo de recurso Microsoft.App/containerApps Microsoft.App/jobs
Entrada y puntos de conexión Admite la entrada HTTP. Sin ingreso (puntos de conexión vacíos)
Modelo de ejecución Servicios de larga duración Tareas de ejecución hasta completar
Tipo de desencadenadores Impulsado por solicitudes Manual, programado o controlado por eventos
Configuración de host en azure.yaml host: containerapp host: containerapp

Recursos adicionales

  • Se actualizó por última vez el