provisioning/docs/MIGRATION_VALIDATION_SUMMARY.md

Migration and Validation System Summary

Overview

A comprehensive migration and validation system has been implemented to transition from the old config.defaults.toml system to the new workspace-based target configuration architecture.

Components Delivered

1. Migration Script

File: /Users/Akasha/project-provisioning/provisioning/scripts/migrate-to-target-configs.nu

Features:

• Automatic detection of old configuration files
• Workspace structure creation with proper directory hierarchy
• Configuration transformation from TOML to YAML with interpolation
• Provider migration with template-based generation
• User context creation for workspace management
• Safety features: dry-run mode, backup option, confirmation prompts

Usage:

# Dry run to preview changes
./provisioning/scripts/migrate-to-target-configs.nu \
  --workspace-name "my-project" \
  --dry-run

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

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

2. Schema Validator

File: /Users/Akasha/project-provisioning/provisioning/core/nulib/lib_provisioning/config/schema_validator.nu

Validation Features:

• Required fields: Ensures mandatory fields are present
• Type checking: Validates field types (string, int, bool, record)
• Enum validation: Restricts values to predefined sets
• Range validation: Validates min/max for numeric values
• Pattern matching: Regex validation for strings
• Deprecation warnings: Alerts for deprecated fields with replacements
• Pretty printing: Formatted validation results

Functions:

# Core validation
validate-config-with-schema $config $schema_file

# Domain-specific validators
validate-provider-config "aws" $config
validate-platform-config "orchestrator" $config
validate-kms-config $config
validate-workspace-config $config

# Display results
print-validation-results $result

3. Test Suite

File: /Users/Akasha/project-provisioning/provisioning/tests/config_validation_tests.nu

Test Coverage:

• ✅ Required fields validation
• ✅ Type validation (int, string, bool)
• ✅ Enum validation
• ✅ Range validation (min/max)
• ✅ Pattern validation (regex)
• ✅ Deprecated fields warning

Run Tests:

nu /Users/Akasha/project-provisioning/provisioning/tests/config_validation_tests.nu

4. Documentation

Migration Guide: /Users/Akasha/project-provisioning/provisioning/docs/MIGRATION_GUIDE.md

• Step-by-step migration process
• Troubleshooting guide
• Rollback procedure
• Migration checklist

Validation Guide: /Users/Akasha/project-provisioning/provisioning/docs/CONFIG_VALIDATION.md

• Schema validation features
• Usage examples
• Common validation patterns
• Best practices

Migration Workflow

Phase 1: Preparation

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

# 2. Review current configuration
provisioning env

# 3. Run dry-run migration
./provisioning/scripts/migrate-to-target-configs.nu \
  --workspace-name "my-project" \
  --dry-run

Phase 2: Execution

# 4. Execute migration with backup
./provisioning/scripts/migrate-to-target-configs.nu \
  --workspace-name "my-project" \
  --backup

# Output shows:
# ✅ Created workspace structure
# ✅ Generated provisioning.yaml
# ✅ Migrated provider configs
# ✅ Created user context

Phase 3: Validation

# 5. Validate workspace configuration
provisioning workspace config validate

# 6. Validate provider configurations
provisioning provider validate aws
provisioning provider validate upcloud

# 7. Validate platform services
provisioning platform validate orchestrator

Phase 4: Testing

# 8. Test operations in check mode
provisioning --check server list
provisioning --check taskserv list

# 9. Run validation test suite
nu provisioning/tests/config_validation_tests.nu

# 10. Verify workspace status
provisioning workspace info

Phase 5: Cleanup

# 11. Remove old configuration (after verification)
rm provisioning/config/config.defaults.toml
rm provisioning/config/config.user.toml

# Keep backup for reference
ls -la provisioning/config.backup.*

New Workspace Structure

~/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 service config
│       ├── control-center.toml       # Control center config
│       └── kms.toml                  # KMS service config
├── infra/
│   └── {infra-name}/                 # Infrastructure definitions
├── .cache/                           # Cache directory
└── .runtime/                         # Runtime data

# User Context
~/Library/Application Support/provisioning/
└── ws_{name}.yaml                    # Workspace context

Schema Validation Examples

Workspace Schema

# Required fields
[required]
fields = ["workspace", "paths"]

# Type validation
[fields.workspace.name]
type = "string"
pattern = "^[a-z][a-z0-9-]*$"

# Enum validation
[fields.debug.log_level]
type = "string"
enum = ["debug", "info", "warn", "error"]

Provider Schema (AWS)

[fields.provider.region]
type = "string"
pattern = "^[a-z]{2}-[a-z]+-\\d+$"

[fields.compute.default_ami]
type = "string"
pattern = "^ami-[a-f0-9]{8,17}$"

# Deprecation
[deprecated]
fields = ["old_region_field"]

[deprecated_replacements]
old_region_field = "provider.region"

Platform Schema (Orchestrator)

[fields.server.port]
type = "int"
min = 1024
max = 65535

[fields.workers]
type = "int"
min = 1
max = 32

Validation Results Format

Success

✅ Validation passed

Errors

❌ Validation failed

Errors:
  • Required field missing: workspace.name
  • Field port type mismatch: expected int, got string
  • Field environment must be one of: dev, staging, prod
  • Field email does not match pattern: ^[a-zA-Z0-9._%+-]+@.*$

