From c772d58a90c50fa01728b2e14d4787313f1a9a13 Mon Sep 17 00:00:00 2001 From: Brad Seiler Date: Fri, 7 Aug 2026 00:48:37 -0400 Subject: [PATCH] docs(media): warn on phase rollback and start compose sharded Document that returning to legacy-only after accepting uploads in sharded-only makes sharded-layout objects unreadable until the phase is raised again. Ship sharded-only in the Compose example environment so fresh stacks never need a backfill, and correct the chart README to reflect that only the chart default remains legacy-only for upgrade safety. Signed-off-by: Brad Seiler --- deploy/charts/buzz/README.md | 9 ++++++--- deploy/compose/.env.example | 12 +++++++----- 2 files changed, 13 insertions(+), 8 deletions(-) diff --git a/deploy/charts/buzz/README.md b/deploy/charts/buzz/README.md index c08a2ff7cc..6c1c1b6144 100644 --- a/deploy/charts/buzz/README.md +++ b/deploy/charts/buzz/README.md @@ -119,6 +119,9 @@ intentionally starts the staged migration. Do not roll `sharded-only` writers back to a Buzz version that predates sharded reads. Returning from `sharded-only` to `dual-read-and-write` does not retroactively recreate legacy copies; run and verify the backfill before relying on old-version rollback. +Never set the phase back to `legacy-only` after any upload has been accepted +in `sharded-only`: `legacy-only` reads only flat keys, so objects that exist +only in the sharded layout return 404 until the phase is raised again. ## Relay Pod extensions @@ -322,6 +325,6 @@ For an **existing deployment**: For a **new empty deployment**, set `BUZZ_MEDIA_MIGRATION_PHASE=sharded-only` (or Helm `relay.mediaMigrationPhase: sharded-only`) before accepting the first upload. This is the recommended starting mode: no legacy objects are created, -so no backfill or deletion Job is ever needed. The chart and Compose defaults -remain `legacy-only` solely to make upgrades behavior-preserving for existing -deployments. +so no backfill or deletion Job is ever needed. The Compose example environment +ships `sharded-only` for this reason; the chart default remains `legacy-only` +solely to keep `helm upgrade` behavior-preserving for existing deployments. diff --git a/deploy/compose/.env.example b/deploy/compose/.env.example index c224c3c350..6bc9155e2b 100644 --- a/deploy/compose/.env.example +++ b/deploy/compose/.env.example @@ -35,11 +35,13 @@ BUZZ_S3_SECRET_KEY=CHANGE_ME_RANDOM_SECRET_KEY BUZZ_S3_BUCKET=buzz-media # Bundled MinIO uses path-style URLs; deploy/compose/compose.yml pins this. BUZZ_S3_ADDRESSING_STYLE=path -# Behavior-preserving upgrade default: read and write only legacy keys. Existing -# deployments use legacy-only -> dual-read-and-write -> backfill -> sharded-only. -# New deployments should select sharded-only before their first upload so they -# never need a backfill. -BUZZ_MEDIA_MIGRATION_PHASE=legacy-only +# Fresh Compose stacks start with an empty bucket, so they begin directly on the +# sharded layout and never need a backfill or cleanup Job. Existing deployments: +# keep your current phase — never jump an in-use legacy bucket to sharded-only, +# and never drop back to legacy-only after accepting sharded-only uploads (either +# direction makes existing objects unreadable). Migrate via legacy-only -> +# dual-read-and-write -> backfill -> sharded-only per deploy/charts/buzz/README.md. +BUZZ_MEDIA_MIGRATION_PHASE=sharded-only # Optional host ports. Base compose publishes the relay directly on BUZZ_HTTP_PORT. BUZZ_HTTP_PORT=3000