Upgrade and format compatibility
The first 4.0.0 production installation is fresh-install only. The retired 1.x/2.x driver has no supported on-disk migration or wire compatibility with this rewrite. Moving application files requires a separately verified external backup and a new volume; never adopt retired disks/journals/PV identities. Pre-release 3.x data is not implicitly production-qualified by installing a 4.0 binary.
For this release line, active mixed-worker/mixed-client rolling upgrades and format downgrades are unsupported. Planned upgrades are quiescent: stop all clients, close descriptors, observe normal CSI unpublish/unstage and zero FUSE mounts, preserve durable authority, update all roles, then remount and verify. A Pod restart does not itself establish unmount. Do not change local CSI, StorageClass bindings, CR creation inputs, Node UID or volume CA as part of a replicated-driver upgrade.
Persisted and wire authority
| Surface | Current contract |
|---|---|
| Kubernetes lifecycle | replicated.csi.tak-os.org/v1alpha1 ReplicatedVolume; immutable request and generation UID; original Node/PVC/PV identities and serving fences must survive. |
| Worker identity and journal | Original immutable volume/generation/peer configuration, stable Raft term and valid contiguous journal/snapshot authority; missing/reset journal is not repaired by deleting identity. |
| Checkpoint | TAKPOINT2, current object/metadata, sparse extents, expiry floor, retry results, durable handles and hardlinks. Current reader also accepts valid TAKBASE1 historical baselines. This is forward-reader support, not permission to downgrade a new checkpoint. |
| File RPC | Authenticated /v1 volume/generation-bound JSON; server rejects unknown request fields. Changes to operation schemas can affect format/wire compatibility. |
| Raft/rebuild | Authenticated membership and checkpoint transport with exact identity, checksums and boundary guards. Endpoint discovery is not membership adoption. |
| Credentials | Volume CA plus file/control bearers and overlap metadata; retain the original signer/CA during normal upgrade. Secret UID equality alone does not prove CA equality. |
There is no negotiated general schema-conversion layer. A binary accepting the same checkpoint magic is not proof that all features it encounters are compatible. Never delete a new checkpoint or retained fields to make an old binary start. Interrupted upgrade preserves the same authority and stays quiescent until one compatible role tuple is restored everywhere.
Historical compatibility record
The 2026-10-26 changed-candidate qualification
passed the exact published 3.2.0 → source eb1dc38 → 3.2.0 → eb1dc38
quiescent pair on the single-node lab, plus four-node old → candidate reopen.
Old bytes/metadata and a new fsynced candidate canary survived both readers with
original volume/backing/CA identities. The candidate emitted no new checkpoint
in that rollback drill: this qualifies its actual journal-replay boundary, not
new-checkpoint downgrade or arbitrary mixed-version operation. Exact image
digests, source/binary comparisons and preserved failed observers are in that
report. Retired-driver migration remains unsupported.
The old compatibility harness has been removed. Its reports retain the source and runtime boundaries recorded at the time. A new floating dependency build is not byte-identical to an old image by assumption. Keep workloads quiescent and preserve original volume, backing, membership and credential authority during upgrades. Active mixed-version operation and format downgrades are unsupported.
Shared-runtime transition in 4.1.0
Release 4.1.0 adds a one-way spec.runtime: shared selection. It does not silently
convert activated legacy generations. Deliver the updated CRD, local CSI 2.1.0 consumer
support and NODE configuration, quiesce consumers, then use the generation-guarded
shared runtime request. Legacy Pods
must terminate normally before exclusive acquisition of the same backing PVCs.
This preserves format and trust identities; no storage copying or new volume
creation is performed. Mixed active manager versions can disagree on allocation
ownership and remain unsupported. Do not downgrade a shared generation to an
older manager/NODE/local-CSI combination. This source transition has not been
observed in a real cluster; the 4.0.1 compilation record does not qualify it.