Skip to content

CONCEPT Cited by 1 source

Version-aligned compatibility scheme

Definition

A version-aligned compatibility scheme numbers a support tool (operator, Helm chart, client library, migration utility, SDK) so its version number matches the underlying system's version number. Adopting it explicitly retires a compatibility matrix document — customers read the single version number instead of cross-referencing a table.

Typically comes with a ±1 minor compatibility window: each support-tool version is compatible with the system version it matches plus the version immediately above and below.

Canonical wiki instance

Redpanda Operator and the Redpanda Helm chart adopted version alignment with v25.1.x (a deliberate jump from v2.4.x), matching Redpanda core's versioning. Framing verbatim:

"We decided to simplify how to determine this compatibility by releasing Redpanda Operator and Helm chart versions that match a specific Redpanda version. This means you can now determine compatibility at a glance without checking a compatibility chart. And, each operator and Helm chart version will also be compatible with the Redpanda version above and below it."

(Source: sources/2025-05-06-redpanda-a-guide-to-redpanda-on-kubernetes)

Compatibility window verbatim example:

Operator / Helm version Compatible Redpanda versions
v25.1.x 24.3.x, 25.1.x, 25.2.x
v25.2.x 25.1.x, 25.2.x, 25.3.x

Trade-offs

Wins

  • Zero compatibility-matrix lookup. Customer looks at Redpanda version, picks matching operator/chart version, done. Matters more as the product surface grows (multiple support tools × multiple core versions = O(n²) matrix entries).
  • Release-planning legibility. Product management, support, docs, and customer success all agree on what "compatible with 25.1" means across the product surface without cross-referencing.
  • Prevents drift. The compatibility matrix is a living document that ages badly if releases ship faster than docs. Alignment retires the maintenance burden.

Costs

  • Version-number discontinuity. Adopting the scheme on a tool that already has its own version history forces a jump — the Redpanda Operator went v2.4.x → v25.1.x, losing the numerical continuity of the 2.x line.
  • Release-cadence coupling. The support tool now must ship a matching release for every core version; divergent release cadences are no longer an option. If core 25.2 ships and the operator isn't ready, either ship a stub operator 25.2 or leave customers without an aligned version.
  • Patch release ambiguity. Patches to operator or chart within a minor (e.g. operator 25.1.3 vs core 25.1.5) still exist; the scheme only aligns on minors.
  • No signal for breaking changes in the support tool. If the operator's CRD schema changes breakingly but core is stable, semver would bump major; version-aligned suppresses this signal.

Preconditions

  • The support tool is versioned downstream of the main system — i.e. the support tool chases the system, not vice versa. True for operators, Helm charts, SDKs. Not true for tools that lead their backing system (migration tools that add SQL features ahead of DB support).
  • One tool per system version. If the vendor ships two operators with different life-cycles both claiming compatibility with the same core version, alignment collapses.
  • Backward / forward compatibility spec is simple enough to be summarised as "±N minors".
Last updated · 470 distilled / 1,213 read