chore: remove bak files
This commit is contained in:
Jesús Pérez
parent
d08602ecc8
commit
6186f51f9f
GPG Key ID:
9F243E355E0BC939
@ -1,385 +0,0 @@
|
|||||||
<p align="center">
|
|
||||||
<img src="resources/provisioning_logo.svg" alt="Provisioning Logo" width="300"/>
|
|
||||||
</p>
|
|
||||||
<p align="center">
|
|
||||||
<img src="resources/logo-text.svg" alt="Provisioning" width="500"/>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
# 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,
|
|
||||||
Nickel, and Rust.
|
|
||||||
|
|
||||||
> **Note**: Architecture Decision Records (ADRs) and design documentation are in `docs/`
|
|
||||||
> directory. This location contains user-facing, operational, and product documentation.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Quick Navigation
|
|
||||||
|
|
||||||
### 🚀 Getting Started
|
|
||||||
|
|
||||||
| Document | Description | Audience |
|
|
||||||
| ---------- | ------------- | ---------- |
|
|
||||||
| **[Installation Guide](getting-started/installation-guide.md)** | Install and configure the system | New Users |
|
|
||||||
| **[Getting Started](getting-started/getting-started.md)** | First steps and basic concepts | New Users |
|
|
||||||
| **[Quick Reference](getting-started/quickstart-cheatsheet.md)** | Command cheat sheet | All Users |
|
|
||||||
| **[From Scratch Guide](guides/from-scratch.md)** | Complete deployment walkthrough | New Users |
|
|
||||||
|
|
||||||
### 📚 User Guides
|
|
||||||
|
|
||||||
| Document | Description |
|
|
||||||
| ---------- | ------------- |
|
|
||||||
| **[CLI Reference](infrastructure/cli-reference.md)** | Complete command reference |
|
|
||||||
| **[Workspace Management](infrastructure/workspace-setup.md)** | Workspace creation and management |
|
|
||||||
| **[Workspace Switching](infrastructure/workspace-switching-guide.md)** | Switch between workspaces |
|
|
||||||
| **[Infrastructure Management](infrastructure/infrastructure-management.md)** | Server, taskserv, cluster operations |
|
|
||||||
| **[Service Management](operations/service-management-guide.md)** | Platform service lifecycle management |
|
|
||||||
| **[OCI Registry](integration/oci-registry-guide.md)** | OCI artifact management |
|
|
||||||
| **[Gitea Integration](integration/gitea-integration-guide.md)** | Git workflow and collaboration |
|
|
||||||
| **[CoreDNS Guide](operations/coredns-guide.md)** | DNS management |
|
|
||||||
| **[Test Environments](testing/test-environment-usage.md)** | Containerized testing |
|
|
||||||
| **[Extension Development](development/extension-development.md)** | Create custom extensions |
|
|
||||||
|
|
||||||
### 🏗️ Architecture
|
|
||||||
|
|
||||||
| Document | Description |
|
|
||||||
| ---------- | ------------- |
|
|
||||||
| **[System Overview](architecture/system-overview.md)** | High-level architecture |
|
|
||||||
| **[Multi-Repo Architecture](architecture/multi-repo-architecture.md)** | Repository structure and OCI distribution |
|
|
||||||
| **[Design Principles](architecture/design-principles.md)** | Architectural philosophy |
|
|
||||||
| **[Integration Patterns](architecture/integration-patterns.md)** | System integration patterns |
|
|
||||||
| **[Orchestrator Model](architecture/orchestrator-integration-model.md)** | Hybrid orchestration architecture |
|
|
||||||
|
|
||||||
### 📋 Architecture Decision Records (ADRs)
|
|
||||||
|
|
||||||
| ADR | Title | Status |
|
|
||||||
| ----- | ------- | -------- |
|
|
||||||
| **[ADR-001](architecture/adr/adr-001-project-structure.md)** | Project Structure Decision | Accepted |
|
|
||||||
| **[ADR-002](architecture/adr/adr-002-distribution-strategy.md)** | Distribution Strategy | Accepted |
|
|
||||||
| **[ADR-003](architecture/adr/adr-003-workspace-isolation.md)** | Workspace Isolation | Accepted |
|
|
||||||
| **[ADR-004](architecture/adr/adr-004-hybrid-architecture.md)** | Hybrid Architecture | Accepted |
|
|
||||||
| **[ADR-005](architecture/adr/adr-005-extension-framework.md)** | Extension Framework | Accepted |
|
|
||||||
| **[ADR-006](architecture/adr/adr-006-provisioning-cli-refactoring.md)** | CLI Refactoring | Accepted |
|
|
||||||
|
|
||||||
### 🔌 API Documentation
|
|
||||||
|
|
||||||
| Document | Description |
|
|
||||||
| ---------- | ------------- |
|
|
||||||
| **[REST API](api-reference/rest-api.md)** | HTTP API endpoints |
|
|
||||||
| **[WebSocket API](api-reference/websocket.md)** | Real-time event streams |
|
|
||||||
| **[Extensions API](development/extensions.md)** | Extension integration APIs |
|
|
||||||
| **[SDKs](api-reference/sdks.md)** | Client libraries |
|
|
||||||
| **[Integration Examples](api-reference/integration-examples.md)** | API usage examples |
|
|
||||||
|
|
||||||
### 🛠️ Development
|
|
||||||
|
|
||||||
| Document | Description |
|
|
||||||
| ---------- | ------------- |
|
|
||||||
| **[Development README](development/README.md)** | Developer overview |
|
|
||||||
| **[Implementation Guide](development/implementation-guide.md)** | Implementation details |
|
|
||||||
| **[Provider Development](development/quick-provider-guide.md)** | Create cloud providers |
|
|
||||||
| **[Taskserv Development](development/taskserv-developer-guide.md)** | Create task services |
|
|
||||||
| **[Extension Framework](development/extensions.md)** | Extension system |
|
|
||||||
| **[Command Handlers](development/command-handler-guide.md)** | CLI command development |
|
|
||||||
|
|
||||||
### 🐛 Troubleshooting
|
|
||||||
|
|
||||||
| Document | Description |
|
|
||||||
| ---------- | ------------- |
|
|
||||||
| **[Troubleshooting Guide](troubleshooting/troubleshooting-guide.md)** | Common issues and solutions |
|
|
||||||
|
|
||||||
### 📖 How-To Guides
|
|
||||||
|
|
||||||
| Document | Description |
|
|
||||||
| ---------- | ------------- |
|
|
||||||
| **[From Scratch](guides/from-scratch.md)** | Complete deployment from zero |
|
|
||||||
| **[Update Infrastructure](guides/update-infrastructure.md)** | Safe update procedures |
|
|
||||||
| **[Customize Infrastructure](guides/customize-infrastructure.md)** | Layer and template customization |
|
|
||||||
|
|
||||||
### 🔐 Configuration
|
|
||||||
|
|
||||||
| Document | Description |
|
|
||||||
| ---------- | ------------- |
|
|
||||||
| **[Workspace Config Architecture](configuration/workspace-config-architecture.md)** | Configuration architecture |
|
|
||||||
|
|
||||||
### 📦 Quick References
|
|
||||||
|
|
||||||
| Document | Description |
|
|
||||||
| ---------- | ------------- |
|
|
||||||
| **[Quickstart Cheatsheet](getting-started/quickstart-cheatsheet.md)** | Command shortcuts |
|
|
||||||
| **[OCI Quick Reference](quick-reference/oci.md)** | OCI operations |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Documentation Structure
|
|
||||||
|
|
||||||
```plaintext
|
|
||||||
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
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 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 **Nickel 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 Nickel
|
|
||||||
- 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
|
|
||||||
Loading…
x
Reference in New Issue
Block a user