Skip to content

Commit 58bd2bc

Browse files
authored
[DOCS] Archived settings block config updates (#82069) (#83175)
**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 #78351 Closes #61175 (cherry picked from commit 47d45d0)
1 parent 370235a commit 58bd2bc

File tree

1 file changed

+25
-16
lines changed

1 file changed

+25
-16
lines changed

docs/reference/upgrade/archived-settings.asciidoc

Lines changed: 25 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,32 @@
11
[[archived-settings]]
22
== Archived settings
33

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

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

1215
[discrete]
1316
[[archived-cluster-settings]]
1417
=== Archived cluster settings
1518

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

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

24-
You can remove archived cluster settings using the
25-
<<cluster-update-settings,cluster update settings API>>.
28+
To remove any archived cluster settings, use the following
29+
<<cluster-update-settings,cluster update settings>> request.
2630

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

51-
You can view archived settings for an index using the <<indices-get-settings,get
52-
index settings API>>.
55+
Archived index settings don't affect an index's configuration or most index
56+
operations, such as indexing or search. However, you'll need to remove them
57+
before you can configure other settings for the index, such as `index.hidden`.
58+
59+
Use the following <<indices-get-settings,get index settings>> request to get a
60+
list indices with archived settings. If the request returns an empty object
61+
(`{ }`), there are no archived index settings.
5362

5463
[source,console]
5564
----
56-
GET my-index/_settings?flat_settings=true&filter_path=**.settings.archived*
65+
GET */_settings?flat_settings=true&filter_path=**.settings.archived*
5766
----
5867
// TEST[s/^/PUT my-index\n/]
5968

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

6473
[source,console]
6574
----
@@ -69,7 +78,7 @@ POST _reindex
6978
"index": "my-index"
7079
},
7180
"dest": {
72-
"index": "reindexed-v8-my-index"
81+
"index": "reindexed-my-index"
7382
}
7483
}
7584
----

0 commit comments

Comments
 (0)