StackPractices
beginner By Mathias Paulenko

Environment Configuration Template

A template to document environment variables, secrets, endpoints, and infrastructure settings for every deployment environment.

Overview

Every application runs in more than one place. There’s a developer laptop, a staging environment that should look like production, and production itself, sometimes split across regions or clusters. Each of those environments carries its own set of values: database hosts, feature flags, API keys, memory limits, retry budgets. When those values only live in somebody’s head, in a forgotten wiki page, or scattered across three CI systems, things break in quiet ways. A deploy works in staging and falls over in production because nobody recorded that production needs QUEUE_MAX_DEPTH=5000. Somebody joining the team burns their first week guessing which endpoint is the real one. An incident drags on for an extra hour because the on-call engineer can’t tell whether CACHE_TTL was supposed to be 300 or 3000.

This template pulls everything about a service’s configuration into one document. It’s deliberately boring — tables, names, owners, dates — because boring is what you want when production is down at 3 AM. The value isn’t in the format; it’s in the discipline of keeping the thing current. Teams that maintain this document well onboard faster, debug environment-specific bugs in minutes instead of hours, and catch configuration drift before it causes an outage.

When to Use

  • Standing up a new service and giving it its first environments.
  • Onboarding a new team member or contractor who needs a map of what is deployed where.
  • Preparing a deployment, migration, or region expansion and needing a checklist of every value that differs.
  • Debugging a bug that reproduces in one environment but not another — the classic “works on my machine” investigation.
  • Auditing for configuration drift after an incident or before a compliance review.
  • Writing a runbook or disaster-recovery plan that must list every dependency and credential location.

If what you need is a procedure for bringing a new environment up from scratch, pair this template with the environment setup guide template, which covers the step-by-step provisioning side.

Prerequisites

  • Access to the deployment platform or cloud console for each environment you will document.
  • A list of the services, databases, caches, queues, and third-party integrations the application depends on.
  • Permission to view where secrets live (you document locations, not values) or a secure handoff process with the security team.
  • A naming convention for environment variables and configuration keys, or the willingness to define one as part of this work.
  • An understanding of any compliance requirements that apply to each environment — production usually has stricter rules about who can see what.

Solution

Template

1. Environment Identification

FieldDescriptionExample
Application / ServiceName of the systemPayment API
Environmentdev, staging, production, etc.production
Region / ZoneGeographic deploymentus-east-1
Cluster / InstanceWhere the app runsprod-k8s-cluster-01
Version deployedCurrent releasev2.4.1
OwnerTeam responsiblePayments team
Last reviewedDate of last update2026-11-10

2. Core Environment Variables

VariablePurposedev Valuestaging Valueproduction ValueSecret
APP_ENVRuntime environmentdevelopmentstagingproductionNo
LOG_LEVELLogging verbositydebuginfowarnNo
API_PORTPort the service listens on80808080443No
DATABASE_URLConnection string for primary databasepostgres://dev-dbpostgres://staging-dbpostgres://prod-dbYes
REDIS_URLCache connection stringredis://dev-redisredis://staging-redisredis://prod-redisYes
JWT_SECRETSecret for token signingdev-secretstaging-secretprod-secretYes
EXTERNAL_API_KEYKey for third-party integrationtest-keytest-keylive-keyYes
FEATURE_FLAG_XToggle for new featuretruetruefalseNo

3. Service Endpoints

ServiceEnvironmentURL / HostPortProtocolNotes
Applicationproductionapi.payments.example.com443HTTPSBehind load balancer
Databaseproductionprod-db.internal.example.com5432PostgreSQLPrivate subnet
Cacheproductionprod-redis.internal.example.com6379RedisPrivate subnet
Message queueproductionprod-rabbit.internal.example.com5672AMQPPrivate subnet
Object storageproductions3://prod-payments-data443HTTPSEncrypted at rest

4. Infrastructure Settings

ResourcedevstagingproductionNotes
Compute1 small container2 medium containers4 large containersAuto-scaling in production
CPU / memory0.5 vCPU / 1 GB1 vCPU / 2 GB2 vCPU / 4 GBPer container
DatabaseShared dev instanceSingle staging instanceMulti-AZ clusterWith read replicas in production
CacheSingle dev nodeSingle staging nodeClustered productionRedis cluster mode
QueueIn-processSingle staging nodeClustered productionMirrors cache topology
StorageStandard classStandard classInfrequent access tierLifecycle policy applied
NetworkPublic for dev toolsPrivate subnetPrivate subnet + NATVPN access required

5. Secrets and Credentials

Secret NameUsed ByStorage LocationRotation ScheduleLast Rotated
DATABASE_PASSWORDApplicationAWS Secrets ManagerQuarterly2026-06-01
JWT_SECRETApplicationHashiCorp VaultQuarterly2026-06-01
EXTERNAL_API_KEYIntegration serviceAzure Key VaultOn vendor rotation2026-05-15
TLS_CERTIFICATELoad balancerAWS ACMAnnual2026-04-20

