Redis to valkey

redis-to-valkey

Migrate Redis (Bitnami-chart Sentinel HA or any standalone/replicated Redis) to Valkey on Kubernetes with data intact, clients reconnected, and no dependency left on dead-ended Bitnami artifacts. Facts below were verified 2026-07-18 against primary sources (valkey source at release tags, chart repos, vendor docs); re-verify anything version-gated before relying on it in a later year.

Why this migration exists

Broadcom locked down the free Bitnami catalog (effective 2025-09-29): versioned images moved to frozen docker.io/bitnamilegacy and most charts froze. charts.bitnami.com still serves, so pinned charts sync fine and the failure arrives later, at image-pull time — the first pod reschedule onto a node without the tag cached fails. Migrate deliberately, but don't assume the status quo is stable (full risk model: references/airgap-gitops.md). Valkey (Linux Foundation fork of Redis 7.2.4, BSD-licensed) is the sanctioned successor — major consumers (Harbor, GitLab) have adopted or officially support it.

The one fact that shapes every plan: the RDB-version wall

Valkey forked at Redis 7.2. Its replication and snapshot formats stayed at the fork point, then diverged on their own path:

Server	Writes RDB	Can load
Redis 7.0	v10	≤ v10
Redis 7.2	v11	≤ v11
Redis 7.4 / 8.x	v12	≤ v12
Valkey 8.0 / 8.1	v11	≤ v11 (v12+ rejected as foreign)
Valkey 9.0 / 9.1	v80 (own numbering)	v11 and v80; Redis v12+ rejected

(Verified in src/rdb.h at release tags: RDB_VERSION, RDB_FOREIGN_VERSION_MIN 12.)

Consequences:

