Plantilla de Configuracion de Entornos

Descripcion General

Toda aplicacion se ejecuta en multiples entornos como desarrollo, staging y produccion. Cada entorno tiene su propia configuracion, endpoints, secretos y ajustes de infraestructura. Esta plantilla ayuda a los equipos a documentar esos ajustes en un solo lugar, facilitando la incorporacion, la depuracion y la recuperacion ante desastres.

Cuando Usar

• For alternatives, see Blue-Green Deployment.

• Configurar una nueva aplicacion o servicio.

• Incorporar un nuevo miembro del equipo o contratista.

• Preparar un plan de despliegue o migracion.

• Solucionar errores especificos de un entorno.

• Auditar la desviacion de configuracion entre entornos.

• Crear un runbook para respuesta a incidentes.

Prerequisitos

• Acceso a la plataforma de despliegue o consola cloud.
• Lista de servicios, bases de datos e integraciones de terceros que usa la aplicacion.
• Permiso para ver secretos y credenciales, o un proceso de entrega seguro.
• Una convencion de nombres para variables de entorno y claves de configuracion.
• Comprension de los requisitos de cumplimiento y seguridad para cada entorno.

Solucion

Plantilla

1. Identificacion del Entorno

Campo	Descripcion	Ejemplo
Aplicacion / Servicio	Nombre del sistema	Payment API
Entorno	dev, staging, production, etc.	production
Region / Zona	Despliegue geografico	us-east-1
Cluster / Instancia	Donde corre la app	prod-k8s-cluster-01
Version desplegada	Release actual	v2.4.1
Dueno	Equipo responsable	Equipo de pagos
Ultima revision	Fecha de ultima actualizacion	2026-06-27

2. Variables de Entorno Principales

Variable	Proposito	Valor dev	Valor staging	Valor production	Secreto
APP_ENV	Entorno de ejecucion	development	staging	production	No
LOG_LEVEL	Verbosidad de logs	debug	info	warn	No
API_PORT	Puerto donde escucha el servicio	8080	8080	443	No
DATABASE_URL	Cadena de conexion a la base de datos principal	postgres://dev-db	postgres://staging-db	postgres://prod-db	Si
REDIS_URL	Cadena de conexion al cache	redis://dev-redis	redis://staging-redis	redis://prod-redis	Si
JWT_SECRET	Secreto para firma de tokens	dev-secret	staging-secret	prod-secret	Si
EXTERNAL_API_KEY	Clave para integracion de terceros	test-key	test-key	live-key	Si
FEATURE_FLAG_X	Interruptor para nueva feature	true	true	false	No

3. Endpoints de Servicios

Servicio	Entorno	URL / Host	Puerto	Protocolo	Notas
Aplicacion	production	api.payments.example.com	443	HTTPS	Detras del load balancer
Base de datos	production	prod-db.internal.example.com	5432	PostgreSQL	Subred privada
Cache	production	prod-redis.internal.example.com	6379	Redis	Subred privada
Cola de mensajes	production	prod-rabbit.internal.example.com	5672	AMQP	Subred privada
Almacenamiento de objetos	production	s3://prod-payments-data	443	HTTPS	Cifrado en reposo

4. Configuracion de Infraestructura

Recurso	dev/test	production	Notas
Computo	1 contenedor pequeno	4 contenedores grandes	Auto-scaling en production
CPU / memoria	0.5 vCPU / 1 GB	2 vCPU / 4 GB	Por contenedor
Base de datos	Instancia compartida dev	Cluster Multi-AZ	Con replicas de lectura en production
Cache	1 nodo	3 nodos	Modo cluster Redis
Cola de mensajes	1 nodo	3 nodos	Misma configuracion
Almacenamiento	Clase estandar	Tier de acceso infrecuente	Politica de ciclo de vida aplicada
Red	Publica para herramientas dev	Subred privada + NAT	Acceso VPN requerido

5. Secretos y Credenciales

