Migration Guide: v2.x → v3.0

Step-by-step instructions for migrating your #divisions deployment to the latest major release. Estimated downtime: 15–30 minutes.

Target Version
v3.0.0+
Compatibility
v2.4.0+ required
Downtime
~20 min
Last Updated
2025-03-14

Overview

v3.0 introduces a completely redesigned runtime engine, breaking changes to the configuration schema, and deprecated legacy API endpoints. This guide ensures a safe, reversible transition with zero data loss.

⚠️ Breaking Changes
Default auth tokens are now SHA-256 hashed. Legacy base64 tokens will be rejected. Ensure your integrations are updated before proceeding.

Prerequisites

  • Current cluster running #divisions v2.4.0 or higher
  • Root/Sudo access to deployment nodes
  • Backup of /etc/divisions/ and database snapshots
  • External DNS management access (for CNAME cutover)
  • Monitoring alerts configured in Datadog/PagerDuty

Pre-Migration Checklist

  • Verify all services are healthy (dvctl health --all)
  • Run schema compatibility validator (dvctl validate --schema v3)
  • Export custom middleware and plugins
  • Notify stakeholders of maintenance window
  • Disable non-critical background jobs

Phase 1: Environment Setup

1
Install v3 Runtime

Download and extract the v3 binaries to your staging environment.

bash
# Add official repository curl -fsSL https://pkg.divisions.io/v3/gpg | sudo tee /etc/apt/trusted.gpg.d/divisions.asc echo "deb [signed-by=/etc/apt/trusted.gpg.d/divisions.asc] https://pkg.divisions.io/v3 stable main" | sudo tee /etc/apt/sources.list.d/divisions.list # Install packages sudo apt update && sudo apt install -y divisions-v3-runtime divisions-cli
2
Generate v3 Configuration

Use the migration tool to convert your existing dv-config.yaml to the new schema.

bash
# Backup current config cp /etc/divisions/dv-config.yaml /etc/divisions/dv-config.yaml.bak # Run schema migration dvctl migrate config --from v2.4 --to v3.0 --output /etc/divisions/dv-config-v3.yaml # Validate new config dvctl validate --file /etc/divisions/dv-config-v3.yaml
ℹ️ Note
Deprecated fields will be automatically converted. Review the generated file for any manual overrides.

Phase 2: Data & Config Migration

3
Migrate State & Indexes

Sync your metadata, routing tables, and cached indexes to the new storage engine.

bash
# Halt traffic ingestion dvctl gateway set-maintenance true # Migrate state store dvctl migrate state --batch-size 1000 --workers 4 # Rebuild search indexes dvctl index rebuild --parallel

Phase 3: Validation & Testing

4
Run Integration Tests

Verify core functionality before opening traffic. The v3 CLI includes a built-in test suite.

bash
# Execute pre-flight checks dvctl test suite --env staging --verbose Expected output: ✔ Authentication flow ✔ Route resolution ✔ Data integrity checks ✔ TLS certificate validation
🛑 Stop Migration
If any test fails, do not proceed to Phase 4. Review logs at /var/log/divisions/migrate.log and contact support.

Phase 4: Cutover & Rollout

5
Switch Traffic & Verify

Update DNS or load balancer rules to point to the v3 cluster. Enable traffic gradually if using blue-green deployment.

bash
# Enable gateway dvctl gateway set-maintenance false # Monitor live health dvctl monitor --live --interval 5s

Rollback Procedure

If critical issues arise post-cutover, revert to v2.x within the maintenance window:

  1. Disable v3 gateway: dvctl gateway set-maintenance true
  2. Restore DNS/LB to v2 endpoints
  3. Restore config: cp /etc/divisions/dv-config.yaml.bak /etc/divisions/dv-config.yaml
  4. Restart v2 services: systemctl restart divisions-v2
  5. Verify traffic flow and data consistency
✅ Rollback Complete
All state migrations are non-destructive. You can retry v3 migration at any time without re-exporting data.

Troubleshooting

Common Issues

  • Schema Validation Failures: Ensure no custom plugins override reserved keys. Use --strict=false for legacy overrides.
  • High CPU during Index Rebuild: Reduce --workers count or schedule during off-peak hours.
  • TLS Handshake Errors: v3 requires TLS 1.2+. Update cert-manager or ACME client.

Log Locations

paths
Runtime: /var/log/divisions/runtime.log Migration: /var/log/divisions/migrate.log Gateway: /var/log/divisions/gateway.log

Support & Resources

Need assistance during migration? Our engineering team is available during the maintenance window.

ℹ️ Post-Migration
After 30 days of stable operation, we recommend removing v2 binaries to free disk space. Run dvctl cleanup --remove-v2.