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
| Field | Description | Example |
|---|---|---|
| Application / Service | Name of the system | Payment API |
| Environment | dev, staging, production, etc. | production |
| Region / Zone | Geographic deployment | us-east-1 |
| Cluster / Instance | Where the app runs | prod-k8s-cluster-01 |
| Version deployed | Current release | v2.4.1 |
| Owner | Team responsible | Payments team |
| Last reviewed | Date of last update | 2026-11-10 |
2. Core Environment Variables
| Variable | Purpose | dev Value | staging Value | production Value | Secret |
|---|---|---|---|---|---|
APP_ENV | Runtime environment | development | staging | production | No |
LOG_LEVEL | Logging verbosity | debug | info | warn | No |
API_PORT | Port the service listens on | 8080 | 8080 | 443 | No |
DATABASE_URL | Connection string for primary database | postgres://dev-db | postgres://staging-db | postgres://prod-db | Yes |
REDIS_URL | Cache connection string | redis://dev-redis | redis://staging-redis | redis://prod-redis | Yes |
JWT_SECRET | Secret for token signing | dev-secret | staging-secret | prod-secret | Yes |
EXTERNAL_API_KEY | Key for third-party integration | test-key | test-key | live-key | Yes |
FEATURE_FLAG_X | Toggle for new feature | true | true | false | No |
3. Service Endpoints
| Service | Environment | URL / Host | Port | Protocol | Notes |
|---|---|---|---|---|---|
| Application | production | api.payments.example.com | 443 | HTTPS | Behind load balancer |
| Database | production | prod-db.internal.example.com | 5432 | PostgreSQL | Private subnet |
| Cache | production | prod-redis.internal.example.com | 6379 | Redis | Private subnet |
| Message queue | production | prod-rabbit.internal.example.com | 5672 | AMQP | Private subnet |
| Object storage | production | s3://prod-payments-data | 443 | HTTPS | Encrypted at rest |
4. Infrastructure Settings
| Resource | dev | staging | production | Notes |
|---|---|---|---|---|
| Compute | 1 small container | 2 medium containers | 4 large containers | Auto-scaling in production |
| CPU / memory | 0.5 vCPU / 1 GB | 1 vCPU / 2 GB | 2 vCPU / 4 GB | Per container |
| Database | Shared dev instance | Single staging instance | Multi-AZ cluster | With read replicas in production |
| Cache | Single dev node | Single staging node | Clustered production | Redis cluster mode |
| Queue | In-process | Single staging node | Clustered production | Mirrors cache topology |
| Storage | Standard class | Standard class | Infrequent access tier | Lifecycle policy applied |
| Network | Public for dev tools | Private subnet | Private subnet + NAT | VPN access required |
5. Secrets and Credentials
| Secret Name | Used By | Storage Location | Rotation Schedule | Last Rotated |
|---|---|---|---|---|
DATABASE_PASSWORD | Application | AWS Secrets Manager | Quarterly | 2026-06-01 |
JWT_SECRET | Application | HashiCorp Vault | Quarterly | 2026-06-01 |
EXTERNAL_API_KEY | Integration service | Azure Key Vault | On vendor rotation | 2026-05-15 |
TLS_CERTIFICATE | Load balancer | AWS ACM | Annual | 2026-04-20 |
6. Configuration Change Log
| Date | Change | Author | Reason | Approved By |
|---|---|---|---|---|
| 2026-06-10 | Increased production cache cluster size | alice@example.com | Prepare for flash sale | bob@example.com |
| 2026-05-22 | Added FEATURE_FLAG_X | carol@example.com | Roll out new checkout flow | dave@example.com |
| 2026-05-01 | Rotated database credentials | platform-team | Quarterly rotation | security-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
| Variable | Development | Staging | Production | Notes |
|---|---|---|---|---|
| DATABASE_HOST | localhost | db.staging.svc | db.prod.svc | Different per env |
| DATABASE_PORT | 5432 | 5432 | 5432 | Same |
| LOG_LEVEL | debug | info | warn | More verbose in dev |
| API_RATE_LIMIT | 100 | 500 | 1000 | Scales with traffic |
| FEATURE_FLAGS | all | selective | conservative | Dev turns them all on |
| CORS_ORIGINS | * | staging.example.com | app.example.com | Restricted in prod |
| REDIS_URL | localhost:6379 | redis.staging:6379 | redis.prod:6379 | Different per env |
| SENTRY_DSN | disabled | staging DSN | prod DSN | Error 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:
Three habits keep the document honest:
- Update it in the same PR that changes the configuration. If
LOG_LEVELgoes frominfotodebugin 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 planand 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_URLshouldn’t becomeDB_CONN_STRINGin 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_URLis 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.
Related Resources
Environment Setup Guide Template
A template for documenting how to set up local development, staging, and production environments consistently and reproducibly.
DocRunbook Template
A reusable template for operational runbooks: incident response, deployment procedures, and routine tasks.
DocDeployment Checklist Template
A copy-paste verification checklist for safe production deployments, from pre-merge tests to post-release monitoring.
PatternExternal Configuration Store Pattern
Centralize application configuration outside deployment artifacts to support live updates, environment separation, and audited changes.
RecipeMount Configs and Secrets into Kubernetes Pods
How to mount ConfigMaps and Secrets into Kubernetes pods using env vars, volumes, projected volumes, and external secret managers.
GuideKubernetes Config Management Guide
Kubernetes configuration management: ConfigMaps, Secrets, External Secrets Operator, sealed secrets, env injection, mounts, and rotation.