110-configuration.mdc

---
title: Configuration Management Engineering Ruleset
description: Patterns for managing configuration with proper precedence, environment variables, and validation.
priority: 110
alwaysApply: true
---

# Configuration Management Engineering Ruleset

**Goal:** Manage configuration consistently across applications with clear precedence, proper validation, and secure defaults.

## Configuration Precedence

Configuration is applied in order, with later sources overriding earlier ones:

1. **System configuration** (`/etc/gitconfig`, `/etc/app/config.yaml`)
2. **User configuration** (`~/.gitconfig`, `~/.app/config.yaml`)
3. **Local/project configuration** (`.git/config`, `./config.yaml`)
4. **Environment variables** (`GIT_AUTHOR_NAME=...`, `APP_API_KEY=...`)
5. **Command-line parameters** (`git commit --author=...`, `app --api-key=...`)

This pattern is used by Git, SSH, and many Unix tools. Use this hierarchy to allow:
- System defaults
- User preferences
- Project settings
- Runtime environment overrides
- Explicit command-line overrides

## Environment Variables

### String Type

Environment variables are **strings** in the OS. Convert them in your application:

```python
#  GOOD: Explicit conversion
port = int(os.getenv("PORT", "8080"))
timeout = float(os.getenv("TIMEOUT", "30.0"))
debug = os.getenv("DEBUG") == "1"

#  BAD: Assuming type
port = os.getenv("PORT", 8080)  # Wrong! Default should be string
```

### Boolean Values

**Use `1` for true. Anything that is not `1` is false.**

```python
#  GOOD: Consistent boolean handling
debug = os.getenv("DEBUG") == "1"
verbose = os.getenv("VERBOSE") == "1"
enabled = os.getenv("FEATURE_ENABLED") == "1"

#  BAD: Parsing various strings
debug = os.getenv("DEBUG", "false").lower() in ["true", "1", "yes", "on"]
# This is brittle and opinionated
```

**Rationale:**
- Simple and unambiguous
- Works across all languages
- No parsing ambiguity
- Consistent with Unix conventions

### Required Values

**Fail fast if required configuration is missing:**

```python
#  GOOD: Fail fast with clear error
api_key = os.getenv("API_KEY")
if not api_key:
    raise ValueError(
        "API_KEY environment variable is required. "
        "Set it with: export API_KEY=your-key"
    )

#  BAD: Silent failure or default
api_key = os.getenv("API_KEY", "")  # What if empty string?
# Later: api_key is empty, fails mysteriously
```

### Default Values

Provide sensible defaults when appropriate:

```python
#  GOOD: Sensible defaults
port = int(os.getenv("PORT", "8080"))
log_level = os.getenv("LOG_LEVEL", "INFO")
timeout = int(os.getenv("TIMEOUT", "30"))

#  GOOD: No default for required values
api_key = os.getenv("API_KEY")
if not api_key:
    raise ValueError("API_KEY is required")
```

## Configuration File Patterns

### YAML Configuration

```yaml
# config.yaml
server:
  host: localhost
  port: 8080
  timeout: 30

database:
  host: localhost
  port: 5432
  name: myapp
  ssl: true

features:
  debug: false
  verbose: false
```

### JSON Configuration

```json
{
  "server": {
    "host": "localhost",
    "port": 8080,
    "timeout": 30
  },
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "myapp",
    "ssl": true
  },
  "features": {
    "debug": false,
    "verbose": false
  }
}
```

### Environment-Specific Configuration

```python
import os
import yaml

def load_config():
    env = os.getenv("ENVIRONMENT", "development")

    # Load base config
    with open("config/base.yaml") as f:
        config = yaml.safe_load(f)

    # Override with environment-specific config
    env_config_path = f"config/{env}.yaml"
    if os.path.exists(env_config_path):
        with open(env_config_path) as f:
            env_config = yaml.safe_load(f)
            config = merge_config(config, env_config)

    # Override with environment variables
    config = apply_env_overrides(config)

    return config
```

## Configuration Validation

### Validate Early

```python
from pydantic import BaseModel, Field, validator
from typing import Optional

class ServerConfig(BaseModel):
    host: str = Field(default="localhost")
    port: int = Field(default=8080, ge=1, le=65535)
    timeout: int = Field(default=30, ge=1)

    @validator("host")
    def validate_host(cls, v):
        if not v:
            raise ValueError("host cannot be empty")
        return v

class AppConfig(BaseModel):
    server: ServerConfig
    api_key: str  # Required, no default

    @validator("api_key")
    def validate_api_key(cls, v):
        if not v or len(v) < 32:
            raise ValueError("api_key must be at least 32 characters")
        return v

# Load and validate
config = AppConfig(
    server={"host": os.getenv("HOST", "localhost")},
    api_key=os.getenv("API_KEY")  # Will raise if missing
)
```

