Michel Roegl-Brunner
960fddb9ee
Some checks failed
Bump build.func Revision / bump-revision (push) Has been cancelled
411 lines
15 KiB
Markdown
411 lines
15 KiB
Markdown
# build.func Architecture Guide
|
|
|
|
## Overview
|
|
|
|
This document provides a high-level architectural overview of `build.func`, including module dependencies, data flow, integration points, and system architecture.
|
|
|
|
## High-Level Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ Proxmox Host System │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ build.func │ │
|
|
│ │ │ │
|
|
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────────┐ │ │
|
|
│ │ │ Entry Point │ │ Configuration │ │ Container Creation │ │ │
|
|
│ │ │ │ │ │ │ │ │ │
|
|
│ │ │ • start() │ │ • variables() │ │ • build_container() │ │ │
|
|
│ │ │ • install_ │ │ • base_ │ │ • create_lxc_container() │ │ │
|
|
│ │ │ script() │ │ settings() │ │ • configure_gpu_ │ │ │
|
|
│ │ │ • advanced_ │ │ • select_ │ │ passthrough() │ │ │
|
|
│ │ │ settings() │ │ storage() │ │ • fix_gpu_gids() │ │ │
|
|
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────────────┘ │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ Module Dependencies │ │
|
|
│ │ │ │
|
|
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────────┐ │ │
|
|
│ │ │ core.func │ │ error_handler. │ │ api.func │ │ │
|
|
│ │ │ │ │ func │ │ │ │ │
|
|
│ │ │ • Basic │ │ • Error │ │ • Proxmox API │ │ │
|
|
│ │ │ utilities │ │ handling │ │ interactions │ │ │
|
|
│ │ │ • Common │ │ • Error │ │ • Container │ │ │
|
|
│ │ │ functions │ │ recovery │ │ management │ │ │
|
|
│ │ │ • System │ │ • Cleanup │ │ • Status │ │ │
|
|
│ │ │ utilities │ │ functions │ │ monitoring │ │ │
|
|
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────────────┘ │ │
|
|
│ │ │ │
|
|
│ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │
|
|
│ │ │ tools.func │ │ │
|
|
│ │ │ │ │ │
|
|
│ │ │ • Additional utilities │ │ │
|
|
│ │ │ • Helper functions │ │ │
|
|
│ │ │ • System tools │ │ │
|
|
│ │ └─────────────────────────────────────────────────────────────────────────┘ │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Module Dependencies
|
|
|
|
### Core Dependencies
|
|
|
|
```
|
|
build.func Dependencies:
|
|
├── core.func
|
|
│ ├── Basic system utilities
|
|
│ ├── Common functions
|
|
│ ├── System information
|
|
│ └── File operations
|
|
├── error_handler.func
|
|
│ ├── Error handling
|
|
│ ├── Error recovery
|
|
│ ├── Cleanup functions
|
|
│ └── Error logging
|
|
├── api.func
|
|
│ ├── Proxmox API interactions
|
|
│ ├── Container management
|
|
│ ├── Status monitoring
|
|
│ └── Configuration updates
|
|
└── tools.func
|
|
├── Additional utilities
|
|
├── Helper functions
|
|
├── System tools
|
|
└── Custom functions
|
|
```
|
|
|
|
### Dependency Flow
|
|
|
|
```
|
|
Dependency Flow:
|
|
├── build.func
|
|
│ ├── Sources core.func
|
|
│ ├── Sources error_handler.func
|
|
│ ├── Sources api.func
|
|
│ └── Sources tools.func
|
|
├── core.func
|
|
│ ├── Basic utilities
|
|
│ └── System functions
|
|
├── error_handler.func
|
|
│ ├── Error management
|
|
│ └── Recovery functions
|
|
├── api.func
|
|
│ ├── Proxmox integration
|
|
│ └── Container operations
|
|
└── tools.func
|
|
├── Additional tools
|
|
└── Helper functions
|
|
```
|
|
|
|
## Data Flow Architecture
|
|
|
|
### Configuration Data Flow
|
|
|
|
```
|
|
Configuration Data Flow:
|
|
├── Environment Variables
|
|
│ ├── Hard environment variables
|
|
│ ├── App-specific .vars
|
|
│ ├── Global default.vars
|
|
│ └── Built-in defaults
|
|
├── Variable Resolution
|
|
│ ├── Apply precedence chain
|
|
│ ├── Validate settings
|
|
│ └── Resolve conflicts
|
|
├── Configuration Storage
|
|
│ ├── Memory variables
|
|
│ ├── Temporary files
|
|
│ └── Persistent storage
|
|
└── Configuration Usage
|
|
├── Container creation
|
|
├── Feature configuration
|
|
└── Settings persistence
|
|
```
|
|
|
|
### Container Data Flow
|
|
|
|
```
|
|
Container Data Flow:
|
|
├── Input Data
|
|
│ ├── Configuration variables
|
|
│ ├── Resource specifications
|
|
│ ├── Network settings
|
|
│ └── Storage requirements
|
|
├── Processing
|
|
│ ├── Validation
|
|
│ ├── Conflict resolution
|
|
│ ├── Resource allocation
|
|
│ └── Configuration generation
|
|
├── Container Creation
|
|
│ ├── LXC container creation
|
|
│ ├── Network configuration
|
|
│ ├── Storage setup
|
|
│ └── Feature configuration
|
|
└── Output
|
|
├── Container status
|
|
├── Access information
|
|
├── Configuration files
|
|
└── Log files
|
|
```
|
|
|
|
## Integration Architecture
|
|
|
|
### With Proxmox System
|
|
|
|
```
|
|
Proxmox Integration:
|
|
├── Proxmox Host
|
|
│ ├── LXC container management
|
|
│ ├── Storage management
|
|
│ ├── Network management
|
|
│ └── Resource management
|
|
├── Proxmox API
|
|
│ ├── Container operations
|
|
│ ├── Configuration updates
|
|
│ ├── Status monitoring
|
|
│ └── Error handling
|
|
├── Proxmox Configuration
|
|
│ ├── /etc/pve/lxc/<ctid>.conf
|
|
│ ├── Storage configuration
|
|
│ ├── Network configuration
|
|
│ └── Resource configuration
|
|
└── Proxmox Services
|
|
├── Container services
|
|
├── Network services
|
|
├── Storage services
|
|
└── Monitoring services
|
|
```
|
|
|
|
### With Install Scripts
|
|
|
|
```
|
|
Install Script Integration:
|
|
├── build.func
|
|
│ ├── Creates container
|
|
│ ├── Configures basic settings
|
|
│ ├── Starts container
|
|
│ └── Provides access
|
|
├── Install Scripts
|
|
│ ├── <app>-install.sh
|
|
│ ├── Downloads application
|
|
│ ├── Configures application
|
|
│ └── Sets up services
|
|
├── Container
|
|
│ ├── Running application
|
|
│ ├── Configured services
|
|
│ ├── Network access
|
|
│ └── Storage access
|
|
└── Integration Points
|
|
├── Container creation
|
|
├── Network configuration
|
|
├── Storage setup
|
|
└── Service configuration
|
|
```
|
|
|
|
## System Architecture Components
|
|
|
|
### Core Components
|
|
|
|
```
|
|
System Components:
|
|
├── Entry Point
|
|
│ ├── start() function
|
|
│ ├── Context detection
|
|
│ ├── Environment capture
|
|
│ └── Workflow routing
|
|
├── Configuration Management
|
|
│ ├── Variable resolution
|
|
│ ├── Settings persistence
|
|
│ ├── Default management
|
|
│ └── Validation
|
|
├── Container Creation
|
|
│ ├── LXC container creation
|
|
│ ├── Network configuration
|
|
│ ├── Storage setup
|
|
│ └── Feature configuration
|
|
├── Hardware Integration
|
|
│ ├── GPU passthrough
|
|
│ ├── USB passthrough
|
|
│ ├── Storage management
|
|
│ └── Network management
|
|
└── Error Handling
|
|
├── Error detection
|
|
├── Error recovery
|
|
├── Cleanup functions
|
|
└── User notification
|
|
```
|
|
|
|
### User Interface Components
|
|
|
|
```
|
|
UI Components:
|
|
├── Menu System
|
|
│ ├── Installation mode selection
|
|
│ ├── Configuration menus
|
|
│ ├── Storage selection
|
|
│ └── GPU configuration
|
|
├── Interactive Elements
|
|
│ ├── Whiptail menus
|
|
│ ├── User prompts
|
|
│ ├── Confirmation dialogs
|
|
│ └── Error messages
|
|
├── Non-Interactive Mode
|
|
│ ├── Environment variable driven
|
|
│ ├── Silent execution
|
|
│ ├── Automated configuration
|
|
│ └── Error handling
|
|
└── Output
|
|
├── Status messages
|
|
├── Progress indicators
|
|
├── Completion information
|
|
└── Access details
|
|
```
|
|
|
|
## Security Architecture
|
|
|
|
### Security Considerations
|
|
|
|
```
|
|
Security Architecture:
|
|
├── Container Security
|
|
│ ├── Unprivileged containers (default)
|
|
│ ├── Privileged containers (when needed)
|
|
│ ├── Resource limits
|
|
│ └── Access controls
|
|
├── Network Security
|
|
│ ├── Network isolation
|
|
│ ├── VLAN support
|
|
│ ├── Firewall integration
|
|
│ └── Access controls
|
|
├── Storage Security
|
|
│ ├── Storage isolation
|
|
│ ├── Access controls
|
|
│ ├── Encryption support
|
|
│ └── Backup integration
|
|
├── GPU Security
|
|
│ ├── Device isolation
|
|
│ ├── Permission management
|
|
│ ├── Access controls
|
|
│ └── Security validation
|
|
└── API Security
|
|
├── Authentication
|
|
├── Authorization
|
|
├── Input validation
|
|
└── Error handling
|
|
```
|
|
|
|
## Performance Architecture
|
|
|
|
### Performance Considerations
|
|
|
|
```
|
|
Performance Architecture:
|
|
├── Execution Optimization
|
|
│ ├── Parallel operations
|
|
│ ├── Efficient algorithms
|
|
│ ├── Minimal user interaction
|
|
│ └── Optimized validation
|
|
├── Resource Management
|
|
│ ├── Memory efficiency
|
|
│ ├── CPU optimization
|
|
│ ├── Disk usage optimization
|
|
│ └── Network efficiency
|
|
├── Caching
|
|
│ ├── Configuration caching
|
|
│ ├── Template caching
|
|
│ ├── Storage caching
|
|
│ └── GPU detection caching
|
|
└── Monitoring
|
|
├── Performance monitoring
|
|
├── Resource monitoring
|
|
├── Error monitoring
|
|
└── Status monitoring
|
|
```
|
|
|
|
## Deployment Architecture
|
|
|
|
### Deployment Scenarios
|
|
|
|
```
|
|
Deployment Scenarios:
|
|
├── Single Container
|
|
│ ├── Individual application
|
|
│ ├── Standard configuration
|
|
│ ├── Basic networking
|
|
│ └── Standard storage
|
|
├── Multiple Containers
|
|
│ ├── Application stack
|
|
│ ├── Shared networking
|
|
│ ├── Shared storage
|
|
│ └── Coordinated deployment
|
|
├── High Availability
|
|
│ ├── Redundant containers
|
|
│ ├── Load balancing
|
|
│ ├── Failover support
|
|
│ └── Monitoring integration
|
|
└── Development Environment
|
|
├── Development containers
|
|
├── Testing containers
|
|
├── Staging containers
|
|
└── Production containers
|
|
```
|
|
|
|
## Maintenance Architecture
|
|
|
|
### Maintenance Components
|
|
|
|
```
|
|
Maintenance Architecture:
|
|
├── Updates
|
|
│ ├── Container updates
|
|
│ ├── Application updates
|
|
│ ├── Configuration updates
|
|
│ └── Security updates
|
|
├── Monitoring
|
|
│ ├── Container monitoring
|
|
│ ├── Resource monitoring
|
|
│ ├── Performance monitoring
|
|
│ └── Error monitoring
|
|
├── Backup
|
|
│ ├── Configuration backup
|
|
│ ├── Container backup
|
|
│ ├── Storage backup
|
|
│ └── Recovery procedures
|
|
└── Troubleshooting
|
|
├── Error diagnosis
|
|
├── Log analysis
|
|
├── Performance analysis
|
|
└── Recovery procedures
|
|
```
|
|
|
|
## Future Architecture Considerations
|
|
|
|
### Scalability
|
|
|
|
```
|
|
Scalability Considerations:
|
|
├── Horizontal Scaling
|
|
│ ├── Multiple containers
|
|
│ ├── Load balancing
|
|
│ ├── Distributed deployment
|
|
│ └── Resource distribution
|
|
├── Vertical Scaling
|
|
│ ├── Resource scaling
|
|
│ ├── Performance optimization
|
|
│ ├── Capacity planning
|
|
│ └── Resource management
|
|
├── Automation
|
|
│ ├── Automated deployment
|
|
│ ├── Automated scaling
|
|
│ ├── Automated monitoring
|
|
│ └── Automated recovery
|
|
└── Integration
|
|
├── External systems
|
|
├── Cloud integration
|
|
├── Container orchestration
|
|
└── Service mesh
|
|
```
|