config¶

Configuration management with inheritance, validation, and AWS deployment.

Provides BaseConfig class for hierarchical configuration management with shared value inheritance, environment-specific parameter generation, and integrated deployment to AWS SSM Parameter Store and S3.

class aws_config.config.DeploymentResult(before_param: Parameter | None, after_param: Parameter | None, s3dir_config: S3Path, s3path_latest: S3Path | None, s3path_versioned: S3Path | None)[source]¶

Result of a BaseConfig.deploy_env_parameter() operation. to AWS SSM Parameter Store and S3.

Parameters:

before_param – Parameter before deployment (if exists)
after_param – Parameter after deployment (if exists)
s3path_latest – S3 path for the latest version (if created)
s3path_versioned – S3 path for the versioned file (if created)

property is_ssm_deployed: bool¶: Indicate if SSM parameter deployment operation happened.

property is_s3_deployed: bool¶: Indicate if S3 parameter deployment operation happened.

property parameter_name: str¶: Get the SSM parameter name after deployment.

property version: int¶: Get the version of the SSM parameter after deployment.

class aws_config.config.DeleteResult(parameter_name: str, s3dir_config: S3Path | None)[source]¶

Result of a BaseConfig.delete_env_parameter() operation. to AWS SSM Parameter Store and S3.

Parameters:

parameter_name – Name of the deleted SSM parameter
s3dir_config – S3 directory where the configuration was stored

class aws_config.config.BaseConfig(data: dict, secret_data: dict, EnvClass: Type[T_BASE_ENV], EnvNameEnumClass: Type[T_BASE_ENV_NAME_ENUM], version: str)[source]¶

Hierarchical configuration management with inheritance, validation, and AWS deployment.

BaseConfig is the core of the aws_config library, providing a complete configuration lifecycle from local development to production deployment. It handles shared value inheritance, environment-specific parameter generation, validation, and integrated deployment to AWS SSM Parameter Store and S3.

Design Philosophy

The configuration system uses a hierarchical structure with shared value inheritance to minimize duplication while maintaining environment-specific customization. Two separate data structures handle sensitive and non-sensitive configuration:

data: Non-sensitive configuration (project settings, S3 URIs, etc.)
secret_data: Sensitive configuration (passwords, API keys, account IDs)

This separation allows for different security handling, deployment strategies, and access controls while maintaining a unified configuration interface.

Configuration Structure

Configuration uses a DEFAULTS section for shared values with environment-specific overrides. Shared values use special prefixes to control inheritance:

* prefix: Available to all environments
env. prefix: Available only to the specified environment

Example configuration structure:

# Non-sensitive data
data = {
    "DEFAULTS": {
        "*.project_name": "my_app",         # Available to all environments
        "*.aws_region": "us-east-1",        # Shared AWS region
        "dev.debug_enabled": True,          # Only available to dev environment
    },
    "dev": {
        "s3uri_data": "s3://myapp-dev/data/",
        "s3uri_artifacts": "s3://myapp-dev/artifacts/",
        "username": "alice",
    },
    "prod": {
        "s3uri_data": "s3://myapp-prod/data/",
        "s3uri_artifacts": "s3://myapp-prod/artifacts/",
        "username": "bob",
    },
}

# Sensitive data
secret_data = {
    "dev": {
        "aws_account_id": "111111111111",
        "password": "alicepassword",
    },
    "prod": {
        "aws_account_id": "111111111111",
        "password": "bobpassword",
    },
}

Configuration Lifecycle

The configuration follows a complete lifecycle from development to production:

Development: Start with two local JSON files

config.json: Non-sensitive configuration
secret-config.json: Sensitive configuration (gitignored)

Load using load_from_file():

data, secret_data = BaseConfig.load_from_file(
    "config.json",
    "secret-config.json"
)
config = MyConfig(
    data=data,
    secret_data=secret_data,
    EnvClass=MyEnv,
    EnvNameEnumClass=MyEnvEnum,
    version="1.0.0"
)

Deployment: Admin deploys configuration to AWS infrastructure

Deploy to SSM Parameter Store (primary) and S3 (backup) using deploy_env_parameter():

# Deploy specific environment
result = config.deploy_env_parameter(
    ssm_client=ssm_client,
    s3_client=s3_client,
    s3dir_config=S3Path("s3://my-config-bucket/configs/"),
    env_name="prod",
    type=ParameterType.SECURE_STRING
)

