Managing Environment Configurations
Overview
Manage application configurations across development, staging, and production environments using .env files, Kubernetes ConfigMaps/Secrets, SSM Parameter Store, and cloud-native configuration services. Enforce consistency, prevent configuration drift, and implement safe promotion workflows between environments.
Prerequisites
- Access to all target environments (dev, staging, production)
- Configuration management tool or pattern identified (dotenv, ConfigMaps, SSM, Consul)
- Version control for configuration files (separate repo or encrypted in application repo)
- Encryption tool for sensitive values (
sops, age, sealed-secrets, or cloud KMS)
- Understanding of which values differ between environments vs. which are shared
Instructions
- Audit existing configuration: scan for
.env files, config/ directories, Kubernetes ConfigMaps, and hardcoded values in source code
- Classify each configuration value: public (non-sensitive, varies per env), secret (credentials, API keys), and static (same across all envs)
- Extract hardcoded values into externalized configuration with a clear naming convention (
APP_DATABASE_HOST, APP_REDIS_URL)
- Create environment-specific configuration files:
.env.development, .env.staging, .env.production
- Encrypt sensitive values using
sops with cloud KMS or sealed-secrets for Kubernetes
- Generate Kubernetes ConfigMaps and Secrets from environment files for cluster-based deployments
- Set up configuration validation: schema checks to ensure all required variables are present before deployment
- Implement promotion workflow: changes go to dev first, then promote to staging after testing, then to production with approval
- Add configuration drift detection: compare running environment against source-of-truth on a schedule
Output
- Environment-specific configuration files (
.env.*, config/*.yaml)
- Kubernetes ConfigMap and Secret manifests per environment
- Configuration schema/validation script to catch missing variables
- SOPS-encrypted secret files with
.sops.yaml rules
- CI/CD pipeline steps for configuration validation and deployment
Error Handling
| Error |
Cause |
Solution |
Missing required environment variable |
Variable defined in schema but absent from .env file |
Add the variable to the environment file; run validation script before deploy |
SOPS decryption failed |
Wrong KMS key or expired credentials |
Verify KMS key ARN in .sops.yaml; refresh cloud credentials |
ConfigMap too large |
Kubernetes 1MB ConfigMap size limit exceeded |
Split into multiple ConfigMaps or mount as files from a volume |
Configuration drift detected |
Manual changes made directly to running environment |
Re-apply configuration from source-of-truth; block direct environment edits |
Secret exposed in logs |
Application logging sensitive config values at startup |
Mask secrets in logging output; audit code for accidental secret printing |
Examples
- "Create an environment configuration system using
.env files for a Node.js app with SOPS encryption for secrets and validation that all required vars are set."
- "Generate Kubernetes ConfigMaps and Secrets from environment files for dev, staging, and production namespaces."
- "Set up a configuration promotion workflow: edit in dev, validate in CI, promote to staging via PR, deploy to production with approval gate."
Resources
1---2name: managing-environment-configurations3description: Implement environment and configuration management with comprehensive guidance and automation. Use when you need to work with environment configuration. Trigger with phrases like "manage environments", "configure environments", or "sync configurations".4license: MIT5---6# Managing Environment Configurations
7
8## Overview
9
10Manage application configurations across development, staging, and production environments using `.env` files, Kubernetes ConfigMaps/Secrets, SSM Parameter Store, and cloud-native configuration services. Enforce consistency, prevent configuration drift, and implement safe promotion workflows between environments.
11
12## Prerequisites
13
14- Access to all target environments (dev, staging, production)
15- Configuration management tool or pattern identified (dotenv, ConfigMaps, SSM, Consul)
16- Version control for configuration files (separate repo or encrypted in application repo)
17- Encryption tool for sensitive values (`sops`, `age`, `sealed-secrets`, or cloud KMS)
18- Understanding of which values differ between environments vs. which are shared
19
20## Instructions
21
221. Audit existing configuration: scan for `.env` files, `config/` directories, Kubernetes ConfigMaps, and hardcoded values in source code
232. Classify each configuration value: public (non-sensitive, varies per env), secret (credentials, API keys), and static (same across all envs)
243. Extract hardcoded values into externalized configuration with a clear naming convention (`APP_DATABASE_HOST`, `APP_REDIS_URL`)
254. Create environment-specific configuration files: `.env.development`, `.env.staging`, `.env.production`
265. Encrypt sensitive values using `sops` with cloud KMS or `sealed-secrets` for Kubernetes
276. Generate Kubernetes ConfigMaps and Secrets from environment files for cluster-based deployments
287. Set up configuration validation: schema checks to ensure all required variables are present before deployment
298. Implement promotion workflow: changes go to dev first, then promote to staging after testing, then to production with approval
309. Add configuration drift detection: compare running environment against source-of-truth on a schedule
31
32## Output
33
34- Environment-specific configuration files (`.env.*`, `config/*.yaml`)
35- Kubernetes ConfigMap and Secret manifests per environment
36- Configuration schema/validation script to catch missing variables
37- SOPS-encrypted secret files with `.sops.yaml` rules
38- CI/CD pipeline steps for configuration validation and deployment
39
40## Error Handling
41
42| Error | Cause | Solution |
43|-------|-------|---------|
44| `Missing required environment variable` | Variable defined in schema but absent from `.env` file | Add the variable to the environment file; run validation script before deploy |
45| `SOPS decryption failed` | Wrong KMS key or expired credentials | Verify KMS key ARN in `.sops.yaml`; refresh cloud credentials |
46| `ConfigMap too large` | Kubernetes 1MB ConfigMap size limit exceeded | Split into multiple ConfigMaps or mount as files from a volume |
47| `Configuration drift detected` | Manual changes made directly to running environment | Re-apply configuration from source-of-truth; block direct environment edits |
48| `Secret exposed in logs` | Application logging sensitive config values at startup | Mask secrets in logging output; audit code for accidental secret printing |
49
50## Examples
51
52- "Create an environment configuration system using `.env` files for a Node.js app with SOPS encryption for secrets and validation that all required vars are set."
53- "Generate Kubernetes ConfigMaps and Secrets from environment files for dev, staging, and production namespaces."
54- "Set up a configuration promotion workflow: edit in dev, validate in CI, promote to staging via PR, deploy to production with approval gate."
55
56## Resources
57
58- 12-Factor App config: https://12factor.net/config
59- SOPS encryption: https://github.com/getsops/sops
60- Kubernetes ConfigMaps: https://kubernetes.io/docs/concepts/configuration/configmap/
61- Sealed Secrets: https://github.com/bitnami-labs/sealed-secrets
62- Consul KV: https://developer.hashicorp.com/consul/docs/dynamic-app-config/kv
gabrielmoreira