## Secret Management

### Never Hardcode Secrets

```python
#  BAD: Hardcoded secrets
API_KEY = "sk-1234567890abcdef"
DATABASE_PASSWORD = "password123"

#  GOOD: From environment or secret manager
API_KEY = os.getenv("API_KEY")
if not API_KEY:
    raise ValueError("API_KEY environment variable required")

#  GOOD: From secret manager
import boto3
secrets_client = boto3.client("secretsmanager")
secret = secrets_client.get_secret_value(SecretId="myapp/api-key")
API_KEY = secret["SecretString"]
```

### Use Secret Managers

- **AWS Secrets Manager** - For AWS workloads
- **HashiCorp Vault** - For on-premises or multi-cloud
- **Azure Key Vault** - For Azure workloads
- **Google Secret Manager** - For GCP workloads
- **Kubernetes Secrets** - For K8s workloads (base64 encoded, not encrypted)

## Configuration Loading Patterns

### Python Example

```python
import os
from typing import Optional
from dataclasses import dataclass

@dataclass
class Config:
    api_key: str
    api_url: str = "https://api.acme.com"
    timeout: int = 30
    debug: bool = False

    @classmethod
    def from_env(cls) -> "Config":
        """Load configuration from environment variables."""
        api_key = os.getenv("API_KEY")
        if not api_key:
            raise ValueError("API_KEY environment variable required")

        return cls(
            api_key=api_key,
            api_url=os.getenv("API_URL", "https://api.acme.com"),
            timeout=int(os.getenv("TIMEOUT", "30")),
            debug=os.getenv("DEBUG") == "1"
        )
```

### Go Example

```go
package config

import (
    "os"
    "strconv"
)

type Config struct {
    APIKey  string
    APIURL  string
    Timeout int
    Debug   bool
}

func LoadFromEnv() (*Config, error) {
    apiKey := os.Getenv("API_KEY")
    if apiKey == "" {
        return nil, fmt.Errorf("API_KEY environment variable required")
    }

    timeout := 30
    if timeoutStr := os.Getenv("TIMEOUT"); timeoutStr != "" {
        var err error
        timeout, err = strconv.Atoi(timeoutStr)
        if err != nil {
            return nil, fmt.Errorf("invalid TIMEOUT: %w", err)
        }
    }

    return &Config{
        APIKey:  apiKey,
        APIURL:  getEnvOrDefault("API_URL", "https://api.acme.com"),
        Timeout: timeout,
        Debug:   os.Getenv("DEBUG") == "1",
    }, nil
}

func getEnvOrDefault(key, defaultValue string) string {
    if value := os.Getenv(key); value != "" {
        return value
    }
    return defaultValue
}
```

## Configuration Files in Version Control

### What to Commit

 **DO commit:**
- Configuration templates (`.env.example`, `config.example.yaml`)
- Default configuration files
- Configuration schemas/validation rules

 **DON'T commit:**
- Secrets or credentials
- Environment-specific values (API keys, passwords)
- Local development overrides
- Generated configuration files

### Template Files

```bash
# .env.example (committed)
API_KEY=your-api-key-here
API_URL=https://api.acme.com
DEBUG=0
TIMEOUT=30

# .env (gitignored, created from template)
API_KEY=sk-actual-key-here
API_URL=https://api.acme.com
DEBUG=1
TIMEOUT=60
```

## Configuration in Different Environments

### Development

```bash
# .env.development
API_URL=http://localhost:3000
DEBUG=1
LOG_LEVEL=DEBUG
```

### Staging

```bash
# .env.staging
API_URL=https://staging-api.acme.com
DEBUG=0
LOG_LEVEL=INFO
```

### Production

```bash
# .env.production (loaded from secret manager)
API_URL=https://api.acme.com
DEBUG=0
LOG_LEVEL=WARN
```

## Best Practices

### Do's

-  Use environment variables for configuration
-  Validate configuration at startup
-  Fail fast if required config is missing
-  Use `1` for boolean true in env vars
-  Provide sensible defaults when appropriate
-  Document all configuration options
-  Use secret managers for sensitive values
-  Follow precedence hierarchy

### Don'ts

-  Hardcode secrets or credentials
-  Parse various boolean string formats
-  Allow silent failures for missing config
-  Commit secrets to version control
-  Use unclear configuration names
-  Mix configuration sources inconsistently

## Review Checklist

When reviewing configuration code, check:

- [ ] No hardcoded secrets or credentials
- [ ] Environment variables used for configuration
- [ ] Required values fail fast with clear errors
- [ ] Boolean env vars use `1` for true
- [ ] Configuration is validated at startup
- [ ] Sensible defaults provided where appropriate
- [ ] Configuration precedence is clear
- [ ] Secret managers used for sensitive values
- [ ] Template files provided (`.env.example`)
- [ ] Configuration is documented
---