Configuration System¶

Understanding Manta’s Distributed Configuration Architecture

The Manta platform employs a sophisticated, hierarchical configuration system designed to support both SDK users and node operators across diverse deployment environments. This architecture enables seamless transitions between development, staging, and production while maintaining security and operational clarity.

Configuration Philosophy¶

The Manta configuration system is built on several core principles:

Separation of Concerns: SDK configurations and Node configurations are completely separate, allowing users to manage client connections independently from node operations.

Hierarchical Overrides: Configuration values cascade through multiple layers, enabling flexible customization while maintaining sensible defaults.

Environment Isolation: Different environments (development, staging, production) can coexist without conflict through profile-based separation.

Security by Design: Sensitive credentials are isolated, encrypted when possible, and never mixed with operational configuration.

Progressive Disclosure: Basic operations require minimal configuration, while advanced features are accessible through detailed configuration options.

Directory Structure Architecture¶

The Manta configuration system centers around the ~/.manta/ directory, which serves as the single source of truth for all platform configuration:

📁 Actual Implementation Structure

~/.manta/
├── sdk/                         # SDK Configuration Module
│   ├── *.toml                   # Individual SDK profiles
│   └── active                   # Active SDK profile reference
├── nodes/                       # Node Configuration Module
│   ├── *.toml                   # Individual node configurations
│   └── default.toml             # Default node template
├── logs/                        # Centralized Logging
│   ├── sdk/                     # SDK operation logs
│   │   └── *.log               # Per-profile log files
│   └── nodes/                   # Node operation logs
│       └── *.log               # Per-node log files
├── certs/                       # Security Certificates
│   ├── ca/                      # Certificate Authority files
│   ├── client/                  # Client certificates
│   └── node/                    # Node certificates
└── credentials.toml             # Encrypted credential storage

This structure reflects the actual implementation rather than aspirational designs, ensuring documentation accuracy and developer success.

Configuration Modules¶

SDK Configuration Module¶

The SDK configuration module (~/.manta/sdk/) manages client-side connection profiles for interacting with Manta managers:

Purpose: Enable SDK users to maintain multiple connection profiles for different Manta deployments without configuration conflicts.

Configuration Scope: - Manager connection parameters (host, port) - Authentication tokens (JWT) - TLS/certificate settings - Client-specific operational preferences

Active Profile System: The active file contains the name of the currently selected profile, enabling context-aware operations without explicit profile specification.

Profile Isolation: Each profile is a completely independent configuration, allowing simultaneous access to multiple Manta deployments.

Node Configuration Module¶

The node configuration module (~/.manta/nodes/) manages distributed node agent settings:

Purpose: Configure node agents that participate in distributed computation, including resource allocation, security settings, and operational parameters.

Configuration Scope: - Identity and authentication (secured tokens, aliases) - Network connectivity (manager endpoints, service ports) - Resource management (CPU, memory, GPU settings) - Container orchestration preferences - Dataset mappings and data access patterns - Security and certificate management - Logging and monitoring configuration

Template System: Common node configurations can be saved as templates and reused across similar deployment scenarios.

Hierarchical Sections: Node configurations are organized into logical sections (identity, network, security, etc.) for maintainability and clarity.

Centralized Logging Architecture¶

The logging system (~/.manta/logs/) provides centralized, structured logging for both SDK and node operations:

Architectural Benefits: - Unified Debugging: All Manta-related logs in a single location - Component Isolation: SDK logs separate from node logs for clarity - Automatic Organization: Log files automatically named based on profiles/nodes - Retention Management: Centralized location enables consistent log rotation policies

Naming Conventions: - SDK logs: Named after profile configurations - Node logs: Named after node aliases or configuration names - Automatic sanitization of names for filesystem compatibility

Certificate Management System¶

The certificate directory (~/.manta/certs/) centralizes TLS/mTLS certificate management:

Security Architecture: - Certificate Authority (CA) certificates for trust establishment - Client certificates for SDK authentication when mTLS is enabled - Node certificates for secure node-to-manager communication - Standardized paths referenced by both SDK and node configurations

Benefits: - Consistent certificate lifecycle management - Simplified rotation and renewal processes - Clear separation between different certificate types - Integration with configuration validation systems

Configuration Hierarchy and Precedence¶

The Manta platform implements a sophisticated precedence system that balances flexibility with predictability:

Priority Cascade¶

Command-line Arguments (Highest Priority) - Explicit parameters passed to CLI commands - Runtime-specific overrides for testing and debugging
Environment Variables - MANTA_* prefixed variables - Container and orchestration-friendly configuration - Deployment-specific overrides
Active Profile Configuration - Selected SDK or node configuration file - Environment-specific operational parameters
Default Profile Configuration - Fallback configuration when no specific profile is active - Baseline operational settings
Built-in System Defaults (Lowest Priority) - Hardcoded reasonable defaults in application code - Ensures operation even with minimal configuration

Environment Variable Integration¶

Environment variables provide deployment-flexibility and integration with container orchestration systems:

