Skip to content

Commit

Permalink
Update snapshot docs for new system index defaults (elastic#120174)
Browse files Browse the repository at this point in the history
With elastic/elasticsearch#79670, you can only include system indices in a snapshot using feature states. This updates some references to taking a snapshots of the `.kibana*` system indices.

Relates to elastic/elasticsearch#81226
  • Loading branch information
jrodewig authored and kibanamachine committed Dec 8, 2021
1 parent 15e4eb0 commit 0ee0b93
Show file tree
Hide file tree
Showing 2 changed files with 14 additions and 6 deletions.
13 changes: 10 additions & 3 deletions docs/setup/upgrade.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -44,13 +44,20 @@ a|
[[upgrade-before-you-begin]]
=== Before you begin

WARNING: {kib} automatically runs upgrade migrations when required. To roll back to an earlier version in case of an upgrade failure, you **must** have a {ref}/snapshot-restore.html[backup snapshot] available. This snapshot must include the `kibana` feature state or all `kibana*` indices. For more information see <<upgrade-migrations, upgrade migrations>>.
[WARNING]
====
{kib} automatically runs upgrade migrations when required. To roll back to an
earlier version in case of an upgrade failure, you **must** have a
{ref}/snapshot-restore.html[backup snapshot] that includes the `kibana` feature
state. Snapshots include this feature state by default.
For more information, refer to <<upgrade-migrations, upgrade migrations>>.
====

Before you upgrade {kib}:

* Consult the <<breaking-changes,breaking changes>>.
* {ref}/snapshots-take-snapshot.html[Take a snapshot] of your data. To roll back to an earlier version, the snapshot must include the `kibana` feature state or all `.kibana*` indices.
* Although not a requirement for rollbacks, we recommend taking a snapshot of all {kib} indices created by the plugins you use such as the `.reporting*` indices created by the reporting plugin.
* {ref}/snapshots-take-snapshot.html[Take a snapshot] of your data. To roll back to an earlier version, the snapshot must include the `kibana` feature state.
* Before you upgrade production servers, test the upgrades in a dev environment.
* See <<preventing-migration-failures, preventing migration failures>> for common reasons upgrades fail and how to prevent these.
* If you are using custom plugins, check that a compatible version is
Expand Down
7 changes: 4 additions & 3 deletions docs/setup/upgrade/upgrade-migrations.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -151,17 +151,18 @@ In order to rollback after a failed upgrade migration, the saved object indices
[float]
===== Rollback by restoring a backup snapshot:

1. Before proceeding, {ref}/snapshots-take-snapshot.html[take a snapshot] that contains the `kibana` feature state or all `.kibana*` indices.
1. Before proceeding, {ref}/snapshots-take-snapshot.html[take a snapshot] that contains the `kibana` feature state.
Snapshots include this feature state by default.
2. Shutdown all {kib} instances to be 100% sure that there are no instances currently performing a migration.
3. Delete all saved object indices with `DELETE /.kibana*`
4. {ref}/snapshots-restore-snapshot.html[Restore] the `kibana` feature state or all `.kibana* indices and their aliases from the snapshot.
4. {ref}/snapshots-restore-snapshot.html[Restore] the `kibana` feature state from the snapshot.
5. Start up all {kib} instances on the older version you wish to rollback to.

[float]
===== (Not recommended) Rollback without a backup snapshot:

1. Shutdown all {kib} instances to be 100% sure that there are no {kib} instances currently performing a migration.
2. {ref}/snapshots-take-snapshot.html[Take a snapshot] that includes the `kibana` feature state or all `.kibana*` indices.
2. {ref}/snapshots-take-snapshot.html[Take a snapshot] that includes the `kibana` feature state. Snapshots include this feature state by default.
3. Delete the version specific indices created by the failed upgrade migration. E.g. if you wish to rollback from a failed upgrade to v7.12.0 `DELETE /.kibana_7.12.0_*,.kibana_task_manager_7.12.0_*`
4. Inspect the output of `GET /_cat/aliases`. If either the `.kibana` and/or `.kibana_task_manager` alias is missing, these will have to be created manually. Find the latest index from the output of `GET /_cat/indices` and create the missing alias to point to the latest index. E.g. if the `.kibana` alias was missing and the latest index is `.kibana_3` create a new alias with `POST /.kibana_3/_aliases/.kibana`.
5. Remove the write block from the rollback indices. `PUT /.kibana,.kibana_task_manager/_settings {"index.blocks.write": false}`
Expand Down

0 comments on commit 0ee0b93

Please sign in to comment.