Provisioning Platform Documentation

Last Updated: 2025-10-06

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)

🔌 API Documentation

🛠️ Development

🐛 Troubleshooting

📖 How-To Guides

🔐 Configuration

📦 Quick References

Documentation Structure

docs/
├── README.md (this file)          # Documentation hub
├── architecture/                  # System architecture
│   ├── ADR/                       # Architecture Decision Records
│   ├── design-principles.md
│   ├── integration-patterns.md
│   └── system-overview.md
├── user/                          # User guides
│   ├── getting-started.md
│   ├── cli-reference.md
│   ├── installation-guide.md
│   └── troubleshooting-guide.md
├── api/                           # API documentation
│   ├── rest-api.md
│   ├── websocket.md
│   └── extensions.md
├── development/                   # Developer guides
│   ├── README.md
│   ├── implementation-guide.md
│   └── kcl/                       # KCL documentation
├── guides/                        # How-to guides
│   ├── from-scratch.md
│   ├── update-infrastructure.md
│   └── customize-infrastructure.md
├── configuration/                 # Configuration docs
│   └── workspace-config-architecture.md
├── troubleshooting/               # Troubleshooting
│   └── CTRL-C_SUDO_HANDLING.md
└── quick-reference/               # Quick refs
    └── SUDO_PASSWORD_HANDLING.md

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 KCL 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
2. Read Getting Started
3. Follow From Scratch Guide
4. Reference Quickstart Cheatsheet

For Developers

1. Review System Overview
2. Study Design Principles
3. Read relevant ADRs
4. Follow Development Guide
5. Reference KCL Quick Reference

For Operators

1. Understand Mode System
2. Learn Service Management
3. Review Infrastructure Management
4. Study OCI Registry

For Architects

1. Read System Overview
2. Study all ADRs
3. Review Integration Patterns
4. Understand Multi-Repo Architecture

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

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
• Review FAQ
• Enable debug mode: provisioning --debug <command>
• Check logs: provisioning platform logs <service>

Contributing

This project welcomes contributions! See Development Guide for:

• Development setup
• Code style guidelines
• Testing requirements
• Pull request process

License

[Add license information]

Version History

Maintained By: Provisioning Team Last Review: 2025-10-06 Next Review: 2026-01-06