6. Configuration Change Log

DateChangeAuthorReasonApproved By
2026-06-10Increased production cache cluster sizealice@example.comPrepare for flash salebob@example.com
2026-05-22Added FEATURE_FLAG_Xcarol@example.comRoll out new checkout flowdave@example.com
2026-05-01Rotated database credentialsplatform-teamQuarterly rotationsecurity-team

Explanation

A single source of truth for environment configuration reduces two kinds of cost. The obvious one is mistakes: a variable set in staging but missing in production, a secret rotated in one vault but not the other. The subtler cost is investigation time. Every “works in staging, fails in prod” bug starts with someone asking what is different between the two, and the answer either takes thirty seconds (diff two rows of this document) or two hours (read Terraform state, kubectl describe, ask three people on Slack).

The template works because it separates three things that are often conflated. Values change per environment and are mostly safe to write down. Secret locations are metadata — the document says JWT_SECRET lives in Vault under a specific path, which tells an engineer where to look without exposing anything. Change history answers the question every incident raises eventually: when did this value last change, and who approved it?

Notice what the template deliberately leaves out. It doesn’t contain actual secret values — ever. If you find yourself typing a real password or API key into a row, stop and put a vault path there instead. It also doesn’t try to replace your infrastructure-as-code. The document is a human-readable index on top of the machines’ source of truth; the section on keeping it in sync below explains how those two stay aligned. For a deeper architectural take on externalizing configuration out of the application itself, see the external configuration store pattern.

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://..."

The split in that example mirrors the split in the template: everything in the ConfigMap can appear verbatim in the document, while the Secret manifest should only ever show up as a reference to where the real values live. For how these objects actually get mounted into pods — as environment variables or as files — see the recipe on mounting ConfigMaps and Secrets in Kubernetes.

Environment Comparison Matrix

VariableDevelopmentStagingProductionNotes
DATABASE_HOSTlocalhostdb.staging.svcdb.prod.svcDifferent per env
DATABASE_PORT543254325432Same
LOG_LEVELdebuginfowarnMore verbose in dev
API_RATE_LIMIT1005001000Scales with traffic
FEATURE_FLAGSallselectiveconservativeDev turns them all on
CORS_ORIGINS*staging.example.comapp.example.comRestricted in prod
REDIS_URLlocalhost:6379redis.staging:6379redis.prod:6379Different per env
SENTRY_DSNdisabledstaging DSNprod DSNError tracking

This matrix is the part of the template you will reach for most often. During a “works in staging” investigation, scanning a row is faster than any tooling. Pay attention to the rows where the Notes column is empty and the values still differ — those are the undocumented differences that bite you. It’s also worth re-reading the matrix before every major deploy; values that made sense six months ago have a way of going stale quietly.

Secret Rotation Schedule Template

=== Secret Rotation Schedule ===

Database credentials:
  - Rotation frequency: Quarterly
  - Owner: Platform team
  - Method: AWS Secrets Manager auto-rotation
  - Last rotated: 2026-06-01
  - Next rotation: 2026-09-01

JWT signing key:
  - Rotation frequency: Every 6 months
  - Owner: Security team
  - Method: Manual with dual-key overlap
  - Last rotated: 2026-04-15
  - Next rotation: 2026-10-15

Stripe API key:
  - Rotation frequency: Annually
  - Owner: Finance engineering
  - Method: Manual via Stripe dashboard
  - Last rotated: 2026-01-10
  - Next rotation: 2027-01-10

Sentry DSN:
  - Rotation frequency: On team member departure
  - Owner: SRE team
  - Method: Manual via Sentry dashboard

Rotation schedules look like overhead until the day an employee leaves with production credentials memorized. The schedule answers three questions at a glance: who owns each secret, when it was last rotated, and what the process is. Note that the DSN entry has an event-driven trigger rather than a calendar date — not every secret rotates on a schedule.

Keeping This Document in Sync

A stale configuration document is worse than no document, because people trust it. The fix isn’t heroic discipline; it’s wiring the document into processes that already exist.

The lifecycle looks like this:

flowchart diagram: Change merged in IaC

Three habits keep the document honest:

  • Update it in the same PR that changes the configuration. If LOG_LEVEL goes from info to debug in production, that PR also edits the matrix row. Reviewers treat a missing doc update the same way they treat a missing test.
  • Review quarterly against the real state. Pull the actual ConfigMap or run terraform plan and diff it against the document. Whatever disagrees is either drift to fix or a doc error to correct — either way you win.
  • Generate what you can. Teams with heavy IaC often auto-generate the variable and endpoint tables from Terraform outputs or Helm values, leaving humans to maintain only the columns that need judgment: purposes, notes, and owners.

If your team already keeps secrets in a dedicated store, that store is your source of truth for section 5 — the document just points at it. The goal is one authoritative system per fact, with this document acting as the index that ties them together.

