Configuration Loading

This directory contains documentation for Blueberry IDP's configuration loading mechanisms and priority systems.

Overview

The configuration loading system implements a priority-based approach where settings can be sourced from multiple locations with clear precedence rules.

Configuration Priority

The system follows this priority order (highest to lowest):

1. Environment Variables - Direct OS environment variables
2. config/app_config.yaml - Repository configuration file
3. Default Values - Hard-coded fallback values

Loading Process

Settings Class Initialization

The Settings class in blueberry/config.py handles all configuration loading:

class Settings:
    def __init__(self, *, debug: bool | None = None, in_cluster: bool | None = None):
        # Check if running under pytest
        running_under_pytest = os.getenv("PYTEST_CURRENT_TEST") is not None

        # Load config/app_config.yaml unless in test environment
        if not running_under_pytest:
            config_path = Path(__file__).parent.parent / "config/app_config.yaml"
            if config_path.exists():
                with open(config_path) as f:
                    file_config = yaml.safe_load(f) or {}
            else:
                file_config = {}
        else:
            file_config = {}

Helper Functions

The system uses helper functions to implement the priority logic:

• get_config(env_var, file_key, default) - String values
• get_bool_config(env_var, file_key, default) - Boolean values
• get_int_config(env_var, file_key, default) - Integer values

Test Environment Handling

The system automatically detects test environments and skips file configuration to ensure consistent test behavior with default values.

Configuration Categories

API Configuration

• API_TITLE - Application title
• API_VERSION - Application version
• DEBUG - Debug mode flag

Server Configuration

• HOST - Server bind address
• PORT - Server port
• RELOAD - Auto-reload flag

GCP Configuration

• GCP_PROJECT_ID - Google Cloud project ID
• REGION - Default GCP region
• GCS_BUCKET - Storage bucket name

Integration Configuration

• GITLAB_URL - GitLab instance URL
• REDIS_HOST - Redis server host
• FIREBASE_PROJECT - Firebase project ID

Environment Configuration

• ENVIRONMENT_PREFIX - Environment naming prefix
• ENVIRONMENT_TTL_HOURS - Default environment TTL
• EPHEMERAL_DOMAIN - Base domain for environments

Best Practices

Environment Variables

• Use uppercase names with underscores
• Provide sensible defaults
• Document all environment variables

Configuration Files

• Use config/app_config.yaml for development overrides
• Don't commit sensitive values to version control
• Use consistent naming with environment variables

Default Values

• Provide safe defaults for all configuration
• Use values that work in development environments
• Document the purpose of each setting

Examples

Environment Variable Override

export DEBUG=true
export PORT=8080
export GCP_PROJECT_ID=my-project

Configuration File Override

# config/app_config.yaml
debug: true
port: 8080
gcp_project_id: my-project

Programmatic Access

from blueberry.config import get_settings

settings = get_settings()
print(f"Debug mode: {settings.debug}")
print(f"Project ID: {settings.project_id}")

Troubleshooting

Configuration Not Loading

• Check file path: config/app_config.yaml should be in repository root
• Verify YAML syntax is valid
• Ensure environment variables use correct names

Test Environment Issues

• Tests use default values only
• File configuration is ignored in tests
• Use explicit parameters for test-specific settings

Priority Confusion

• Environment variables always win
• File config overrides defaults
• Use get_settings() to inspect final values

Related Files

• blueberry/config.py - Main configuration class
• config/app_config.yaml - Development configuration file
• charts/blueberry/templates/configmap.yml - Kubernetes ConfigMap template
• charts/blueberry/values.yaml - Helm default values