Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DOC] Clarify compatibility of Saved Objects across versions #63090

Merged
merged 7 commits into from
Mar 8, 2021
Merged

[DOC] Clarify compatibility of Saved Objects across versions #63090

Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
0cae060
[DOC] Clarify compatibility of Saved Objects across versions
lucabelluccini Apr 9, 2020
d84dba2
Update docs/management/managing-saved-objects.asciidoc
lucabelluccini Mar 1, 2021
3cb4e6d
Merge branch 'master' into docs-kibana-so-import-export-compat
rudolf Mar 8, 2021
cd635dd
Saved objects compatibility
rudolf Mar 8, 2021
22dd697
Merge branch 'docs-kibana-so-import-export-compat' of github.com:elas…
rudolf Mar 8, 2021
12cb9e3
clarify that same version export/import is compatible
rudolf Mar 8, 2021
f80d367
Add compatibility to SO import API docs
rudolf Mar 8, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions docs/management/managing-saved-objects.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,17 @@ have multiple environments for development and production.
Import and export also work well when you have a large number
of objects to update and want to batch the process.

[float]
==== Compatibility across versions and downgrades
Copy link
Contributor

Choose a reason for hiding this comment

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

As you removed the content about downgrades, should the title be "Compatibility across versions"?


We do not guarantee compatibility of a Saved Object exported from newer Kibana version and imported to older Kibana version:
Copy link
Contributor

Choose a reason for hiding this comment

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

@rudolf I thought importing objects with a higher migrationVersion to an older instance would just throw an error for the object, but I can't find this behavior in src/core/server/saved_objects/import/import_saved_objects.ts?

Copy link
Contributor

Choose a reason for hiding this comment

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

Based on this forum post https://discuss.elastic.co/t/copy-visualisation-and-dashboards/225958 I don't think it's producing a nice error message, just failing with a generic "Could not be processed"

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Any update on this?

Copy link
Contributor

@rudolf rudolf May 13, 2020 •
edited
Loading

Choose a reason for hiding this comment

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

Before creating any objects we migrate them, so trying to import a newer object will fail the migration and therefore the SavedObjectsRepository#bulkCreate.

The API correctly responds with:

{"statusCode":422,"error":"Unprocessable Entity","message":"Document \"d3d7af60-4c81-11e8-b3d7-01146121b73d\" has property \"index-pattern\" which belongs to a more recent version of Kibana [8.1.0]. The last known version is [7.6.0]"

But like @flash1293 said we don't display this to users, I'll open an issue for this.

Copy link
Contributor

Choose a reason for hiding this comment

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

When importing using the deprecated .json file format we correctly surface the error in the UI.

Copy link
Contributor

Choose a reason for hiding this comment

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

Created #66387

lucabelluccini marked this conversation as resolved.
Show resolved Hide resolved

* New functionalities (e.g. a new Visualization type or new options in existing visualizations) cannot be reproduced in previous versions
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
* New functionalities (e.g. a new Visualization type or new options in existing visualizations) cannot be reproduced in previous versions
* New functionalities (for example, a new visualization type or new options in an existing visualization) cannot be reproduced in previous versions.

* The exported format of Saved Objects can change without notice and it is guaranteed to work only when reimported on the same (or more recent) Kibana version
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
* The exported format of Saved Objects can change without notice and it is guaranteed to work only when reimported on the same (or more recent) Kibana version
* The exported format of saved objects can change without notice and is guaranteed to work only when reimported on the same (or more recent) {kib} version.


Kibana automatically performs a Saved Object migration at every upgrade (even minor versions) due to format changes, new features or fixes.
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
Kibana automatically performs a Saved Object migration at every upgrade (even minor versions) due to format changes, new features or fixes.
{kib} automatically migrates saved objects at every upgrade, including minor versions, due to format changes, new features, and fixes.

Copy link
Contributor

Choose a reason for hiding this comment

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

This sounds like it should be the first sentence:

Kibana automatically migrates saved objects at every upgrade, including minor versions, due to format changes, new features, and fixes. However, compatibility of a saved object exported from a newer {kib} version and imported to an older {kib} version (including patch versions) is not guaranteed:


The official process to perform a Kibana downgrade is to restore a snapshot of the Kibana indices taken before the upgrade. Please **always** snapshot all the Kibana indices prior upgrading.
rudolf marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Contributor Author

Choose a reason for hiding this comment

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

Suggested change
The official process to perform a Kibana downgrade is to restore a snapshot of the Kibana indices taken before the upgrade. Please **always** snapshot all the Kibana indices prior upgrading.

Copy link
Contributor

Choose a reason for hiding this comment

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

This section would flow better under the Export section.

You might also consider moving this content to this doc: https://www.elastic.co/guide/en/kibana/current/upgrade-migrations.html and then linking to it from the Saved objects doc.
.


[float]
==== Import
Expand Down