Provisioning Platform Documentation
Last Updated: 2025-01-02 (Phase 3.A Cleanup Complete)
Status: ✅ Primary documentation source (145 files consolidated)
Welcome to the comprehensive documentation for the Provisioning Platform - a modern, cloud-native infrastructure automation system built with Nushell, KCL, and Rust.
Quick Navigation
🚀 Getting Started
📚 User Guides
🏗️ Architecture
📋 Architecture Decision Records (ADRs)
| ADR |
Title |
Status |
| ADR-001 |
Project Structure Decision |
Accepted |
| ADR-002 |
Distribution Strategy |
Accepted |
| ADR-003 |
Workspace Isolation |
Accepted |
| ADR-004 |
Hybrid Architecture |
Accepted |
| ADR-005 |
Extension Framework |
Accepted |
| ADR-006 |
CLI Refactoring |
Accepted |
🔌 API Documentation
🛠️ Development
🐛 Troubleshooting
📖 How-To Guides
🔐 Configuration
📦 Quick References
Documentation Structure
provisioning/docs/src/
├── README.md (this file) # Documentation hub
├── getting-started/ # Getting started guides
│ ├── installation-guide.md
│ ├── getting-started.md
│ └── quickstart-cheatsheet.md
├── architecture/ # System architecture
│ ├── adr/ # Architecture Decision Records
│ ├── design-principles.md
│ ├── integration-patterns.md
│ ├── system-overview.md
│ └── ... (and 10+ more architecture docs)
├── infrastructure/ # Infrastructure guides
│ ├── cli-reference.md
│ ├── workspace-setup.md
│ ├── workspace-switching-guide.md
│ └── infrastructure-management.md
├── api-reference/ # API documentation
│ ├── rest-api.md
│ ├── websocket.md
│ ├── integration-examples.md
│ └── sdks.md
├── development/ # Developer guides
│ ├── README.md
│ ├── implementation-guide.md
│ ├── quick-provider-guide.md
│ ├── taskserv-developer-guide.md
│ └── ... (15+ more developer docs)
├── guides/ # How-to guides
│ ├── from-scratch.md
│ ├── update-infrastructure.md
│ └── customize-infrastructure.md
├── operations/ # Operations guides
│ ├── service-management-guide.md
│ ├── coredns-guide.md
│ └── ... (more operations docs)
├── security/ # Security docs
├── integration/ # Integration guides
├── testing/ # Testing docs
├── configuration/ # Configuration docs
├── troubleshooting/ # Troubleshooting guides
└── quick-reference/ # Quick references
```plaintext
---
## Key Concepts
### Infrastructure as Code (IaC)
The provisioning platform uses **declarative configuration** to manage infrastructure. Instead of manually creating resources, you define what you want in Nickel configuration files, and the system makes it happen.
### Mode-Based Architecture
The system supports four operational modes:
- **Solo**: Single developer local development
- **Multi-user**: Team collaboration with shared services
- **CI/CD**: Automated pipeline execution
- **Enterprise**: Production deployment with strict compliance
### Extension System
Extensibility through:
- **Providers**: Cloud platform integrations (AWS, UpCloud, Local)
- **Task Services**: Infrastructure components (Kubernetes, databases, etc.)
- **Clusters**: Complete deployment configurations
### OCI-Native Distribution
Extensions and packages distributed as OCI artifacts, enabling:
- Industry-standard packaging
- Efficient caching and bandwidth
- Version pinning and rollback
- Air-gapped deployments
---
## Documentation by Role
### For New Users
1. Start with **[Installation Guide](getting-started/installation-guide.md)**
2. Read **[Getting Started](getting-started/getting-started.md)**
3. Follow **[From Scratch Guide](guides/from-scratch.md)**
4. Reference **[Quickstart Cheatsheet](guides/quickstart-cheatsheet.md)**
### For Developers
1. Review **[System Overview](architecture/system-overview.md)**
2. Study **[Design Principles](architecture/design-principles.md)**
3. Read relevant **[ADRs](architecture/)**
4. Follow **[Development Guide](development/README.md)**
5. Reference **KCL Quick Reference**
### For Operators
1. Understand **[Mode System](infrastructure/mode-system)**
2. Learn **[Service Management](operations/service-management-guide.md)**
3. Review **[Infrastructure Management](infrastructure/infrastructure-management.md)**
4. Study **[OCI Registry](integration/oci-registry-guide.md)**
### For Architects
1. Read **[System Overview](architecture/system-overview.md)**
2. Study all **[ADRs](architecture/)**
3. Review **[Integration Patterns](architecture/integration-patterns.md)**
4. Understand **[Multi-Repo Architecture](architecture/multi-repo-architecture.md)**
---
## System Capabilities
### ✅ Infrastructure Automation
- Multi-cloud support (AWS, UpCloud, Local)
- Declarative configuration with KCL
- Automated dependency resolution
- Batch operations with rollback
### ✅ Workflow Orchestration
- Hybrid Rust/Nushell orchestration
- Checkpoint-based recovery
- Parallel execution with limits
- Real-time monitoring
### ✅ Test Environments
- Containerized testing
- Multi-node cluster simulation
- Topology templates
- Automated cleanup
### ✅ Mode-Based Operation
- Solo: Local development
- Multi-user: Team collaboration
- CI/CD: Automated pipelines
- Enterprise: Production deployment
### ✅ Extension Management
- OCI-native distribution
- Automatic dependency resolution
- Version management
- Local and remote sources
---
## Key Achievements
### 🚀 Batch Workflow System (v3.1.0)
- Provider-agnostic batch operations
- Mixed provider support (UpCloud + AWS + local)
- Dependency resolution with soft/hard dependencies
- Real-time monitoring and rollback
### 🏗️ Hybrid Orchestrator (v3.0.0)
- Solves Nushell deep call stack limitations
- Preserves all business logic
- REST API for external integration
- Checkpoint-based state management
### ⚙️ Configuration System (v2.0.0)
- Migrated from ENV to config-driven
- Hierarchical configuration loading
- Variable interpolation
- True IaC without hardcoded fallbacks
### 🎯 Modular CLI (v3.2.0)
- 84% reduction in main file size
- Domain-driven handlers
- 80+ shortcuts
- Bi-directional help system
### 🧪 Test Environment Service (v3.4.0)
- Automated containerized testing
- Multi-node cluster topologies
- CI/CD integration ready
- Template-based configurations
### 🔄 Workspace Switching (v2.0.5)
- Centralized workspace management
- Single-command workspace switching
- Active workspace tracking
- User preference system
---
## Technology Stack
| Component | Technology | Purpose |
|-----------|------------|---------|
| **Core CLI** | Nushell 0.107.1 | Shell and scripting |
| **Configuration** | KCL 0.11.2 | Type-safe IaC |
| **Orchestrator** | Rust | High-performance coordination |
| **Templates** | Jinja2 (nu_plugin_tera) | Code generation |
| **Secrets** | SOPS 3.10.2 + Age 1.2.1 | Encryption |
| **Distribution** | OCI (skopeo/crane/oras) | Artifact management |
---
## Support
### Getting Help
- **Documentation**: You're reading it!
- **Quick Reference**: Run `provisioning sc` or `provisioning guide quickstart`
- **Help System**: Run `provisioning help` or `provisioning <command> help`
- **Interactive Shell**: Run `provisioning nu` for Nushell REPL
### Reporting Issues
- Check **[Troubleshooting Guide](infrastructure/troubleshooting-guide.md)**
- Review **[FAQ](troubleshooting/troubleshooting-guide.md)**
- Enable debug mode: `provisioning --debug <command>`
- Check logs: `provisioning platform logs <service>`
---
## Contributing
This project welcomes contributions! See **[Development Guide](development/README.md)** for:
- Development setup
- Code style guidelines
- Testing requirements
- Pull request process
---
## License
[Add license information]
---
## Version History
| Version | Date | Major Changes |
|---------|------|---------------|
| **3.5.0** | 2025-10-06 | Mode system, OCI registry, comprehensive documentation |
| **3.4.0** | 2025-10-06 | Test environment service |
| **3.3.0** | 2025-09-30 | Interactive guides system |
| **3.2.0** | 2025-09-30 | Modular CLI refactoring |
| **3.1.0** | 2025-09-25 | Batch workflow system |
| **3.0.0** | 2025-09-25 | Hybrid orchestrator architecture |
| **2.0.5** | 2025-10-02 | Workspace switching system |
| **2.0.0** | 2025-09-23 | Configuration system migration |
---
**Maintained By**: Provisioning Team
**Last Review**: 2025-10-06
**Next Review**: 2026-01-06