# Deploy consolidated multi-environment configuration
result = config.deploy_env_parameter(
    ssm_client=ssm_client,
    s3_client=s3_client,
    s3dir_config=S3Path("s3://my-config-bucket/configs/"),
    # env_name defaults to ALL
)

This creates:

SSM Parameter: my_app-prod (environment-specific) or my_app (consolidated)
S3 Files: latest.json and v1.json (versioned backup)

Runtime Access: Applications load configuration from SSM

Use load_parameter() in application code:

# Production application loads its specific environment
data, secret_data = BaseConfig.load_parameter(
    ssm_client=ssm_client,
    parameter_name="my_app-prod",
    with_decryption=True
)
config = MyConfig(data=data, secret_data=secret_data, ...)
env = config.get_env("prod")

# Admin tools load consolidated configuration
data, secret_data = BaseConfig.load_parameter(
    ssm_client=ssm_client,
    parameter_name="my_app",
    with_decryption=True
)
config = MyConfig(data=data, secret_data=secret_data, ...)
dev_env = config.get_env("dev")
prod_env = config.get_env("prod")

Disaster Recovery: Restore from S3 backup when SSM is unavailable

Use load_from_s3() for disaster recovery:

# Load from S3 backup when SSM Parameter Store is unavailable
data, secret_data = BaseConfig.load_from_s3(
    s3_client=s3_client,
    s3dir_config=S3Path("s3://my-config-bucket/configs/"),
    parameter_name="my_app-prod"  # or None for auto-discovery
)
config = MyConfig(data=data, secret_data=secret_data, ...)

Parameter Naming Conventions

SSM Parameter names follow consistent patterns:

Environment-specific: {project_name}-{env_name} (e.g., my_app-prod)
Consolidated: {project_name} (e.g., my_app)

S3 backup structure:

See aws_config.s3.S3Parameter.get_s3path()

Type Safety and Validation

BaseConfig uses generic types to ensure type safety:

T_BASE_ENV: Environment dataclass type (e.g., MyEnv)
T_BASE_ENV_NAME_ENUM: Environment name enum type (e.g., MyEnvEnum)

Environment instances are automatically validated using Pydantic/dataclass validation when calling get_env().

Deployment Strategy

The library supports both environment-specific and consolidated deployment patterns:

Environment-specific: Each environment gets its own SSM parameter (my_app-dev, my_app-prod) containing only that environment’s configuration
Consolidated: Single SSM parameter (my_app) contains all environments for admin tools and cross-environment operations

Security Features

Separation of sensitive and non-sensitive data
Automatic encryption using SSM SecureString parameters
S3 backup with optional encryption and access controls
Configurable AWS resource tagging for compliance and cost tracking

Error Handling

Validates project and environment names against standards
Validates configuration structure and data types
Provides detailed error messages for configuration issues
Graceful handling of missing parameters and network issues

Parameters:

data – Non-sensitive configuration data with DEFAULTS and environment sections
secret_data – Sensitive configuration data organized by environment
EnvClass – Environment dataclass type for validation and type safety
EnvNameEnumClass – Environment name enum class for validation
version – Configuration version for tracking and deployment

Example:

Complete configuration setup:

from enum import Enum
from dataclasses import dataclass
from pydantic import Field

class EnvNameEnum(BaseEnvNameEnum):
    dev = "dev"
    prod = "prod"

@dataclass
class MyEnv(BaseEnv):
    username: str = Field()
    password: str = Field()
    s3uri_data: str = Field()

class MyConfig(BaseConfig[MyEnv, EnvNameEnum]):
    pass

# Load from local files during development
data, secret_data = MyConfig.load_from_file(
    "config.json", "secret-config.json"
)

config = MyConfig(
    data=data,
    secret_data=secret_data,
    EnvClass=MyEnv,
    EnvNameEnumClass=EnvNameEnum,
    version="1.0.0"
)

# Get typed environment configuration
prod_env = config.get_env("prod")
print(f"Production S3 URI: {prod_env.s3uri_data}")
print(f"Username: {prod_env.username}")

Note

This is the core class of the aws_config library. All configuration management, validation, inheritance, and deployment functionality is built around this class.