Browse Source

[DOCS] Archived settings block config updates (#82069)

**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
James Rodewig 3 years ago
parent
commit
47d45d0a14
1 changed files with 25 additions and 16 deletions
  1. 25 16
      docs/reference/upgrade/archived-settings.asciidoc

+ 25 - 16
docs/reference/upgrade/archived-settings.asciidoc

@@ -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]
 ----
@@ -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]
 ----
@@ -69,7 +78,7 @@ POST _reindex
     "index": "my-index"
   },
   "dest": {
-    "index": "reindexed-v8-my-index"
+    "index": "reindexed-my-index"
   }
 }
 ----