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

lucabelluccini · 2020-04-09T08:38:29Z

Summary

Clarify compatibility of Saved Objects across versions and best practices for Kibana downgrades.
It might be moved to "Limitations" sections, eventually.

Checklist

Delete any items that are not applicable to this PR.

Documentation was added for features that require explanation or tutorials

pgayvallet · 2020-04-09T09:10:02Z

docs/management/managing-saved-objects.asciidoc

+[float]
+==== Compatibility across versions and downgrades
+
+We do not guarantee compatibility of a Saved Object exported from newer Kibana version and imported to older Kibana version:


@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?

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"

Any update on this?

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.

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

Created #66387

docs/management/managing-saved-objects.asciidoc

gchaps

The Kibana docs include this topic under Upgrade: Troubleshooting saved object migrations. This page includes information about the automatic upgrade.

So I think maybe we can include something like this on that page:

NOTE: A saved object exported from Kibana is only guaranteed to work when imported in the same, or more recent version, of Kibana. To work with saved objects in a previous version of Kibana, restore the snapshot of the Kibana indices taken prior to the upgrade.

If they followed the instructions on the upgrade page, they should have taken a snapshot prior to upgrading.

lucabelluccini · 2020-05-13T15:14:51Z

I would mention the compatibility thing also in the import/export APIs as a user might be interested in copying an object from one instance to another and they might be in different versions (new to old and old to new).

gchaps · 2020-05-13T15:17:55Z

So in these two topics?

https://www.elastic.co/guide/en/kibana/current/saved-objects-api-export.html
https://www.elastic.co/guide/en/kibana/current/saved-objects-api-import.html

lucabelluccini · 2020-05-13T15:23:11Z

So in these two topics?

https://www.elastic.co/guide/en/kibana/current/saved-objects-api-export.html
https://www.elastic.co/guide/en/kibana/current/saved-objects-api-import.html

Yes, this would be great - Or maybe on https://www.elastic.co/guide/en/kibana/current/saved-objects-api.html where we can explain what a Saved Object is and the compatibility. I'm sharing some thoughts but not 100% sure where they should be placed.

elasticmachine · 2020-05-15T09:32:21Z

Pinging @elastic/kibana-platform (Team:Platform)

gchaps · 2020-05-15T13:39:12Z

@lucabelluccini This topic has a brief explanation of what a saved object is. Let me know if you think that explanation should be improved as well.

elasticmachine · 2020-05-21T16:22:06Z

Pinging @elastic/kibana-docs (Team:Docs)

ppf2 · 2020-10-01T20:53:55Z

Bump. Still a recurring question from the field. Would like to see this officially documented :)

lucabelluccini · 2020-10-02T23:24:12Z

As @ppf2 suggests, we need a clear statement of the compatibility of Saved Objects across versions and list the supported "backup" options for Kibana Saved Objects (snapshot of .kibana or export via Kibana UI or via Kibana APIs).

lucabelluccini · 2020-12-02T18:59:28Z

