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/
323 lines
6.1 KiB
Django/Jinja
323 lines
6.1 KiB
Django/Jinja
# Workspace {{ workspace_name | title }} - Deployment Guide
|
|
|
|
**Workspace**: {{ workspace_name }}
|
|
**Location**: {{ workspace_path }}
|
|
**Provider**: {{ primary_provider | title }}{% if primary_zone %} ({{ primary_zone }} zone){% endif %}
|
|
**Active Infrastructures**: {{ infrastructures | join(sep=', ') }}
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
This guide provides step-by-step instructions for deploying the **{{ workspace_name }}** infrastructure.
|
|
|
|
{% for infra in infrastructures %}
|
|
### Infrastructure: {{ infra | title }}
|
|
|
|
**Purpose**: {{ infrastructure_purposes[infra] }}
|
|
**Location**: `infra/{{ infra }}/`
|
|
|
|
{% endfor %}
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
Before deploying, ensure you have completed:
|
|
|
|
1. **Installation Validation Guide**
|
|
- Available at: `provisioning/docs/src/getting-started/installation-validation-guide.md`
|
|
- Verify all prerequisites are installed
|
|
|
|
2. **Required Tools**
|
|
- Nushell 0.109.0+
|
|
- Nickel 1.x.x
|
|
- Docker 20.10+
|
|
- macOS, Linux, or WSL2
|
|
|
|
3. **Provider Credentials**
|
|
{% for provider in providers %}
|
|
- {{ provider | title }} account and credentials
|
|
{% endfor %}
|
|
|
|
4. **SSH Key**
|
|
- Location: `~/.ssh/id_deployment.pub`
|
|
- Generate if missing: `ssh-keygen -t ed25519 -f ~/.ssh/id_deployment`
|
|
|
|
---
|
|
|
|
## Section 1: Credentials Setup
|
|
|
|
### Step 1.1: {{ primary_provider | title }} Credentials
|
|
|
|
**Option A: Environment Variables**
|
|
|
|
```bash
|
|
{% for var, hint in provider_env_vars %}
|
|
export {{ var }}="{{ hint }}"
|
|
{% endfor %}
|
|
```
|
|
|
|
**Option B: Configuration File**
|
|
|
|
Create `~/.config/{{ primary_provider | lower }}.yaml`:
|
|
|
|
```yaml
|
|
{% for key, value in provider_config_example %}
|
|
{{ key }}: {{ value }}
|
|
{% endfor %}
|
|
```
|
|
|
|
### Step 1.2: Verify Credentials
|
|
|
|
```bash
|
|
# Test provider connectivity
|
|
provisioning -c server create --infra {{ default_infra }}
|
|
```
|
|
|
|
Expected: Shows servers to be created (dry-run check, no resources created)
|
|
|
|
---
|
|
|
|
## Section 2: SSH Key Configuration
|
|
|
|
### Step 2.1: Verify SSH Key
|
|
|
|
```bash
|
|
ls -la ~/.ssh/id_deployment.pub
|
|
```
|
|
|
|
### Step 2.2: Generate SSH Key (if needed)
|
|
|
|
```bash
|
|
ssh-keygen -t ed25519 -f ~/.ssh/id_deployment -C "provisioning@{{ workspace_name }}"
|
|
```
|
|
|
|
### Step 2.3: Update Configuration (if needed)
|
|
|
|
**File**: `infra/{{ default_infra }}/servers.ncl`
|
|
|
|
```nickel
|
|
ssh_key_path = "~/.ssh/id_deployment.pub"
|
|
```
|
|
|
|
---
|
|
|
|
## Section 3: Workspace Activation
|
|
|
|
### Step 3.1: Register Workspace
|
|
|
|
```bash
|
|
provisioning workspace register {{ workspace_name }} {{ workspace_path }}
|
|
```
|
|
|
|
### Step 3.2: Activate Workspace
|
|
|
|
```bash
|
|
provisioning workspace activate {{ workspace_name }}:{{ default_infra }}
|
|
```
|
|
|
|
### Step 3.3: Verify Configuration
|
|
|
|
```bash
|
|
cd {{ workspace_path }}
|
|
|
|
# Validate Nickel syntax
|
|
{% for infra in infrastructures -%}
|
|
nickel typecheck infra/{{ infra }}/main.ncl
|
|
{% endfor %}
|
|
|
|
# Workspace validation
|
|
nu workspace.nu validate
|
|
```
|
|
|
|
---
|
|
|
|
## Section 4: Pre-Deployment Review
|
|
|
|
### Step 4.1: Review Infrastructure Configuration
|
|
|
|
```bash
|
|
cd {{ workspace_path }}
|
|
|
|
# View server definitions
|
|
cat infra/{{ default_infra }}/servers.ncl
|
|
```
|
|
|
|
Expected servers:
|
|
{% for server in servers -%}
|
|
- {{ server.name }} ({{ server.plan }}, {{ server.storage }}GB)
|
|
{% endfor %}
|
|
|
|
### Step 4.2: Check Pricing
|
|
|
|
```bash
|
|
provisioning price --infra {{ default_infra }}
|
|
```
|
|
|
|
Expected monthly cost: {{ pricing_estimate }}
|
|
|
|
### Step 4.3: Dry-Run Deployment
|
|
|
|
```bash
|
|
provisioning -c server create --infra {{ default_infra }}
|
|
```
|
|
|
|
---
|
|
|
|
## Section 5: Deploy Servers
|
|
|
|
**⚠️ WARNING: This creates REAL resources and incurs COSTS**
|
|
|
|
### Pre-Deployment Checklist
|
|
|
|
```
|
|
[ ] Provider credentials configured and tested
|
|
[ ] SSH key exists and path is correct
|
|
[ ] Workspace activated
|
|
[ ] Configuration validated
|
|
[ ] Dry-run passed
|
|
[ ] Pricing reviewed and acceptable
|
|
```
|
|
|
|
### Step 5.1: Create Servers
|
|
|
|
```bash
|
|
cd {{ workspace_path }}/infra/{{ default_infra }}
|
|
|
|
provisioning server create
|
|
```
|
|
|
|
Expected duration: 2-5 minutes
|
|
|
|
### Step 5.2: Verify Deployment
|
|
|
|
```bash
|
|
provisioning server list --infra {{ default_infra }}
|
|
```
|
|
|
|
### Step 5.3: Test SSH Connectivity
|
|
|
|
```bash
|
|
provisioning server ssh {{ servers[0].name }} --command "uptime"
|
|
```
|
|
|
|
---
|
|
|
|
## Section 6: Install Services (Optional)
|
|
|
|
Once servers are deployed, install services:
|
|
|
|
{% for service in taskservs -%}
|
|
### Install {{ service | title }}
|
|
|
|
```bash
|
|
provisioning taskserv create {{ service }} --infra {{ default_infra }}
|
|
```
|
|
|
|
{% endfor %}
|
|
|
|
Verify all services:
|
|
|
|
```bash
|
|
provisioning taskserv list --infra {{ default_infra }}
|
|
```
|
|
|
|
---
|
|
|
|
## Section 7: Verification & Monitoring
|
|
|
|
### Step 7.1: Server Health Check
|
|
|
|
```bash
|
|
provisioning server list --infra {{ default_infra }}
|
|
```
|
|
|
|
Expected: All servers showing "running" status
|
|
|
|
### Step 7.2: Network Connectivity
|
|
|
|
```bash
|
|
{% if servers %}
|
|
# Test connectivity between servers
|
|
ssh root@{{ servers[0].name }} "ping -c 3 {{ servers[0].name }}"
|
|
{% endif %}
|
|
```
|
|
|
|
### Step 7.3: Monitor Workflows
|
|
|
|
```bash
|
|
provisioning workflow list
|
|
provisioning workflow monitor <workflow_id>
|
|
```
|
|
|
|
---
|
|
|
|
## Section 8: Troubleshooting
|
|
|
|
See `docs/troubleshooting.md` for common issues and solutions.
|
|
|
|
**Quick Reference**:
|
|
- Authentication issues: Check provider credentials
|
|
- SSH failures: Wait 2-3 minutes for server boot
|
|
- Service installation errors: Check server resources
|
|
|
|
---
|
|
|
|
## Section 9: Cleanup & Teardown
|
|
|
|
### Step 9.1: Delete Servers
|
|
|
|
```bash
|
|
cd {{ workspace_path }}/infra/{{ default_infra }}
|
|
|
|
provisioning server delete
|
|
```
|
|
|
|
### Step 9.2: Clean Cache
|
|
|
|
```bash
|
|
provisioning cache clean
|
|
rm -rf {{ workspace_path }}/.providers/*/state/*
|
|
```
|
|
|
|
---
|
|
|
|
## Quick Reference Commands
|
|
|
|
```bash
|
|
# Setup
|
|
cd {{ workspace_path }}
|
|
|
|
# Activate
|
|
provisioning workspace activate {{ workspace_name }}:{{ default_infra }}
|
|
|
|
# Validate
|
|
provisioning -c server create --infra {{ default_infra }}
|
|
|
|
# Deploy
|
|
provisioning server create --infra {{ default_infra }}
|
|
|
|
# Verify
|
|
provisioning server list --infra {{ default_infra }}
|
|
|
|
# Cleanup
|
|
provisioning server delete --infra {{ default_infra }}
|
|
provisioning cache clean
|
|
```
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
After deployment:
|
|
1. Configure applications
|
|
2. Set up monitoring
|
|
3. Plan backup strategy
|
|
4. Configure security
|
|
|
|
For more information, see:
|
|
- Configuration Guide: `docs/configuration-guide.md`
|
|
- Troubleshooting Guide: `docs/troubleshooting.md`
|
|
- Installation Guide: `provisioning/docs/src/getting-started/installation-validation-guide.md`
|