Upgrade ES | Full restart & update overrode config files by stefnestor · Pull Request #5848 · elastic/docs-content

stefnestor · 2026-04-09T15:03:53Z

Summary

👋 The Elasticsearch upgrade guide used to outline

that full upgrades are allowed. This drift is documented in [Internal]: Elasticsearch - Documenting full restart-upgrades of clusters #3879.
We also used to document that downgrades aren't allowed, example evidence.
And what I actually wanted to edit is that our users are experiencing upgrade issues because we don't document that if they override config files they need to manually account for any drift via step ::::{step} Upgrade the shutdown node's version.

I also tried to shift doc to :::::{stepper} as I saw elsewhere which looked shiny+helpful to be able to link to each step.

Generative AI disclosure

Did you use a generative AI (GenAI) tool to assist in creating this contribution?

Yes
No

eedugon · 2026-04-09T17:02:49Z

@stefnestor , in order for the preview of this PR to work, when working from a fork, we now need your profile to be public to verify elastic org membership and then enable automatic previews.

You can do that simply by flipping to public here: https://github.com/orgs/elastic/people?query=stefnestor

An alternative would be to push directly your local branch to the docs-content repo instead of using your own fork.

stefnestor · 2026-04-09T19:54:04Z

Thanks, @eedugon! I was wondering why it wasn't triggering for me to see 🙏

github-actions · 2026-04-09T19:55:14Z

🔍 Preview links for changed docs

github-actions · 2026-04-09T19:55:18Z

Vale Linting Results

Summary: 1 warning, 2 suggestions found

⚠️ Warnings (1)

File	Line	Rule	Message
deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md	86	Elastic.Spelling	'Becausee' is a possible misspelling.

💡 Suggestions (2)

File	Line	Rule	Message
deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md	85	Elastic.WordChoice	Consider using 'deactivate, deselect, hide, turn off' instead of 'Disable', unless the term is in the UI.
deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md	119	Elastic.WordChoice	Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI.

The Vale linter checks documentation changes against the Elastic Docs style guide.

To use Vale locally or report issues, refer to Elastic style guide for Vale.

Co-authored-by: Stef Nestor <26751266+stefnestor@users.noreply.github.com>

stefnestor · 2026-04-17T14:39:48Z

Bump @elastic/admin-docs 🙏

Copilot

Pull request overview

Updates the self-managed Elasticsearch upgrade documentation to explicitly cover full cluster restart upgrades, reinforce no-downgrade guidance, and add a step reminding users to reconcile config overrides that may drift during upgrades.

Changes:

Add guidance that cluster upgrades can be done via rolling upgrade (recommended) or full cluster restart, with associated implications.
Convert the upgrade procedure into a stepper-based runbook and add a new step to merge config overrides (to avoid config drift).
Add a cross-link from node roles documentation to the data tiers page for tiered data node roles.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 9 comments.

File	Description
deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md	Reworks the upgrade page into a stepper runbook, adds full-restart option and config-drift guidance, and updates surrounding upgrade caveats.
deploy-manage/distributed-architecture/clusters-nodes-shards/node-roles.md	Adds an explicit link from specialized data roles to the data tiers documentation.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Stef Nestor <26751266+stefnestor@users.noreply.github.com>

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

yetanothertw

Sorry for keeping you waiting for so long, Stef!

I've completed the first round of reviews. Please let me know what you think.

Co-authored-by: Vlada Chirmicci <vlada.chirmicci@elastic.co> Co-authored-by: Stef Nestor <26751266+stefnestor@users.noreply.github.com>

stefnestor · 2026-04-24T22:25:40Z

Thanks, @yetanothertw ! 🙇‍♀️

I think there's just two baby wording/formatting issues remaining that I've induced if you'll kindly advise. 🙏

Co-authored-by: Stef Nestor <26751266+stefnestor@users.noreply.github.com> Co-authored-by: Vlada Chirmicci <vlada.chirmicci@elastic.co>

github-actions · 2026-04-30T20:16:33Z

Elastic Docs AI PR menu

Check the box to run an AI review for this pull request.

Review docs changes (docs-review). Status: not started.

Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team.

stefnestor · 2026-04-30T20:18:55Z

Ready again, @yetanothertw. TIA! 🙏

yetanothertw

Left to minor suggestions for some lead-in sentences, but looks good otherwise!

Thank you so much for fixing up this page! 🎉 The stepper makes it look sleek and the additional context makes it so much more cohesive!

yetanothertw · 2026-05-01T10:15:17Z

Re the suggestion to create a troubleshooting page for commonly encountered issues during an upgrade, it'd be a good way to test out the new troubleshooting template. There's also more guidance about writing troubleshooting type of content that complements the template.

Btw, I'm not trying to pressure you into creating that content, just sharing these links (as I've found them helpful) in case you want to bookmark them for another time. ☺️

Co-authored-by: Vlada Chirmicci <vlada.chirmicci@elastic.co>

