Implantar contêineres no Serviço de Aplicativo do Azure: runtime, configuração, diagnóstico e solução de problemas

radio_button_uncheckedshort_text1. Da imagem portátil ao aplicativo Web de produção

O contêiner faz um processador de documentos com IA se comportar de maneira consistente em desenvolvimento, teste e produção, mas a imagem isolada não oferece infraestrutura, escala, roteamento, segredos nem diagnóstico. O Serviço de Aplicativo do Azure fornece essa camada gerenciada. A equipe publica uma imagem Linux, injeta valores específicos de cada ambiente no runtime e opera o serviço sem administrar os hosts.

O exemplo recebe documentos, extrai texto e metadados e devolve dados estruturados. A demanda cresce no horário comercial, a produção usa Armazenamento do Azure e credenciais de APIs dependentes, e as falhas precisam ser separadas entre pull da imagem, inicialização, configuração, integridade e código.

• Implantar imagens personalizadas do Registro de Contêiner do Azure ou de outro registro compatível.
• Configurar comando de inicialização, porta HTTP, armazenamento compartilhado, Always On e verificação de integridade.
• Fornecer configurações, cadeias de conexão, valores fixos por slot e referências do Cofre de Chaves.
• Usar logs, site SCM/Kudu, Azure Monitor e SSH opcional para diagnóstico.

Resumo do tópico

O Serviço de Aplicativo transforma uma imagem portátil em aplicativo Web operado ao acrescentar computação, configuração, escala, roteamento e diagnóstico gerenciados.

radio_button_uncheckedshort_text2. Origens de imagem e implantação pelo portal

Um aplicativo Web para contêineres obtém a imagem de um registro. O Registro de Contêiner do Azure é a origem natural de produção quando são necessários identidade do Azure, rede privada, replicação geográfica, integrações de verificação e controle por função. A opção de registro privado atende Docker Hub, GitHub Container Registry e registros próprios compatíveis com Docker Registry HTTP API V2 por HTTPS; imagens públicas dispensam credenciais.

1. Escolha assinatura, grupo de recursos, região e um nome de aplicativo globalmente exclusivo.
2. Selecione Contêiner como modelo de publicação e Linux como sistema operacional.
3. Selecione ou crie um plano do Serviço de Aplicativo.
4. Na guia de contêiner, escolha o registro, a autenticação, o repositório, a imagem e uma tag explícita.
5. Revise, crie e valide o nome de host padrão.

No mesmo escopo de assinatura, o portal consegue listar registros, repositórios e tags. Em outros registros privados, informe URL, usuário e senha. Prefira uma tag única e testada a latest para preservar a rastreabilidade.

Resumo do tópico

Escolha registro, referência determinística, plano e autenticação; o Serviço de Aplicativo provisiona o runtime Web e obtém a imagem.

radio_button_uncheckedshort_text3. Autenticação no registro com identidade gerenciada

A identidade gerenciada é a recomendação de produção porque fornece ao aplicativo uma identidade do Microsoft Entra e evita senhas do registro armazenadas. A identidade atribuída pelo sistema acompanha o ciclo de vida do aplicativo. A identidade atribuída pelo usuário é um recurso independente, útil quando precisa existir antes do aplicativo ou atender vários consumidores intencionalmente.

Conceda apenas a função AcrPull no registro ou no menor escopo compatível e configure o Serviço de Aplicativo para usá-la no pull. Credenciais administrativas simplificam alguns laboratórios, porém criam segredo duradouro, exigem o usuário administrador do registro e aumentam o trabalho de rotação e auditoria.

az webapp identity assign --resource-group myResourceGroup --name myDocumentProcessor

ACR_ID=$(az acr show --resource-group myResourceGroup --name myregistry --query id -o tsv)
PRINCIPAL_ID=$(az webapp identity show --resource-group myResourceGroup --name myDocumentProcessor --query principalId -o tsv)
az role assignment create --assignee $PRINCIPAL_ID --scope $ACR_ID --role AcrPull

az webapp config set --resource-group myResourceGroup --name myDocumentProcessor \
  --generic-configurations '{"acrUseManagedIdentityCreds": true}'

az webapp config container set --resource-group myResourceGroup --name myDocumentProcessor \
  --container-image-name myregistry.azurecr.io/docprocessor:v1

Se o registro usa ponto de extremidade privado, também são necessários integração de rede virtual do Serviço de Aplicativo, resolução DNS funcional e vnetImagePullEnabled para encaminhar o pull pela rede virtual.

Resumo do tópico

Identidade gerenciada mais AcrPull elimina credenciais armazenadas; um registro privado também depende de rede e DNS corretos.

radio_button_uncheckedshort_text4. CLI, Visual Studio Code, atualização da imagem e entrega contínua