Hello @rudolf
It is great since #82406 we'll surface the fact we're trying to import a NEW saved object into an OLD Kibana instance.
But I still think it is nice to document importing saved objects from version N to N-1 is not possible especially because users will not see the actual error message ...which belongs to a more recent version of Kibana (... until #82406 is out.

lucabelluccini · 2020-12-02T19:12:30Z

docs/management/managing-saved-objects.asciidoc

+
+Kibana automatically performs a Saved Object migration at every upgrade (even minor versions) due to format changes, new features or fixes.
+
+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.


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.

elasticmachine · 2021-03-01T11:01:02Z

Pinging @elastic/kibana-core (Team:Core)

docs/management/managing-saved-objects.asciidoc

gchaps

LGTM

gchaps · 2021-03-08T22:55:28Z

docs/api/saved-objects/import.asciidoc

@@ -6,6 +6,18 @@

 experimental[] Create sets of {kib} saved objects from a file created by the export API.

+==== Compatibility across versions
+Saved objects can only be imported into the same version, a newer minor on the same major or the next major. Exported saved objects are not backwards compatible and cannot be imported into an older version of {kib}. See the table below for compatibility examples:


Suggested change

Saved objects can only be imported into the same version, a newer minor on the same major or the next major. Exported saved objects are not backwards compatible and cannot be imported into an older version of {kib}. See the table below for compatibility examples:

Saved objects can only be imported into the same version, a newer minor on the same major, or the next major. Exported saved objects are not backwards compatible and cannot be imported into an older version of {kib}. See the table below for compatibility examples:

gchaps · 2021-03-08T22:57:05Z

docs/management/managing-saved-objects.asciidoc

+
+With each release, {kib} introduces changes to the way saved objects are stored. When importing a saved object, {kib} will run the necessary migrations to ensure that the imported saved objects are compatible with the current version.
+
+However, saved objects can only be imported into the same version, a newer minor on the same major or the next major. Exported saved objects are not backwards compatible and cannot be imported into an older version of {kib}. See the table below for compatibility examples:


Suggested change

However, saved objects can only be imported into the same version, a newer minor on the same major or the next major. Exported saved objects are not backwards compatible and cannot be imported into an older version of {kib}. See the table below for compatibility examples:

However, saved objects can only be imported into the same version, a newer minor on the same major, or the next major. Exported saved objects are not backwards compatible and cannot be imported into an older version of {kib}. See the table below for compatibility examples:

Please make sure the comma is correct.

…63090)" This reverts commit 4c58e70.

…63090)" (#94070) This reverts commit 4c58e70.

kibanamachine · 2021-03-10T23:05:54Z

Friendly reminder: Looks like this PR hasn’t been backported yet.
To create backports run node scripts/backport --pr 63090 or prevent reminders by adding the backport:skip label.

kibanamachine · 2021-03-11T23:15:53Z

Friendly reminder: Looks like this PR hasn’t been backported yet.
To create backports run node scripts/backport --pr 63090 or prevent reminders by adding the backport:skip label.

kibanamachine · 2021-03-12T23:25:53Z

Friendly reminder: Looks like this PR hasn’t been backported yet.
To create backports run node scripts/backport --pr 63090 or prevent reminders by adding the backport:skip label.

jportner · 2021-06-29T16:12:48Z

This was mistakenly never backported to 7.x, before the 7.13 branch was cut. So I'm now backporting it to 7.13 and 7.x.

Edit: I see this was reverted in favor of #94072, I'll backport that instead.

[DOC] Clarify compatibility of Saved Objects across versions

0cae060

lucabelluccini requested review from timroes and gchaps April 9, 2020 08:38

timroes requested review from a team and removed request for timroes April 9, 2020 09:00

pgayvallet reviewed Apr 9, 2020

View reviewed changes

rudolf reviewed May 13, 2020

View reviewed changes

docs/management/managing-saved-objects.asciidoc Outdated Show resolved Hide resolved

rudolf self-assigned this May 13, 2020

gchaps reviewed May 13, 2020

View reviewed changes

rudolf added Feature:Kibana Management Feature label for Data Views, Advanced Setting, Saved Object management pages Feature:Saved Objects Team:Core Core services & architecture: plugins, logging, config, saved objects, http, ES client, i18n, etc labels May 15, 2020

gchaps added the Team:Docs label May 21, 2020

lucabelluccini commented Dec 2, 2020

View reviewed changes

lucabelluccini marked this pull request as ready for review March 1, 2021 11:01

lucabelluccini commented Mar 1, 2021

View reviewed changes

docs/management/managing-saved-objects.asciidoc Outdated Show resolved Hide resolved

Update docs/management/managing-saved-objects.asciidoc

d84dba2

lucabelluccini requested a review from pgayvallet March 1, 2021 11:02

rudolf added v7.0.3 v7.1.3 v7.2.3 v7.3.3 v7.4.3 v7.5.2 v7.6.3 v7.7.2 and removed v7.9.0 v7.9.1 v7.9.2 v7.9.3 labels Mar 8, 2021

rudolf enabled auto-merge (squash) March 8, 2021 21:45

gchaps approved these changes Mar 8, 2021

View reviewed changes

rudolf merged commit 4c58e70 into master Mar 8, 2021

