Fix index compatibility table header#7186
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. |
🔍 Preview links for changed docs |
Elastic Docs Style Checker (Vale)Summary: 1 warning found
|
| File | Line | Rule | Message |
|---|---|---|---|
| deploy-manage/tools/snapshot-and-restore.md | 167 | 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.
sabarasaba
left a comment
sabarasaba
left a comment
There was a problem hiding this comment.
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 | |
There was a problem hiding this comment.
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.
eedugon
left a comment
eedugon
left a comment
There was a problem hiding this comment.
I like a lot this PR, thanks a lot of adding this "Kibana compatibility" new section.
I've shared a few comments for your consideration but feel free to ignore if you don't feel they add much value.
| @@ -158,22 +158,32 @@ You can’t restore a snapshot to an earlier version of {{es}}. For example, you | |||
|
|
|||
| Any index you restore from a snapshot must also be compatible with the current cluster’s version. If you try to restore an index created in an incompatible version, the restore attempt fails. | |||
There was a problem hiding this comment.
After this line, in the "INDEX COMPATIBILITY" section, I'd suggest to add some extra scope of what we mean exactly with compatibility, and that compatibility doesn't mean restored data will be valid, as that depends on the data owner expectations (such as Kibana data, but this could happen with other stack features data if they write in their own indices).
Let me explain:
When it comes to snapshot compatibility or index compatibility we talk about the capacity of Elasticsearch of restoring indices from snapshots created in older versions of Elasticsearch. Compatibility means that Elasticsearch is capable of restoring the original index and data (maybe as read-only in case of archive mode), but that does not mean that the data will be VALID for the application using it in all cases <-- that's the important thing to clarify.
For user data, compatibility will almost always imply that the restored data will be valid to the user, but for Kibana or stack features data this validity that cannot be guaranteed, as the application could expect different data format in different stack versions (such as Kibana). Because of that, users shouldn't use snapshot and restore as a way to "upgrade" except if they are focused only on the data they own.
I love the sentence you included:
Restoring an old snapshot directly to a 9.x cluster is not a shortcut around the normal upgrade paths. It is recommended you upgrade to the latest compatible minor release before a major upgrade, even when you use snapshots to move data between clusters.
Maybe that sentence could be included as an important note in this index compatibility intro, more than just in the Kibana use case that you are documenting.
Anyway feel free to ignore this if you or the rest of the team believes it doesn't add value, the current PR is really good and adds value!
There was a problem hiding this comment.
This is such a good comment and observation, you're totally right! We're missing crucial context, so I've tried to add some. Can you please review this again and let me know if this is what you had in mind, @eedugon ? 🙏
Edu's feedback Co-authored-by: Edu González de la Herrán <25320357+eedugon@users.noreply.github.com>
4 participants
Summary
Fixes #6819 which reports:
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:
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
VALIDATED by Eng (internal slack):
Supported path:
Alternatively:
If the user only needs data and not the Kibana state:
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:
This is another option (currently on this branch):
Both are quite similar. Not sure which one is clearer.
Generative AI disclosure