Skip to main content

Configuration Management - API Specification

Introduction​

This API specification documents the programmatic interfaces for the Configuration Management module of Codomyrmex. The module provides comprehensive configuration management, validation, and deployment capabilities for the Codomyrmex ecosystem, supporting multiple configuration sources, validation schemas, and secure secret management.

Functions​

Function: load_configuration(config_paths: List[str], environment: str = "development", overrides: Optional[Dict] = None, **kwargs) -> Configuration​

  • Description: Load and merge configuration from multiple sources with environment-specific overrides.
  • Parameters:
    • config_paths: List of file paths or URLs to configuration files.
    • environment: Target environment (development, staging, production).
    • overrides: Optional runtime configuration overrides.
    • **kwargs: Additional loading options (format, validation, etc.).
  • Return Value: Merged and validated Configuration object.
  • Errors: Raises ConfigurationError for loading failures or validation errors.

Function: validate_configuration(config: Union[Dict, Configuration], schema: Optional[ConfigSchema] = None, **kwargs) -> Dict​

  • Description: Validate configuration against schemas and business rules.

  • Parameters:

    • config: Configuration to validate (dict or Configuration object).
    • schema: Optional JSON schema for validation.
    • **kwargs: Validation options (strict_mode, custom_validators, etc.).

  • Return Value:

    {
        "valid": <bool>,
        "errors": [<list_of_validation_errors>],
        "warnings": [<list_of_warnings>],
        "schema_compliant": <bool>,
        "business_rules_passed": <bool>
    }

  • Errors: Raises ValidationError for schema violations or business rule failures.

Function: manage_secrets(operation: str, secret_path: str, value: Optional[str] = None, **kwargs) -> Dict​

  • Description: Secure secret management including storage, retrieval, and rotation.

  • Parameters:

    • operation: Operation type (get, set, rotate, delete).
    • secret_path: Path/key for the secret.
    • value: Value for set operations.
    • **kwargs: Operation-specific options (encryption, ttl, etc.).

  • Return Value:

    {
        "operation": <str>,
        "secret_path": <str>,
        "success": <bool>,
        "value": <str>,  # Only for get operations
        "metadata": {
            "created_at": <timestamp>,
            "last_rotated": <timestamp>,
            "encryption": <str>
        }
    }

  • Errors: Raises SecretManagementError for security or access failures.

Function: deploy_configuration(config: Configuration, target: str, strategy: str = "rolling", **kwargs) -> ConfigDeployment​

  • Description: Deploy configuration to target environments with rollback capabilities.
  • Parameters:
    • config: Configuration to deploy.
    • target: Deployment target (environment, service, file path).
    • strategy: Deployment strategy (rolling, blue_green, canary).
    • **kwargs: Deployment options (timeout, validation, backup, etc.).
  • Return Value: ConfigDeployment object with tracking and rollback capabilities.
  • Errors: Raises DeploymentError for deployment failures.

Function: monitor_config_changes(config_path: str, callback: Optional[Callable] = None, **kwargs) -> ConfigurationMonitor​

  • Description: Monitor configuration files for changes and drift detection.
  • Parameters:
    • config_path: Path to configuration file or directory to monitor.
    • callback: Optional callback function for change notifications.
    • **kwargs: Monitoring options (interval, patterns, recursive, etc.).
  • Return Value: ConfigurationMonitor object providing real-time change tracking.
  • Errors: Raises MonitoringError for filesystem or permission issues.

Function: audit_configuration(config: Configuration, audit_rules: Optional[List] = None, **kwargs) -> ConfigAudit​

  • Description: Audit configuration for compliance, security, and best practices.
  • Parameters:
    • config: Configuration to audit.
    • audit_rules: Optional custom audit rules to apply.
    • **kwargs: Audit options (severity_levels, categories, etc.).
  • Return Value: ConfigAudit object with findings, recommendations, and compliance status.
  • Errors: Raises AuditError for audit execution failures.

Data Structures​

Configuration​

Represents a loaded and validated configuration:

{
    "data": {<configuration_data>},
    "metadata": {
        "sources": [<list_of_source_files>],
        "environment": <str>,
        "loaded_at": <timestamp>,
        "validated": <bool>,
        "schema_version": <str>
    },
    "overrides": {<runtime_overrides>},
    "secrets": {<encrypted_secret_references>}
}