rudolf added a commit that referenced this pull request Mar 9, 2021

Revert "[DOC] Clarify compatibility of Saved Objects across versions (#…

454119c

…63090)" This reverts commit 4c58e70.

rudolf mentioned this pull request Mar 9, 2021

Revert "[DOC] Clarify compatibility of Saved Objects across versions" #94070

Merged

rudolf added a commit that referenced this pull request Mar 9, 2021

Revert "[DOC] Clarify compatibility of Saved Objects across versions (#…

1f4a72e

…63090)" (#94070) This reverts commit 4c58e70.

rudolf mentioned this pull request Mar 9, 2021

Saved objects import compatibility across versions #94072

Merged

9 tasks

rudolf deleted the docs-kibana-so-import-export-compat branch March 9, 2021 15:53

kibanamachine added the backport missing Added to PRs automatically when the are determined to be missing a backport. label Mar 10, 2021

rudolf added the backport:skip This commit does not require backporting label Mar 15, 2021

kibanamachine removed the backport missing Added to PRs automatically when the are determined to be missing a backport. label Mar 15, 2021

jportner added v7.13.0 v7.14.0 labels Jun 29, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

lucabelluccini commented Apr 9, 2020

pgayvallet Apr 9, 2020

flash1293 Apr 9, 2020

lucabelluccini May 13, 2020

rudolf May 13, 2020 •

edited

Loading

rudolf May 13, 2020

rudolf May 13, 2020

gchaps left a comment

lucabelluccini commented May 13, 2020

gchaps commented May 13, 2020

lucabelluccini commented May 13, 2020

elasticmachine commented May 15, 2020

gchaps commented May 15, 2020 •

edited

Loading

elasticmachine commented May 21, 2020

ppf2 commented Oct 1, 2020

lucabelluccini commented Oct 2, 2020

lucabelluccini commented Dec 2, 2020 •

edited

Loading

lucabelluccini Dec 2, 2020

elasticmachine commented Mar 1, 2021

gchaps left a comment

gchaps Mar 8, 2021

gchaps Mar 8, 2021

gchaps Mar 8, 2021

kibanamachine commented Mar 10, 2021

kibanamachine commented Mar 11, 2021

kibanamachine commented Mar 12, 2021

jportner commented Jun 29, 2021 •

edited

Loading


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

		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.

	Saved objects can only be imported into the same version, a newer minor on the same major or the next major. Exported saved objects are not backwards compatible and cannot be imported into an older version of {kib}. See the table below for compatibility examples:
	Saved objects can only be imported into the same version, a newer minor on the same major, or the next major. Exported saved objects are not backwards compatible and cannot be imported into an older version of {kib}. See the table below for compatibility examples:


		With each release, {kib} introduces changes to the way saved objects are stored. When importing a saved object, {kib} will run the necessary migrations to ensure that the imported saved objects are compatible with the current version.

		However, saved objects can only be imported into the same version, a newer minor on the same major or the next major. Exported saved objects are not backwards compatible and cannot be imported into an older version of {kib}. See the table below for compatibility examples:

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

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

Conversation

lucabelluccini commented Apr 9, 2020

Summary

Checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rudolf May 13, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gchaps left a comment

Choose a reason for hiding this comment

lucabelluccini commented May 13, 2020

gchaps commented May 13, 2020

lucabelluccini commented May 13, 2020

elasticmachine commented May 15, 2020

gchaps commented May 15, 2020 • edited Loading

elasticmachine commented May 21, 2020

ppf2 commented Oct 1, 2020

lucabelluccini commented Oct 2, 2020

lucabelluccini commented Dec 2, 2020 • edited Loading

Choose a reason for hiding this comment

elasticmachine commented Mar 1, 2021

gchaps left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kibanamachine commented Mar 10, 2021

kibanamachine commented Mar 11, 2021

kibanamachine commented Mar 12, 2021

jportner commented Jun 29, 2021 • edited Loading

rudolf May 13, 2020 •

edited

Loading

gchaps commented May 15, 2020 •

edited

Loading

lucabelluccini commented Dec 2, 2020 •

edited

Loading

jportner commented Jun 29, 2021 •

edited

Loading