Gerenciamento de Segredos
Carregue segredos de variáveis de ambiente, arquivos ou cofres - nunca do git.
Receita
Cartão de receita de referência rápida - pronto para copiar e colar.
import os
DATABASE_URL = os.environ["DATABASE_URL"]Quando usar isso:
- Chaves de API
- Senhas de banco de dados
- Chaves de assinatura
Exemplo de Trabalho
# monta um segredo k8s em /run/secrets/db_url
DATABASE_URL = Path("/run/secrets/db_url").read_text().strip()O que isso demonstra:
- variáveis de ambiente
- montagens de segredo em tempo de execução
- sem segredos no repositório
Análise Detalhada
Como Funciona
- Segredos são rotacionados sem alterações de código.
- Separa a configuração das credenciais.
- Escaneia o histórico do git se houver vazamentos.
Armadilhas
- Validação de limites ignorada - Dados inválidos chegam às camadas de persistência. Correção: Valide com Pydantic ou formulários do framework na borda.
- Vazamento de rastros de pilha (stack traces) - Clientes veem erros internos. Correção: Mapeie exceções para respostas HTTP estáveis.
- Bloqueio de loops de eventos assíncronos - Workers param sob carga concorrente. Correção: Use drivers assíncronos ou wrappers de threadpool.
- Segredos no controle de origem - Credenciais vazam através do histórico do git. Correção: Carregue segredos de variáveis de ambiente ou de um cofre em tempo de execução.
- Falta de observabilidade - Incidentes são difíceis de depurar. Correção: Adicione logs estruturados, métricas e IDs de requisição.
Alternativas
| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| Framework alternativo neste cookbook | Padrão da equipe ou monólito existente | API Greenfield com restrições diferentes |
| BaaS Gerenciado | MVP apenas CRUD | Autenticação personalizada, fluxos de trabalho ou necessidades de conformidade |
| gRPC | RPC interno de alta performance | Clientes HTTP públicos e acesso ao navegador |
FAQs
Quando devo adotar o gerenciamento de segredos?
Use-o quando os padrões e trade-offs nesta página corresponderem à sua API ou limite de dados.
Qual é o principal erro de produção com o gerenciamento de segredos?
Ignorar validação, timeouts ou contratos de erro explícitos na borda HTTP.
Como testar o gerenciamento de segredos?
Use o cliente de teste do framework, substitua dependências e afirme o status e a forma do JSON.
O gerenciamento de segredos funciona com Python 3.14?
Sim - os exemplos visam Python 3.14 com versões de framework fixadas do rodapé da pilha.
Como o gerenciamento de segredos se relaciona com Pydantic 2?
Valide e serialize nas bordas; mantenha os serviços funcionando com objetos de domínio tipados.
Síncrono ou assíncrono?
Prefira rotas assíncronas quando I/O domina; mantenha o trabalho da CPU pequeno ou descarregue para workers.
Onde a lógica de negócios deve viver?
Handlers finos; serviços possuem regras; repositórios possuem consultas.
Como documentar APIs?
Publique documentação OpenAPI ou de esquema que corresponda aos modelos de resposta no código.
O que devo ler em seguida?
Siga os links Relacionados para a próxima camada de profundidade nesta seção.
Como me mantenho seguro?
Autentique chamadores, autorize por recurso, limite a taxa e nunca registre segredos.
Primeiro passo de performance?
Meça a latência do banco de dados e de upstream antes de trocar de framework.
Relacionados
- Princípios Básicos de Design de API - Convenções REST
- OAuth2 & JWT - Fluxos de Token
- Gerenciamento de Segredos - Variáveis de ambiente e cofres
- Validação de Entrada e Injeção - Defesas
Versões da Pilha: 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+.