Implantar e expor APIs de inferência de IA no AKS (Serviço de Kubernetes do Azure)
Crie manifestos de Deployment e Service do Kubernetes, conecte o AKS às imagens de contêiner, publique pontos de extremidade estáveis, valide cargas com kubectl e diagnostique as falhas mais frequentes.
Tempo de estudo sugerido: 80 minutos • Nível intermediário • Reescrita autoral completa com versão resumida de cada tópico, avaliação comentada e laboratório AKS guiado
Por João Ricardo Dutra••Conteúdo autoral completo
1. Da imagem de contêiner a um ponto de extremidade de IA altamente disponível
O opera um plano de controle gerenciado sobre a infraestrutura do . Você fornece a capacidade do e as definições da carga, enquanto o gerencia o plano de controle. Isso atende de inferência, pesquisa vetorial e outros componentes de IA que exigem implantação repetível, resiliência, escala e acesso de rede.
Uma FastAPI em contêiner só se torna uma aplicação operável quando o Kubernetes sabe o que executar, quantas cópias manter, quais recursos e configurações usar e como os clientes chegarão até ela. Manifestos descrevem esse estado desejado, e o reconcilia continuamente a realidade com a declaração.
Pod é a menor unidade implantável e normalmente envolve um contêiner da aplicação.
cria, substitui e mantém a quantidade desejada de Pods.
Service fornece ou estável e distribui tráfego para Pods selecionados por rótulo.
kubectl envia manifestos, consulta estados, lê e mostra eventos de diagnóstico.
Resumo do tópico
O gerencia a orquestração; Pods executam contêineres, Deployments preservam réplicas, Services estabilizam o acesso e kubectl controla e diagnostica a carga.
2. Relação entre Pods, Deployments, Services e rótulos
Executar um Pod diretamente é possível, porém frágil. Um controla um ReplicaSet, o ReplicaSet mantém os Pods e substitui automaticamente uma instância com falha. O Service não guarda endereços efêmeros: seu seletor encontra Pods com rótulos correspondentes e encaminha conexões a esses pontos de extremidade.
O contrato de rótulos é decisivo. Se o modelo do Pod usa app: inference- e o Service procura outro valor, o Service existe sem . Os nomes do e do Service não precisam coincidir; a porta 80 do Service também pode encaminhar corretamente para a porta 8080 do contêiner.
cuida do ciclo de vida; Service descobre rótulos correspondentes e oferece conectividade estável.
Resumo do tópico
O controla o ciclo dos Pods; o Service os descobre por rótulos. São os rótulos, e não os nomes dos objetos, que conectam os recursos.
3. Anatomia de um manifesto do Kubernetes
Um usa apiVersion apps/v1 e kind . identifica o objeto e pode indicar um . spec declara replicas, selector e o modelo de Pod. O modelo repete o rótulo selecionado e contém as definições dos contêineres. O arquivo declarativo pode ser revisado, versionado e reaplicado.
A imagem segue registro.azurecr.io/repositorio:tag. Crie e envie a imagem antes da implantação, confirme que o pode acessá-la, inclua código e dependências e prefira uma tag imutável a latest quando a reprodutibilidade for importante.
Resumo do tópico
O manifesto reúne identidade, réplicas, rótulos, modelo de Pod, imagem, portas, recursos e configuração em um documento versionável de estado desejado.
4. Réplicas, disponibilidade, solicitações e limites de recursos
Duas réplicas dão tolerância básica à falha de um Pod; três formam uma base de produção mais forte; quatro ou mais devem ser justificadas por tráfego e teste de carga, pois cada cópia consome computação. O Kubernetes reinicia Pods com falha, mas várias réplicas mantêm atendimento durante a recuperação.
Solicitações reservam o necessário para o agendamento. Sem nó com CPU ou memória disponível, o Pod fica Pending. Limites restringem consumo: CPU é limitada por ; ultrapassar memória pode gerar OOMKilled e reinício. Para um modelo pequeno, 2–4 GiB com cerca de 20% de folga e um a dois núcleos pode ser um ponto inicial, não uma regra universal.
Campos de recursos e efeito operacional.
Campo
Finalidade
Sinal de falha
replicas
Cópias simultâneas do Pod
Poucas réplicas reduzem resiliência e vazão.
.cpu / memory
Garantia usada pelo agendador
Solicitações grandes deixam Pods Pending.
limits.cpu
Máximo de CPU
Pressão sustentada causa e latência.
limits.memory
Máximo de memória
Excesso pode finalizar com OOMKilled.
Resumo do tópico
Use réplicas para resiliência e vazão medida; defina solicitações para agendamento e limites para contenção e ajuste tudo com o comportamento real do modelo.
5. Variáveis de ambiente, Segredos e acesso ao registro
Use variáveis literais para configurações não confidenciais, como nome do modelo e da . Para chaves e credenciais, referencie um Secret do Kubernetes com valueFrom e secretKeyRef. Crie-o separadamente com kubectl create secret generic -secrets --from-literal=-key=<valor>. Nunca confirme o valor no manifesto ou histórico do código.
O também precisa autenticar no . Em um registro comum, a integração concede AcrPull à do kubelet. Um registro com exige Registry Repository Reader. Um registro privado externo pode exigir image pull Secret. Valide o modelo aplicável em vez de presumir acesso automático.
Resumo do tópico
Mantenha configuração comum em variáveis, valores sensíveis em Secrets referenciados e conceda à identidade do kubelet a função mínima correta para baixar imagens.
6. Escolher o tipo correto de Service do Kubernetes
IPs de Pods são efêmeros. Um Service cria um ponto virtual persistente e continua encaminhando para Pods correspondentes após substituições. O tipo correto depende de quem chama a carga.
Tipos de Service no .
Tipo
Alcance
Uso comum
Somente dentro do ; padrão
interna, banco vetorial ou comunicação entre serviços.
Porta alta em cada de nó
Acesso simples de desenvolvimento ou integração com balanceador externo.
LoadBalancer
público ou privado gerenciado pelo
de produção exposta à internet ou privadamente.
ExternalName
Alias para nome externo; sem balanceamento
Representar uma dependência externa como Service.
Para roteamento de vários aplicativos, encerramento ou regras por host e caminho, Ingress pode ser mais adequado do que um LoadBalancer público por Service. O foco do módulo permanece nos quatro tipos acima.
Resumo do tópico
Use internamente, em cenários diretos limitados, LoadBalancer para exposição gerenciada pelo e ExternalName como alias externo.
7. Manifesto Service, seletores e mapeamento de portas
O manifesto usa apiVersion v1 e kind Service. type controla a exposição, selector associa o Service aos rótulos dos Pods, port recebe clientes e targetPort encaminha à aplicação em cada contêiner. A porta 80 pode encaminhar ao FastAPI na 8080; costuma usar 443 quando o encerramento está configurado.
O tipo altera a entrada; selector e targetPort preservam o contrato final com os Pods.
No , o segue nomedoservice..svc..local. usa -do-no:, geralmente acima de 30000. LoadBalancer usa o endereço externo atribuído e exibido por kubectl svc.
Resumo do tópico
O seletor precisa corresponder aos rótulos; port recebe o cliente e targetPort encaminha ao processo da aplicação.
8. Aplicar manifestos e entender a reconciliação
kubectl apply lê e cria ou atualiza objetos. O Kubernetes baixa imagens, agenda Pods, inicia contêineres, cria o Service e provisiona a rede. A operação é assíncrona: sucesso significa que o estado desejado foi aceito, não que todos os Pods ou o público estejam prontos.
Aplicar um diretório é conveniente, mas pode enviar não relacionado. Mantenha artefatos delimitados e revise mudanças. Reaplicar é idempotente no modelo declarativo: o plano de controle compara a configuração enviada com o estado vivo e reconcilia a diferença.
Resumo do tópico
Use kubectl apply para declarar recursos e observe a reconciliação separadamente, pois Pods, download de imagens e terminam de forma assíncrona.
9. Verificar Pods, , Service, e conectividade
Uma implantação saudável mostra a quantidade READY pretendida, Pods Running, AVAILABLE igual à meta e endereço do Service coerente com o tipo. Pending pode ser transitório; indica falha repetida na inicialização. EXTERNAL- de um LoadBalancer pode ficar pending enquanto o o provisiona.
kubectl get pods
kubectl get deployment
kubectl get svc inference-api-service
kubectl logs -l app=inference-api
# Test an internal ClusterIP Service
kubectl run -it --rm debug --image=alpine:latest --restart=Never -- sh
wget http://inference-api-service:80
# Test a public LoadBalancer address
curl http://<EXTERNAL-IP>
curl http://<EXTERNAL-IP>/predict -X POST -d '{"input":"test"}'
Para acesso interno, inicie um Pod de depuração descartável e chame o nome do Service. Para acesso externo, teste o público e uma rota real de inferência. Saúde, prontidão e inferência validam camadas distintas: o processo pode estar vivo sem ter o modelo pronto.
A implantação só termina após validar imagem, estado do Kubernetes, rede e comportamento da aplicação.
Resumo do tópico
Confira estado, e endereço do Service e teste saúde, prontidão e inferência real; aceitar o manifesto não conclui a implantação.
10. Diagnosticar e
significa que o nó não conseguiu obter a imagem. Inspecione eventos, verifique host, repositório e tag, confirme a existência com az acr repository list ou show-tags e valide a função entre e registro. docker pull manual ajuda a separar referência inválida de permissão do .
significa que o contêiner inicia e encerra repetidamente. Leia atuais e --previous e descreva o Pod. Causas comuns: variável ausente, Secret indisponível, comando ou porta incorreta, falha ao carregar o modelo ou configuração não montada. Execute a imagem localmente para separar defeito do contêiner de configuração do .
# Image pull or scheduling events
kubectl describe pod <pod-name>
# Current and previous-container logs
kubectl logs <pod-name>
kubectl logs <pod-name> --since=10m
kubectl logs <pod-name> --previous
# Capacity and Service selectors
kubectl get nodes
kubectl top nodes
kubectl get pods --show-labels
kubectl get pods -L app
kubectl describe svc inference-api-service
Resumo do tópico
Use eventos para imagem e agendamento, atuais e anteriores para falhas da aplicação e compare permissões, manifesto e execução local.
11. Diagnosticar Pods Pending e Services sem
Um Pod permanentemente Pending geralmente não pode ser agendado por falta de CPU ou memória solicitada, restrição de nó ou nó não saudável. Descreva Pod e nós, consulte kubectl top nodes se Metrics Server estiver disponível, reduza solicitações irreais ou aumente a capacidade com az aks scale após validar custo e cota.
Um Service com : <none> não encaminha tráfego. Compare kubectl pods --show-labels ou -L app com kubectl describe svc. Corrija rótulo do modelo ou seletor e garanta que os Pods estejam Ready.
Resumo do tópico
Pending é principalmente investigação de capacidade e agendamento; ausência de é investigação de rótulos, prontidão e seletores.
12. Exercício guiado: implantar uma de inferência de IA
O laboratório leva cerca de 30–40 minutos. Ele implanta um modelo do , e ; completa . e service. com contêiner, sondas, limites e balanceamento; e usa um cliente Python para testar saúde, prontidão e inferência.
Baixe o projeto inicial e revise a aplicação e os espaços dos manifestos.
Implante os recursos do com uma identidade autorizada.
Complete imagem, sondas, solicitações, limites, rótulos, seletores e portas.
Aplique os manifestos, aguarde Pods e endereço do LoadBalancer e diagnostique falhas.
Execute os testes de saúde, prontidão e inferência e remova recursos descartáveis.
Pré-requisitos: assinatura do ,, Python 3.12 ou posterior, CLI do atual e kubectl. As tarefas do podem não ser cobertas por créditos gratuitos e exigir pagamento conforme o uso ou outro plano pago.
Resumo do tópico
O laboratório une ,,,, sondas, recursos, balanceamento e testes Python em um fluxo completo.
13. Revisão da avaliação e decisões de prova
Justificativa das respostas.
Questão
Resposta correta
Motivo
Internet com balanceamento gerenciado pelo
LoadBalancer
Provisiona e endereço externo.
Solicitações excedem todos os nós
Pod permanece Pending
O agendador não encontra capacidade.
Contrato entre e Service
Rótulos do modelo coincidem com selector
Seletores descobrem por rótulo.
de contêiner reiniciado
kubectl <pod-name> --previous
Lê a instância encerrada anterior.
Campo replicas
Quantidade de cópias simultâneas do Pod
O controlador mantém esse estado desejado.
Resumo do tópico
LoadBalancer expõe, afetam agendamento, rótulos conectam Service e Pods, --previous recupera a falha anterior e replicas controla as cópias.
14. Checklist de produção e referências oficiais
Use tags imutáveis e valide autenticação entre e registro.
Mantenha segredos fora do Git e referencie Secrets ou solução externa.
Defina solicitações, limites, réplicas e sondas com testes de carga.
Faça rótulos e seletores coincidirem e valide port para targetPort.
Observe Pods, disponibilidade, , eventos, , saúde, prontidão e inferência.
Prefira exposição privada, , Ingress, políticas de rede e privilégio mínimo quando exigidos.
Prontidão de produção combina imagens repetíveis, acesso mínimo, recursos e sondas comprovados, rede estável e observabilidade em camadas apoiada pela documentação atual.