It also helps to name things the same way everywhere. A pattern like SERVICE_RESOURCE_PROPERTY — say PAYMENT_DB_HOST — keeps the doc, the Terraform files, and the Kubernetes manifests grep-compatible. Divergent names (DB_URL in one place, db.url in another) turn every investigation into a translation exercise.

Variants

  • Microservices environment configuration: One document per service with cross-service endpoint references, plus a shared service registry for inter-service URLs.
  • Infrastructure-as-Code environment configuration: Links to Terraform variable files or CloudFormation parameter files replace hand-maintained value columns.
  • Container environment configuration: Focus on Docker Compose files, Kubernetes ConfigMaps, and Secrets per namespace.
  • Serverless environment configuration: Document function-level variables, API Gateway settings, event source mappings, and concurrency limits.
  • Mobile app environment configuration: Document backend endpoints, API keys, and feature flags per build variant (debug, staging, release).
  • Database environment configuration: Focus on connection strings, replica endpoints, backup settings, and failover procedures.

What works

  • Keep secrets out of version control and out of this document; record vault paths instead.
  • Use the same variable names across environments — DATABASE_URL shouldn’t become DB_CONN_STRING in production.
  • Document why a value differs between environments in the Notes column, not just that it does.
  • Review and update the document after every deployment that touches configuration.
  • Separate sensitive values from non-sensitive configuration at the table level, so the doc can live somewhere broadly readable.
  • Automate generation from infrastructure-as-code where possible.
  • Include contact information for the environment owner — during an incident, “who do I ask” matters as much as “what is the value”.

Common Mistakes

  • Hard-coding environment-specific values in source code, then wondering why the same build behaves differently.
  • Storing real secrets in this document or in plain-text files beside it.
  • Updating the configuration but not the document — the number one cause of stale docs.
  • Using different variable names for the same concept in different environments.
  • Mixing configuration for unrelated services into one document nobody owns.
  • Omitting the reason for a difference, so nobody knows whether it’s intentional or drift.
  • Forgetting third-party integrations — webhooks, payment gateways, email providers all have per-environment endpoints and keys too.

Troubleshooting

  • A variable exists in staging but is missing in production: compare the variable table against the actual ConfigMap or environment manifest. The usual cause is a config change that was applied by hand in staging and never made it into IaC for production.
  • The document says one thing, the cluster says another: trust the cluster, then figure out which side drifted. If someone hot-patched production during an incident and forgot to write it down, update both the doc and IaC so it doesn’t get overwritten on the next deploy.
  • A rotation happened but the app still uses the old secret: check whether the application caches credentials at startup. Many apps need a restart or a secret-reload hook to pick up rotated values; document which behavior applies in the Notes column.
  • New team member can’t tell which endpoint is real: that’s a symptom of exactly what this template fixes. Fill in section 3 first; it’s the highest-value table for onboarding.
  • Two services disagree about a shared value: when a variable like QUEUE_URL is consumed by more than one service, decide which service’s document owns it and link to that row from the others. Duplicated facts drift.

See Also

Frequently Asked Questions

Should we store secrets in this document?

No. Store secret names, storage locations, and rotation schedules here, but keep actual values in a dedicated vault such as AWS Secrets Manager, HashiCorp Vault, or a cloud key vault. This document should tell people where to find secrets, never contain them.

How do we keep this document up to date?

Assign an owner, require doc updates in the same PR as configuration changes, and run a quarterly review that diffs the document against real state. The "update in the same PR" rule is what makes the rest sustainable.

What is the difference between environment variables and configuration files?

Environment variables are for values that change between environments or are sensitive. Configuration files work better for stable, structured settings that benefit from versioning and validation. Most real systems use both: env vars for deployment-specific values, config files for application defaults.

How do we manage configuration for multiple environments without duplication?

Use a base configuration with environment-specific overrides — Helm values files, Kustomize overlays, or a dotenv hierarchy (.env.base, .env.staging, .env.production). Keep the base in version control, keep per-environment secrets in a vault, and validate required variables in CI so a missing key fails the pipeline instead of production.

What is configuration drift and how do we prevent it?

Drift is when an environment's real state differs from its documented or declared state, usually from manual changes. Prevent it by routing all changes through IaC, restricting manual edits in production, running terraform plan or a drift detector on a schedule, and reconciling emergency manual changes back into code within a day.

How do we bootstrap a new environment?

Create the resources in IaC, generate or import secrets into the vault, deploy base infrastructure, run smoke tests against the endpoints, verify monitoring is live, then document the environment in the matrix and assign an owner. The environment setup guide template walks through the provisioning steps in more detail.

How do we version configuration changes?

Keep non-sensitive configuration in Git next to the application code, and use the change log section of this template for human-readable history. For secrets, version the metadata (name, rotation date, owner) rather than the value. When a deploy changes configuration, the same commit should show up in both places.