Feature/improved upgrade notes#115
Merged
julialongtin merged 37 commits intomainfrom Apr 30, 2026
Merged
Conversation
The previous example put rabbitmq under brig.rabbitmq, which doesn't exist in the brig chart. The correct path is brig.config.rabbitmq. The secrets example also belongs in secrets.yaml, not values.yaml. The redundant 'port: 5672 # default' line is removed since the chart default covers it. Source: confirmed by Mohit while debugging the path during a customer upgrade run.
The artifact tarball URL is needed for offline installs and is currently not findable from this page. Also fixes the 'release chagelog' → 'release changelog' typo while editing the same paragraph.
Calls out the two major pieces of work in this upgrade (redis-ephemeral swap, PostgreSQL conversation migration) so readers know what they're in for. Also makes explicit that 'this change restarts pods' phrasing refers to behavior after helm upgrade, not values-file watching, since that caused real confusion during a customer upgrade.
The previous page only mentioned redis-ephemeral as context for the gundeck.config.redis.host change. The chart deployment itself is a required step that must happen before the wire-server helm upgrade, and that wasn't called out anywhere. Adds explicit ordering and the helm command, plus a forward reference to the cleanup section for removing the old databases-ephemeral chart. Renames the section to 'What must change' with numbered ordering so the upgrade flow is clear.
The 5.24 background-worker chart needs additional fields that weren't fully called out: postgresql.host in values, pgPassword in secrets. Adds these explicitly with the kubectl command to retrieve the existing password. Pulls the conversation migration section out from under background-worker, it gets its own post-upgrade section in a later commit. Adds an inline warning about the chart's misleading default for postgresMigration.conversation, since it points at PostgreSQL by default but the data is still in Cassandra for non-migrated installs.
Adds a real-world example of 'kubectl get svc | grep redis' output so readers know what to expect, and explains why both the new and old services may appear during the transition. Calls out the wire-server-deploy prod-values.example.yaml bug where gundeck.config.redis.host is set to the old databases-ephemeral service. Also adds the helm upgrade run as the last numbered step so the sequence ends with the actual upgrade command. Source: known bug confirmed by Veki during a customer upgrade run.
The previous page presented the PostgreSQL conversation migration as optional, with a single sentence linking out to a config-options page. That framing is what caused the cascade of bugs at 5.25 for sites that treated it as truly optional. Promotes the migration to mandatory and inlines the full three-step recipe verbatim from the wire-server CHANGELOG, plus log and metric verification steps. The link to config-options is no longer the only source of truth for the procedure. Source for the procedure wording: wire-server CHANGELOG entry for release 5.24.0.
Adds the bin/helm-operations.sh CERT_MASTER_EMAIL bash-syntax bug that affects fresh 5.23.1 starting points. Also clarifies that the brig non-federated workaround is fixed at 5.25 so readers know when to remove it. Source: cert-manager email bug confirmed by Mohit while reproducing a fresh install.
Verification gives concrete grep patterns and expected log lines for brig, background-worker and gundeck after the upgrade, plus a postgres conversation count check. Cleanup documents removing the now-unused databases-ephemeral chart, which is not auto-removed by the upgrade. Disk space footer covers the /opt/assets growth across repeated setup-offline-sources runs and how to recover. The note specifies the assethost (not the adminhost) since the path only exists there.
Calls out the dependency on having completed the 5.24 conversation migration before reaching this release. The chart-default issue at 5.25 makes that prerequisite load-bearing.
The previous version of this page said there were no mandatory changes at 5.25. That was wrong. The 5.25 background-worker chart defaults postgresMigration.conversation to postgresql, which breaks deployments that have not completed the conversation migration. The wrong default was the proximate cause of conversation-loss reports during 5.24 to 5.25 upgrades. Replaces the no-changes note with explicit instructions for both the 'have migrated' and 'have not migrated' cases. Notes that the chart default is corrected at 5.26 so readers know when this changes.
Webapp builds after November 2025 require mlsPrivateKeys to be set even when MLS is disabled. Existing deployments that originally ran older versions may not have these keys configured and will hit a confusing webapp error. Source: investigation by Mohit while reproducing the issue.
Operators who override galley.settings.featureFlags.cells must add the new required fields (channels/groups/one2one/users/collabora/ publicLinks/storage/metadata) before upgrading. Operators who rely on the chart default are not affected. Also adds the wire-server helm upgrade run as the last numbered step so the sequence ends with the actual upgrade command. Source: wire-server CHANGELOG entry for release 5.25.0.
The previous wording showed enableFederation: false in the example yaml, which was the opposite of the workaround it was telling readers to remove. Renames the section to 'Notes from the previous release' and states clearly that the 5.24 workaround can be removed.
…k footer Tightens the wording on the existing optional sections and notes when each one is relevant. Documents the two new failure metrics (wire_local_convs_migration_failed and wire_user_remote_convs_migration_failed) and what to do when they reach 1. Adds the standard disk space footer. Source for the new metrics: wire-server CHANGELOG entry for 5.25.0.
The 5.26 helm charts have unresolved issues in federated mode and the release PR was closed without merging. Federated deployments need to go straight from 5.25 to 5.27. Banner makes this visible at the top of the page so readers do not pick this version by accident. Source: confirmed by Veki and Julia during a customer upgrade run.
The previous wording said the previous release 'introduced a bug' that this release fixes, but the wrong default has been in place since 5.24 and the 5.25 page now warns about it. This release just corrects the default. Reframes the note accordingly and explains what action is needed for readers who relied on the default at 5.25. Source: wire-server CHANGELOG entry for release 5.26.0.
Kubernetes versions below 1.27 are no longer supported. Operators on older clusters need to upgrade Kubernetes first. User search results now carry user type information, but only after the elasticsearch index is refilled from Cassandra. Anyone invoking brig-index directly also needs to add PostgreSQL connection parameters. Source: wire-server CHANGELOG entry for release 5.26.0.
Replaces the vague 'see the changelog' link with the actual three-step procedure. The migration only applies if the 5.24 conversation data migration has already been completed. Adds the standard disk space footer. Source for the procedure: wire-server CHANGELOG entry for 5.26.0.
Adds the artifact URL and prerequisites including the supported skip of 5.26 for federated environments. Replaces the vague link-out for the team features migration with the full four-step procedure including the optional Cassandra table drop. Adds a note about webapp, team-settings, and account-pages now being standalone charts so readers do not look for their values inside values/wire-server/values.yaml. Adds the standard disk space footer. Source for the migration procedure: wire-server CHANGELOG entry for release 5.27.0.
Adds When/Who tags to the existing image-override breaking change and clarifies that the change only affects deployments that override images. Documents the previously-undocumented mandatory action to remove and re-create apps that existed before user-type tracking. Without this, those apps will appear as regular users in search and API responses. Adds the Cassandra 4.1.x recommendation as a non-breaking note. Source for both new sections: wire-server CHANGELOG entry for release 5.28.0.
The wire-server release notes mark this release as broken and tell readers to upgrade from 5.28 directly to 5.30. Adds a banner at the top of the page making this clear, and a prerequisites note for readers who land here for reference. Source: wire-server CHANGELOG entries for 5.29.0 and 5.30.0.
The previous page only mentioned the proxy toggle change. The underlying chart consolidation that motivated it was not documented, and the tags obsoletion list was incomplete. Adds the full list of moved services and obsolete tags. Documents the metallb wrapper chart removal which previously had no mention. Cross-links forward to 5.30 where tags.proxy becomes required again, so readers do not remove a tag that they will need to add back at the next version. Source: wire-server CHANGELOG entry for release 5.29.0.
Drops the redundant 'tags.proxy is now obsolete' section since this is already covered as part of the chart consolidation in mandatory changes. Renames the proxy reference section to make its scope explicit and fixes a typo in the embedded comment. Adds the configurable rate-limit status code as a small optional note from the changelog. Source for the rate-limit configurability: wire-server CHANGELOG entry for release 5.29.0.
New page documenting the 5.30 release. Covers the three operator- relevant changes from the release notes: tags.proxy must be set explicitly again (reversing the 5.29 obsoletion), the restund chart is no longer shipped (migrate to coturn), and the recommended cleanup of duplicated background-worker overrides now that background-worker reuses galley's configmap and secrets. Also adds entries for 5.26 through 5.30 to mkdocs.yml so the pages appear in the navigation. Previously only 5.24 and 5.25 were listed despite the 5.26 to 5.29 pages already existing. Source for the 5.30 changes: wire-server CHANGELOG entry for release 5.30.0.
Not relevant to the version upgrade flow, this is install-time noise that doesn't belong on a per-version config reference page.
…tion step The Heads up paragraph telling readers that every value change has to be followed by a helm upgrade was redundant. Inlining the actual command at each migration step makes it explicit and unambiguous, and removes the need for the meta-note.
…s bug Causation hasn't been definitively established, several deploys exhibited the symptom but the chain isn't fully proven. Softens the wording on both pages accordingly.
Removes 'This is the part that's been flaky in the past. Don't skip it.', 'Seriously.', 'please don't, but if it has to happen', and 'no rush' across the affected pages. Also tightens the rate-limit note in 5.29 and fixes a typo in the same paragraph.
The section described how to tune the conversation migration when it is run at 5.25 rather than at 5.24 (where it belongs). The right guidance is to follow the documented sequence, this page should not have content for not following it.
…tion Each post-upgrade data migration now starts with a callout asking operators to back up the Cassandra galley keyspace and the target PostgreSQL database before running any of the steps. The migrations start writing to PostgreSQL from step 1 onwards, so rolling back without a backup is not straightforward.
julialongtin
approved these changes
Apr 30, 2026
| ``` | ||
|
|
||
| Then set accordingly: | ||
| Or watch the metrics, both of these should hit `1.0`: |
Member
There was a problem hiding this comment.
add a 'if you need to pull metrics manually' link here.
| --values ./values/wire-server/secrets.yaml | ||
| ``` | ||
|
|
||
| From now on reads and writes both go to PostgreSQL. This configuration must be kept on every subsequent upgrade. |
Member
There was a problem hiding this comment.
the last part of this sentence is unclear.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Change type
Basic information
Testing
Tracking