1. REPLICAOF, RDB file copy, DUMP/RESTORE, and MIGRATE work only from Redis ≤ 7.2.x sources. A full sync ships an RDB stream; a DUMP payload embeds RDB encodings. From Redis 7.4+ these fail with Can't handle RDB format version 12.
2. Worse than failing: a Valkey replica FLUSHES its own dataset before it discovers the incoming RDB is unreadable (valkey-io/valkey#2588). Never point a Valkey holding data at a source "to see if replication works".
3. Valkey 9 is a one-way door. Its v80 snapshots load on nothing else — not Redis, not Valkey 8. The final pre-cutover Redis RDB is the only rollback artifact; archive it before decommissioning.
4. The wall is about persistence formats, not the wire protocol. Any client speaking RESP to Redis 7.2 works against Valkey — which is exactly why logical replay (next section) is version-agnostic.

Choosing a transfer method

Two layers exist; pick by source version and data class:

Version-bound (physical) — only for Redis ≤ 7.2.x sources:

• Live: on Valkey run REPLICAOF <redis-host> 6379, wait for master_link_status:up + offset convergence, repoint clients, REPLICAOF NO ONE.
• Offline: BGSAVE → poll LASTSAVE → stop Redis → place dump.rdb in Valkey's data dir → start Valkey with AOF disabled for the first boot (an enabled AOF silently wins over the RDB and the server boots empty), re-enable after.

Version-agnostic (logical replay) — any Redis version → any Valkey: Tools that decode the data themselves and re-issue plain commands; the target only ever sees ordinary RESP traffic.

• RedisShake (tair-opensource, v4.6+): live PSync sync (keeps target in sync while apps are repointed one at a time), RDB-file reader, SCAN reader. Supports Redis 2.8–8.4.x → Valkey 8–9, standalone/Sentinel/cluster. Caveats: no resume (restart = full recopy); panics on topology change — quiesce failovers during the run.
• rdb-cli (redis/librdb): parses any-version dump.rdb offline and replays it as commands. Best for maintenance-window cutovers.

No transfer (fresh start) — legitimate for disposable data classes:

Data class	Examples	Loss consequence	Verdict
Pure cache	page/object caches	cold-cache latency blip	fresh start
Sessions	encrypted web sessions	users re-authenticate once	fresh start (announce it)
Job queues / app state	Sidekiq, jobservice queues, schedules	enqueued work permanently lost	must transfer (or drain queues to empty in maintenance mode first)

Read references/data-transfer.md for full recipes (RedisShake configs incl. Sentinel endpoints, rdb-cli build, verification commands, air-gap delivery of both tools).

Cutover runbook (side-by-side, any method)

Never upgrade in place — resource naming, UIDs, and formats differ across charts. Deploy Valkey next to Redis, move data, repoint, decommission:

1. Deploy the Valkey release side-by-side (new release name). Decide the Sentinel master-set name up front — keeping the old name (commonly mymaster) means zero client-side master-set changes.
2. Pre-verify the empty Valkey: SENTINEL ckquorum <group> returns OK, SENTINEL get-master-addr-by-name <group> answers, auth works.
3. Quiesce writers: scale client Deployments to 0 or enable the app's maintenance mode. (For live RedisShake sync, start the sync before this step and quiesce only for the final repoint.)
4. Move the data per the method chosen above. Skip for fresh-start classes.
5. Repoint the app: sentinel endpoint list + master-set name + password secret (shape may change per chart — see values translation). For URL-style single-endpoint apps note that some Valkey charts' HA service exposes ONLY the sentinel port — the app must actually speak Sentinel.
6. Scale up and verify: DBSIZE comparison, sampled keys with TTLs intact, app functional probe, exporter metrics flowing.
7. Archive the final Redis RDB (rollback artifact — see one-way door), soak, then delete the Bitnami release, its PVCs, and its image pins.

Chart selection and values translation

As of 2026-07-18: groundhog2k/valkey (Sentinel HA haMode, upstream valkey/valkey images, tracks Valkey releases within days, bus-factor 1) and CloudPirates valkey (Sentinel + an externalReplica migration mode, multi-maintainer, cosign-signed, but one extra OCI library-chart to mirror) are the production-ready Sentinel options. The official valkey-io chart has no Sentinel yet (replication without automatic failover; Sentinel PR pending — recheck before new deployments, a first-party chart likely wins long-term). The Bitnami valkey chart is frozen with dead-ended images. The official valkey-operator is cluster-mode-only and self-declared not production-ready.

Bitnami-redis values do NOT translate 1:1. The traps that break clients or lose data are: auth as config-file fragments instead of a bare password secret, an HA service exposing only 26379, a different default master-set name, persistence defaulting to emptyDir, ServiceMonitor defaulting ON, and UID 999 vs Bitnami's 1001. Full mapping table, behavioral diffs, and exporter wiring: references/chart-migration.md.

Reconnecting consumer applications

Apps fall into config-surface classes — identify the class, then the translation is mechanical: Sentinel-aware (endpoint list + master-set + possibly a separate sentinel password), URL-based single endpoint (needs a real 6379 service or must be switched to its Sentinel mode), DB-index multiplexed (one server, many logical DBs — preserve index assignments), and version-parsing (Valkey hardcodes redis_version:7.2.4 forever — real version is in valkey_version; two-part 7.2 builds have crashed naive parsers). Classes, verification steps, and the dated per-product compatibility log (Harbor, GitLab, oauth2-proxy, Open WebUI, Sidekiq, Sentry): references/app-cutover.md and references/known-consumers.md.

Air-gap and GitOps rewiring

The complete mirror list for a Sentinel HA migration is short: 2 images (docker.io/valkey/valkey, exporter oliver006/redis_exporter — also on ghcr.io and quay.io), 1 vendored chart tarball, and optionally the RedisShake static binary (single-file Go binary from GitHub releases; also ghcr.io/tair-opensource/redisshake as an image). For Argo CD: keep the multi-source $values pattern and swap only the chart source; vendoring the chart into git is the only bootstrap-safe option when the migrated Redis backs the cluster's own registry (a registry cannot host the chart for its own dependency's replacement). Details, OCI syntax (no oci:// prefix in Argo repoURL), Bitnami-endpoint risk model, and Renovate notes: references/airgap-gitops.md.

Pitfalls quick index

Before executing any plan, scan references/pitfalls.md (19 entries by severity). Beyond the traps already covered above: dual-channel replication

• Sentinel phantom replicas on Kubernetes (#2338 — fix shipped in Valkey 9.1.0 ONLY; keep dual-channel-replication-enabled no below that); HEXPIRE absent until Valkey 9; io-threads default-on in Valkey 8+ raising per-pod CPU vs single-threaded Redis sizing.

Reference files

File	Read when
references/data-transfer.md	moving data: recipes for REPLICAOF / RDB copy / RedisShake / rdb-cli, verification, tool delivery offline
references/chart-migration.md	selecting a chart or translating Bitnami redis values
references/app-cutover.md	repointing applications; config-surface classes; verification checklist
references/known-consumers.md	dated per-product compatibility findings (log-style, append-only)
references/airgap-gitops.md	air-gapped mirroring, chart vendoring, Argo CD source rewiring
references/pitfalls.md	always, before executing a migration plan