Nombre del Secreto	Usado Por	Ubicacion de Almacenamiento	Programa de Rotacion	Ultima Rotacion
DATABASE_PASSWORD	Aplicacion	AWS Secrets Manager	Trimestral	2026-06-01
JWT_SECRET	Aplicacion	HashiCorp Vault	Trimestral	2026-06-01
EXTERNAL_API_KEY	Servicio de integracion	Azure Key Vault	En rotacion del proveedor	2026-05-15
TLS_CERTIFICATE	Load balancer	AWS ACM	Anual	2026-04-20

6. Registro de Cambios de Configuracion

Fecha	Cambio	Autor	Razon	Aprobado Por
2026-06-10	Aumento del cluster de cache en produccion	alice@example.com	Preparar venta flash	bob@example.com
2026-05-22	Agregado FEATURE_FLAG_X	carol@example.com	Desplegar nuevo flujo de checkout	dave@example.com
2026-05-01	Rotacion de credenciales de base de datos	platform-team	Rotacion trimestral	security-team

Explicacion

Una unica fuente de verdad para la configuracion de entornos reduce la confusion y los errores. Cuando las variables, endpoints y secretos estan documentados, los equipos pueden desplegar mas rapido, depurar problemas entre entornos y recuperarse de incidentes sin adivinar. La plantilla tambien ayuda a identificar diferencias entre entornos, una fuente comun de errores en produccion.

Ejemplo de ConfigMap y Secret en Kubernetes

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
  namespace: production
data:
  DATABASE_HOST: "db.production.svc.cluster.local"
  DATABASE_PORT: "5432"
  REDIS_URL: "redis://redis.production.svc.cluster.local:6379"
  LOG_LEVEL: "info"
  FEATURE_FLAGS: "checkout-v2,search-v3"
  API_RATE_LIMIT: "1000"
  CORS_ORIGINS: "https://app.example.com,https://admin.example.com"
---
apiVersion: v1
kind: Secret
metadata:
  name: app-secrets
  namespace: production
type: Opaque
stringData:
  DATABASE_PASSWORD: "rotated-2026-06"
  JWT_SECRET: "rotated-2026-06"
  STRIPE_API_KEY: "sk_live_..."
  SENTRY_DSN: "https://..."

Matriz de Comparacion de Entornos

Variable	Desarrollo	Staging	Produccion	Notas
DATABASE_HOST	localhost	db.staging.svc	db.prod.svc	Diferente por entorno
DATABASE_PORT	5432	5432	5432	Igual
LOG_LEVEL	debug	info	warn	Mas verbose en dev
API_RATE_LIMIT	100	500	1000	Escala con trafico
FEATURE_FLAGS	todas	selectivas	conservadoras	Dev habilita todas
CORS_ORIGINS	*	staging.example.com	app.example.com	Restringido en prod
REDIS_URL	localhost:6379	redis.staging:6379	redis.prod:6379	Diferente por entorno
SENTRY_DSN	deshabilitado	DSN staging	DSN prod	Tracking de errores

Plantilla de Calendario de Rotacion de Secretos

=== Calendario de Rotacion de Secretos ===

Credenciales de base de datos:
  - Frecuencia de rotacion: Trimestral
  - Responsable: Equipo de plataforma
  - Metodo: Auto-rotacion de AWS Secrets Manager
  - Ultima rotacion: 2026-06-01
  - Proxima rotacion: 2026-09-01

Clave de firma JWT:
  - Frecuencia de rotacion: Cada 6 meses
  - Responsable: Equipo de seguridad
  - Metodo: Manual con superposicion de doble clave
  - Ultima rotacion: 2026-04-15
  - Proxima rotacion: 2026-10-15

Stripe API key:
  - Frecuencia de rotacion: Anual
  - Responsable: Ingenieria de finanzas
  - Metodo: Manual via dashboard de Stripe
  - Ultima rotacion: 2026-01-10
  - Proxima rotacion: 2027-01-10

