Plantilla de Configuración de Entornos
Una plantilla para documentar variables de entorno, secretos, endpoints y ajustes de infraestructura de cada entorno de despliegue.
Overview
Toda aplicación corre en más de un lugar. Está el portátil del desarrollador, un entorno de staging que debería parecerse a producción, y producción en sí, a veces repartida entre regiones o clusters. Cada uno de esos entornos lleva su propio conjunto de valores: hosts de base de datos, feature flags, API keys, límites de memoria, presupuestos de reintentos. Cuando esos valores solo viven en la cabeza de alguien, en una página de wiki olvidada o repartidos entre tres sistemas de CI, las cosas se rompen de forma silenciosa. Un despliegue funciona en staging y cae en producción porque nadie registró que producción necesita QUEUE_MAX_DEPTH=5000. Un recién llegado pasa su primera semana adivinando qué endpoint es el real. Una incidencia se alarga una hora extra porque el ingeniero de guardia no sabe si CACHE_TTL debería ser 300 o 3000.
Esta plantilla es un único documento que captura todo lo que un ingeniero necesita saber sobre cómo está configurado un servicio en cada entorno. Es deliberadamente aburrida: tablas, nombres, responsables, fechas. El valor no está en el formato sino en la disciplina de mantenerla al día. Los equipos que mantienen bien este documento incorporan gente más rápido, depuran errores específicos de entorno en minutos en lugar de horas y detectan la desviación de configuración antes de que provoque una caída.
When to Use
- Al configurar una aplicación o servicio nuevo y establecer sus primeros entornos.
- Al incorporar un miembro nuevo del equipo o un contratista que necesita un mapa de qué está desplegado dónde.
- Al preparar un despliegue, migración o expansión de región y necesitar una lista de cada valor que difiere.
- Al depurar un error que se reproduce en un entorno pero no en otro — la clásica investigación de “en mi máquina funciona”.
- Al auditar desviación de configuración tras una incidencia o antes de una revisión de cumplimiento.
- Al escribir un runbook o plan de recuperación ante desastres que debe listar cada dependencia y ubicación de credenciales.
Si lo que necesitas es un procedimiento para levantar un entorno nuevo desde cero, combina esta plantilla con la plantilla de guía de configuración de entorno, que cubre el aprovisionamiento paso a paso.
Prerequisites
- Acceso a la plataforma de despliegue o consola cloud de cada entorno que vas a documentar.
- Una lista de los servicios, bases de datos, cachés, colas e integraciones de terceros de los que depende la aplicación.
- Permiso para ver dónde viven los secretos (documentas ubicaciones, no valores) o un proceso de entrega seguro con el equipo de seguridad.
- Una convención de nombres para variables de entorno y claves de configuración, o la voluntad de definir una como parte de este trabajo.
- Comprensión de los requisitos de cumplimiento que aplican a cada entorno — producción suele tener reglas más estrictas sobre quién puede ver qué.
Solution
Template
1. Identificación del Entorno
| Campo | Descripción | Ejemplo |
|---|---|---|
| Aplicación / Servicio | Nombre del sistema | Payment API |
| Entorno | dev, staging, production, etc. | production |
| Región / Zona | Despliegue geográfico | us-east-1 |
| Cluster / Instancia | Dónde corre la app | prod-k8s-cluster-01 |
| Versión desplegada | Release actual | v2.4.1 |
| Responsable | Equipo responsable | Equipo de pagos |
| Última revisión | Fecha de última actualización | 2026-11-10 |
2. Variables de Entorno Principales
| Variable | Propósito | Valor dev | Valor staging | Valor production | Secreto |
|---|---|---|---|---|---|
APP_ENV | Entorno de ejecución | 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 conexión a la base de datos principal | postgres://dev-db | postgres://staging-db | postgres://prod-db | Sí |
REDIS_URL | Cadena de conexión al caché | redis://dev-redis | redis://staging-redis | redis://prod-redis | Sí |
JWT_SECRET | Secreto para firma de tokens | dev-secret | staging-secret | prod-secret | Sí |
EXTERNAL_API_KEY | Clave para integración de terceros | test-key | test-key | live-key | Sí |
FEATURE_FLAG_X | Interruptor para nueva feature | true | true | false | No |
3. Endpoints de Servicios
| Servicio | Entorno | URL / Host | Puerto | Protocolo | Notas |
|---|---|---|---|---|---|
| Aplicación | production | api.payments.example.com | 443 | HTTPS | Detrás del balanceador de carga |
| Base de datos | production | prod-db.internal.example.com | 5432 | PostgreSQL | Subred privada |
| Caché | 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. Configuración de Infraestructura
| Recurso | dev | staging | production | Notas |
|---|---|---|---|---|
| Cómputo | 1 contenedor pequeño | 2 contenedores medianos | 4 contenedores grandes | Auto-scaling en producción |
| CPU / memoria | 0.5 vCPU / 1 GB | 1 vCPU / 2 GB | 2 vCPU / 4 GB | Por contenedor |
| Base de datos | Instancia compartida dev | Instancia única staging | Cluster Multi-AZ | Con réplicas de lectura en producción |
| Caché | 1 nodo dev | 1 nodo staging | Cluster en producción | Modo cluster Redis |
| Cola | En proceso | 1 nodo staging | Cluster en producción | Replica la topología del caché |
| Almacenamiento | Clase estándar | Clase estándar | Tier de acceso infrecuente | Política de ciclo de vida aplicada |
| Red | Pública para herramientas dev | Subred privada | Subred privada + NAT | Acceso VPN requerido |
5. Secretos y Credenciales
| Nombre del Secreto | Usado Por | Ubicación de Almacenamiento | Programa de Rotación | Última Rotación |
|---|---|---|---|---|
DATABASE_PASSWORD | Aplicación | AWS Secrets Manager | Trimestral | 2026-06-01 |
JWT_SECRET | Aplicación | HashiCorp Vault | Trimestral | 2026-06-01 |
EXTERNAL_API_KEY | Servicio de integración | Azure Key Vault | En rotación del proveedor | 2026-05-15 |
TLS_CERTIFICATE | Balanceador de carga | AWS ACM | Anual | 2026-04-20 |
6. Registro de Cambios de Configuración
| Fecha | Cambio | Autor | Razón | Aprobado Por |
|---|---|---|---|---|
| 2026-06-10 | Aumento del cluster de caché en producción | 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 | Rotación de credenciales de base de datos | platform-team | Rotación trimestral | security-team |
Explanation
Una única fuente de verdad para la configuración de entornos reduce dos tipos de coste. El obvio son los errores: una variable puesta en staging pero ausente en producción, un secreto rotado en un vault pero no en el otro. El coste más sutil es el tiempo de investigación. Todo error de “funciona en staging, falla en prod” empieza con alguien preguntando qué es diferente entre ambos, y la respuesta lleva treinta segundos (comparar dos filas de este documento) o dos horas (leer el estado de Terraform, hacer kubectl describe, preguntar a tres personas en Slack).
La plantilla funciona porque separa tres cosas que suelen mezclarse. Los valores cambian por entorno y en su mayoría se pueden escribir sin problema. Las ubicaciones de secretos son metadatos — el documento dice que JWT_SECRET vive en Vault bajo una ruta concreta, lo que le dice a un ingeniero dónde mirar sin exponer nada. El historial de cambios responde la pregunta que toda incidencia acaba planteando: ¿cuándo cambió este valor por última vez y quién lo aprobó?
Fíjate en lo que la plantilla deja fuera deliberadamente. No contiene valores de secretos reales — nunca. Si te encuentras escribiendo una contraseña o API key real en una fila, para y pon una ruta del vault en su lugar. Tampoco intenta reemplazar tu infraestructura como código. El documento es un índice legible por humanos sobre la fuente de verdad de las máquinas; la sección sobre mantenerlo sincronizado explica cómo ambos se alinean. Para una visión arquitectónica más profunda sobre sacar la configuración fuera de la aplicación, mira el patrón de almacén externo de configuración.
Kubernetes ConfigMap and Secret Example
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://..."
La división de ese ejemplo refleja la división de la plantilla: todo lo que está en el ConfigMap puede aparecer literalmente en el documento, mientras que el manifiesto Secret solo debería aparecer como una referencia a dónde viven los valores reales. Para ver cómo estos objetos se montan realmente en los pods — como variables de entorno o como archivos — mira la receta sobre montar ConfigMaps y Secrets en Kubernetes.
Environment Comparison Matrix
| Variable | Desarrollo | Staging | Producción | Notas |
|---|---|---|---|---|
| DATABASE_HOST | localhost | db.staging.svc | db.prod.svc | Diferente por entorno |
| DATABASE_PORT | 5432 | 5432 | 5432 | Igual |
| LOG_LEVEL | debug | info | warn | Más verbose en dev |
| API_RATE_LIMIT | 100 | 500 | 1000 | Escala con el tráfico |
| 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 |
Esta matriz es la parte de la plantilla que más usarás. Durante una investigación de “funciona en staging”, escanear una fila es más rápido que cualquier herramienta. Presta atención a las filas donde la columna de Notas está vacía y los valores aún así difieren — esas son las diferencias no documentadas que te muerden. También vale la pena releer la matriz antes de cada despliegue importante; los valores que tenían sentido hace seis meses tienden a quedar obsoletos sin hacer ruido.
Secret Rotation Schedule Template
=== Calendario de Rotación de Secretos ===
Credenciales de base de datos:
- Frecuencia de rotación: Trimestral
- Responsable: Equipo de plataforma
- Método: Auto-rotación de AWS Secrets Manager
- Última rotación: 2026-06-01
- Próxima rotación: 2026-09-01
Clave de firma JWT:
- Frecuencia de rotación: Cada 6 meses
- Responsable: Equipo de seguridad
- Método: Manual con superposición de doble clave
- Última rotación: 2026-04-15
- Próxima rotación: 2026-10-15
Stripe API key:
- Frecuencia de rotación: Anual
- Responsable: Ingeniería de finanzas
- Método: Manual vía dashboard de Stripe
- Última rotación: 2026-01-10
- Próxima rotación: 2027-01-10
Sentry DSN:
- Frecuencia de rotación: A la salida de un miembro del equipo
- Responsable: Equipo SRE
- Método: Manual vía dashboard de Sentry
Los calendarios de rotación parecen burocracia hasta el día en que alguien se va de la empresa con las credenciales de producción memorizadas. El calendario responde tres preguntas de un vistazo: quién es responsable de cada secreto, cuándo se rotó por última vez y cuál es el proceso. Fíjate en que la entrada del DSN tiene un disparador por evento en lugar de una fecha — no todo secreto rota por calendario.
Keeping This Document in Sync
Un documento de configuración desactualizado es peor que no tener documento, porque la gente confía en él. La solución no es disciplina heroica; es conectar el documento a procesos que ya existen.
El ciclo de vida es así:
Tres hábitos mantienen el documento honesto:
- Actualízalo en el mismo PR que cambia la configuración. Si
LOG_LEVELpasa deinfoadebugen producción, ese PR también edita la fila de la matriz. Los revisores tratan una actualización de doc ausente igual que un test ausente. - Revisa trimestralmente contra el estado real. Saca el ConfigMap real o ejecuta
terraform plany compáralo con el documento. Lo que discrepe es o desviación por corregir o un error del doc por arreglar — en ambos casos ganas. - Genera lo que puedas. Los equipos con mucho IaC suelen autogenerar las tablas de variables y endpoints desde outputs de Terraform o values de Helm, dejando a los humanos solo las columnas que requieren criterio: propósitos, notas y responsables.
Si tu equipo ya guarda los secretos en un almacén dedicado, ese almacén es tu fuente de verdad para la sección 5 — el documento solo apunta a él. El objetivo es un sistema autoritativo por dato, con este documento actuando como el índice que los une.
Una cosa más que se paga sola rápido: una convención de nombres escrita. Elige un patrón como SERVICIO_RECURSO_PROPIEDAD y mantenlo en todos los entornos. Cuando el doc, los archivos de Terraform y los manifiestos de Kubernetes usan nombres idénticos, buscar dónde se define un valor es trivial. Cuando los nombres divergen — DB_URL en Terraform, DATABASE_URL en el ConfigMap, db.url en un properties — toda investigación empieza con un ejercicio de traducción.
Variants
- Configuración de entornos para microservicios: Un documento por servicio con referencias cruzadas a endpoints de otros servicios, más un registro de servicios compartido para las URLs inter-servicio.
- Configuración de entornos con infraestructura como código: Enlaces a archivos de variables de Terraform o parámetros de CloudFormation reemplazan las columnas de valores mantenidas a mano.
- Configuración de entornos para contenedores: Enfoque en archivos Docker Compose, ConfigMaps y Secrets de Kubernetes por namespace.
- Configuración de entornos serverless: Documenta variables por función, ajustes de API Gateway, mapeos de fuentes de eventos y límites de concurrencia.
- Configuración de entornos para app móvil: Documenta endpoints de backend, API keys y feature flags por variante de build (debug, staging, release).
- Configuración de entornos para base de datos: Enfoque en cadenas de conexión, endpoints de réplicas, ajustes de backup y procedimientos de failover.
What works
- Mantén los secretos fuera del control de versiones y fuera de este documento; registra rutas del vault en su lugar.
- Usa los mismos nombres de variables en todos los entornos —
DATABASE_URLno debería convertirse enDB_CONN_STRINGen producción. - Documenta por qué un valor difiere entre entornos en la columna de Notas, no solo que difiere.
- Revisa y actualiza el documento tras cada despliegue que toque configuración.
- Separa valores sensibles de la configuración no sensible a nivel de tabla, para que el doc pueda vivir en un sitio legible por todos.
- Automatiza la generación desde infraestructura como código donde sea posible.
- Incluye información de contacto del responsable del entorno — durante una incidencia, “a quién pregunto” importa tanto como “cuál es el valor”.
Common Mistakes
- Hard-codear valores específicos de entorno en el código fuente, y luego preguntarse por qué el mismo build se comporta distinto.
- Guardar secretos reales en este documento o en archivos de texto plano junto a él.
- Actualizar la configuración pero no el documento — la causa número uno de docs obsoletos.
- Usar nombres de variables distintos para el mismo concepto en distintos entornos.
- Mezclar configuración de servicios no relacionados en un documento que nadie posee.
- Omitir la razón de una diferencia, de modo que nadie sabe si es intencional o desviación.
- Olvidar las integraciones de terceros — webhooks, pasarelas de pago, proveedores de email también tienen endpoints y claves por entorno.
Troubleshooting
- Una variable existe en staging pero falta en producción: compara la tabla de variables contra el ConfigMap o manifiesto de entorno real. La causa habitual es un cambio de configuración aplicado a mano en staging que nunca llegó a IaC para producción.
- El documento dice una cosa, el cluster dice otra: confía en el cluster y luego averigua qué lado se desvió. Si alguien parcheó producción en caliente durante una incidencia y olvidó anotarlo, actualiza tanto el doc como IaC para que no se sobrescriba en el próximo despliegue.
- Hubo una rotación pero la app sigue usando el secreto viejo: comprueba si la aplicación cachea credenciales al arrancar. Muchas apps necesitan reinicio o un hook de recarga de secretos para recoger valores rotados; documenta qué comportamiento aplica en la columna de Notas.
- Un miembro nuevo no sabe qué endpoint es el real: es el síntoma de exactamente lo que esta plantilla arregla. Rellena la sección 3 primero; es la tabla de mayor valor para la incorporación.
- Dos servicios discrepan sobre un valor compartido: cuando una variable como
QUEUE_URLla consumen varios servicios, decide qué documento de servicio la posee y enlaza a esa fila desde los demás. Los datos duplicados se desvían.
See Also
Preguntas frecuentes
¿Debemos guardar secretos en este documento?
No. Guarda aquí los nombres de secretos, ubicaciones de almacenamiento y calendarios de rotación, pero mantén los valores reales en un vault dedicado como AWS Secrets Manager, HashiCorp Vault o un key vault en la nube. Este documento debe decir a la gente dónde encontrar los secretos, nunca contenerlos.
¿Cómo mantenemos este documento actualizado?
Asigna un responsable, exige actualizaciones del doc en el mismo PR que los cambios de configuración, y ejecuta una revisión trimestral que compare el documento con el estado real. La regla de "actualizar en el mismo PR" es lo que hace sostenible todo lo demás.
¿Cuál es la diferencia entre variables de entorno y archivos de configuración?
Las variables de entorno son para valores que cambian entre entornos o son sensibles. Los archivos de configuración funcionan mejor para ajustes estables y estructurados que se benefician de versionado y validación. La mayoría de sistemas reales usan ambos: variables de entorno para valores específicos del despliegue, archivos de configuración para los valores por defecto de la aplicación.
¿Cómo gestionamos la configuración de múltiples entornos sin duplicación?
Usa una configuración base con sobrescrituras por entorno — archivos values de Helm, overlays de Kustomize o una jerarquía dotenv (.env.base, .env.staging, .env.production). Mantén la base en control de versiones, los secretos por entorno en un vault, y valida las variables requeridas en CI para que una clave ausente falle la pipeline en lugar de producción.
¿Qué es la desviación de configuración y cómo la prevenimos?
La desviación es cuando el estado real de un entorno difiere de su estado documentado o declarado, normalmente por cambios manuales. Prevénla enrutando todos los cambios por IaC, restringiendo ediciones manuales en producción, ejecutando terraform plan o un detector de desviación periódicamente, y reconciliando los cambios manuales de emergencia de vuelta al código en un día.
¿Cómo inicializamos un entorno nuevo?
Crea los recursos en IaC, genera o importa los secretos al vault, despliega la infraestructura base, ejecuta smoke tests contra los endpoints, verifica que el monitoreo está activo, documenta el entorno en la matriz y asigna un responsable. La plantilla de guía de configuración de entorno recorre los pasos de aprovisionamiento con más detalle.
¿Cómo versionamos los cambios de configuración?
Mantén la configuración no sensible en Git junto al código de la aplicación, y usa la sección de registro de cambios de esta plantilla como historial legible. Para secretos, versiona los metadatos (nombre, fecha de rotación, responsable) en lugar del valor. Cuando un despliegue cambia configuración, el mismo commit debería aparecer en ambos sitios.
Recursos Relacionados
Plantilla de Guía de Configuración de Entorno
Una plantilla para documentar cómo configurar entornos de desarrollo local, staging y producción de forma consistente y reproducible.
DocPlantilla de Runbook
Una plantilla reutilizable para runbooks operacionales: respuesta a incidentes, procedimientos de deployment y tareas rutinarias.
DocPlantilla de Checklist de Despliegue
Una checklist de verificación lista para copiar que asegura despliegues de producción seguros, desde los tests previos hasta el monitoreo posterior.
PatternPatrón de Almacén Externo de Configuración
Centraliza la configuración de aplicaciones fuera de los artefactos de despliegue para soportar actualizaciones en vivo, separación de entornos y cambios auditados.
RecipeMontar ConfigMaps y Secrets en Pods de Kubernetes
Cómo montar ConfigMaps y Secrets en pods de Kubernetes usando variables de entorno, volúmenes, volúmenes proyectados y gestores externos de secrets.
GuideGuía de Gestión de Configuración en Kubernetes
Gestión de configuración en Kubernetes: ConfigMaps, Secrets, External Secrets Operator, sealed secrets, inyección env, montajes y rotación.