Implantar backends de IA nos Aplicativos de Contêiner do Azure: ambientes, YAML, segredos, registros e verificação
Crie um caminho de implantação repetível para uma API de processamento de documentos, do limite do ambiente e pull privado ao rollout por revisões, logs e integridade das réplicas.
Tempo de estudo sugerido: 70 minutos • Nível intermediário • Reescrita autoral completa com versão resumida de cada tópico e laboratório guiado na CLI do Azure
Por João Ricardo Dutra••Conteúdo autoral completo
1. Por que um de IA combina com os
Considere uma que recebe documentos, extrai texto, chama um provedor de embeddings e devolve vetores para pesquisa. O tráfego é irregular, a configuração muda por ambiente, credenciais giram e uma falha na inicialização precisa ser distinguida de erro de modelo ou rede. Os executam esses serviços em uma plataforma enquanto o opera o plano de controle do Kubernetes e a orquestração.
O modelo reúne entrada incorporada, dimensionamento orientado a eventos, segredos no escopo do aplicativo, , centralizados e revisões imutáveis. Assim, a equipe pode validar a nova revisão antes de transferir todo o tráfego.
Escolher o ambiente para rede, isolamento, governança e .
Implantar pela CLI do ou por versionado.
Manter configuração e segredos fora da imagem.
Autenticar o pull privado e verificar aplicativo, revisão, réplica e .
Resumo do tópico
Os Aplicativos de Contêiner fornecem um runtime gerenciado e baseado em revisões para serviços de IA em contêiner sem exigir que a equipe opere Kubernetes.
2. O ambiente como limite operacional
Um ambiente dos Aplicativos de Contêiner é um limite lógico seguro para aplicativos e trabalhos. , worker e processadores relacionados podem compartilhar rede interna e destino de ; desenvolvimento, teste e produção podem ficar separados para conter o impacto de mudanças. Portanto, o ambiente define isolamento e operação, não apenas organização.
Decisões de projeto do ambiente.
Decisão
Efeito
Uso recomendado
Ciclo de vida
Separa configuração e risco de implantação.
Ambientes distintos para desenvolvimento, teste e produção.
Rede
Controla comunicação privada, integração com rede virtual e alcance.
Agrupe serviços que precisam do mesmo caminho privado.
Observabilidade
Os aplicativos podem enviar dados ao mesmo Analytics.
Defina destino, retenção, consultas e alertas antes da produção.
Capacidade
Perfis de carga dão suporte a Consumo e Dedicado; somente Consumo é legado.
Prefira perfis de carga em projetos novos.
Padronize os nomes de grupos, ambientes e aplicativos. Mais ambientes aumentam o isolamento, mas também multiplicam rede, política, e tarefas de ciclo de vida.
O ambiente agrupa componentes com o mesmo limite de rede e observabilidade; separar ciclos de vida reduz o raio de impacto.
Resumo do tópico
O ambiente delimita rede e observabilidade compartilhadas; separe por ciclo de vida e segurança sem ignorar o custo operacional.
3. Criar, inspecionar, conectar e observar o ambiente
Instale ou atualize a extensão containerapp e registre Microsoft.App e Microsoft.OperationalInsights. Criar o ambiente explicitamente dá controle de nome e ciclo de vida quando vários aplicativos o compartilham; az containerapp up pode criar recursos automaticamente em um protótipo.
az login
az upgrade
az extension add --name containerapp --upgrade
az provider register --namespace Microsoft.App
az provider register --namespace Microsoft.OperationalInsights
az group create --name rg-ai200-aca --location centralus
az containerapp env create \
--name aca-env-ai200 \
--resource-group rg-ai200-aca \
--location centralus
az containerapp env show \
--name aca-env-ai200 \
--resource-group rg-ai200-aca
A entrada pode ser externa para uma chamada pelo cliente ou interna para um componente acessível apenas no ambiente. Essa escolha precisa corresponder ao alcance do ambiente e à rede virtual. Use rede personalizada para pontos de extremidade privados, grupos de segurança de rede, saída controlada, ou de Aplicativo; o tipo de rede não é simplesmente trocado depois da criação.
A integração do centraliza stdout, stderr, eventos de dimensionamento, eventos de plataforma e Dapr opcional. Projete os desde o início, pois não é possível reconstruir o histórico após um incidente.
Resumo do tópico
Prepare CLI e provedores, crie o limite compartilhado, alinhe entrada e rede e estabeleça centralizados antes do tráfego.
4. Implantação rápida e implantação explícita pela CLI do
az containerapp up é o caminho mais curto de uma imagem ou fonte local ao aplicativo e ajuda na exploração. az containerapp create explicita ambiente, grupo, imagem, entrada e porta de destino. Use caminho de repositório totalmente qualificado e em minúsculas para evitar falhas de referência confundidas com erro de autenticação.
O FQDN devolvido é o primeiro a testar. Um aplicativo interno não oferece o mesmo acesso público; nesse caso, a falha da chamada externa pode ser o comportamento esperado.
Resumo do tópico
Use up para começar rapidamente e create para implantar em recursos conhecidos; deixe imagem, entrada e porta inequívocas.
5. Revisões, e entrega repetível
Uma revisão é um instantâneo imutável das configurações do seu escopo. Alterar imagem, variáveis de ambiente, recursos ou regras de escala produz nova revisão. Configurações no escopo do aplicativo — segredos, credenciais do registro, modo de revisão e grande parte da entrada — são aplicadas sem criá-la. Essa diferença explica por que algumas atualizações aparecem na lista de revisões e outras não.
No modo de revisão única, padrão, a substituta fica saudável antes de receber o tráfego da anterior. No modo múltiplo, várias revisões ficam ativas para divisão de tráfego, blue-green e reversão controlada. Valide antes de mover todo o tráfego.
Com --, o arquivo é a fonte de verdade para as propriedades declaradas; evite parâmetros concorrentes. Nome, grupo e ambiente continuam identificando o destino. Versione apenas declarações não sensíveis. , GitHub Actions e o portal do são alternativas, mas CLI e esclarecem quais propriedades mudam.
A entrega por revisões separa criação, validação, movimento de tráfego e reversão.
Resumo do tópico
Use para reduzir desvio e revisões para tornar mudanças visíveis, testáveis e reversíveis.
6. Variáveis de ambiente para configuração não sensível
, nível de ,, escolha de modelo, tempos limite e lotes pertencem às variáveis de ambiente, não à imagem. Defina valores iniciais com --env-vars e mescle mudanças com --set-env-vars; evite nomes duplicados, pois prevalece a última ocorrência.
Como ficam no modelo da revisão, mudanças normalmente criam nova versão. Isso ajuda na auditoria e reversão, mas valores secretos nunca devem aparecer como variáveis em texto claro nem entrar no .
Resumo do tópico
Mantenha a imagem portátil e injete apenas comportamento não sensível por variáveis no escopo da revisão.
7. Segredos do aplicativo e referências do
Chaves de , senhas e material de assinatura pertencem a segredos. Um segredo fica no escopo do aplicativo, e várias revisões podem referenciá-lo. Mapeie-o para variável com secretref:<nome> na CLI ou secretRef no , sem revelar o valor.
az containerapp update -n ai-document-api -g rg-ai200-aca \
--set-env-vars LOG_LEVEL=debug FEATURE_EMBEDDINGS=true
az containerapp secret set -n ai-document-api -g rg-ai200-aca \
--secrets embeddings-api-key="REPLACE_WITH_REAL_VALUE"
az containerapp update -n ai-document-api -g rg-ai200-aca \
--set-env-vars EMBEDDINGS_API_KEY=secretref:embeddings-api-key
Adicionar, alterar ou excluir segredo não cria revisão nem atualiza automaticamente um contêiner que usa valor armazenado diretamente. Depois da rotação, crie revisão ou reinicie a existente. Antes de excluir, remova as referências e desative as revisões antigas.
Em produção, uma referência do torna o cofre a fonte de verdade. Habilite , conceda o papel mínimo Usuário de Segredos do e informe e identidade. sem versão acompanha a mais recente e é atualizada periodicamente; versionada fixa um valor. Não grave o segredo em repositório, ou histórico do shell.
Resumo do tópico
Proteja valores no escopo do aplicativo, exponha-os por referências e use com para rotação auditável.
8. Fazer pull seguro de imagens privadas
Um registro privado reduz exposição da cadeia de suprimentos e controla quem obtém imagens. Usuário e senha funcionam amplamente, mas criam credenciais duradouras. Para o , é preferível porque autentica pelo sem armazenar senha.
Conceda somente AcrPull no modelo clássico e associe a identidade e o hostname completo ao aplicativo. Uma identidade atribuída pelo usuário pode receber permissão antes do primeiro pull; a atribuída pelo sistema acompanha o ciclo de vida do aplicativo.
IDENTITY_ID=$(az identity show -g rg-ai200-aca -n id-ai200-pull --query id -o tsv)
PRINCIPAL_ID=$(az identity show -g rg-ai200-aca -n id-ai200-pull --query principalId -o tsv)
ACR_ID=$(az acr show -g rg-ai200-aca -n myregistry --query id -o tsv)
az role assignment create --assignee-object-id "$PRINCIPAL_ID" \
--assignee-principal-type ServicePrincipal --scope "$ACR_ID" --role AcrPull
az containerapp identity assign -n ai-document-api -g rg-ai200-aca \
--user-assigned "$IDENTITY_ID"
az containerapp registry set -n ai-document-api -g rg-ai200-aca \
--server myregistry.azurecr.io --identity "$IDENTITY_ID"
az containerapp registry list -n ai-document-api -g rg-ai200-aca
A configuração do registro fica separada do código e no escopo do aplicativo. Confirme com registry list ou registry show. Falha ImagePull deve ser tratada como autorização, hostname, ou rede até os provarem outra causa.
Entrega privada combina menor privilégio com evidência posterior à implantação.
Resumo do tópico
Prefira e menor privilégio no , qualifique a imagem e confirme a associação antes de culpar o código.
9. Começar a verificação pela configuração e pelos
A verificação compara intenção e estado. Primeiro confirme provisionamento, revisão mais recente, entrada, porta e FQDN. Use de console para stdout/stderr da aplicação e de sistema para pull, provisionamento e escala.
az containerapp show -n ai-document-api -g rg-ai200-aca \
--query "{fqdn:properties.configuration.ingress.fqdn,latest:properties.latestRevisionName,state:properties.provisioningState}"
az containerapp logs show -n ai-document-api -g rg-ai200-aca --tail 30
az containerapp logs show -n ai-document-api -g rg-ai200-aca --follow --tail 30
az containerapp logs show -n ai-document-api -g rg-ai200-aca --type system
az containerapp revision list -n ai-document-api -g rg-ai200-aca --all -o table
az containerapp replica list -n ai-document-api -g rg-ai200-aca -o table
--follow acompanha tráfego ao vivo e --tail controla o contexto. Erros comuns são variável ausente, binding incorreto, indisponível, credencial inválida, crash ou permissão do registro. Nunca registre chaves, conteúdo dos documentos ou dados pessoais.
Resumo do tópico
Confirme configuração e alcance; depois escolha de console ou sistema conforme o sintoma seja do contêiner ou da plataforma.
10. Revisões, réplicas, escala e rollout seguro
A lista de revisões prova a criação de uma versão, identifica ativas e inativas e mostra integridade; use --all para investigar versões desativadas. A réplica é uma instância em execução e revela escala a zero, partida fria, loop de falha, ausência de instâncias e comportamento de expansão.
Evidência operacional.
Evidência
Pergunta
Resposta comum
Aplicativo
Entrada e revisão são as planejadas?
Corrigir escopo do aplicativo ou testar na rede correta.
Console
O processo iniciou e atendeu?
Corrigir binding, configuração, dependência ou código.
Sistema
A plataforma obteve e provisionou a imagem?
Corrigir autorização, , rede ou capacidade.
Revisão
A atualização criou e ativou versão saudável?
Manter tráfego na anterior e reparar a nova.
Réplicas
Há instâncias e escala esperada?
Investigar regras, latência ou crash loop.
Automatize consultas com --query, espere a revisão saudável, chame /health e só então transfira tráfego. Em IA orientada a requisições, mínimo de réplicas e gates devem considerar partida fria e latência das dependências.
Resumo do tópico
Revisões descrevem versões; réplicas descrevem capacidade em execução. Use ambas com antes de declarar sucesso.
11. Laboratório guiado: de documentos em contêiner
Reserve cerca de 30 minutos. Você precisa de assinatura com permissões de implantação e atribuição de papel, CLI atual, e Python 3.12 opcional. A disponibilidade de ACR Tasks e o uso de créditos gratuitos mudam; confirme condições e custos atuais.
Crie uma pequena com /health.
Crie grupo, , identidade e ambiente.
Compile e envie versão explícita; conceda permissão de pull.
Implante com entrada externa, porta e autenticação por identidade.
Defina variáveis e referencie a chave de embeddings como segredo.
Chame FQDN e ; acompanhe de console e sistema.
Liste revisões e réplicas; publique v2, valide e documente reversão.
Exclua apenas o grupo do laboratório após confirmar que não há recursos compartilhados.
az containerapp update -n ai-document-api -g rg-ai200-aca \
--image myregistry.azurecr.io/ai-document-api:v2
FQDN=$(az containerapp show -n ai-document-api -g rg-ai200-aca \
--query properties.configuration.ingress.fqdn -o tsv)
curl -fsS "https://$FQDN/health"
az containerapp revision list -n ai-document-api -g rg-ai200-aca -o table
Resumo do tópico
O laboratório reúne infraestrutura, autorização privada, configuração externa, implantação, testes, , revisão, réplicas e limpeza.
12. Avaliação reescrita e explicada
Decida pelo conceito.
Cenário
Melhor resposta
Motivo
Vários aplicativos compartilham rede privada e .
Usar o mesmo ambiente planejado para esse limite.
O ambiente carrega rede e observabilidade compartilhadas.
Configuração precisa de revisão e controle de versão.
Usar create/update --.
A declaração fica repetível e o desvio aparece.
Chave de embeddings não pode entrar no .
Guardar segredo e usar secretref/secretRef.
Somente o nome entra no modelo.
É preciso confirmar a nova versão.
Executar az containerapp revision list.
Mostra revisões geradas por mudanças do seu escopo.
A imagem nova não inicia.
Começar com az containerapp show e de sistema quando houver suspeita de pull.
Os trazem a evidência mais rápida.
Resumo do tópico
Escolha ambiente para limites, para configuração revisada, segredos para credenciais, revisões para versões e para diagnóstico.
13. Revisão final e referências da Microsoft
Ambientes definem limites seguros de rede e observabilidade.
CLI e permitem implantação rápida e repetível.
Configurações de revisão e aplicativo têm comportamentos distintos.
Variáveis guardam valores não sensíveis; segredos e protegem credenciais.
é preferida para o .
Estado, , revisões e réplicas concluem a verificação.
Uma implantação pronta para produção é declarativa, baseada em identidade, configurada externamente, consciente de revisões, observável e validada antes do tráfego.