Sentry DSN:
  - Frecuencia de rotacion: Al salida de miembro del equipo
  - Responsable: Equipo SRE
  - Metodo: Manual via dashboard de Sentry

Variantes

• Configuracion de entornos para microservicios: Un documento por servicio con referencias cruzadas a endpoints de otros servicios.
• Configuracion de entornos con infraestructura como codigo: Enlaces a archivos de variables de Terraform o CloudFormation.
• Configuracion de entornos para contenedores: Enfoque en Docker compose, Kubernetes ConfigMaps y Secrets.
• Configuracion de entornos serverless: Documenta variables a nivel de funcion, ajustes de API Gateway y fuentes de eventos.
• Configuracion de entornos para app movil: Documenta endpoints backend, API keys y feature flags por variante de build.
• Configuracion de entornos para base de datos: Enfoque en cadenas de conexion, endpoints de replicas y ajustes de backup.

Lo que funciona

• Manten los secretos fuera del control de versiones y almacenalos en un vault seguro.
• Usa los mismos nombres de variables en todos los entornos cuando sea posible.
• Documenta por que un valor difiere entre entornos.
• Revisa y actualiza el documento despues de cada despliegue o cambio de infraestructura mayor.
• Separa valores sensibles de la configuracion no sensible.
• Automatiza la generacion de este documento desde infraestructura como codigo cuando sea posible.
• Usa una convencion de nombres consistente para variables de entorno.
• Incluye informacion de contacto del dueno del entorno.

Errores Comunes

• Hard-codear valores especificos del entorno en el codigo fuente.
• Almacenar secretos en texto plano o archivos sin cifrar.
• No actualizar el documento despues de cambios de configuracion.
• Usar nombres de variables diferentes para el mismo concepto en distintos entornos.
• Mezclar configuracion de multiples entornos en un solo archivo.
• Omitir la razon de las diferencias entre entornos.
• No incluir endpoints o credenciales de servicios de terceros.

Troubleshooting

• Pipeline fails silently: enable verbose logging and store pipeline artifacts between stages so you can inspect the exact state that failed.
• Container crashes on startup: check that environment variables, secrets, and config files are mounted correctly. Read the first 50 lines of logs before scaling replicas.
• Deployment rolls back repeatedly: verify health checks, resource limits, and startup probes. A failing readiness probe is a common cause of rolling restarts.
• Slow CI builds: cache dependencies and docker layers. Split large test suites into parallel jobs to reduce wall-clock time.
• Drift between environments: use infrastructure-as-code and immutable artifacts.

Notas de Producción

• Despliega gradualmente usando canary o blue-green para detectar regresiones temprano.
• Configura alertas para errores, latencia p99 y tasa de fallos antes de habilitar en producción.
• Documenta el rollback en el runbook; prueba el procedimiento en staging al menos una vez por trimestre.
• Revisa logs estructurados con correlation IDs para trazar requests end-to-end en incidentes.

Puntos Clave

• Aplica plantilla de configuracion de entornos cuando necesites una solución práctica para tu caso de uso.
• Monitorea el rendimiento después de implementar; mide latencia, errores y uso de recursos antes y después.
• Revisa la sección de Troubleshooting ante errores comunes; la mayoría tienen causa raíz documentada con solución.
• Mantén dependencias actualizadas y ejecuta tests en CI para prevenir regresiones en producción.

Errores Comunes en Producción

• Dejar campos requeridos vacíos o usar respuestas vagas de una palabra.
• Llenar el documento una vez y nunca actualizarlo cuando cambia el alcance o las decisiones.
• Guardar el documento donde el equipo no lo busque durante incidentes o revisiones.
• No asignar un responsable, fecha límite o cadencia de revisión.
• Copiar texto base sin eliminar secciones que no aplican.
• Saltar el control de versiones, lo que impide rollback y responsabilidad.
• No vincular el documento con decisiones relacionadas o acciones de seguimiento.
• Evitar revisiones trimestrales que retirarían secciones obsoletas o sin uso.