Melhores Práticas de Implantação

Lançamentos reproduzíveis, observáveis e reversíveis mantêm as APIs Python disponíveis enquanto as equipes enviam código diariamente. Estas regras se aplicam desde Dockerfiles até CI/CD e rollouts do Kubernetes.

Como Usar Esta Lista

• Valide antes da primeira implantação em produção e após qualquer SEV envolvendo rollout ou configuração.
• Emparelhe com Pipelines de CI/CD para aplicação automatizada.
• Trate endpoints de readiness ausentes como um bloqueador de merge para serviços HTTP.

A - Build e Imagem

• Build Docker multi-stage com imagem base slim. Sem toolchain de compilador na camada de runtime.
• Fixe Python 3.14 e dependências com uv lockfile. uv sync --frozen em CI e Dockerfile.
• Execute o container como usuário não-root. Caminhos graváveis apenas onde necessário.
• .dockerignore exclui .venv, testes, git. Contexto menor e builds mais rápidos.
• Marque imagens com SHA do git, nunca :latest em produção. Artefato imutável por lançamento.

B - Runtime e Servidores

• Use Gunicorn+UvicornWorker ou equivalente para FastAPI em produção. Não o servidor de desenvolvimento com --reload.
• Documente o CMD exato do container no repositório. Mesmo comando no manifesto K8s e docker-compose.
• Defina requisições e limites de CPU/memória a partir de testes de carga. Previne OOMKill e agendamento de vizinhos barulhentos.
• Configure timeouts de desligamento gracioso. Corresponda terminationGracePeriodSeconds e Gunicorn --graceful-timeout.
• Vincule 0.0.0.0 atrás de LB/ingress. TLS termina na borda, não ad-hoc no container da aplicação.

C - Configuração e Segredos

• Valide configurações com Pydantic 2 na inicialização. Falhe rapidamente em variáveis de ambiente de produção ausentes.
• Injete segredos de SSM/Secrets Manager/K8s Secret. Não em camadas de imagem ou git.
• Separe a configuração por ambiente com a mesma imagem. Apenas referências de ambiente mudam entre staging/produção.
• Redija segredos em logs e relatórios de erro. Use SecretStr e scrubbers do Sentry.
• Planeje a rotação de segredos sem reconstrução. Reinício em rolling pega novos valores.

D - Implantação e Migrações

• Atualização em rolling com maxUnavailable: 0 para APIs HA. Aumente novos pods antes de drenar os antigos.
• Verificações de readiness verificam DB e dependências críticas; liveness permanece barata. Evite loops de reinício em picos.
• Execute migrações como um Job ou fase separada. Expanda-contrate para alterações de schema que quebram compatibilidade.
• Teste de fumaça /health após implantação em CI/CD. Bloqueie promoção em caso de falha.
• Documente rollback: reimplantar SHA anterior. Pratique rollback em staging trimestralmente.

E - Observabilidade e Operações

• Emita logs JSON estruturados para stdout. Plataformas de container agregam automaticamente.
• Exponha métricas Prometheus ou APM em cada serviço. Taxa de erro e alarmes de latência por rota.
• Rastreie métricas DORA: frequência de implantação, tempo de ciclo, MTTR, taxa de falha de alteração. Melhore deliberadamente.
• Separe Deployments de web e worker. Escale workers vinculados à CPU independentemente.
• Escaneie imagens em CI para CVEs. Reconstrua a imagem base em cadência de patches.

FAQs

Relacionado

• Noções Básicas de Implantação - Fundamentos de WSGI/ASGI
• Implantações Zero-Downtime - rolling e migrações
• Pipelines de CI/CD - automação
• Melhores Práticas de Observabilidade - sinais em produção
• Configuração e Segredos em Produção - configuração 12-factor

Versões da Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.