From 5a1128ff41e6e644c9b34830cff2d136e13fa259 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 2 Nov 2026 20:53:23 +0000 Subject: [PATCH] Upgrade notes: stop every 2.1 instance before the first 2.2.0 one starts docs/deployment.md lets a release say when it needs more than a rolling restart, and 2.2.0's notes did not. While 2.1 instances still serve after the first 2.2.0 instance has migrated: - they skip a credential-forwarding realm 2.2.0 has rewritten with `accept_client_passwords` (the [auth.upstream_basic] seed does so at the first start), since 2.1 parses realm rows with deny_unknown_fields, and its users get 401 there; - a policy saved on 2.2.0 with a glob in `protected_tags`, run by a 2.1 worker, deletes the tags the glob protects, and 2.1 ignores the package delay's per-package overrides; - an account they create or set to Reader gets no built-in `reader` role, which migration 0013 gave once, so it reads nothing on 2.2.0. The note says to stop every 2.1 instance first, as 2.1.0's did for 2.0.0 (#615), how to with the chart and the manifests, and what to check after an upgrade that rolled. Fixes #788 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_012e6DJc1H3748D8sheqhKTV --- docs/changes/2.2.0/788.upgrade.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 docs/changes/2.2.0/788.upgrade.md diff --git a/docs/changes/2.2.0/788.upgrade.md b/docs/changes/2.2.0/788.upgrade.md new file mode 100644 index 00000000..d4be3aaa --- /dev/null +++ b/docs/changes/2.2.0/788.upgrade.md @@ -0,0 +1,19 @@ +**Stop every 2.1 instance before the first 2.2.0 instance starts**, rather +than rolling the upgrade. The first 2.2.0 instance migrates the database, +and 2.1 instances that still serve then go wrong in three ways. They sign +no one in through a credential-forwarding realm: 2.2.0 writes the new +`accept_client_passwords` setting into the realm of `[auth.upstream_basic]` +when it first starts (and into any such realm it saves), 2.1 cannot read +the realm then and skips it ("credential-forwarding realm skipped"), and +its users get 401 from those instances. An image retention policy saved on +2.2.0 with a glob in `protected_tags` deletes, when a 2.1 instance runs it, +the old tags the glob protects, since 2.1 reads `release-*` as a tag's +name; 2.1 also ignores the package delay's per-package overrides. And an +account a 2.1 instance creates (an OIDC or trusted-header first sign-in) or +sets to Reader gets no built-in `reader` role, which the upgrade gives only +to the accounts that exist when it runs: on 2.2.0 it is Roles only and +reads nothing. With the Helm chart, upgrade with +`--set strategy.type=Recreate` or scale the deployment to zero first; with +the Kubernetes manifests, scale the `forge` deployment to zero before +applying 2.2.0. After an upgrade that rolled, look in **Admin → Users** for +accounts created meanwhile whose access level is Roles only.