## Summary 👋 Follow-up of #5848 to create separate upgrade troubleshooting page. This assumes but does not breaking rely on errors WIP documenting in - #6534 - #6535 - #6536 - #6537 - elastic/elasticsearch#149765 - elastic/elasticsearch#149768 It will hopefully be less necessary after elastic/kibana#266733 There's various page cross-links/cross-reference between troubleshooting "rolling upgrading Elasticsearch" and the "upgrade assistant" before it, so starting together <details><summary>Non-exhaustive related links</summary> --- - https://support.elastic.co/knowledge/1bbb4cc9 - https://discuss.elastic.co/t/issues-upgrading-elasticsearch-from-8-to-9-due-to-old-7-x-indices-and-restricted-kibana-indices/379133/11 - elastic/kibana#119652 (comment) - https://support.elastic.co/knowledge/3e27188b - https://support.elastic.co/knowledge/56149373 - https://support.elastic.co/knowledge/cb3db1e7 - https://support.elastic.co/knowledge/f3c6ea67 - elastic/elasticsearch#86801 - elastic/kibana#116209 - https://support.elastic.co/knowledge/295e812f - https://support.elastic.co/knowledge/794038f9 - https://support.elastic.co/knowledge/dd79602f - https://support.elastic.co/knowledge/e3d44d38 --- </details> ## Generative AI disclosure 1. Did you use a generative AI (GenAI) tool to assist in creating this contribution? - [ ] Yes - [X] No --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Marci W <333176+marciw@users.noreply.github.com>

stefnestor added 2 commits April 3, 2026 17:04

stef_upgradeES

34f16c9

Upgrade ES | Full restart & update overrode config files

33a6efc

stefnestor requested a review from a team as a code owner April 9, 2026 15:03

Merge branch 'main' into stef_esUpgrade

864e78d

Merge branch 'main' into stef_esUpgrade

edce8c4

stefnestor commented Apr 9, 2026

View reviewed changes

Comment thread deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md Outdated

stefnestor commented Apr 9, 2026

View reviewed changes

Comment thread deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md Outdated

stefnestor commented Apr 9, 2026

View reviewed changes

Comment thread deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md Outdated

stefnestor commented Apr 9, 2026

View reviewed changes

Comment thread deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md Outdated

stefnestor commented Apr 9, 2026

View reviewed changes

Comment thread deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md Outdated

stefnestor added 2 commits April 9, 2026 14:03

grammar 🙏

e118177

Co-authored-by: Stef Nestor <26751266+stefnestor@users.noreply.github.com>

added step closes

7a77efe

marciw requested a review from Copilot April 23, 2026 15:05

Copilot started reviewing on behalf of marciw April 23, 2026 15:14 View session

Copilot AI reviewed Apr 23, 2026

View reviewed changes

stefnestor commented Apr 23, 2026

View reviewed changes

Comment thread deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md Outdated

stefnestor and others added 3 commits April 23, 2026 09:36

Copilot feedback

a18d65b

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Stef Nestor <26751266+stefnestor@users.noreply.github.com>

Merge branch 'main' into stef_esUpgrade

e7e917f

Apply suggestion from @Copilot

acd2482

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

yetanothertw requested changes Apr 24, 2026

View reviewed changes

code review 🙏

318e15b

Co-authored-by: Vlada Chirmicci <vlada.chirmicci@elastic.co> Co-authored-by: Stef Nestor <26751266+stefnestor@users.noreply.github.com>

Merge branch 'main' into stef_esUpgrade

687ca46

stefnestor enabled auto-merge (squash) April 24, 2026 22:26

feedback 🙏

4756b92

Co-authored-by: Stef Nestor <26751266+stefnestor@users.noreply.github.com> Co-authored-by: Vlada Chirmicci <vlada.chirmicci@elastic.co>

Merge branch 'main' into stef_esUpgrade

b67fdcf

yetanothertw approved these changes May 1, 2026

View reviewed changes

Comment thread deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md Outdated

Comment thread deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md Outdated

stefnestor and others added 2 commits May 1, 2026 07:32

feedback 🙏

446235f

Co-authored-by: Vlada Chirmicci <vlada.chirmicci@elastic.co>

Merge branch 'main' into stef_esUpgrade

f3c3168

stefnestor merged commit c5905a0 into elastic:main May 1, 2026
11 checks passed

stefnestor mentioned this pull request May 9, 2026

Troubleshooting Elasticsearch Upgrades #6396

Merged

2 tasks

shainaraskas mentioned this pull request Jun 5, 2026

[Internal]: Elasticsearch - Documenting full restart-upgrades of clusters #3879

Closed

Uh oh!

Conversation

stefnestor commented Apr 9, 2026

Summary

Generative AI disclosure

Uh oh!

eedugon commented Apr 9, 2026

Uh oh!

stefnestor commented Apr 9, 2026

Uh oh!

github-actions Bot commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

github-actions Bot commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Vale Linting Results

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

stefnestor commented Apr 17, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yetanothertw left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

stefnestor commented Apr 24, 2026

Uh oh!

github-actions Bot commented Apr 30, 2026

Elastic Docs AI PR menu

Uh oh!

stefnestor commented Apr 30, 2026

Uh oh!

yetanothertw left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

yetanothertw commented May 1, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

github-actions Bot commented Apr 9, 2026 •

edited

Loading

github-actions Bot commented Apr 9, 2026 •

edited

Loading