Troubleshooting Elasticsearch Upgrades#6396
Conversation
Elastic Docs AI PR menuCheck the box to run an AI review for this pull request.
Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
🔍 Preview links for changed docs |
|
👋 howdy, team! In famous "many errors reduce down to a handful of core issues", this PR (with it's blossoming sub-PRs) documents the majority of the issues users surface to Support during Elasticsearch upgrade, both during the Upgrade Assistant as well as during actual upgrade. I did both pages simultaneously mostly as part of process trying to unwind that hairball since majority of errors are cascades of templates or index compatibility due to failing to do the upgrade assistant fully. 🙏 TIA! |
There was a problem hiding this comment.
Docs review summary
Focus areas
- Style and clarity: Found several issues with phrasing, including redundant wording ("due to due diligence"), awkward constructions ("ensure to"), and overuse of first-person plural ("we"). Present tense should be used more consistently per style guide.
- Jargon: No unexplained jargon detected. Good use of product names and technical terms with appropriate context.
- Frontmatter and applies_to:
- Critical typo:
troubleshooting-upgrade-assistant.mdhas "Assitant" instead of "Assistant" innavigation_title - Duplicate descriptions: Both new troubleshooting files use identical description text ("Common upgrade issues and resolutions."), which violates the requirement for unique descriptions
applies_tousage appears correct
- Critical typo:
- Content type fit: Both new pages are labeled as
type: troubleshootingbut function more as wayfinding/collection pages rather than dedicated troubleshooting pages. They lack the standard Symptoms and Resolution structure required for dedicated troubleshooting pages. This is acceptable per the content-type guidelines for "generic wayfinding pages" that "organize multiple related troubleshooting topics," but the generic titles and structure should be intentional. - Parent issue satisfaction: The PR references #5848 as a follow-up. The changes successfully create separate troubleshooting pages for upgrade issues as intended, moving content from the main upgrade guide into dedicated troubleshooting documentation.
Nits
- Line 15 of
troubleshooting-upgrades.md: "beginning upgrading" could be "beginning the upgrade" - Multiple instances could be tightened: "you would commonly filter" → "commonly filter", "you should end up with" → "you should have"
- The phrase "for your reference" appears multiple times and adds little value
Notes
- The changes appropriately refactor the "Rolling upgrades considerations" section from
elasticsearch.mdinto a dedicated troubleshooting page, improving discoverability - Cross-linking between the upgrade documentation and new troubleshooting pages is well implemented
- The new tip callouts in
elasticsearch.mdandupgrade-assistant.mdappropriately direct users to the troubleshooting resources
Generated by Docs review agent for issue #6396 · ● 1.3M
|
|
||
| Production environments should have [at least three master-eligible nodes for high availability](/deploy-manage/deploy/elastic-cloud/elastic-cloud-hosted-planning.md). In a testing or development environment with only one or two master-eligible nodes, you cannot avoid stopping half or more of the master-eligible nodes, so the cluster will always [become unavailable](/troubleshoot/elasticsearch/discovery-troubleshooting.md#discovery-no-master) at some point during the upgrade. | ||
|
|
||
| You must restart all the stopped master-eligible nodes to allow the cluster to re-form. This might cause a [premature cluster version update](#troubleshooting-upgrades-theory-version). |
There was a problem hiding this comment.
Unclear connection: The statement "You must restart all the stopped master-eligible nodes to allow the cluster to re-form. This might cause a premature cluster version update." could be clearer about when this causes the problem.
Consider: "You must restart all the stopped master-eligible nodes to allow the cluster to re-form. If those restarted nodes are all running the upgraded version, this will cause a premature cluster version update."
|
|
||
| This error indicates the [Upgrade Assistant](/deploy-manage/upgrade/prepare-to-upgrade/upgrade-assistant.md) was not fully completed during [upgrade preparation work](/deploy-manage/upgrade/prepare-to-upgrade.md). | ||
|
|
||
| You should reset this node's version upgrade, rejoin it to cluster at the earlier version, and complete the [Upgrade Assistant](/deploy-manage/upgrade/prepare-to-upgrade/upgrade-assistant.md) critical items before beginning upgrading. Refer also to [Troubleshoot Upgrade Assistant](/troubleshoot/elasticsearch/troubleshooting-upgrade-assistant.md). |
There was a problem hiding this comment.
Clarity: "You should reset this node's version upgrade" is vague. Consider being more specific about what action to take:
"Downgrade this node back to the earlier version, allow it to rejoin the cluster, and complete the Upgrade Assistant critical items before attempting to upgrade again. Refer also to Troubleshoot Upgrade Assistant."
|
Bumping @elastic/admin-docs 🙏 |
|
@stefnestor I pushed quite a few changes. 🐌 Please take a quick look before merging. By the way, for all docs-content PRs, please make sure to check the preview links that are automatically generated. Some issues are more apparent that way, like in this screenshot: |
|
Fabulous, cheers! 🙇♀️ |
2 participants
Summary
👋 Follow-up of #5848 to create separate upgrade troubleshooting page.
This assumes but does not breaking rely on errors WIP documenting in
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
Non-exhaustive related links
.securityindex fails ifsecurity-index-template-v6is still present elasticsearch#86801Generative AI disclosure