Gerenciamento de Configuração

O gerenciamento de configuração separa o que muda por ambiente de como a automação o aplica. Projetos de infraestrutura em Python usam templates, arquivos de configuração em camadas e stores de segredos para que dev, staging e prod permaneçam estruturalmente idênticos sem copiar pilhas inteiras.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

from pydantic_settings import BaseSettings, SettingsConfigDict
 
class AppSettings(BaseSettings):
    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
    environment: str = "dev"
    database_url: str
    log_level: str = "info"
 
settings = AppSettings()  # lê variáveis de ambiente e opcionalmente .env localmente

# app.env.j2
APP_ENV={{ environment }}
DATABASE_URL={{ database_url }}
LOG_LEVEL={{ log_level }}

Quando usar isso:

• Mesmo template, valores diferentes entre dev/stage/prod
• Segredos fora do git com referências injetadas no momento da implantação
• Validação de configuração antes da aplicação com modelos Pydantic
• Flags de recursos e limites que diferem por ambiente
• Ansible/Pulumi/Terraform consumindo um esquema de configuração

Exemplo de Trabalho

Configuração YAML em camadas, renderização Jinja2 e stub de busca de segredos para um script de implantação.

"""render_config.py - carrega a configuração do ambiente, mescla segredos, renderiza o template."""
from __future__ import annotations
 
import json
from pathlib import Path
 
import yaml
from jinja2 import Environment, FileSystemLoader, select_autoescape
 
ROOT = Path(__file__).parent
CONFIG_DIR = ROOT / "config"
 
def load_yaml(path: Path) -> dict:
    with path.open() as f:
        return yaml.safe_load(f) or {}
 
def load_config(environment: str) -> dict:
    base = load_yaml(CONFIG_DIR / "base.yaml")
    env = load_yaml(CONFIG_DIR / f"{environment}.yaml")
    merged = {**base, **env, "environment": environment}
    return merged
 
def fetch_secret(name: str) -> str:
    # Produção: boto3.client("secretsmanager").get_secret_value(...)
    return f"SECRET::{name}"
 
def render(template_name: str, context: dict) -> str:
    env = Environment(
        loader=FileSystemLoader(ROOT / "templates"),
        autoescape=select_autoescape(),
    )
    template = env.get_template(template_name)
    return template.render(**context)
 
if __name__ == "__main__":
    cfg = load_config("staging")
    cfg["database_password"] = fetch_secret("db/password")
    output = render("service.env.j2", cfg)
    print(output)
    print(json.dumps({"rendered_for": cfg["environment"]}))

# config/base.yaml
log_level: info
service_port: 8080

# config/staging.yaml
database_host: staging.db.internal
feature_new_ui: true

# templates/service.env.j2
APP_ENV={{ environment }}
LOG_LEVEL={{ log_level }}
PORT={{ service_port }}
DATABASE_HOST={{ database_host }}
DATABASE_PASSWORD={{ database_password }}
FEATURE_NEW_UI={{ feature_new_ui }}

O que isso demonstra:

• A mesclagem de YAML base + ambiente mantém a estrutura DRY (Don't Repeat Yourself)
• Segredos buscados no momento da renderização, nunca commitados em templates
• Jinja2 renderiza arquivos de ambiente finais para injeção no template do Ansible ou em contêineres
• Linha de log JSON registra qual ambiente foi renderizado para auditoria

Mergulho Profundo

Como Funciona

• Camada de dados: YAML/JSON/TOML por ambiente + validação de esquema
• Camada de segredos: SSM, Secrets Manager, Vault ou store de segredos de CI
• Camada de template: Jinja2, envsubst ou variáveis do Terraform/Pulumi
• Camada de aplicação: Ansible, Kubernetes ou systemd carregam artefatos renderizados
• Fluxo de alterações: editar configuração no git → validar → renderizar → implantar → verificar

Configuração vs. Segredos

Notas de Python

from pydantic import Field, SecretStr
from pydantic_settings import BaseSettings
 
class DeploySettings(BaseSettings):
    environment: str
    db_password: SecretStr = Field(alias="DATABASE_PASSWORD")
 
    def redacted(self) -> dict:
        return self.model_dump(mode="json", exclude={"db_password"})

Armadilhas

• Segredos em prod.yaml - credenciais no histórico do git para sempre. Correção: armazene ARNs ou nomes de segredos, resolva em tempo de execução.
• Templates bifurcados por ambiente - desvio quando um ambiente recebe uma correção. Correção: um template, apenas dados específicos do ambiente.
• Validação ausente - erros de digitação chegam à produção como implantações falhas. Correção: modelos Pydantic ou JSON Schema em CI.
• Arquivos renderizados legíveis por qualquer pessoa - chmod 644 em .env com senhas. Correção: 0600 de propriedade apenas para o usuário do serviço.
• Templates com entrada não confiável - SSTI se os templates incluírem conteúdo do usuário. Correção: mantenha os templates internos; nunca incorpore strings de usuário em Jinja2.

Alternativas

FAQs

Relacionado

• Noções Básicas de Automação de Infraestrutura - separação de ambientes
• Ansible - módulo template e group_vars
• Secrets Manager & SSM - resolução de segredos AWS
• Configuração e Segredos em Produção - injeção em tempo de execução
• Melhores Práticas de Automação de Infraestrutura - regras de configuração versionada

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+.