Implantar no Aplicativos de Contêiner do Azure usando a Azure Developer CLI

A CLI de Desenvolvedor do Azure (azd) dá suporte à implantação de Aplicativos de Contêiner do Azure e Tarefas de Aplicativo de Contêiner do Azure. Para aplicativos de contêiner do Azure, azd oferece duas estratégias de implantação:

  • Estratégia baseada em imagem. Separa as atualizações de configuração do aplicativo de contêiner das implantações de imagens.
  • Estratégia baseada em revisão. Combina ambos em uma única implantação e dá suporte a padrões de distribuição avançados.

As seções a seguir explicam ambas as estratégias, além de como implantar trabalhos de aplicativos de contêiner.

Implantar no Container Apps Express (versão preliminar)

azddá suporte a implantações baseadas em imagem para Aplicativos de Contêiner do Azure express (preview). Use o host existente containerapp em azure.yaml; você não precisa de um tipo de host separado para o Express:

Importante

O suporte expresso ao Container Apps requer azd a versão 1.35.0-beta.1 ou posterior.

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

Em sua infraestrutura, crie um ambiente gerenciado com properties.environmentMode definido como Express. O aplicativo de contêiner deve referenciar esse ambiente e incluir uma tag azd-service-name que corresponda ao nome do serviço em azure.yaml:

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

Defina o Microsoft.App/containerApps recurso com environmentId definido como containerAppsEnvironment.id. Adicione uma azd-service-name marca com o valor web para que ele corresponda ao nome do serviço em azure.yaml.

Durante azd deploy, azd detecta o modo expresso do ambiente pai e atualiza a imagem do contêiner sem definir um sufixo de revisão personalizado ou pesos de tráfego. O Express executa uma atualização contínua de revisão única automaticamente.

Use a estratégia de implantação baseada em imagem para o Express. A estratégia baseada em revisão não adapta o Bicep de implantação para express e o Express não dá suporte a várias revisões ou divisão de tráfego. Antes de definir sua infraestrutura, examine a disponibilidade atual e as limitações do recurso express.

Estratégia de implantação baseada em imagem

Nessa estratégia, a configuração do aplicativo de contêiner é criada e atualizada durante azd provision, enquanto a imagem do contêiner é atualizada durante azd deploy.

  • A definição do aplicativo de contêiner (recursos, variáveis de ambiente, probes de integridade e assim por diante) reside em um módulo Bicep aplicado durante o provisionamento.
  • Apenas a referência da imagem do contêiner (containers[0].image) muda durante a implantação.

Comportamento de revisão

Cada alteração na configuração ou imagem do aplicativo dispara uma nova revisão:

Passo Command Aplica alterações a Anotações
1 azd provision Variáveis de ambiente, recursos, pontos de montagem, sondas, balanceadores de carga Cria uma nova revisão
2 azd deploy Imagem do contêiner Cria outra revisão

Cada revisão aloca réplicas adicionais no ambiente de Aplicativos de Contêiner, o que pode aumentar temporariamente o uso de recursos e o custo.

Observação

Padrões avançados de distribuição, como azul-verde ou canário, não têm suporte nessa estratégia.

Configurar implantações baseadas em imagem

Para garantir que azd provision atualize um aplicativo de contêiner existente sem sobrescrever a imagem implantada mais recente, execute uma operação upsert. Esse padrão é implementado pelo módulo AVM container-app-upsert e consiste em duas etapas:

  1. Em sua main.parameters.json, defina um parâmetro que referencie a variável SERVICE_{NAME}_RESOURCE_EXISTSfornecida pelo azd. Essa variável é definida automaticamente no azd momento do provisionamento para indicar se o recurso já 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. No arquivo Bicep, faça referência ao exists parâmetro para controlar se o aplicativo contêiner deve ser criado ou atualizado. O container-app-upsert módulo encapsula essa 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
  }
}

    Esta abordagem permite que azd provision faça upsert (atualize se existir, crie se não) o recurso do aplicativo de contêiner com segurança, sem verificações manuais.

    Dica

    Mantenha o apiVersion em azure.yaml alinhado com o apiVersion do módulo Bicep para Microsoft.App/containerApps para evitar incompatibilidades.

Estratégia de implantação baseada em revisão

