StackPractices
beginner Por Mathias Paulenko

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

CampoDescripciónEjemplo
Aplicación / ServicioNombre del sistemaPayment API
Entornodev, staging, production, etc.production
Región / ZonaDespliegue geográficous-east-1
Cluster / InstanciaDónde corre la appprod-k8s-cluster-01
Versión desplegadaRelease actualv2.4.1
ResponsableEquipo responsableEquipo de pagos
Última revisiónFecha de última actualización2026-11-10

2. Variables de Entorno Principales

VariablePropósitoValor devValor stagingValor productionSecreto
APP_ENVEntorno de ejecucióndevelopmentstagingproductionNo
LOG_LEVELVerbosidad de logsdebuginfowarnNo
API_PORTPuerto donde escucha el servicio80808080443No
DATABASE_URLCadena de conexión a la base de datos principalpostgres://dev-dbpostgres://staging-dbpostgres://prod-dbSí
REDIS_URLCadena de conexión al cachéredis://dev-redisredis://staging-redisredis://prod-redisSí
JWT_SECRETSecreto para firma de tokensdev-secretstaging-secretprod-secretSí
EXTERNAL_API_KEYClave para integración de tercerostest-keytest-keylive-keySí
FEATURE_FLAG_XInterruptor para nueva featuretruetruefalseNo

3. Endpoints de Servicios

ServicioEntornoURL / HostPuertoProtocoloNotas
Aplicaciónproductionapi.payments.example.com443HTTPSDetrás del balanceador de carga
Base de datosproductionprod-db.internal.example.com5432PostgreSQLSubred privada
Cachéproductionprod-redis.internal.example.com6379RedisSubred privada
Cola de mensajesproductionprod-rabbit.internal.example.com5672AMQPSubred privada
Almacenamiento de objetosproductions3://prod-payments-data443HTTPSCifrado en reposo

4. Configuración de Infraestructura

RecursodevstagingproductionNotas
Cómputo1 contenedor pequeño2 contenedores medianos4 contenedores grandesAuto-scaling en producción
CPU / memoria0.5 vCPU / 1 GB1 vCPU / 2 GB2 vCPU / 4 GBPor contenedor
Base de datosInstancia compartida devInstancia única stagingCluster Multi-AZCon réplicas de lectura en producción
Caché1 nodo dev1 nodo stagingCluster en producciónModo cluster Redis
ColaEn proceso1 nodo stagingCluster en producciónReplica la topología del caché
AlmacenamientoClase estándarClase estándarTier de acceso infrecuentePolítica de ciclo de vida aplicada
RedPública para herramientas devSubred privadaSubred privada + NATAcceso VPN requerido

5. Secretos y Credenciales

Nombre del SecretoUsado PorUbicación de AlmacenamientoPrograma de RotaciónÚltima Rotación
DATABASE_PASSWORDAplicaciónAWS Secrets ManagerTrimestral2026-06-01
JWT_SECRETAplicaciónHashiCorp VaultTrimestral2026-06-01
EXTERNAL_API_KEYServicio de integraciónAzure Key VaultEn rotación del proveedor2026-05-15
TLS_CERTIFICATEBalanceador de cargaAWS ACMAnual2026-04-20

6. Registro de Cambios de Configuración

FechaCambioAutorRazónAprobado Por
2026-06-10Aumento del cluster de caché en producciónalice@example.comPreparar venta flashbob@example.com
2026-05-22Agregado FEATURE_FLAG_Xcarol@example.comDesplegar nuevo flujo de checkoutdave@example.com
2026-05-01Rotación de credenciales de base de datosplatform-teamRotación trimestralsecurity-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

VariableDesarrolloStagingProducciónNotas
DATABASE_HOSTlocalhostdb.staging.svcdb.prod.svcDiferente por entorno
DATABASE_PORT543254325432Igual
LOG_LEVELdebuginfowarnMás verbose en dev
API_RATE_LIMIT1005001000Escala con el tráfico
FEATURE_FLAGStodasselectivasconservadorasDev habilita todas
CORS_ORIGINS*staging.example.comapp.example.comRestringido en prod
REDIS_URLlocalhost:6379redis.staging:6379redis.prod:6379Diferente por entorno
SENTRY_DSNdeshabilitadoDSN stagingDSN prodTracking 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í:

flowchart diagram: Cambio mergeado en IaC

Tres hábitos mantienen el documento honesto:

  • Actualízalo en el mismo PR que cambia la configuración. Si LOG_LEVEL pasa de info a debug en 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 plan y 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_URL no debería convertirse en DB_CONN_STRING en 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_URL la 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.