Warnings

⚠️  Warnings:
  • Field old_field is deprecated. Use new_field instead.
  • Field legacy_setting is deprecated. Use new_setting instead.

Integration with CLI

New Commands

# Workspace management
provisioning workspace config validate
provisioning workspace info
provisioning workspace list

# Provider validation
provisioning provider validate aws
provisioning provider validate --all

# Platform validation
provisioning platform validate orchestrator
provisioning platform validate --all

Migration Command (Future)

# Integrated migration command
provisioning migrate config \
  --workspace-name "my-project" \
  --backup \
  --dry-run

Testing

Unit Tests

# Run validation test suite
nu /Users/Akasha/project-provisioning/provisioning/tests/config_validation_tests.nu

# Expected output:
# 🧪 Configuration Validation Test Suite
# ======================================
#
# Test 1: Required Fields Validation
#   ✅ PASSED
#
# Test 2: Type Validation
#   ✅ PASSED
#
# Test 3: Enum Validation
#   ✅ PASSED
#
# Test 4: Range Validation
#   ✅ PASSED
#
# Test 5: Pattern Validation
#   ✅ PASSED
#
# Test 6: Deprecated Fields Warning
#   ✅ PASSED
#
# 📊 Results: 6 passed, 0 failed
# ✅ All tests passed!

Integration Tests

# Test workspace creation
provisioning workspace create test-workspace

# Validate created workspace
provisioning workspace config validate --workspace test-workspace

# Test provider configuration
provisioning provider validate aws --workspace test-workspace

Error Handling

Migration Errors

Workspace exists:

# Error: Workspace path already exists
# Solution: Use merge mode or different name
./provisioning/scripts/migrate-to-target-configs.nu \
  --workspace-name "my-project-v2"

Old config not found:

# Info: No old config found. System may already be migrated.
# Solution: No action needed

Validation Errors

Schema not found:

# Error: Schema file not found: /path/to/schema.toml
# Solution: Ensure schema files exist in correct location

Type mismatch:

# Error: Field port type mismatch: expected int, got string
# Solution: Fix config file (remove quotes from numbers)

Best Practices

1. Always Backup

./provisioning/scripts/migrate-to-target-configs.nu \
  --workspace-name "production" \
  --backup  # ← Always use --backup for production

2. Dry Run First

# Preview changes before applying
./provisioning/scripts/migrate-to-target-configs.nu \
  --workspace-name "production" \
  --dry-run

3. Validate Early

# Validate during development
provisioning workspace config validate

# Validate before deployment
provisioning workspace config validate --verbose

4. Test Thoroughly

# Run test suite
nu provisioning/tests/config_validation_tests.nu

# Test operations in check mode
provisioning --check server list

5. Document Changes

# Keep migration log
./provisioning/scripts/migrate-to-target-configs.nu \
  --workspace-name "production" \
  --backup 2>&1 | tee migration.log

Troubleshooting

Common Issues

1. Migration fails with "workspace exists"

   • Use --workspace-name with different name
   • Or allow merge when prompted

2. Validation fails after migration

   • Check validation output for specific errors
   • Review and fix config files
   • Re-run validation

3. Provider authentication fails

   • Update credentials in provider config files
   • Validate provider configuration
   • Test provider connection

4. Commands can't find configuration

   • Check workspace context: provisioning workspace info
   • Activate workspace: provisioning workspace activate my-project
   • Or set: export PROVISIONING_WORKSPACE="my-project"

Next Steps

1. Review generated configurations - Customize for your needs
2. Update provider credentials - Configure cloud provider access
3. Test operations - Run commands in --check mode
4. Update CI/CD pipelines - Integrate validation into pipelines
5. Document customizations - Keep team documentation updated

Files Created

File	Purpose
/Users/Akasha/project-provisioning/provisioning/scripts/migrate-to-target-configs.nu	Migration script
/Users/Akasha/project-provisioning/provisioning/core/nulib/lib_provisioning/config/schema_validator.nu	Schema validation library
/Users/Akasha/project-provisioning/provisioning/tests/config_validation_tests.nu	Validation test suite
/Users/Akasha/project-provisioning/provisioning/docs/MIGRATION_GUIDE.md	Migration documentation
/Users/Akasha/project-provisioning/provisioning/docs/CONFIG_VALIDATION.md	Validation documentation
/Users/Akasha/project-provisioning/provisioning/docs/MIGRATION_VALIDATION_SUMMARY.md	This summary

Success Criteria

✅ Migration script:

• Detects old configuration
• Creates workspace structure
• Migrates provider configs
• Generates user context
• Safety features (dry-run, backup)

✅ Schema validator:

• Validates required fields
• Checks types
• Validates enums
• Range validation
• Pattern matching
• Deprecation warnings

✅ Test suite:

• 6 comprehensive tests
• All test scenarios covered
• Clear pass/fail reporting

✅ Documentation:

• Complete migration guide
• Validation guide with examples
• Troubleshooting procedures
• Best practices

Conclusion

The migration and validation system provides a complete, safe, and validated path from the old configuration system to the new workspace-based architecture. All components are tested, documented, and ready for use.