provisioning/docs/src/development/migration-guide.md

Migration Guide: Target-Based Configuration System

Overview

This guide walks through migrating from the old config.defaults.toml system to the new workspace-based target configuration system.

Migration Path

Old System                          New System
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
config.defaults.toml          →     ~/workspaces/{name}/config/provisioning.yaml
config.user.toml              →     ~/Library/Application Support/provisioning/ws_{name}.yaml
providers/{name}/config       →     ~/workspaces/{name}/config/providers/{name}.toml
                              →     ~/workspaces/{name}/config/platform/{service}.toml
```plaintext

## Step-by-Step Migration

### 1. Pre-Migration Check

```bash
# Check current configuration
provisioning env

# Backup current configuration
cp -r provisioning/config provisioning/config.backup.$(date +%Y%m%d)
```plaintext

### 2. Run Migration Script (Dry Run)

```bash
# Preview what will be done
./provisioning/scripts/migrate-to-target-configs.nu \
  --workspace-name "my-project" \
  --dry-run
```plaintext

### 3. Execute Migration

```bash
# Run with backup
./provisioning/scripts/migrate-to-target-configs.nu \
  --workspace-name "my-project" \
  --backup

# Or specify custom workspace path
./provisioning/scripts/migrate-to-target-configs.nu \
  --workspace-name "my-project" \
  --workspace-path "$HOME/my-custom-path" \
  --backup
```plaintext

### 4. Verify Migration

```bash
# Validate workspace configuration
provisioning workspace config validate

# Check workspace status
provisioning workspace info

# List all workspaces
provisioning workspace list
```plaintext

### 5. Test Configuration

```bash
# Test with new configuration
provisioning --check server list

# Test provider configuration
provisioning provider validate aws

# Test platform configuration
provisioning platform orchestrator status
```plaintext

### 6. Update Environment Variables (if any)

```bash
# Old approach (no longer needed)
# export PROVISIONING_CONFIG_PATH="/path/to/config.defaults.toml"

# New approach - workspace is auto-detected from context
# Or set explicitly:
export PROVISIONING_WORKSPACE="my-project"
```plaintext

### 7. Clean Up Old Configuration

```bash
# After verifying everything works
rm provisioning/config/config.defaults.toml
rm provisioning/config/config.user.toml

# Keep backup for reference
# provisioning/config.backup.YYYYMMDD/
```plaintext

## Migration Script Options

### Required Arguments

- `--workspace-name`: Name for the new workspace (default: "default")

### Optional Arguments

- `--workspace-path`: Custom path for workspace (default: `~/workspaces/{name}`)
- `--dry-run`: Preview migration without making changes
- `--backup`: Create backup of old configuration files

### Examples

```bash
# Basic migration with default workspace
./provisioning/scripts/migrate-to-target-configs.nu --backup

# Custom workspace name
./provisioning/scripts/migrate-to-target-configs.nu \
  --workspace-name "production" \
  --backup

# Custom workspace path
./provisioning/scripts/migrate-to-target-configs.nu \
  --workspace-name "staging" \
  --workspace-path "/opt/workspaces/staging" \
  --backup

# Dry run first
./provisioning/scripts/migrate-to-target-configs.nu \
  --workspace-name "production" \
  --dry-run
```plaintext

## New Workspace Structure

After migration, your workspace will look like:

```plaintext
~/workspaces/{name}/
├── config/
│   ├── provisioning.yaml          # Main workspace config
│   ├── providers/
│   │   ├── aws.toml               # AWS provider config
│   │   ├── upcloud.toml           # UpCloud provider config
│   │   └── local.toml             # Local provider config
│   └── platform/
│       ├── orchestrator.toml      # Orchestrator config
│       ├── control-center.toml    # Control center config
│       └── kms.toml               # KMS config
├── infra/
│   └── {infra-name}/              # Infrastructure definitions
├── .cache/                        # Cache directory
└── .runtime/                      # Runtime data
```plaintext

User context stored at:

```plaintext
~/Library/Application Support/provisioning/
└── ws_{name}.yaml                 # User workspace context
```plaintext

## Configuration Schema Validation

### Validate Workspace Config

```bash
# Validate main workspace configuration
provisioning workspace config validate

