504 lines
12 KiB
Markdown
504 lines
12 KiB
Markdown
# 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**:
|
|
```bash
|
|
# 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**:
|
|
```nushell
|
|
# 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**:
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```toml
|
|
# 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)
|
|
|
|
```toml
|
|
[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)
|
|
|
|
```toml
|
|
[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
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
```bash
|
|
# Integrated migration command
|
|
provisioning migrate config \
|
|
--workspace-name "my-project" \
|
|
--backup \
|
|
--dry-run
|
|
```
|
|
|
|
## Testing
|
|
|
|
### Unit Tests
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
# Info: No old config found. System may already be migrated.
|
|
# Solution: No action needed
|
|
```
|
|
|
|
### Validation Errors
|
|
|
|
**Schema not found**:
|
|
```bash
|
|
# Error: Schema file not found: /path/to/schema.toml
|
|
# Solution: Ensure schema files exist in correct location
|
|
```
|
|
|
|
**Type mismatch**:
|
|
```bash
|
|
# Error: Field port type mismatch: expected int, got string
|
|
# Solution: Fix config file (remove quotes from numbers)
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
### 1. Always Backup
|
|
|
|
```bash
|
|
./provisioning/scripts/migrate-to-target-configs.nu \
|
|
--workspace-name "production" \
|
|
--backup # ← Always use --backup for production
|
|
```
|
|
|
|
### 2. Dry Run First
|
|
|
|
```bash
|
|
# Preview changes before applying
|
|
./provisioning/scripts/migrate-to-target-configs.nu \
|
|
--workspace-name "production" \
|
|
--dry-run
|
|
```
|
|
|
|
### 3. Validate Early
|
|
|
|
```bash
|
|
# Validate during development
|
|
provisioning workspace config validate
|
|
|
|
# Validate before deployment
|
|
provisioning workspace config validate --verbose
|
|
```
|
|
|
|
### 4. Test Thoroughly
|
|
|
|
```bash
|
|
# Run test suite
|
|
nu provisioning/tests/config_validation_tests.nu
|
|
|
|
# Test operations in check mode
|
|
provisioning --check server list
|
|
```
|
|
|
|
### 5. Document Changes
|
|
|
|
```bash
|
|
# 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.
|