Upgrade Guide for the SOAP-2-REST Platform

Overview

This guide describes the standard procedure for upgrading the SOAP-2-REST platform between releases. The platform is designed with specific principles to ensure that upgrades are safe, predictable, and observable. As version v1.0 is the first generally available release, this procedure applies to all future upgrades from that point forward.

The core principles of the upgrade process are:

• Automated Schema Migrations: Database schema changes are applied automatically on startup by the admin-api service using Flyway. Migrations are immutable and forward-only. Manual schema intervention is not required.
• Preservation of Service Behavior: Upgrading the platform does not alter your existing service mappings or their generated API contracts. Published APIs continue to function identically after an upgrade.
• Observable Provenance: Each service logs its build information (commit, branch, timestamp, image tag) at startup. This data is also exposed as deployment metadata, allowing you to confirm the exact version of each component that is running.
• Stateless Deployment: Configuration, such as environment variables and secret bindings, is reapplied on every deployment. The system does not inherit these from previous deployments, ensuring a consistent state.

Standard Upgrade Procedure

Follow these steps to perform a standard upgrade of the platform.

1. Read Target Release Notes: Before beginning, review the release notes for your target version. Pay close attention to any notes on license, schema, or breaking-change items.
2. Confirm License Compatibility: A major product upgrade may require a new license format. Verify that your current license is compatible with the target version.
3. Back up the Database: Perform a complete backup of the PostgreSQL database.
4. Pull Target Images: Pull the new container images for the control plane, runtime, and worker components at the target version tag.
5. Deploy the Control Plane: Deploy the admin-api (control plane) component first. On startup, it will apply any necessary database schema migrations. Wait for it to report a healthy state and confirm that the schema validation was successful.
6. Deploy Runtime and Worker: Once the control plane is healthy, deploy the runtime and worker components. Confirm that each service starts and reaches a healthy state.
7. Refresh Traffic Relay (if applicable): If you use a separate traffic relay or ingest virtual machine, update it to the matching image version. This ensures its embedded logic is compatible with the new database schema.

   WARNING

   A stale traffic relay may silently fail to write new ingest data after a schema change. It is critical to keep this component in sync with the rest of the platform.

8. Verify the Upgrade:
   • Check the startup logs for each service to confirm the deploy-provenance line reflects the new version.
   • Load the administration dashboard.
   • Execute a test call through a representative API service.
   • Confirm that new analytics and discovery data is being written to the database.

Deployment Order and Rationale

The order in which components are deployed is critical for a successful upgrade. The admin-api service owns and manages the database schema, so it must be upgraded before other components that depend on that schema.

The required sequence is:

1. admin-api
2. runtime
3. worker
4. relay/ingest (if used)

This flow ensures that the database schema is at the correct version before the runtime, worker, and relay services start, preventing compatibility issues.

flowchart TD
    A["1. Deploy Control Plane (admin-api)"] --> B{"Database Schema"};
    A -- "Applies migrations on startup" --> B;
    B -- "Is now at target version" --> C["2. Deploy Runtime"];
    B -- "Is now at target version" --> D["3. Deploy Worker"];
    B -- "Is now at target version" --> E["4. Deploy Traffic Relay (if used)"];
    C --> F["Ready to serve traffic"];
    D --> G["Ready to process data"];
    E --> H["Ready to ingest data"];

Rollback Procedures

If an upgrade encounters a problem, you can roll back using one of the following methods.

Application Rollback

To roll back the application code, redeploy the previous image tags for the admin-api, runtime, and worker components. Because service mapping versions and generated contracts are preserved independently of platform upgrades, this action restores the previous behavior.

Schema Rollback

If a schema-level rollback is necessary, you must restore the database from the backup you created before the upgrade. The release notes for a given version will explicitly state if a schema change cannot be tolerated by a previous version of the application and will provide specific guidance.

Service-Level Rollback

Independent of a platform upgrade, an API publisher can roll back a single service's mapping to a previously published version at any time from the UI. This does not require a platform rollback.

Zero-Downtime Considerations

The platform is designed to support zero-downtime upgrades in high-availability (HA) environments.

• The runtime component autoscales and maintains a warm minimum, allowing for rolling updates without dropping traffic.
• The admin-api applies database migrations before it begins serving traffic, ensuring the new schema is ready before dependent services are cycled.
• For HA deployments on platforms like Kubernetes, use a standard rolling-update strategy. Always deploy the admin-api first to prepare the schema before the runtime pods are replaced.
• If a release requires a long-running migration, such as building an index on a large table, it is performed out-of-band to prevent the upgrade process from stalling.

See Also

• Release Notes
• License Model
• Backup & Restore
• Publish & Version a Service

All SOAP-to-REST docs