ConfigSchema​

JSON schema definition for configuration validation:

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {<schema_properties>},
    "required": [<list_of_required_fields>],
    "additionalProperties": <bool>,
    "metadata": {
        "version": <str>,
        "description": <str>,
        "created_by": <str>
    }
}

ConfigDeployment​

Tracks configuration deployment status and history:

{
    "id": <str>,
    "config_id": <str>,
    "target": <str>,
    "strategy": <str>,
    "status": "pending|in_progress|completed|failed|rolled_back",
    "start_time": <timestamp>,
    "end_time": <timestamp>,
    "backup_path": <str>,
    "rollback_available": <bool>,
    "validation_results": {<deployment_validation>},
    "error_message": <str>
}

ConfigAudit​

Results of configuration audit and compliance checking:

{
    "config_id": <str>,
    "audit_timestamp": <timestamp>,
    "overall_score": <float>,
    "compliance_status": "compliant|non_compliant|warning",
    "findings": [
        {
            "rule": <str>,
            "severity": "critical|high|medium|low|info",
            "message": <str>,
            "path": <str>,
            "recommendation": <str>
        }
    ],
    "categories": {
        "security": <score>,
        "performance": <score>,
        "maintainability": <score>,
        "compliance": <score>
    }
}

SecretManager​

Manages encrypted secrets and credentials:

{
    "backend": <str>,  # vault, aws_secretsmanager, azure_keyvault, etc.
    "encryption_method": <str>,
    "rotation_policy": {<rotation_rules>},
    "access_policies": [<list_of_access_policies>],
    "audit_log": [<list_of_secret_access_events>]
}

Error Handling​

All functions follow consistent error handling patterns:

  • Configuration Errors: ConfigurationError for loading, parsing, or merging failures
  • Validation Errors: ValidationError for schema violations or business rule failures
  • Security Errors: SecretManagementError for encryption, access, or key management issues
  • Deployment Errors: DeploymentError for configuration deployment failures
  • Monitoring Errors: MonitoringError for filesystem monitoring issues
  • Audit Errors: AuditError for compliance checking failures

Integration Patterns​

With Environment Setup​

from codomyrmex.config_management import load_configuration
from codomyrmex.environment_setup import validate_environment

# Validate the runtime environment before loading configuration
env_report = validate_environment(min_python="3.11")
if not env_report.valid:
    raise RuntimeError(f"Environment incomplete: {env_report.missing_items}")

# Load environment-specific configuration: config/app.yaml merged with
# config/environments/$ENVIRONMENT/app.yaml and APP_* environment variables
config = load_configuration("app")

With Security Audit​

from codomyrmex.config_management import ConfigurationMonitor
from codomyrmex.security.digital import scan_secrets

# Audit configuration files for compliance issues
monitor = ConfigurationMonitor()
config_audit = monitor.audit_configuration("production", "config/")
print(config_audit.compliance_status, config_audit.issues_found)

# Follow up with secret scanning
secret_findings = scan_secrets("config/")

With Project Orchestration​

from codomyrmex.config_management import deploy_configuration
from codomyrmex.logistics.orchestration.project import execute_workflow

# Deploy configuration as part of workflow
result = execute_workflow("config_deployment", {
    "config_management": {
        "config_path": "config/production.yaml",
        "target": "production_cluster",
        "strategy": "blue_green"
    }
})

Security Considerations​

  • Secret Encryption: All secrets are encrypted at rest and in transit
  • Access Control: Configuration access is controlled by roles and permissions
  • Audit Logging: All configuration changes are logged for compliance
  • Validation: Strict validation prevents injection and configuration attacks
  • Backup Security: Configuration backups are encrypted and access-controlled
  • Key Rotation: Automatic rotation of encryption keys for long-term security

Performance Characteristics​

  • Lazy Loading: Configurations are loaded on-demand to reduce startup time
  • Caching: Validated configurations are cached for performance
  • Efficient Validation: Schema validation is optimized for large configurations
  • Monitoring Overhead: Minimal performance impact from configuration monitoring
  • Secret Retrieval: Efficient secret caching with automatic refresh