Skip to content

Align the server upgrade guide with current upgrade guidance - #5738

Merged
Duncanma merged 5 commits into
mainfrom
duncan/upgrade-guide-playbook-alignment
Nov 18, 2026
Merged

Duncanma merged 5 commits into
mainfrom
duncan/upgrade-guide-playbook-alignment

Conversation

@Duncanma

@Duncanma Duncanma commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

What

Updates Upgrade the Temporal Server to match the server-operations upgrade playbook, which the Server team considers the most current guidance. #5716 already aligned the checklist on the upgrade path (one minor version at a time, latest patch first), and the playbook agrees with that rule. This PR fixes the rest of the page.

Corrections

  • Why not to skip a minor version. The page said skipping makes old data formats unreadable and the upgrade fails. The playbook says the server doesn't enforce the path. Stepping avoids skipping version-gated startup work such as background data migrations, and it's the tested, supported path.
  • Schema step. The page said to check the release notes for whether a schema update is needed. Now it says to always update the schema before rolling out the binary. One update-schema run applies every intermediate version.
  • Wait time. The fixed "allow approximately 10 minutes on each version" is replaced by a table of metrics to watch until they settle.

Added

  • Release notes can require an intermediate version, and that overrides the normal path. Includes a concrete example path (v1.20.0 → v1.20.5 → v1.21.6 → v1.22.0).
  • A caution in the PostgreSQL section about the v1.30/v1.31 executions_visibility rebuild: use v1.30.5+ and v1.31.3+, plan a maintenance window, and have free space of up to twice the table size.
  • The startup schema check and its error, numHistoryShards, and service rollout order.
  • Rollback: binary only, schema stays forward.
  • Multi-Cluster Replication: passive first, with no failover during an upgrade. The self-hosted Multi-Cluster Replication page now links to this section.

The existing per-database schema commands are unchanged. The Kubernetes and pre-rollout dynamic-config tuning from the playbook are left out for now.

Sources and checks

  • Source: the server-operations upgrade playbook (tsurdilo/temporal-server-operations, playbooks/server-upgrade.md). The docs don't link to it. tsurdilo, could you review for accuracy?
  • PostgreSQL patch versions are confirmed against the release notes: Combine PostgreSQL Visibility schema upgrades from v1.10 through v1.13 temporal#10371 shipped in v1.30.5 and v1.31.1, and Optimize Visibility PostgreSQL upgrade schema v1.14 temporal#11599 shipped in v1.31.3.
  • Rollback is confirmed in common/persistence/schema/version.go, which rejects only a schema older than expected.
  • All seven metric names exist in common/metrics/metric_defs.go. Only three have entries in the service metrics reference, so only those are linked.
  • vale --config .vale-ci.ini is clean, and yarn build passes with all new anchors present.

Follow-up (not in this PR)

docs/encyclopedia/temporal-service/temporal-server.mdx says "We aim to publish incremental upgrade guides for each minor and major version." That's a future promise, which the style guide disallows, and it may no longer be planned.

Related: #5716. This PR also adds the topic to the Kapa decision log from #5717.

Corrects three claims in the upgrade guide against the server-operations
upgrade playbook:

- Skipping a minor version isn't blocked by unreadable data formats. The
  server doesn't enforce the path; stepping one minor at a time avoids
  skipping version-gated startup work, and it's the tested path.
- Always run the schema update before rolling out the binary, rather than
  checking release notes for whether one is needed. One run applies every
  intermediate schema version.
- Replace the fixed 10-minute wait per version with the metrics to watch.

Adds the release-notes override, the PostgreSQL v1.30/v1.31 Visibility
table rebuild (fixed in v1.30.5, v1.31.1, and v1.31.3 by
temporalio/temporal#10371 and #11599), the startup schema check, service
order, rollback, and passive-first upgrades with Multi-Cluster
Replication, plus a pointer from the Multi-Cluster Replication page.
@Duncanma
Duncanma requested a review from a team as a code owner November 16, 2026 18:50
Copilot AI balanced review requested due to automatic review settings November 16, 2026 18:50
@vercel

vercel Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
temporal-documentation Ready Ready Preview Nov 18, 2026 10:28pm UTC

Request Review

@github-actions

Copy link
Copy Markdown
Contributor

📖 Docs PR preview links

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The upgrade guidance applies zero-value targets to cumulative counters, risking indefinite pauses, and omits topology restrictions needed for passive-first upgrades to preserve the receiver-version rule.

2 open issues
What changed in this PR

Updates the self-hosted Temporal Server upgrade guide to align with current server-operations guidance, building on the upgrade-path clarification in #5716.

Changes:

  • Clarifies sequential upgrades, schema-first rollout, and service restart guidance.
  • Replaces the fixed wait time with metric checks and adds PostgreSQL rebuild precautions and binary rollback instructions.
  • Adds Multi-Cluster Replication upgrade guidance and links it from the replication guide.
File Description
docs/​production-deployment/​self-hosted-guide/​upgrade-server.mdx Revises upgrade planning, execution, verification, rollback, and replication guidance.
docs/​production-deployment/​self-hosted-guide/​multi-cluster-replication.mdx Adds an upgrade-order summary and links to the upgrade procedure.

Review effort: Balanced

Four of the verification metrics are counters, so the near-zero targets apply to their recent rate. Passive-first ordering only holds when one Temporal Service is active for every Global Namespace.
@Duncanma
Duncanma merged commit d13935b into main Nov 18, 2026
18 checks passed
@Duncanma
Duncanma deleted the duncan/upgrade-guide-playbook-alignment branch November 18, 2026 22:28

This branch was successfully deployed

1 active deployment
Preview — 5a55ca97 Deployed Nov 18, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants