Skip to content

Commit

Permalink
[DOCS] Archived settings block config updates (elastic#82069)
Browse files Browse the repository at this point in the history
**Changes:**

* Notes that archived cluster settings block cluster setting updates. Previously, the docs stated that ES ignored archived cluster settings.
* Notes that archived index settings can block index settings updates. For example, it blocks `index.hidden` but not `number_of_replicas`. Previously, the docs stated that you could safely ignore archived index settings.

Relates elastic#78351

Closes elastic#61175
  • Loading branch information
jrodewig authored Jan 26, 2022
1 parent 444f716 commit 47d45d0
Showing 1 changed file with 25 additions and 16 deletions.
41 changes: 25 additions & 16 deletions docs/reference/upgrade/archived-settings.asciidoc
Original file line number Diff line number Diff line change
@@ -1,28 +1,32 @@
[[archived-settings]]
== Archived settings

{es} typically removes support for deprecated settings at major version
releases. If you upgrade a cluster with a deprecated persistent cluster setting
to a version that no longer supports the setting, {es} automatically archives
that setting. Similarly, if you upgrade a cluster that contains an index with an
If you upgrade a cluster with a deprecated persistent cluster setting to a
version that no longer supports the setting, {es} automatically archives that
setting. Similarly, if you upgrade a cluster that contains an index with an
unsupported index setting, {es} archives the index setting.

Archived settings start with the `archived.` prefix and are ignored by {es}.
We recommend you remove any archived settings after upgrading. Archived
settings are considered invalid and can interfere with your ability to configure
other settings.

Archived settings start with the `archived.` prefix.

[discrete]
[[archived-cluster-settings]]
=== Archived cluster settings

After an upgrade, you can view archived cluster settings using the
<<cluster-get-settings,cluster get settings API>>.
Use the following <<cluster-update-settings,cluster update settings>> request to
check for archived cluster settings. If the request returns an empty object
(`{ }`), there are no archived cluster settings.

[source,console]
----
GET _cluster/settings?flat_settings=true&filter_path=persistent.archived*
----

You can remove archived cluster settings using the
<<cluster-update-settings,cluster update settings API>>.
To remove any archived cluster settings, use the following
<<cluster-update-settings,cluster update settings>> request.

[source,console]
----
Expand All @@ -48,18 +52,23 @@ templates during an upgrade. Attempts to use a template that contains an
unsupported index setting will fail and return an error. This includes automated
operations, such the {ilm-init} rollover action.

You can view archived settings for an index using the <<indices-get-settings,get
index settings API>>.
Archived index settings don't affect an index's configuration or most index
operations, such as indexing or search. However, you'll need to remove them
before you can configure other settings for the index, such as `index.hidden`.

Use the following <<indices-get-settings,get index settings>> request to get a
list indices with archived settings. If the request returns an empty object
(`{ }`), there are no archived index settings.

[source,console]
----
GET my-index/_settings?flat_settings=true&filter_path=**.settings.archived*
GET */_settings?flat_settings=true&filter_path=**.settings.archived*
----
// TEST[s/^/PUT my-index\n/]

Removing archived index settings requires a reindex after the upgrade. However,
reindexing can be resource intensive. Because {es} ignores archived settings,
you can safely leave them in place if wanted.
Removing an index's archived index settings requires a <<docs-reindex,reindex>>.
Reindexing can be resource-intensive and time-consuming. Before you start, test
the reindex with a subset of the data to estimate your time requirements.

[source,console]
----
Expand All @@ -69,7 +78,7 @@ POST _reindex
"index": "my-index"
},
"dest": {
"index": "reindexed-v8-my-index"
"index": "reindexed-my-index"
}
}
----
Expand Down

0 comments on commit 47d45d0

Please sign in to comment.