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 --frozenem CI e Dockerfile. - Execute o container como usuário não-root. Caminhos graváveis apenas onde necessário.
-
.dockerignoreexclui.venv, testes, git. Contexto menor e builds mais rápidos. - Marque imagens com SHA do git, nunca
:latestem 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
terminationGracePeriodSecondse Gunicorn--graceful-timeout. - Vincule
0.0.0.0atrá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
SecretStre 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: 0para 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
/healthapó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
Qual é a configuração mínima de produção?
Imagem testada, Gunicorn/Uvicorn, endpoints de saúde, configuração baseada em env, gate de teste CI, rollback de tag com um clique.
Quando usar Lambda vs K8s?
Lambda para trabalho baseado em eventos/picos; K8s para HTTP estável, websockets e plataforma uniforme multi-serviço.
Quantos workers Gunicorn?
Teste de carga - comece perto da contagem de CPU para serviços de I/O assíncrono; reduza quando limitado por memória por worker.
Arquivos .env são aceitáveis alguma vez?
Apenas para desenvolvimento local - nunca na imagem; produção usa injeção de segredos da plataforma.
Como lidar com arquivos estáticos?
CDN ou armazenamento de objetos para escala; collectstatic na build para Django conforme necessário.
E sobre feature flags?
Desacople a implantação de código arriscado da exposição - flags desativadas até que o rollout seja verificado.
Como implantar o admin do Django com segurança?
Mesmas regras de rolling; exportações de admin de longa duração podem precisar de worker separado ou ajuste de timeout.
Ambientes de preview?
Implantação acionada por PR com dados semeados acelera a revisão antes da promoção para staging.
Como o lint de documentação se encaixa?
Execute npx tsx scripts/lint-docs.ts em prebuild ao enviar o site de documentação com um monorepo de aplicação.
Maior anti-padrão de implantação?
Enviar migração de DB que quebra e alteração de código atomicamente - sempre expanda-contrate entre lançamentos.
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+.