elasticsearch/docs/reference/upgrade/archived-settings.asciidoc

[[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
unsupported index setting, {es} archives the index setting.

Archived settings start with the `archived.` prefix and are ignored by {es}.

[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>>.

[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>>.

[source,console]
----
PUT _cluster/settings
{
  "persistent": {
    "archived.*": null
  }
}
----

{es} doesn't archive transient cluster settings or settings in
`elasticsearch.yml`. If a node includes an unsupported setting in
`elasticsearch.yml`, it will return an error at startup.

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

IMPORTANT: Before you upgrade, remove any unsupported index settings from index
and component templates. {es} doesn't archive unsupported index settings in
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>>.

[source,console]
----
GET my-index/_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.

[source,console]
----
POST _reindex
{
  "source": {
    "index": "my-index"
  },
  "dest": {
    "index": "reindexed-v8-my-index"
  }
}
----
// TEST[s/^/PUT my-index\n/]