Multiple Software Versions Support

Andi Lamprecht ·2026-05-11· 3 min read· Draft

Context

Our platform architecture must accommodate multiple concurrent software versions that can access the same persistence layer. This requirement arises from the need for seamless migrations between versions and the ability for clients to operate with various software versions simultaneously.

Key Terms

• Control Plane: The platform for managing the lifecycle of environments.
• Client: The owner of environments, with each client potentially managing one or more environments.
• Environment: A collection of software, data, and cloud resources.
• Tenant: The owner of data within an environment, where each environment can host multiple tenants.
• Ephemeral Environment: An environment that does not require cloud resources and can be installed locally (e.g., on a laptop) for testing purposes.

Decision

We will implement an architecture that supports N software versions (Helm releases) with access to a single shared persistence layer.

Each environment will be assigned a unique domain to ensure proper routing and isolation.

Benefits

1. Smooth Migration Between Versions:

   • Enables a gradual transition from old to new versions without disruption.
   • Allows for rollback if issues are encountered.
   • Ensures data consistency during migration.

2. Multi-Version Support:

   • Clients can work with multiple software versions at the same time.
   • Accommodates varying client adoption timelines.
   • Facilitates A/B testing of features across different versions.

Consequences

Positive

• Increased flexibility for clients.
• Reduced downtime during upgrades.
• Enhanced testing capabilities through version comparison.

Negative

• Additional complexity in the design of the persistence layer.
• Necessity for strict backward and forward compatibility.
• Heightened testing requirements to ensure functionality across versions.

Software Requirements

To support this architecture, the software must fulfill the following requirements:

1. Data Schema Compatibility:

   • Implement schema versioning.
   • Ensure backward compatibility for database schemas.
   • Design for graceful handling of missing or additional fields.

2. API Versioning:

   • Explicitly version all APIs.
   • Maintain compatibility across multiple versions.
   • Support deprecation patterns for evolving APIs.

3. Resource Isolation:

   • Establish clear boundaries between version-specific resources.
   • Implement shared resource access controls.
   • Facilitate version-aware resource allocation.

4. Monitoring and Observability:

   • Utilize version-tagged metrics and logs.

Environment Types

Standard Environments

• Full allocation of cloud resources.
• Production-grade persistence.
• Capable of multi-tenancy.
• Unique domain for each environment.

Ephemeral Environments

• No cloud resources required.
• Capable of local installation on laptops.
• Limited to testing purposes.
• May feature a simplified persistence model.
• Maintains a unique domain identifier.

Implementation Notes

• Helm charts must be designed to support the side-by-side installation of multiple versions.
• The persistence layer must ensure compatibility across specified version ranges.
• Migration tools should be available for transitioning releases between versions.

Database Schema Evolution Patterns

1. Additive Schema Changes:

   • Only add new tables, columns, or indexes.
   • Avoid deleting or modifying existing schema elements.
   • Use deprecation labels for obsolete elements.

2. Schema Version Tables:

   • Maintain a dedicated schema_version table.
   • Track applied migrations with timestamps.
   • Include version compatibility information.

3. Migration Strategies:

   • Implement dual-write during transition periods.
   • Use database views to present consistent interfaces.

Multi-Version API Design Guidelines

1. API Versioning Approaches:

   • Utilize URL-based versioning (e.g., /api/v1/, /api/v2/).

2. Backward Compatibility Requirements:

   • Never remove fields from responses.
   • Accept but ignore unknown fields in requests.
   • Maintain deprecated endpoints.

3. Documentation and Discovery:

   • Provide OpenAPI/Swagger specifications for each version.
   • Clearly outline deprecation timelines and migration paths.