From 4782cf4d9158e401d76b4bce3d63f8953890b120 Mon Sep 17 00:00:00 2001 From: David Turner Date: Mon, 27 Sep 2021 16:56:35 +0100 Subject: [PATCH] Add docs for pre-release version compatibility (#78317) The reference manual includes docs on version compatibility in various places, but it's not clear that these docs only apply to released versions and that the rules for pre-release versions are stricter than folks expect. This commit adds some words to the docs for unreleased versions which explains this subtlety. --- docs/reference/ccr/index.asciidoc | 2 +- .../modules/remote-clusters-shared.asciidoc | 24 +++++++++++++++++ .../modules/remote-clusters.asciidoc | 26 ++++++++----------- .../reference/snapshot-restore/index.asciidoc | 14 ++++++++++ docs/reference/upgrade.asciidoc | 12 +++++++++ 5 files changed, 62 insertions(+), 16 deletions(-) create mode 100644 docs/reference/modules/remote-clusters-shared.asciidoc diff --git a/docs/reference/ccr/index.asciidoc b/docs/reference/ccr/index.asciidoc index 777e5a829a82..b853587bf5cb 100644 --- a/docs/reference/ccr/index.asciidoc +++ b/docs/reference/ccr/index.asciidoc @@ -32,7 +32,7 @@ If newer, the versions must also be compatible as outlined in the following matr [[ccr-version-compatibility]] .Version compatibility matrix ==== -include::../modules/remote-clusters.asciidoc[tag=remote-cluster-compatibility-matrix] +include::../modules/remote-clusters-shared.asciidoc[tag=remote-cluster-compatibility-matrix] ==== [discrete] diff --git a/docs/reference/modules/remote-clusters-shared.asciidoc b/docs/reference/modules/remote-clusters-shared.asciidoc new file mode 100644 index 000000000000..36985f20eb5a --- /dev/null +++ b/docs/reference/modules/remote-clusters-shared.asciidoc @@ -0,0 +1,24 @@ +// tag::remote-cluster-compatibility-matrix[] +[cols="^,^,^,^,^,^,^,^"] +|==== +| 7+^h| Local cluster +h| Remote cluster | 5.0->5.5 | 5.6 | 6.0->6.6 | 6.7 | 6.8 | 7.0 | 7.1->7.x +| 5.0->5.5 | {yes-icon} | {yes-icon} | {no-icon} | {no-icon} | {no-icon} | {no-icon} | {no-icon} +| 5.6 | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {no-icon} | {no-icon} +| 6.0->6.6 | {no-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {no-icon} | {no-icon} +| 6.7 | {no-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {no-icon} +| 6.8 | {no-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} +| 7.0 | {no-icon} | {no-icon} | {no-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} +| 7.1->7.x | {no-icon} | {no-icon} | {no-icon} | {no-icon} | {yes-icon} | {yes-icon} | {yes-icon} +|==== + +ifeval::["{release-state}"!="released"] +NOTE: This documentation is for {es} {version}, which is not yet released. The +above compatibility table only applies if the local or remote cluster is running +a released version of {es}. A local cluster running a pre-release build of {es} +can also communicate with remote clusters running the same pre-release build. +Running a mix of pre-release builds is unsupported and typically will not work, +even if the builds are the same version. +endif::[] + +// end::remote-cluster-compatibility-matrix[] diff --git a/docs/reference/modules/remote-clusters.asciidoc b/docs/reference/modules/remote-clusters.asciidoc index 2f1ca497e46c..4a21e45de17b 100644 --- a/docs/reference/modules/remote-clusters.asciidoc +++ b/docs/reference/modules/remote-clusters.asciidoc @@ -65,20 +65,7 @@ local and remote nodes. [%collapsible%open] .Version compatibility table ==== -// tag::remote-cluster-compatibility-matrix[] -[cols="^,^,^,^,^,^,^,^"] -|==== -| 7+^h| Local cluster -h| Remote cluster | 5.0->5.5 | 5.6 | 6.0->6.6 | 6.7 | 6.8 | 7.0 | 7.1->7.x -| 5.0->5.5 | {yes-icon} | {yes-icon} | {no-icon} | {no-icon} | {no-icon} | {no-icon} | {no-icon} -| 5.6 | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {no-icon} | {no-icon} -| 6.0->6.6 | {no-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {no-icon} | {no-icon} -| 6.7 | {no-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {no-icon} -| 6.8 | {no-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} -| 7.0 | {no-icon} | {no-icon} | {no-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} -| 7.1->7.x | {no-icon} | {no-icon} | {no-icon} | {no-icon} | {yes-icon} | {yes-icon} | {yes-icon} -|==== -// end::remote-cluster-compatibility-matrix[] +include::remote-clusters-shared.asciidoc[tag=remote-cluster-compatibility-matrix] ==== * *role*: Dedicated master nodes are never selected as gateway nodes. @@ -100,7 +87,16 @@ to the sniff <>, the remote connections are subject to the same version compatibility rules as <>. +Proxy mode has the same version compatibility requirements as sniff mode. + +[%collapsible] +[[proxy-mode-version-compatibility]] +.Version compatibility matrix +==== +include::remote-clusters-shared.asciidoc[tag=remote-cluster-compatibility-matrix] +==== + include::cluster/remote-clusters-security.asciidoc[] include::cluster/remote-clusters-connect.asciidoc[] include::../../../x-pack/docs/en/security/authentication/remote-clusters-privileges.asciidoc[] -include::cluster/remote-clusters-settings.asciidoc[] \ No newline at end of file +include::cluster/remote-clusters-settings.asciidoc[] diff --git a/docs/reference/snapshot-restore/index.asciidoc b/docs/reference/snapshot-restore/index.asciidoc index a40eba86b2ca..0f15ff4e5f07 100644 --- a/docs/reference/snapshot-restore/index.asciidoc +++ b/docs/reference/snapshot-restore/index.asciidoc @@ -94,6 +94,20 @@ The following conditions apply for restoring snapshots and indices across versio The one caveat is that snapshots taken by {es} 2.0 can be restored in clusters running {es} 5.0. ==== +ifeval::["{release-state}"!="released"] +[[snapshot-prerelease-build-compatibility]] +NOTE: This documentation is for {es} {version}, which is not yet released. The +compatibility table above applies only to snapshots taken in a released version +of {es}. If you're testing a pre-release build of {es} then you can also take +and restore snapshots as normal, but you must not use the same snapshot +repository with other builds of {es} even if the builds are the same version. +Different pre-release builds of {es} may use different and incompatible +repository layouts. If the repository layout is incompatible with the {es} build +in use then taking and restoring snapshots may result in errors or may appear to +succeed having silently lost some data. You should discard the repository when +moving to a different build. +endif::[] + Each snapshot can contain indices created in various versions of {es}. This includes backing indices created for data streams. When restoring a snapshot, it must be possible to restore all of these indices into the target cluster. If any diff --git a/docs/reference/upgrade.asciidoc b/docs/reference/upgrade.asciidoc index 16a35e5e85ed..5c3d648023c3 100644 --- a/docs/reference/upgrade.asciidoc +++ b/docs/reference/upgrade.asciidoc @@ -87,6 +87,18 @@ When upgrading to a new version of {es}, you need to upgrade each of the products in your Elastic Stack. For more information, see the {stack-ref}/upgrading-elastic-stack.html[Elastic Stack Installation and Upgrade Guide]. +ifeval::["{release-state}"!="released"] +[[upgrade-pre-release]] +NOTE: This documentation is for {es} {version}, which is not yet released. You +may run a pre-release build of {es} for testing, and you may upgrade from an +earlier released version to a pre-release build of {es} {version} if permitted +by the compatibility table above, but upgrading from a pre-release build to +another build (whether released or not) is unsupported. Upgrading a pre-release +build may result in errors or may appear to succeed having silently lost some +data. You should discard the contents of a cluster running a pre-release build +when moving to a different build. +endif::[] + -- include::upgrade/rolling_upgrade.asciidoc[]