Chapter 3. Migrating with minimal downtime

Phase 1: Preparation

1. Deploy load balancer

   If not already using a load balancer, deploy nginx or HAProxy in front of your existing 2.6 deployment:

   1. Deploy load balancer
   2. Configure to route traffic to 2.6
   3. Update client applications to connect through load balancer
   4. Validate all traffic flows correctly

   See Updating registry configuration for load balancer configuration examples.

2. Prepare Apicurio Registry 3.x infrastructure

   Deploy the infrastructure for Apicurio Registry 3.x without starting the registry application:

   • For SQL storage: Deploy a separate database instance or create a separate schema
   • For KafkaSQL storage: Use the same Kafka cluster but configure a different topic name
   • Prepare TLS certificates (can reuse 2.6 certificates)
   • Configure the OAuth2/OIDC authentication provider

   See Updating registry configuration for detailed configuration changes.

   Checkpoint: v2 traffic flowing through load balancer, v3 infrastructure ready.

Phase 2: Pre-migration validation

3. Enable read-only mode

   Configure the load balancer to block write operations while allowing read operations. This prevents data changes during export.

   Update your load balancer configuration to block POST, PUT, PATCH, and DELETE methods:

   # nginx read-only configuration
   server {
       location / {
           if ($request_method !~ ^(GET|HEAD|OPTIONS)$) {
               return 405 "Registry temporarily in read-only mode for migration";
           }
           proxy_pass http://registry-v2:8080;
       }
   }

   Copy to Clipboard Toggle word wrap

   Reload the load balancer configuration and verify that read-only mode works correctly.

   Impact: Read operations (schema lookups) continue normally. Write operations (new schemas, updates) return HTTP 405. Kafka producers with auto-registration enabled cannot register new schemas.

4. Capture baseline metrics

   Record the current state of your 2.6 deployment for comparison after migration.

   For the metrics capture procedure, see Migration scripts reference.

   Checkpoint: Read-only mode active, write operations blocked. Baseline documented, ready for data migration.

Phase 3: Data migration

5. Export data from 2.6

   Export all artifacts, versions, metadata, and rules from 2.6 while the registry is in read-only mode.

   For the export procedure, see Migrating Apicurio Registry data.

   Important

   Access the registry directly (not through the load balancer) to bypass read-only restrictions on admin endpoints if needed.

   Checkpoint: Export complete, data snapshot captured.

6. Deploy Apicurio Registry 3.x

   Deploy Apicurio Registry 3.x using the infrastructure prepared in Step 2. Configure the v3 deployment similarly to the previous v2 deployment. Note that various configuration parameters are renamed or changed.

   See Updating registry configuration for v3 configuration information and examples.

   Checkpoint: Apicurio Registry 3.x deployed and healthy (empty, awaiting import).

7. Import data into Apicurio Registry 3.x

   Import the exported ZIP archive into the 3.x deployment.

   For the import procedure, see Migrating Apicurio Registry data.

   Note

   The import adds to existing data and does not replace it. For best results, import into an empty v3 registry.

   Checkpoint: Import complete, ready for validation.

8. Validate import

   Verify the Apicurio Registry 3.x deployment and confirm that the data migration succeeded.

   For the validation procedure, see Migrating Apicurio Registry data.

   If validation fails, investigate import logs and retry if necessary. Do not proceed to traffic switch until all checks pass.

   Checkpoint: v3 has all data, data metrics match v2, ready for traffic switch.

Phase 4: Traffic switch

9. Switch load balancer to Apicurio Registry 3.x

   Update the load balancer configuration to route to Apicurio Registry 3.x and enable read/write operations. The following example shows an nginx configuration:

   # nginx v3 configuration (read/write enabled)
   upstream registry {
       server registry-v3:8080;
   }
   
   server {
       location / {
           # All methods allowed
           proxy_pass http://registry;
           proxy_set_header Host $host;
       }
   }

   Copy to Clipboard Toggle word wrap

   Reload the load balancer.

   Service Interruption: This operation may cause 10-30 seconds of brief service interruption during the reload. If your load balancer supports graceful reloads (for example, nginx -s reload), the interruption may be minimal.

   Checkpoint: All traffic routed to v3, write operations resumed.

10. Verify traffic to the v3 deployment

    Confirm traffic is flowing to Apicurio Registry 3.x through the load balancer. Verify the registry is accessible, version is 3.x, health checks pass, and write operations are enabled.

    For the verification procedure, see Migration scripts reference.

    Checkpoint: Confirmed v3 is accessible and write operations working, no errors in logs.

Phase 5: Post-migration validation

11. Test v2 API backward compatibility

    Verify that existing v2 clients can access the 3.x registry through the v2 API compatibility layer.

    For backward compatibility details and client migration guidance, see Migrating Apicurio Registry client applications.

    Checkpoint: v2 clients work correctly against v3 registry.

12. Test v3 Core API functionality

    Verify v3-specific API features work correctly, including system endpoints, search endpoints, admin endpoints, and the Branch API.

    For the v3 API verification procedure, see Migration scripts reference.

    Checkpoint: v3 Core API features working correctly.

13. Run smoke tests

    Execute production smoke tests to validate critical functionality:

    1. Test critical client applications
    2. Verify Kafka SerDes applications work (if applicable)
    3. Check authentication and authorization
    4. Monitor error rates and performance metrics
    5. Validate no increase in 4xx/5xx errors

    Checkpoint: All smoke tests passed, production traffic stable.

Phase 6: Stabilization

14. Monitor and observe

    Keep 2.6 running but not serving traffic for rollback capability:

    • Monitor Apicurio Registry 3.x for 24-48 hours minimum
    • Watch for error rates, performance issues, or unexpected behavior
    • Prepare for immediate rollback if critical issues arise (switch load balancer back to v2)
    • Begin planning gradual client application migration to v3 SDKs

    See Migrating registry client applications for guidance on updating client applications.

    Checkpoint: v3 stable for 1-7 days, no rollback needed.

15. Decommission 2.6

    After 1-7 days of successful operation on Apicurio Registry 3.x, decommission v2 infrastructure.

    Update documentation to reflect v3 as the production registry.

    Checkpoint: Migration complete, v2 decommissioned.