A CLI do Azure é adequada a scripts e CI/CD porque recurso, plano, imagem e tag ficam explícitos. O Visual Studio Code com extensões Docker e Serviço de Aplicativo oferece um fluxo guiado: compilar localmente, enviar ao registro e implantar a tag escolhida. A produção ainda precisa de validação independente de identidade e funções.

Ao mudar a referência da imagem, o serviço reinicia as instâncias e obtém a nova versão. Em toda reinicialização há um pull, porém apenas camadas alteradas são transferidas quando existe cache. Uma nova instância, mudança de host ou alteração de camada de preço pode exigir download completo; o tamanho da imagem afeta diretamente prontidão e inicialização a frio.

Reutilizar a mesma tag não produz por si só um evento de versão. Reinicie o aplicativo ou habilite implantação contínua para que o push no registro chame um webhook. Um pipeline maduro compila, testa, publica versão imutável, atualiza a referência, espera a prontidão e conserva dados para reversão.

az webapp config container set -g myResourceGroup -n myDocumentProcessor \
  --container-image-name myregistry.azurecr.io/docprocessor:v2

az webapp deployment container config -g myResourceGroup -n myDocumentProcessor --enable-cd true
az webapp show -g myResourceGroup -n myDocumentProcessor --query defaultHostName -o tsv

Resumo do tópico

Automatize mudanças explícitas de versão, compreenda o cache de camadas e conecte o push do registro a uma liberação testada e observável.

radio_button_uncheckedshort_text5. Comando de inicialização e porta HTTP

O Serviço de Aplicativo normalmente respeita ENTRYPOINT e CMD do Dockerfile. Um comando personalizado pode acrescentar argumentos do ambiente, executar inicialização, iniciar gerenciador de processos ou substituir padrões do framework. Ele substitui CMD; ENTRYPOINT permanece. Use shell somente quando operadores como && ou expansão de variáveis forem necessários.

A documentação atual da Microsoft pressupõe porta 80 no contêiner Linux personalizado. Se o processo escuta em outra porta, defina WEBSITES_PORT. A plataforma encerra TLS e encaminha HTTP para uma única porta; o processo deve escutar em 0.0.0.0, não apenas localhost. EXPOSE documenta a intenção da imagem, mas não substitui a configuração da plataforma.

az webapp config set --resource-group myResourceGroup --name myDocumentProcessor \
  --startup-file "gunicorn --bind=0.0.0.0:8000 --workers=4 app:application"

az webapp config appsettings set --resource-group myResourceGroup --name myDocumentProcessor \
  --settings WEBSITES_PORT=8000 WEBSITES_ENABLE_APP_SERVICE_STORAGE=true

az webapp config set --resource-group myResourceGroup --name myDocumentProcessor \
  --always-on true --generic-configurations '{"healthCheckPath":"/health"}'

Resumo do tópico

Preserve os padrões da imagem quando possível; se precisar substituir CMD, alinhe WEBSITES_PORT à única porta HTTP e escute em todas as interfaces.

radio_button_uncheckedshort_text6. Armazenamento persistente, Always On e integridade

A camada gravável do contêiner é efêmera. Reinicialização, movimentação ou substituição pode remover arquivos fora de um volume. Em contêineres Linux, habilitar o armazenamento do Serviço de Aplicativo torna /home persistente e compartilhado entre instâncias; /home/LogFiles guarda logs acessíveis pela plataforma. Planeje a cota no plano e monte Armazenamento do Azure quando capacidade, compartilhamento ou I/O ultrapassarem o volume interno.

Always On evita ociosidade e reduz a inicialização a frio percebida. Está disponível a partir do nível Básico e ajuda APIs de produção, imagens grandes, inicialização lenta e trabalhos em segundo plano. A expansão ainda inicia novas instâncias, portanto imagens enxutas e inicialização otimizada continuam essenciais.

A verificação de integridade chama periodicamente um caminho. Retorne 200 apenas se a instância puder atender; falhas repetidas a retiram do balanceador e uma falha prolongada pode substituí-la. O caminho da plataforma precisa corresponder exatamente ao endpoint do aplicativo. A verificação deve ser rápida e útil; alterações reiniciam o aplicativo.

@app.route('/health')
def health_check():
    try:
        db.execute('SELECT 1')
        storage.list_containers()
        return {'status': 'healthy'}, 200
    except Exception:
        return {'status': 'unhealthy'}, 503

Resumo do tópico

Use /home para persistência planejada, Always On contra ociosidade e um endpoint correspondente para proteger o tráfego de instâncias sem integridade.

radio_button_uncheckedshort_text7. Configurações de aplicativo e cadeias de conexão