SDK Environment Variables: - MANTA_SDK_PROFILE: Override active SDK profile - MANTA_HOST: Override manager host - MANTA_PORT: Override manager port - MANTA_TOKEN: Override authentication token

Node Environment Variables: - MANTA_NODE_CONFIG: Override node configuration file - MANTA_MANAGER_HOST: Override manager endpoint - MANTA_SECURED_TOKEN: Override node authentication

Security Considerations: Sensitive tokens in environment variables should be used cautiously in production environments due to process visibility.

Profile System Design¶

Active Profile Management¶

The profile system enables seamless context switching between different Manta environments:

SDK Profiles: Each profile represents a complete connection configuration for a specific Manta deployment: - Development manager on localhost - Staging manager with test data - Production manager with live workloads

Node Profiles: Each configuration represents a complete node deployment specification: - GPU worker configurations for machine learning workloads - CPU cluster configurations for distributed computing - Edge node configurations for federated scenarios

Context Preservation: The active profile system maintains user context across CLI sessions and API calls.

Configuration Validation Architecture¶

Both SDK and node configurations implement comprehensive validation:

Validation Categories: - Syntax Validation: TOML format correctness and schema compliance - Semantic Validation: Logical consistency of configuration values - Resource Validation: Availability of specified paths, certificates, and endpoints - Security Validation: Token format verification and certificate chain validation

Early Detection: Validation occurs at configuration load time rather than operation execution, preventing runtime failures.

User Guidance: Validation errors include specific guidance for resolution, reducing debugging time.

Security and Credential Management¶

Credential Isolation Principles¶

The Manta configuration system implements security-first credential management:

Separation of Concerns: Operational configuration is completely separate from authentication credentials, enabling secure sharing of configuration templates.

Encryption at Rest: Sensitive credentials are encrypted when stored locally, protecting against unauthorized access.

Credential Rotation: The system supports credential updates without requiring configuration changes, enabling security best practices.

Access Control: Credential files use restrictive filesystem permissions (600) to prevent unauthorized access.

Certificate Lifecycle Management¶

TLS certificate management is integrated into the configuration system:

Centralized Storage: All certificates in a standardized directory structure Automatic Discovery: Configurations reference standard certificate paths Validation Integration: Certificate validity checked during configuration validation Renewal Support: Certificate updates do not require configuration changes

Configuration Evolution and Migration¶

Backward Compatibility Strategy¶

The configuration system is designed to evolve while maintaining compatibility:

Legacy Format Support: Older configuration formats are automatically converted to current standards Graceful Degradation: Missing optional configuration sections use reasonable defaults Migration Tooling: Built-in tools assist in upgrading configuration formats Version Tracking: Configuration files include version metadata for compatibility determination

Future-Proofing Architecture¶

The modular design enables extension without breaking existing deployments:

Plugin Configuration: New features can add configuration sections without affecting existing functionality Profile Extensions: Additional profile types can be added for specialized deployment scenarios Tool Integration: External tools can extend the configuration system through standardized interfaces

Best Practices and Patterns¶

Configuration Organization¶

Environment Separation: Maintain distinct profiles for each deployment environment to prevent accidental cross-environment operations.

Template Usage: Create reusable configuration templates for common deployment patterns, reducing configuration errors and maintenance overhead.

Documentation: Include descriptive comments in configuration files explaining environment-specific choices and operational constraints.

Validation Habits: Regularly validate configurations, especially after changes or when debugging operational issues.

Security Practices¶

Credential Hygiene: Never include sensitive tokens directly in configuration files; use credential isolation or environment variable references.

Certificate Management: Implement regular certificate rotation schedules and automated renewal where possible.

Access Control: Maintain strict filesystem permissions on the ~/.manta/ directory and its contents.

Audit Trails: Monitor configuration changes in production environments for security and compliance purposes.

Operational Considerations¶

Monitoring and Observability¶

The centralized logging system enables comprehensive platform monitoring:

Log Aggregation: All Manta operations log to the centralized location, enabling unified monitoring solutions.

Configuration Drift: Differences between deployed configurations and desired state can be detected through log analysis.

Performance Metrics: Configuration impacts on performance can be correlated through consistent logging.

Troubleshooting and Debugging¶

The hierarchical configuration system provides structured debugging approaches:

Configuration Priority: When troubleshooting unexpected behavior, examine the configuration precedence chain to identify override sources.

Validation Reports: Use built-in validation tools to identify configuration issues before they impact operations.

Log Correlation: Centralized logs enable correlation between configuration changes and operational behavior.

Profile Isolation: Test configuration changes in isolated profiles before applying to production environments.

Conclusion¶

The Manta configuration system represents a carefully designed balance between simplicity and flexibility. By separating SDK and node configurations, implementing hierarchical precedence, and providing centralized logging and security management, the system enables both simple getting-started experiences and sophisticated production deployments.

This architecture supports the platform’s distributed nature while maintaining operational clarity and security, making it suitable for everything from single-developer experimentation to large-scale federated learning deployments.

⚙️ Configuration Architecture Mastered! You now understand the theoretical foundations of Manta's configuration system.