Nessa estratégia, a definição do aplicativo de contêiner e a imagem são implantadas juntas durante azd deploy.

  • A configuração do aplicativo de contêiner reside em um módulo Bicep dedicado aplicado durante a implantação.

  • As alterações em variáveis de ambiente, imagens, recursos e configurações de balanceamento de carga são distribuídas como uma única revisão.

    Dica

    Essa estratégia dá suporte a padrões de distribuição azul-verde, canário e outros padrões de distribuição avançados.

Configurar implantações baseadas em revisão

  1. Defina a implantação do aplicativo de contêiner criando um arquivo infra para seu serviço, como infra/api.bicep. Você pode definir seu aplicativo de contêiner usando o módulo baseado em AVM ou definindo o recurso diretamente:

    @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. Forneça parâmetros no momento da implantação criando um arquivo de parâmetros (por exemplo 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}" }
  }
}

    Observação

    SERVICE_API_IMAGE_NAME é definido dinamicamente durante a implantação e não faz parte das saídas de provisionamento.

    Quando você executa azd deploy, a revisão do aplicativo de contêiner é aplicada usando a definição de recurso acima.

    Dica

    Passe quaisquer saídas adicionais de azd provision como parâmetros para azd deploy se o seu aplicativo de contêiner fizer referência a outros recursos provisionados.

Resumo da comparação

Aspecto Baseado em imagem Baseado em revisão
Comando Atualizar azd provision + azd deploy azd deploy somente
Tipo de implementação Duas revisões Revisão única
Controle de implantação Gerenciado por azd Configurável (azul-verde, canário)
Caso de uso Ambientes simples Implantações avançadas
Local de definição do aplicativo de contêiner Bicep em tempo de provisionamento Bicep em tempo de implantação

Implantar trabalhos de aplicativos de contêiner

Além de aplicativos de contêiner, azd oferece suporte à implantação de trabalhos de Aplicativos de Contêiner do Azure (Microsoft.App/jobs). Os Trabalhos de Aplicativos de Contêiner são projetados para tarefas que são executadas até a conclusão, como processamento em lote, tarefas agendadas ou trabalho orientado a eventos.

Observação

Os Trabalhos de Aplicativos de Contêiner usam a mesma configuração host: containerapp em azure.yaml. Nenhum novo tipo de host é necessário. O modelo Bicep decide se azd deve provisionar um Aplicativo de Contêiner ou uma Tarefa de Aplicativo de Contêiner com base no tipo de recurso que você define.

Como funciona

Quando azd descobre um recurso de trabalho marcado com azd-service-name:

  1. Compila e envia por push a imagem do Docker para o Registro de Contêiner do Azure (o mesmo que os Aplicativos de Contêiner).
  2. Atualiza a imagem do contêiner da tarefa chamando a API de Trabalhos de Aplicativos de Contêiner em vez da API de Aplicativos de Contêiner.
  3. Retorna pontos de extremidade vazios, porque os trabalhos não têm entrada.

Configurar uma implantação de Trabalho de Aplicativo de Contêiner

  1. Defina o arquivo azure.yaml para o seu serviço de tarefas. Use host: containerapp e language: docker:

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

  2. Crie um módulo Bicep para provisionar um recurso Microsoft.App/jobs. Marque o recurso com azd-service-name para que azd possa descobri-lo. Os parâmetros e as referências de recurso existentes (registro de contêiner, ambiente gerenciado, identidade) seguem o mesmo padrão dos exemplos de Aplicativos de Contêiner acima:

    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

    O valor da tag azd-service-name deve corresponder ao nome do serviço no seu arquivo azure.yaml. Essa tag é como azd associa o recurso provisionado ao seu serviço.

  3. Execute azd up para provisionar e implantar. A CLI detecta automaticamente que o recurso marcado é um Job de Aplicativo de Contêiner e realiza a implantação conforme necessário.

Principais diferenças dos Aplicativos de Contêiner

Aspecto Aplicativos de Contêiner Trabalhos de Aplicativos de Contêiner
Tipo de recurso Microsoft.App/containerApps Microsoft.App/jobs
Entrada/pontos de extremidade Dá suporte à entrada HTTP Sem entrada (pontos de extremidade vazios)
Modelo de execução Serviços de execução longa Tarefas de execução até a conclusão
Tipos de gatilho Controlado por solicitação Manual, agendado ou controlado por eventos
Configuração do host em azure.yaml host: containerapp host: containerapp

Recursos adicionais

  • Última atualização em