Configurações de aplicativo são pares nome-valor criptografados e injetados como variáveis de ambiente. Assim, desenvolvimento, homologação e produção reutilizam a mesma imagem. Use nomes portáveis com letras, números e sublinhados; chaves .NET aninhadas em Linux substituem dois-pontos por dois sublinhados, como ConnectionStrings__DefaultConnection.

Cadeias de conexão acrescentam um prefixo pelo tipo: SQL Server usa SQLCONNSTR_, SQL do Azure usa SQLAZURECONNSTR_, MySQL usa MYSQLCONNSTR_, PostgreSQL usa POSTGRESQLCONNSTR_ e personalizada usa CUSTOMCONNSTR_. Runtimes não .NET normalmente preferem configurações comuns, pois não aproveitam essa convenção.

az webapp config appsettings set --resource-group myResourceGroup --name myDocumentProcessor \
  --settings STORAGE_ACCOUNT_NAME=mystorageaccount LOG_LEVEL=INFO MAX_DOCUMENT_SIZE_MB=50

az webapp config connection-string set --resource-group myResourceGroup --name myDocumentProcessor \
  --connection-string-type SQLAzure \
  --settings DefaultConnection="Server=myserver.database.windows.net;Database=mydb;..."

az webapp config appsettings set --resource-group myResourceGroup --name myDocumentProcessor \
  --settings API_KEY="@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/api-key)"

Resumo do tópico

Injete valores do ambiente em vez de reconstruir a imagem e use cadeias tipadas apenas quando o runtime espera seus prefixos.

radio_button_uncheckedshort_text8. Edição em massa, slots e referências do Cofre de Chaves

Quando houver muitos valores, exporte as configurações em JSON, revise como código e reaplique o arquivo. O portal também oferece edição avançada em JSON. Nunca confirme segredos reais de produção no repositório.

Slots de implantação executam versões separadas no mesmo plano. A troca move código e a maior parte da configuração; os valores marcados como configuração de slot permanecem no ambiente. Identificadores, endpoints, bancos, sinalizadores, diagnóstico detalhado e a maioria das referências do Cofre de Chaves devem ficar presos ao slot quando uma troca seria perigosa.

A referência do Cofre de Chaves permite ler um segredo pelo nome normal da variável sem alterar o código. Habilite identidade gerenciada e conceda leitura, de preferência pela função Usuário de Segredos do Key Vault no Azure RBAC. Sem versão, a referência acompanha a versão mais recente; o cache é atualizado em até 24 horas, e uma mudança de configuração ou atualização explícita antecipa a resolução.

az webapp config appsettings list -g myResourceGroup -n myDocumentProcessor -o json > settings.json
az webapp config appsettings set -g myResourceGroup -n myDocumentProcessor --settings @settings.json

az webapp config appsettings set -g myResourceGroup -n myDocumentProcessor --slot staging \
  --settings ENVIRONMENT=staging API_ENDPOINT=https://api-staging.example.com \
  --slot-settings ENVIRONMENT API_ENDPOINT

Resumo do tópico

Trate configuração como dado revisável, fixe valores sensíveis ao ambiente no slot e armazene segredos gerenciados no Cofre de Chaves.

radio_button_uncheckedshort_text9. Logs do contêiner, fluxo de logs e site SCM/Kudu

A plataforma captura stdout e stderr: mensagens do aplicativo, exceções, framework, requisições e ciclo de vida. Escreva logs estruturados e úteis no console, sem credenciais nem conteúdo de documentos. O log no sistema de arquivos disponibiliza a saída em /home/LogFiles para diagnóstico de curto prazo.

az webapp log config --resource-group myResourceGroup --name myDocumentProcessor \
  --docker-container-logging filesystem

az webapp log tail --resource-group myResourceGroup --name myDocumentProcessor

O fluxo de logs mostra novas entradas em tempo real e identifica instâncias em expansão. O site https://<app-name>.scm.azurewebsites.net oferece Environment, navegador do armazenamento montado, downloads e despejo de diagnóstico. Ele é um site auxiliar, não o próprio contêiner; portanto não enxerga todos os processos nem caminhos efêmeros da imagem em execução.

Resumo do tópico

Envie a saída a stdout/stderr, acompanhe-a em incidentes e use Kudu para variáveis aplicadas, arquivos montados e pacotes de diagnóstico.

radio_button_uncheckedshort_text10. Azure Monitor, Log Analytics e SSH opcional

Logs locais não bastam para retenção. Configurações de diagnóstico podem enviar AppServiceConsoleLogs, AppServiceHTTPLogs, AppServicePlatformLogs e AppServiceAppLogs ao Azure Monitor, Log Analytics, Hubs de Eventos ou conta de armazenamento. A centralização permite consultas Kusto, alertas, pastas de trabalho, painéis, retenção e correlação.

