jerry/buzz
1
0
Fork 0
mirror of https://github.com/block/buzz.git synced 2026-11-09 02:41:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(media): warn on phase rollback and start compose sharded

Browse Source 
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 <seiler@squareup.com>
This commit is contained in:
Brad Seiler
2026-08-07 00:48:37 -04:00
committed by coder
parent 4622480662
commit c772d58a90
2 changed files with 13 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
deploy/charts/buzz/README.md
View File

@@ -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.

12
deploy/compose/.env.example
View File

@@ -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