44648e3206
- Remove KCL ecosystem (~220 files deleted) - Migrate all infrastructure to Nickel schema system - Consolidate documentation: legacy docs → provisioning/docs/src/ - Add CI/CD workflows (.github/) and Rust build config (.cargo/) - Update core system for Nickel schema parsing - Update README.md and CHANGES.md for v5.0.0 release - Fix pre-commit hooks: end-of-file, trailing-whitespace - Breaking changes: KCL workspaces require migration - Migration bridge available in docs/src/development/
352 lines
8.8 KiB
Django/Jinja
352 lines
8.8 KiB
Django/Jinja
# Workspace {{ workspace_name | title }} Documentation
|
|
|
|
**Complete guide for deploying and managing {{ workspace_name }} infrastructure**
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
This documentation covers deployment, configuration, and troubleshooting for the **{{ workspace_name }}** workspace.
|
|
|
|
**Key Details**:
|
|
- **Location**: {{ workspace_path }}
|
|
- **Provider**: {{ primary_provider | title }}{% if primary_zone %} ({{ primary_zone }}){% endif %}
|
|
- **Infrastructures**: {{ infrastructures | join(sep=', ') | title }}
|
|
- **Estimated Cost**: {{ pricing_estimate }}
|
|
|
|
---
|
|
|
|
## Documentation Files
|
|
|
|
### 1. [Deployment Guide](deployment-guide.md)
|
|
**Purpose**: Step-by-step deployment instructions
|
|
|
|
**Sections**:
|
|
- Prerequisites verification
|
|
- Credentials setup ({{ primary_provider | title }})
|
|
- SSH key configuration
|
|
- Workspace activation
|
|
- Server deployment
|
|
- Service installation
|
|
- Verification and monitoring
|
|
- Cleanup procedures
|
|
|
|
**When to use**: Follow this guide to deploy infrastructure from scratch.
|
|
|
|
---
|
|
|
|
### 2. [Configuration Guide](configuration-guide.md)
|
|
**Purpose**: Configuration reference and options
|
|
|
|
**Sections**:
|
|
- Configuration hierarchy
|
|
- Master configuration
|
|
- Provider configuration
|
|
- Infrastructure settings
|
|
- Server definitions
|
|
- Task services configuration
|
|
- Validation procedures
|
|
- Common configuration changes
|
|
|
|
**When to use**: Consult when modifying workspace configuration.
|
|
|
|
---
|
|
|
|
### 3. [Troubleshooting Guide](troubleshooting.md)
|
|
**Purpose**: Solutions for common issues
|
|
|
|
**Sections**:
|
|
- Authentication & credentials issues
|
|
- Server deployment problems
|
|
- Configuration validation errors
|
|
- Service installation failures
|
|
- Network connectivity issues
|
|
- Performance issues
|
|
- Debug procedures
|
|
- Diagnosis checklist
|
|
|
|
**When to use**: Consult when deployment fails or issues occur.
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
### First Time Deployment
|
|
|
|
1. **Read Installation Guide**:
|
|
```bash
|
|
cat provisioning/docs/src/getting-started/installation-validation-guide.md
|
|
```
|
|
|
|
2. **Follow Deployment Guide**:
|
|
```bash
|
|
cat docs/deployment-guide.md
|
|
```
|
|
|
|
3. **Verify Deployment**:
|
|
```bash
|
|
provisioning server list
|
|
provisioning price --infra {{ default_infra }}
|
|
```
|
|
|
|
### Modify Configuration
|
|
|
|
1. **Review Options**: Read `configuration-guide.md`
|
|
2. **Make Changes**: Edit `infra/{{ default_infra }}/servers.ncl`
|
|
3. **Validate**: `nickel typecheck infra/{{ default_infra }}/main.ncl`
|
|
4. **Deploy**: `provisioning -c server create --infra {{ default_infra }}`
|
|
|
|
### Troubleshoot Issues
|
|
|
|
1. **Find Issue**: Search in `troubleshooting.md`
|
|
2. **Follow Solutions**: Execute recommended steps
|
|
3. **Check Logs**: `tail -f provisioning/platform/orchestrator/data/orchestrator.log`
|
|
|
|
---
|
|
|
|
## Workspace Overview
|
|
|
|
{% for infra in infrastructures %}
|
|
### Infrastructure: {{ infra | title }}
|
|
|
|
**Purpose**: {{ infrastructure_purposes[infra] }}
|
|
|
|
**Location**: `infra/{{ infra }}/`
|
|
|
|
**Servers**:
|
|
{% for server in servers %}
|
|
- `{{ server.name }}` - {{ server.plan }} ({{ server.storage }}GB storage)
|
|
{% endfor %}
|
|
|
|
**Services**:
|
|
{% for service in taskservs %}
|
|
- {{ service }}
|
|
{% endfor %}
|
|
|
|
**Provider**: {{ primary_provider | title }}{% if primary_zone %} ({{ primary_zone }} zone){% endif %}
|
|
|
|
{% endfor %}
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
Before using this workspace:
|
|
|
|
1. **Complete Installation Validation**
|
|
- Read: `provisioning/docs/src/getting-started/installation-validation-guide.md`
|
|
- Verify all prerequisites installed
|
|
|
|
2. **Have Provider Account**
|
|
- Account at {{ provider_url }}
|
|
- API credentials available
|
|
- Sufficient account balance
|
|
|
|
3. **Have SSH Key**
|
|
- Generate: `ssh-keygen -t ed25519 -f ~/.ssh/id_deployment`
|
|
- Location: `~/.ssh/id_deployment.pub`
|
|
|
|
---
|
|
|
|
## Key Commands
|
|
|
|
### Workspace Management
|
|
|
|
```bash
|
|
# Register workspace
|
|
provisioning workspace register {{ workspace_name }} {{ workspace_path }}
|
|
|
|
# Activate workspace
|
|
provisioning workspace activate {{ workspace_name }}:{{ default_infra }}
|
|
|
|
# Check active workspace
|
|
provisioning workspace active
|
|
|
|
# Validate workspace
|
|
nu workspace.nu validate
|
|
```
|
|
|
|
### Server Management
|
|
|
|
```bash
|
|
# List servers
|
|
provisioning server list --infra {{ default_infra }}
|
|
|
|
# Check pricing
|
|
provisioning price --infra {{ default_infra }}
|
|
|
|
# Dry-run deployment
|
|
provisioning -c server create --infra {{ default_infra }}
|
|
|
|
# Deploy servers
|
|
provisioning server create --infra {{ default_infra }}
|
|
|
|
# SSH to server
|
|
provisioning server ssh {{ servers[0].name }}
|
|
|
|
# Delete servers
|
|
provisioning server delete --infra {{ default_infra }}
|
|
```
|
|
|
|
### Configuration Management
|
|
|
|
```bash
|
|
# Validate Nickel files
|
|
nickel typecheck config/config.ncl
|
|
nickel typecheck infra/{{ default_infra }}/main.ncl
|
|
|
|
# Validate workspace
|
|
nu workspace.nu validate
|
|
|
|
# Export configuration
|
|
provisioning config export
|
|
```
|
|
|
|
---
|
|
|
|
## Common Workflows
|
|
|
|
### Complete Deployment
|
|
|
|
```bash
|
|
# 1. Activate workspace
|
|
provisioning workspace activate {{ workspace_name }}:{{ default_infra }}
|
|
|
|
# 2. Check pricing
|
|
provisioning price --infra {{ default_infra }}
|
|
|
|
# 3. Dry-run
|
|
provisioning -c server create --infra {{ default_infra }}
|
|
|
|
# 4. Deploy
|
|
provisioning server create --infra {{ default_infra }}
|
|
|
|
# 5. Verify
|
|
provisioning server list --infra {{ default_infra }}
|
|
```
|
|
|
|
### Update Configuration
|
|
|
|
```bash
|
|
# 1. Make changes
|
|
vim infra/{{ default_infra }}/servers.ncl
|
|
|
|
# 2. Validate
|
|
nickel typecheck infra/{{ default_infra }}/main.ncl
|
|
|
|
# 3. Dry-run
|
|
provisioning -c server create --infra {{ default_infra }}
|
|
|
|
# 4. Deploy
|
|
provisioning server create --infra {{ default_infra }}
|
|
```
|
|
|
|
### Cleanup
|
|
|
|
```bash
|
|
# 1. Delete servers
|
|
provisioning server delete --infra {{ default_infra }}
|
|
|
|
# 2. Clean cache
|
|
provisioning cache clean
|
|
rm -rf {{ workspace_path }}/.providers/*/state/*
|
|
|
|
# 3. Verify
|
|
provisioning server list --infra {{ default_infra }}
|
|
```
|
|
|
|
---
|
|
|
|
## Workspace Structure
|
|
|
|
```
|
|
{{ workspace_path }}/
|
|
├── docs/ # This directory
|
|
│ ├── README.md # Overview and quick start
|
|
│ ├── deployment-guide.md # Deployment instructions
|
|
│ ├── configuration-guide.md # Configuration reference
|
|
│ └── troubleshooting.md # Common issues
|
|
│
|
|
├── config/ # Workspace configuration
|
|
│ ├── config.ncl # Master Nickel config
|
|
│ ├── kms.toml # KMS configuration
|
|
│ ├── providers/ # Provider configs
|
|
│ └── generated/ # Exported TOML files
|
|
│
|
|
├── infra/ # Infrastructure definitions
|
|
{% for infra in infrastructures %}
|
|
│ ├── {{ infra }}/ # {{ infra | title }} infrastructure
|
|
│ │ ├── main.ncl # Main entry point
|
|
│ │ ├── settings.ncl # Settings
|
|
│ │ ├── servers.ncl # Server definitions
|
|
│ │ └── taskservs/ # Task services
|
|
{% endfor %}
|
|
│
|
|
├── .providers/ # Provider modules
|
|
├── .taskservs/ # Task service modules
|
|
├── .kms/ # KMS data
|
|
├── data/ # Runtime data (cache, prices)
|
|
│
|
|
├── workspace.nu # Workspace utility
|
|
└── README.md # Workspace overview (root)
|
|
```
|
|
|
|
---
|
|
|
|
## Support & Resources
|
|
|
|
### Documentation
|
|
|
|
- **Installation**: `provisioning/docs/src/getting-started/installation-validation-guide.md`
|
|
- **Deployment**: `docs/deployment-guide.md`
|
|
- **Configuration**: `docs/configuration-guide.md`
|
|
- **Troubleshooting**: `docs/troubleshooting.md`
|
|
|
|
### External Resources
|
|
|
|
- **{{ primary_provider | title }}**: {{ provider_url }}
|
|
- **{{ primary_provider | title }} API**: {{ provider_api_url }}
|
|
- **Kubernetes**: https://kubernetes.io/docs/
|
|
|
|
### Getting Help
|
|
|
|
**For Deployment Issues**:
|
|
- See Deployment section in troubleshooting.md
|
|
- Check logs: `tail -f provisioning/platform/orchestrator/data/orchestrator.log`
|
|
- Enable debug: `provisioning --debug server create --infra {{ default_infra }}`
|
|
|
|
**For Configuration Issues**:
|
|
- See Configuration section in troubleshooting.md
|
|
- Review examples in configuration-guide.md
|
|
- Validate: `nickel typecheck config/config.ncl`
|
|
|
|
**For Service Issues**:
|
|
- See Service Installation section in troubleshooting.md
|
|
- Check service status: `provisioning taskserv list --infra {{ default_infra }}`
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
1. **Start with Installation Validation**
|
|
- Read: `provisioning/docs/src/getting-started/installation-validation-guide.md`
|
|
|
|
2. **Follow Deployment Guide**
|
|
- Read: `docs/deployment-guide.md`
|
|
- Execute step-by-step
|
|
|
|
3. **Modify Configuration (Optional)**
|
|
- Read: `docs/configuration-guide.md`
|
|
- Make needed changes
|
|
|
|
4. **Troubleshoot if Issues**
|
|
- Read: `docs/troubleshooting.md`
|
|
- Find and fix issues
|
|
|
|
---
|
|
|
|
**Workspace**: {{ workspace_name }}
|
|
**Location**: {{ workspace_path }}
|
|
**Provider**: {{ primary_provider | title }}
|
|
**Infrastructures**: {{ infrastructures | join(sep=', ') | title }}
|
|
**Generated**: 2025-01-07
|