Solucionar problemas de falhas comuns de implantação no Aplicativos de Contêiner do Azure

Este artigo ajuda você a identificar e resolver cenários de falha de implantação que mais frequentemente exigem escalonamento de suporte em Aplicativos de Contêiner do Azure. Cada cenário inclui sintomas, etapas de diagnóstico do portal e da CLI e resoluções.

Localize o sintoma na tabela de referência rápida e siga o link para o cenário de correspondência.

Referência rápida de sintomas

Onde procurar: superfícies de diagnóstico

Use as superfícies de diagnóstico a seguir para investigar falhas de implantação.

Falhas na extração de imagem

Falhas ao baixar a imagem são uma das causas mais comuns de erros de implantação. Eles geralmente ocorrem antes que Aplicativos de Contêiner do Azure possa criar uma revisão utilizável.

Symptoms

• Nenhuma revisão criada.
• provisioningState é Failed.
• A mensagem de erro menciona ImagePullBackOff, UNAUTHORIZED ou manifest unknown.

Onde procurar: diagnóstico de extração de imagens

# Check app-level provisioning state and error
az containerapp show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> \
  --query "{provisioning:properties.provisioningState, error:properties.provisioningError, latestRevision:properties.latestRevisionName}" -o json

# List revisions (expect empty or failed)
az containerapp revision list -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> \
  --query "[].{name:name, health:properties.healthState, provisioning:properties.provisioningState}" -o table

Causas e resoluções comuns

Falhas na inicialização e de contêiner

Use esta seção quando uma revisão é criada, mas a carga de trabalho não inicia ou não continua em execução.

Symptoms

• A revisão foi criada, mas healthState é Unhealthy.
• runningState é Failed.
• Os logs do console podem estar vazios (o contêiner é encerrado antes de registrar a saída).

Onde procurar: falha e diagnóstico de inicialização

# Inspect revision detail
az containerapp revision show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --revision <REV> \
  --query "{health:properties.healthState, running:properties.runningState, details:properties.runningStateDetails, error:properties.provisioningError}" -o json

# Pull console logs (if any output was written)
az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --tail 100

# Pull system logs for platform-level events
az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --type system --tail 50

Causas e resoluções comuns

Problemas de acesso secreto

Use esta seção para solucionar problemas de valores secretos ausentes ou vazios que interrompem a configuração do aplicativo em runtime.

Symptoms

• O contêiner é iniciado, mas o aplicativo falha porque um valor de configuração esperado está vazio ou ausente.
• Variáveis de ambiente que fazem referência a segredos não têm valor.

Onde procurar: diagnósticos de referência secreta

# List secrets defined on the app
az containerapp secret list -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> -o table

# Show the revision template to verify env var references
az containerapp revision show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --revision <REV> \
  --query "properties.template.containers[].env" -o json

Causas e resoluções comuns

Falhas de referência do Key Vault

Use esta seção quando os segredos com suporte Key Vault não forem resolvidos durante a implantação ou enquanto o aplicativo estiver em execução.

Symptoms

• A implantação falha ou o valor do segredo não está disponível.
• Os logs do sistema fazem referência a erros de acesso ao Key Vault.
• provisioningError menciona falha de autenticação ou autorização no Key Vault.

Onde procurar: diagnóstico de acesso ao Key Vault

# List secrets and check for Key Vault reference status
az containerapp secret list -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> -o json

# Verify managed identity is assigned
az containerapp identity show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME>

Causas e resoluções comuns

Configuração incorreta de identidade gerenciada

Use esta seção quando a autenticação nos serviços do Azure falhar, mesmo que seu aplicativo esteja configurado para usar identidade gerenciada.

Symptoms

• O código do aplicativo recebe 401 (não autorizado) ou 403 (proibido) ao chamar serviços Azure.
• Falha na aquisição do token de identidade gerenciada.

Onde procurar: diagnósticos de identidade e autorização

# Verify identity configuration
az containerapp identity show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME>

# Check role assignments for the identity's principal ID
az role assignment list --assignee <PRINCIPAL_ID> --all -o table

Causas e resoluções comuns

Problemas de tempo de inicialização

Use esta seção quando os contêineres de inicialização bloquearem a inicialização ou falharem antes que o contêiner principal possa começar a atender ao tráfego.

Symptoms

• O aplicativo nunca atinge um estado em execução.
• Os contêineres de inicialização aparecem presos ou falham.
• Os logs do sistema mostram o contêiner de inicialização em execução, mas nunca concluído.

Onde procurar: diagnóstico do contêiner de inicialização

# Check revision running state
az containerapp revision show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --revision <REV> \
  --query "{running:properties.runningState, details:properties.runningStateDetails}" -o json

# Check init container logs
az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --container <INIT_CONTAINER_NAME> --tail 100

# System logs for platform events
az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --type system --tail 50

Causas e resoluções comuns

Falhas de sondas de saúde

Use esta seção quando as revisões forem implantadas com êxito, mas estiverem marcadas como não íntegras ou forem afetadas por verificações de investigação.

Symptoms

• A revisão é provisionada, mas o status de execução é Degraded.
• Os registros do sistema mostram eventos Unhealthy com detalhes de falha da sonda.
• O aplicativo funciona localmente, mas falha nas verificações de integridade na ACA.

Onde procurar: diagnóstico de integridade da investigação

# Check the revision's probe configuration
az containerapp revision show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --revision <REV> \
  --query "properties.template.containers[].probes" -o json

# System logs for probe failure events
az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --type system --tail 50

Causas e resoluções comuns

Valores padrão da sonda

