configuration

Configuration Management

Purpose: Manage application configuration securely across environments. Goal: Externalized config, no hardcoded secrets, fail-fast validation. Note: For implementation, see C# Development or Python Development.

---

Prerequisites

• Understanding of environment variables
• Access to a secrets manager for production

Decision Tree

Configuration concern?
+- Where to store?
| +- Secrets (passwords, API keys) -> Vault / secrets manager
| +- Environment-specific -> Environment variables
| +- App defaults -> Config file (appsettings.json, .env.example)
| - Feature flags -> Remote config service
+- How to validate?
| +- Required values? -> Fail fast at startup (not at first use)
| +- Typed values? -> Parse + validate on load
| - Schema validation? -> Use config class / Pydantic model
- Multiple environments?
 +- Use layered config: base + environment override
 - NEVER commit .env files (use .env.example as template)

Configuration Hierarchy

Priority (highest to lowest):
 1. Command-line arguments
 2. Environment variables
 3. Environment-specific config files
 4. Base config files
 5. Default values in code

Principle: Higher priority sources override lower ones.

---

Environment Variables

When to Use

Environment Variables For:

• Secrets (API keys, passwords, connection strings)
• Environment-specific URLs (API endpoints)
• Feature toggles that change per environment
• Cloud provider credentials

Config Files For:

• Structured configuration (nested settings)
• Default values
• Non-sensitive settings
• Documentation of available options

Best Practices

[PASS] DO:
 - Use descriptive names: DATABASE_URL, API_KEY, FEATURE_NEW_UI_ENABLED
 - Prefix with app name for namespacing: MYAPP_DATABASE_URL
 - Document all required environment variables
 - Provide sensible defaults where safe
 - Validate on startup (fail fast)

[FAIL] DON'T:
 - Hardcode secrets in code or config files
 - Commit .env files to version control
 - Use environment variables for complex nested config
 - Leave required variables undocumented

---

Core Rules

Practice	Description
Externalize config	No config in code, all external
Fail fast	Validate all required config at startup
Use secrets manager	Never commit secrets to version control
Type safety	Use strongly-typed config classes
Default values	Provide sensible defaults where safe
Document	List all config options and their purpose
Environment parity	Same config structure across all environments
Immutable config	Don't change config at runtime

---

Anti-Patterns

• Hardcoded Secrets: Embedding API keys or passwords in source code -> Use a secrets manager (Key Vault, AWS Secrets Manager) and environment variables
• Config Sprawl: Scattering configuration across dozens of unrelated files -> Consolidate into a layered config hierarchy with clear precedence
• Runtime Mutation: Changing configuration values after startup without restart -> Treat config as immutable; redeploy or use feature flag service for dynamic values
• Missing Validation: Accessing config values deep in business logic without checking them -> Validate all required config at startup and fail fast with clear error messages
• Environment Leakage: Using production secrets in dev or committing .env files -> Use .env.example as template, add .env to .gitignore, separate secrets per environment
• Stringly Typed Config: Accessing config as raw strings throughout the codebase -> Bind config to strongly-typed classes or models with validation
• Default Overuse: Silently falling back to defaults for critical values like database URLs -> Require explicit values for critical config; only default non-critical settings

---

Configuration Libraries

Language	Libraries
.NET	IConfiguration, IOptions<T>, Azure Key Vault SDK
Python	python-dotenv, pydantic-settings, boto3 (AWS)
Node.js	dotenv, convict, config
Java	Spring Config, Apache Commons Configuration
Go	viper, envconfig

---

See Also: Security - C# Development - Python Development

Troubleshooting

Issue	Solution
Config not loading in production	Check environment variable names match, verify config file is deployed
Secrets exposed in config files	Use secrets manager or user-secrets for development, never commit secrets
Feature flag not toggling	Check flag evaluation context, verify flag provider connection

References

• Typed Config Secrets Flags
• Config Files And Anti Patterns