# Validate specific provider
provisioning provider validate aws

# Validate platform service
provisioning platform validate orchestrator
```plaintext

### Manual Validation

```nushell
use provisioning/core/nulib/lib_provisioning/config/schema_validator.nu *

# Validate workspace config
let config = (open ~/workspaces/my-project/config/provisioning.yaml | from yaml)
let result = (validate-workspace-config $config)
print-validation-results $result

# Validate provider config
let aws_config = (open ~/workspaces/my-project/config/providers/aws.toml | from toml)
let result = (validate-provider-config "aws" $aws_config)
print-validation-results $result
```plaintext

## Troubleshooting

### Migration Fails

**Problem**: Migration script fails with "workspace path already exists"

**Solution**:

```bash
# Use merge mode
# The script will prompt for confirmation
./provisioning/scripts/migrate-to-target-configs.nu --workspace-name "existing"

# Or choose different workspace name
./provisioning/scripts/migrate-to-target-configs.nu --workspace-name "existing-v2"
```plaintext

### Config Not Found

**Problem**: Commands can't find configuration after migration

**Solution**:

```bash
# Check workspace context
provisioning workspace info

# Ensure workspace is active
provisioning workspace activate my-project

# Manually set workspace
export PROVISIONING_WORKSPACE="my-project"
```plaintext

### Validation Errors

**Problem**: Configuration validation fails after migration

**Solution**:

```bash
# Check validation output
provisioning workspace config validate

# Review and fix errors in config files
vim ~/workspaces/my-project/config/provisioning.yaml

# Validate again
provisioning workspace config validate
```plaintext

### Provider Configuration Issues

**Problem**: Provider authentication fails after migration

**Solution**:

```bash
# Check provider configuration
cat ~/workspaces/my-project/config/providers/aws.toml

# Update credentials
vim ~/workspaces/my-project/config/providers/aws.toml

# Validate provider config
provisioning provider validate aws
```plaintext

## Testing Migration

Run the test suite to verify migration:

```bash
# Run configuration validation tests
nu provisioning/tests/config_validation_tests.nu

# Run integration tests
provisioning test --workspace my-project

# Test specific functionality
provisioning --check server list
provisioning --check taskserv list
```plaintext

## Rollback Procedure

If migration causes issues, rollback:

```bash
# Restore old configuration
cp -r provisioning/config.backup.YYYYMMDD/* provisioning/config/

# Remove new workspace
rm -rf ~/workspaces/my-project
rm ~/Library/Application\ Support/provisioning/ws_my-project.yaml

# Unset workspace environment variable
unset PROVISIONING_WORKSPACE

# Verify old config works
provisioning env
```plaintext

## Migration Checklist

- [ ] Backup current configuration
- [ ] Run migration script in dry-run mode
- [ ] Review dry-run output
- [ ] Execute migration with backup
- [ ] Verify workspace structure created
- [ ] Validate all configurations
- [ ] Test provider authentication
- [ ] Test platform services
- [ ] Run test suite
- [ ] Update documentation/scripts if needed
- [ ] Clean up old configuration files
- [ ] Document any custom changes

## Next Steps

After successful migration:

1. **Review Workspace Configuration**: Customize `provisioning.yaml` for your needs
2. **Configure Providers**: Update provider configs in `config/providers/`
3. **Configure Platform Services**: Update platform configs in `config/platform/`
4. **Test Operations**: Run `--check` mode commands to verify
5. **Update CI/CD**: Update pipelines to use new workspace system
6. **Document Changes**: Update team documentation

## Additional Resources

- [Workspace Configuration Schema](../config/workspace.schema.toml)
- [Provider Configuration Schemas](../extensions/providers/*/config.schema.toml)
- [Platform Configuration Schemas](../platform/*/config.schema.toml)
- [Configuration Validation Guide](CONFIG_VALIDATION.md)
- [Workspace Management Guide](WORKSPACE_GUIDE.md)