Quando você habilita o ingresso e não configura sondas, a ACA aplica estes valores padrão:

Problemas na entrada e no roteamento de tráfego

Use esta seção quando o aplicativo estiver em execução, mas as solicitações falharem porque as configurações de tráfego de entrada ou revisão estão incorretas.

Symptoms

• O aplicativo está em execução e íntegro, mas as solicitações HTTP retornam erros (404, 502) ou nenhuma resposta.
• O aplicativo funciona por meio az containerapp exec , mas não por meio da URL pública.

Onde procurar: diagnóstico de entrada e tráfego

# Check ingress configuration and traffic split
az containerapp show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> \
  --query "{ingress:properties.configuration.ingress, latestReady:properties.latestReadyRevisionName}" -o json

# Verify the FQDN
az containerapp show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --query "properties.configuration.ingress.fqdn" -o tsv

Causas e resoluções comuns

Autenticação do Registro de Contêiner

Use esta seção quando as extrações de imagem falharem porque o aplicativo não consegue se autenticar no registro de contêiner.

Symptoms

• A implantação falha em UNAUTHORIZED: authentication required.
• Esse erro geralmente mascara outros problemas (como uma marca de imagem incorreta) porque o Registro rejeita a solicitação antes de poder verificar a marca.

Onde procurar: diagnósticos de autenticação do registro

# Check configured registries
az containerapp show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> \
  --query "properties.configuration.registries" -o json

# Verify ACR credentials work
az acr login --name <AZURE_CONTAINER_REGISTRY_NAME>
docker pull <AZURE_CONTAINER_REGISTRY_NAME>.azurecr.io/<REPOSITORY_NAME>:<TAG>

Causas e resoluções comuns

Resumo do fluxo de trabalho de diagnóstico

Use esta sequência quando não tiver certeza do que falhou:

1. Execute az containerapp show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> -o json. Verifique provisioningState, provisioningError e latestRevisionName.

2. Execute az containerapp revision list -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> -o table. Se a lista estiver vazia, a falha será um problema de extração de imagem ou de validação do modelo (falhas de extração de imagem e autenticação do Registro de Contêiner). Se houver uma revisão, continue na etapa 3.

3. Execute az containerapp revision show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --revision <REV> -o json. Verifique healthState, runningState, runningStateDetails e provisioningError.

4. Execute az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --type system --tail 50 para exibir eventos no nível da plataforma, como falhas de investigação, erros de identidade e problemas de sincronização secreta.

5. Execute az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --tail 100 para exibir o stdout/stderr do aplicativo, incluindo rastreamentos de pilha, erros de configuração e falhas de conexão.

6. Execute az containerapp identity show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> para verificar a configuração de identidade se erros relacionados à autenticação apareceram nas etapas anteriores.

Use a opção Diagnosticar e resolver problemas no portal

Consultas do Log Analytics para uma investigação mais aprofundada

Se a saída da CLI e o diagnóstico do portal não forem suficientes, consulte os logs subjacentes diretamente no Log Analytics. As duas consultas a seguir abrangem os pontos de partida mais comuns para falhas no nível da plataforma e erros HTTP no nível de entrada.

Localizar falhas no nível do sistema

ContainerAppSystemLogs_CL
| where RevisionName_s == "<REV>"
| where Log_s contains "BackOff" or Log_s contains "Failed" or Log_s contains "Error"
  or Reason_s == "Unhealthy"
| project TimeGenerated, Reason_s, Log_s
| order by TimeGenerated desc
| take 50

Esta consulta mostra erros ao extrair imagem, falhas de sondagem, erros de provisionamento e outros eventos da plataforma.

Localizar erros HTTP (requer que os logs de HTTP estejam habilitados)

A camada de entrada gera logs HTTP, e você aceita recebê-los. Habilite esses logs por meio das configurações de diagnóstico do Azure Monitor no ambiente gerenciado do Container Apps. Depois de habilitá-los, a tabela ContainerAppHTTPLogs aparece no Log Analytics. Pode levar vários minutos para que a tabela apareça.

ContainerAppHTTPLogs
| where TimeGenerated > ago(1h)
| where StatusCode >= 400
| project TimeGenerated, ContainerAppName, RevisionName, Method, Path,
  StatusCode, ResponseCodeDetails, RequestDuration, RequestId
| order by TimeGenerated desc
| take 100

Essa consulta filtra os logs HTTP da camada de entrada para mostrar apenas solicitações com falha (código de status 400 ou superior) da última hora. Ele retorna o carimbo de data/hora, o nome do aplicativo e da revisão, o método HTTP e o caminho, o código de status do erro, um ResponseCodeDetails campo que indica se o erro se originou do contêiner (via_upstream) ou da plataforma (route_not_found, connection_timeout), a duração da solicitação e uma ID de solicitação exclusiva que você pode usar para correlacionar com os logs do aplicativo.

Para mais consultas, inclusive análise de solicitações lentas, taxa de erros por revisão, rastreamento de solicitações individuais e pontos de extremidade com mais falhas, consulte Monitorar logs em Aplicativos de Contêiner do Azure com o Log Analytics.

Conteúdo relacionado

• Solucionar problemas de um aplicativo de contêiner
• Gerencie segredos em Aplicativos de Contêiner do Azure
• Identidades gerenciadas nos Aplicativos de Contêiner do Azure
• Sondagens de saúde em Aplicativos de Contêiner do Azure
• Entrada nos Aplicativos de Contêiner do Azure
• Monitorar logs nos Aplicativos de Contêiner do Azure com o Log Analytics