Skip to content

Fix index compatibility table header#7186

Open
yetanothertw wants to merge 5 commits into
mainfrom
index-compatibility-table
Open

Fix index compatibility table header#7186
yetanothertw wants to merge 5 commits into
mainfrom
index-compatibility-table

Conversation

@yetanothertw

@yetanothertw yetanothertw commented Jul 2, 2026

Copy link
Copy Markdown
Member

Summary

Fixes #6819 which reports:

  1. the docs don't mention that Kibana versions complicate snapshot restores:

I attempted to take a snapshot on ELK version 8.1.0 and restore it on version 9.2.4 which failed with the log FATAL Error: Kibana 8.1.0 deployment detected. Please upgrade to Kibana 8.18.0 or newer before upgrading to 9.x series.

  1. confusion around the way the table headings are with a single header row labeled only the left column (Index creation version).

Fix for the 1st problem

The PRs linked on the issue added a guard (that's present in the current Kibana main and here) the minimum version seems to be hardcoded here.

After restoring a snapshot from an 8.1.0 cluster, .kibana still has aliases like .kibana_8.1.0. Kibana 9.2.4 sees that, compares it to 8.18.0, and fails fatally before migrations run.

PREVIEW AVAILABLE HERE

Why snapshot restore fails here

My friend Claude reckons:

Snapshot/restore can move Elasticsearch data, but it does not replace the required Kibana upgrade path:

  1. Snapshot from 8.1.0 includes Kibana system indices (.kibana, .kibana_task_manager, etc.) and their version aliases.
  2. Restore onto a 9.2.4 cluster brings those indices back as-is.
  3. Kibana 9.2.4 starts, hits saved-object migration, sees .kibana_8.1.0, and refuses to proceed.

Elasticsearch version compatibility for data indices is separate from Kibana saved-object migration compatibility. A restore that ES accepts can still fail when Kibana starts.

What the user should do instead

NEEDS TO BE VALIDATED by Eng:

Supported path:

  1. Restore the snapshot to an 8.18+ or 8.19 cluster (ideally latest 8.19 patch per upgrade docs).
  2. Start Kibana 8.19 and let saved-object migrations complete.
  3. Snapshot from 8.19 and restore to 9.2.4. (9.2.4 is used as an example as that's what the user reported they had).

Alternatively:

If the user only needs data and not the Kibana state:

  1. Restore without the kibana feature state / .kibana* indices and accept a fresh Kibana setup.
  2. Use reindex-from-remote for data-only migration (as noted in snapshot compatibility docs).

Fix for the 2nd problem

The table is correct but ambiguous: since both axes use version numbers, but only one axis was named, I'm adding another row to name both dimensions. This matches an existing docs pattern (in the CCS table). This should reduce transpose misreads without changing the underlying compatibility data.
Unfortunately, there's tooling limitation we need to work around as cell merging is not possible, which is why I chose this option.

PREVIEW AVAILABLE HERE

This is one option:

image

This is another option (currently on this branch):

image

Both are quite similar. Not sure which one is clearer.

Generative AI disclosure

  1. Did you use a generative AI (GenAI) tool to assist in creating this contribution?
  • Yes
  • No

@yetanothertw yetanothertw self-assigned this Jul 2, 2026
@github-actions

github-actions Bot commented Jul 2, 2026

Copy link
Copy Markdown
Contributor

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.

@github-actions

github-actions Bot commented Jul 2, 2026

Copy link
Copy Markdown
Contributor

🔍 Preview links for changed docs

@github-actions

github-actions Bot commented Jul 2, 2026

Copy link
Copy Markdown
Contributor

Elastic Docs Style Checker (Vale)

Summary: 1 warning found

⚠️ Warnings (1): Fix when the suggestion improves clarity or correctness.
File Line Rule Message
deploy-manage/tools/snapshot-and-restore.md 161 Elastic.DirectionalLanguage Don't use directional language. Use 'the label of the element' instead of 'in the left'.

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.

@yetanothertw yetanothertw marked this pull request as ready for review July 6, 2026 10:11
@yetanothertw yetanothertw requested a review from a team as a code owner July 6, 2026 10:11

@sabarasaba sabarasaba left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I think it makes sense and it matches what we discussed over slack


| | | | | | | |
|-----------------------|-----|--------|-------|----------|---------|-----|
| | Cluster version (restore target) <br> {{version.stack.base}}–{{version.stack}} | 8.3–8.19 | 8.0–8.2 | 7.2–7.17 | 7.0–7.1 | 6.8 |

@jloleysens jloleysens Jul 6, 2026

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.

I think this change makes sense. I often call it "stack" version to imply Kibana, Elasticsearch and everything else, but if "cluster" is consistent language then let's stick with that.

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.

[Website]: Incorrect snapshot version compatibility table

3 participants