RESOURCE_ID=$(az webapp show -g myResourceGroup -n myDocumentProcessor --query id -o tsv)
WORKSPACE_ID=$(az monitor log-analytics workspace show -g myResourceGroup -n myWorkspace --query id -o tsv)

az monitor diagnostic-settings create --resource "$RESOURCE_ID" \
  --name appServiceDiagnostics --workspace "$WORKSPACE_ID" \
  --logs '[{"category":"AppServiceConsoleLogs","enabled":true},{"category":"AppServiceHTTPLogs","enabled":true}]'

AppServiceConsoleLogs
| where TimeGenerated > ago(1h)
| where ResultDescription has_any ("error", "exception", "failed")
| project TimeGenerated, _ResourceId, ResultDescription
| order by TimeGenerated desc

SSH é opcional e precisa estar previsto na imagem: OpenSSH instalado, porta 2222 e configuração exigida pelo Serviço de Aplicativo. A sessão entra em uma instância; alterações na camada do contêiner somem na reinicialização. Use SSH para inspeção pontual, nunca como mecanismo de implantação.

Resumo do tópico

Exporte categorias para análise durável e alertas; reserve SSH para investigação temporária dentro da instância.

radio_button_uncheckedshort_text11. Árvore de decisão para solução de problemas

Reproduza localmente com configuração não secreta equivalente e investigue de fora para dentro: imagem e registro, configuração do serviço, prontidão, roteamento e dependências. Isso evita atribuir todo erro HTTP ao código.

Resumo do tópico

Diagnostique por camadas: pull, inicialização, configuração, porta, binding, integridade, rota, armazenamento e dependências.

radio_button_uncheckedshort_text12. Laboratório guiado: imagem privada no Serviço de Aplicativo

O exercício fornecido estima 30 minutos. Exige assinatura com permissão de implantação e atribuição de função, CLI do Azure atual, Visual Studio Code e, opcionalmente, Python 3.12 ou posterior. O material informa que ACR Tasks pode não estar disponível em créditos gratuitos; confirme a elegibilidade e os custos atuais antes de executar.

1. Crie uma API pequena com /health e endpoint de teste.
2. Crie grupo dedicado e Registro de Contêiner do Azure; compile uma tag explícita com ACR Tasks.
3. Crie plano Linux e aplicativo Web para contêineres.
4. Habilite identidade atribuída pelo sistema, conceda AcrPull e ative o pull por identidade.
5. Defina WEBSITES_PORT, configurações, armazenamento quando necessário, Always On e integridade.
6. Habilite logs e acompanhe a inicialização.
7. Teste o nome de host e o endpoint; valide valores não secretos no Kudu.
8. Publique uma tag única nova, atualize, valide e documente reversão.
9. Exclua o grupo dedicado se não contiver ativos compartilhados.

az group create -n rg-ai200-appservice-lab -l eastus
az acr create -g rg-ai200-appservice-lab -n <registro-globalmente-unico> --sku Basic
az acr build -r <registro-globalmente-unico> -t docprocessor:v1 .
az appservice plan create -g rg-ai200-appservice-lab -n plan-ai200 --is-linux --sku B1
az webapp create -g rg-ai200-appservice-lab -p plan-ai200 -n <aplicativo-globalmente-unico> \
  --container-image-name <registro>.azurecr.io/docprocessor:v1

Resumo do tópico

O laboratório comprova compilação, pull privado, runtime, configuração externa, integridade, logs, teste funcional, atualização e limpeza.

radio_button_uncheckedshort_text13. Verificação de conhecimento reescrita e comentada

Resumo do tópico

Associe porta, persistência, afinidade de slot, caminho de integridade e inspeção de ambiente ao controle do Serviço de Aplicativo correspondente.

radio_button_uncheckedshort_text14. Revisão final e referências da Microsoft

• O Serviço de Aplicativo obtém a imagem e gerencia o runtime Web.
• Identidade gerenciada com AcrPull é a autenticação preferida para registro privado.
• Inicialização, porta, armazenamento, Always On e integridade definem o comportamento.
• Configurações e Cofre de Chaves mantêm ambiente e segredos fora da imagem.
• Logs, Kudu, Azure Monitor, Log Analytics e SSH formam o conjunto de diagnóstico.
• A liberação termina somente depois de prontidão, teste, observabilidade e evidência de reversão.

1. Microsoft Learn: módulo Implantar contêineres no Serviço de Aplicativo
2. Configurar um contêiner personalizado
3. Implantação contínua com contêineres personalizados
4. Configurar aplicativo e cadeias de conexão
5. Usar referências do Cofre de Chaves
6. Configurar slots de implantação
7. Habilitar logs de diagnóstico
8. Monitorar o Serviço de Aplicativo

Resumo do tópico

Um contêiner pronto para produção combina implantação determinística, acesso por identidade, runtime explícito, configuração externa e observabilidade durável.