Upgrade and version-skew policy

What MySQL and sidecar versions Bloodraven supports, how to move between them, and what mismatches the operator tolerates during a rollout.

This page is deliberately narrow. It covers the MySQL image (spec.image) and the sidecar image (spec.sidecarImage). Operator (Helm chart) upgrades and CRD-version migrations are separate topics.

Supported MySQL versions

Bloodraven supports a single MySQL version at a time, pinned to the default spec.image tag:

• Today: mysql:9.6. This is the default for new deployments and the only version exercised in CI, the playground, and backup / restore paths.
• When released: mysql:9.7 (the first MySQL 9.x LTS). Once 9.7 is available, it becomes the long-term supported tag. Bloodraven does not intend to track 9.8 or later Innovation releases — 9.7 LTS is the target you should expect to run for a long time.

The following are not supported:

• MySQL 8.0 and 8.4. If you run these today, upgrade MySQL to 9.6 outside of Bloodraven before adopting the operator, or bootstrap a fresh failover group from a mysqlsh-produced dump using initFromBackup.
• MySQL 9.x Innovation releases beyond the pinned supported tag (currently 9.6, later 9.7).
• MySQL 5.7 and earlier (no GTID, no clone plugin).

:::caution Pin, don't float Always pin spec.image to an immutable tag (e.g. mysql:9.6, not mysql:9). A floating tag can drift you onto an unsupported version between pod restarts. See the Production hardening checklist. :::

Implementation prerequisites

These are satisfied by the supported tags and only matter if you point Bloodraven at something else: GTID-only replication (SOURCE_AUTO_POSITION=1), the MySQL clone plugin (CLONE INSTANCE FROM), and the REPLICA/SOURCE SQL vocabulary. The operator does not validate these at startup — an unsupported image surfaces as MySQL pod failures, not an operator admission error.

The 9.6 → 9.7 transition

When MySQL 9.7 ships, the supported upgrade path is a rolling image bump:

1. Confirm spec.updateStrategy: OrderedUpdate is set (it is the default).
2. Bump spec.image to the 9.7 pinned tag.
3. kubectl apply.
4. Watch status.updatePhase and the Updating / Bootstrapping conditions on status.conditions, and confirm replication catches up before the second site rolls.
5. Run a backup-verification drill (see Backup verification) against the new version.

With OrderedUpdate, Bloodraven upgrades the standby first, then fails over to it, then upgrades the old active. This is the direction MySQL's rolling-upgrade contract requires: the replica's MySQL version must be ≥ the primary's during the rollout. See Failover → Ordered updates for the full sequence.

:::danger Do not use updateStrategy: Recreate for a major bump Recreate restarts both sites simultaneously. If one pod's in-place MySQL upgrade stalls or fails, you lose write availability with no healthy primary and no rollback path. Use OrderedUpdate for any MySQL image change. :::

For MySQL-level upgrade semantics — data-dictionary migrations, deprecated-feature removals, schema changes — defer to Oracle's own 9.x upgrade notes. Bloodraven drives the rollout; it does not duplicate the MySQL upgrade matrix.

Cross-site version skew

Transient (during a rollout): allowed. The OrderedUpdate sequence keeps the newer MySQL on the replica side of replication throughout the bump, which is MySQL-supported. The skew window lasts from the moment the standby finishes upgrading until the old active has been restarted on the new image — roughly pod-ready time plus the failover drain. No user action is required.

Steady-state (intentional per-site version split): not supported. spec.image is a single field per MysqlFailoverGroup; SiteSpec has no per-site image override. The operator reconciles both site Deployments to the same image tag. If you edit a site's Deployment manifest out of band to pin a different tag, the next reconcile reverts it.

Sidecar ↔ operator skew

The sidecar binary and the operator binary are released together. The supported configuration is matching versions: spec.sidecarImage built from the same release as the running operator Deployment.

Bloodraven tolerates a one-minor transient skew in either direction during a rolling upgrade. Both sides of the HTTP surface between the two are additive-only:

• Operator endpoints (polled by sidecars): /healthz, /status, /active-site, /pitr-cutoff.
• Sidecar endpoints (polled by the operator and peer sidecars): /health, /status, /peer/ping, /peer/active-site, /archiver/status.

A briefly older-or-newer sidecar stays compatible with the operator while pods roll. Skew beyond one minor is not tested and not guaranteed.

When a release bumps both spec.image and spec.sidecarImage together, OrderedUpdate restarts the sidecar as part of the pod restart it already performs — the replica-first ordering applies automatically, no separate sidecar sequencing is required.

Restoring across versions

MysqlBackup.status.mysqlImage records the image tag that produced each dump. The safe path is to restore onto the same major version that produced the backup. A 9.6 dump can be restored onto 9.7 once 9.7 is the supported tag, subject to MySQL's own forward-compat guarantees. Do not restore a 9.7 dump onto 9.6 — MySQL does not support version downgrade of data.

Backup-restore throughput and sizing guidance live under a separate performance guide (WISHLIST #27).

What Bloodraven does not do

• No version admission check. Setting spec.image to an unsupported tag will not produce a CRD validation error. MySQL itself rejects unsupported upgrades at pod start.
• No skip-a-major guardrail. There is no enforcement that blocks an 8.0 → 9.6 jump or a 9.6 → 9.8+ jump at the operator layer.
• No downgrade path. MySQL does not support version downgrade, and Bloodraven inherits that limitation.
• No per-site MySQL version. The CRD does not expose a per-site image, so mixed-version steady state is not expressible.