[DOCS] Add transient settings migration guide (#80091) (#80272)

Changes:

* Adds a transient settings migration guide to the 7.16 docs.
* Updates the related deprecation docs to link to the guide.

Closes #80055

Relates to #79167.

docs/reference/cluster/update-settings.asciidoc

@@ -48,8 +48,9 @@ PUT /_cluster/settings
 
 An example of a transient update:
 
-NOTE: Transient settings are deprecated and will be removed in a future release.
-Use persistent cluster settings instead.
+// tag::transient-settings-deprecation[]
+deprecated::[7.16,Transient settings are deprecated and will be removed in a future release. Use persistent cluster settings instead. See the <<transient-settings-migration-guide>>.]
+// end::transient-settings-deprecation[]
 
 [source,console]
 --------------------------------------------------

docs/reference/migration/migrate_8_0.asciidoc

@@ -145,9 +145,7 @@ include::migrate_8_0/threadpool.asciidoc[]
 include::migrate_8_0/transform.asciidoc[]
 include::migrate_8_0/transport.asciidoc[]
 include::migrate_8_0/watcher.asciidoc[]
-include::migrate_8_0/migrate_to_java_time.asciidoc[]
 
-////
 [discrete]
 [[deprecated-8.0]]
 === Deprecations
@@ -162,4 +160,29 @@ NOTE: Significant changes in behavior are deprecated in a minor release and
 the old behavior is supported until the next major release.
 To find out if you are using any deprecated functionality,
 enable <<deprecation-logging, deprecation logging>>.
-////
+
+[discrete]
+[[breaking_80_settings_deprecations]]
+==== Settings deprecations
+
+[[deprecate-transient-cluster-settings]]
+.Transient cluster settings are deprecated.
+[%collapsible]
+====
+*Details* +
+Starting in 7.16, transient cluster settings are deprecated and will be removed in a future release. This is because transient
+cluster settings have an unpredictable lifecycle. Transient cluster settings do not survive full cluster restarts or
+cluster instability. In these cases, {es} recovers the cluster state
+from persistent storage, effectively erasing the transient settings. The loss of transient settings can happen
+unexpectedly, leading to a potentially undesired cluster configuration.
+
+*Impact* +
+To avoid deprecation warnings, discontinue use of transient settings when modifying
+your cluster settings through the `PUT _cluster/settings` REST API. Use persistent
+settings instead. See the
+{ref}/transient-settings-migration-guide.html[Transient settings migration
+guide]. 
+====
+
+include::migrate_8_0/migrate_to_java_time.asciidoc[]
+include::transient-settings-migration-guide.asciidoc[]

docs/reference/migration/transient-settings-migration-guide.asciidoc

@@ -0,0 +1,120 @@
+[[transient-settings-migration-guide]]
+=== Transient settings migration guide
+
+////
+[source,console]
+----
+PUT _cluster/settings
+{
+  "transient": {
+    "cluster.indices.close.enable": false,
+    "indices.recovery.max_bytes_per_sec": "50mb"
+  }
+}
+----
+// TEST[warning:[transient settings removal] Updating cluster settings through transientSettings is deprecated. Use persistent settings instead.]
+////
+
+Transient cluster settings are deprecated. Previously, you could use transient
+settings to make temporary configuration changes to a cluster. However, a
+cluster restart or cluster instability can unexpectedly clear these settings,
+leading to a potentially undesired cluster configuration.
+
+To avoid deprecation warnings, reset any transient settings you've configured on
+your cluster. Convert any transient setting you'd like to keep to a persistent
+setting, which persists across cluster restarts and cluster instability. You
+should also update any custom workflows and applications to use persistent
+settings instead of transient settings.
+
+IMPORTANT: Some Elastic products may use transient settings when performing
+specific operations. Only reset transient settings configured by you, your
+users, or your custom workflows and applications.
+
+To reset and convert transient settings:
+
+. Get a list of any configured transient settings using the
+<<cluster-get-settings,cluster get settings API>>.
++
+[source,console]
+----
+GET _cluster/settings?flat_settings=true&filter_path=transient
+----
+// TEST[continued]
++
+The API returns transient settings in the `transient` object. If this object is
+empty, your cluster has no transient settings, and you can skip the remaining
+steps.
++
+[source,console-result]
+----
+{
+  "persistent": { ... },
+  "transient": {
+    "cluster.indices.close.enable": "false",
+    "indices.recovery.max_bytes_per_sec": "50mb"
+  }
+}
+----
+// TESTRESPONSE[s/"persistent": \{ \.\.\. \},//]
+
+. Copy any settings you'd like to convert into the `persistent` object of a
+<<cluster-update-settings,cluster update settings API>> request. In the same
+request, reset any transient settings by assigning them a `null` value.
++
+NOTE: Resetting transient settings will emit a deprecation warning.
++
+[source,console]
+----
+PUT _cluster/settings
+{
+  "persistent": {
+    "cluster.indices.close.enable": false,
+    "indices.recovery.max_bytes_per_sec": "50mb"
+  },
+  "transient": {
+    "*": null
+  }
+}
+----
+// TEST[continued]
+// TEST[warning:[transient settings removal] Updating cluster settings through transientSettings is deprecated. Use persistent settings instead.]
+
+. Use the <<cluster-get-settings,cluster get settings API>> to confirm your
+cluster has no remaining transient settings.
++
+[source,console]
+----
+GET _cluster/settings?flat_settings=true
+----
+// TEST[continued]
++
+If the `transient` object is empty, your cluster has no transient settings.
++
+[source,console-result]
+----
+{
+  "persistent": {
+    "cluster.indices.close.enable": "false",
+    "indices.recovery.max_bytes_per_sec": "50mb",
+    ...
+  },
+  "transient": {
+  }
+}
+----
+// TESTRESPONSE[s/"50mb",/"50mb"/]
+// TESTRESPONSE[s/\.\.\.//]
+
+////
+[source,console]
+----
+PUT _cluster/settings
+{
+  "persistent" : {
+    "cluster.indices.close.enable": null,
+    "indices.recovery.max_bytes_per_sec": null
+  }
+}
+----
+// TEST[continued]
+////

docs/reference/setup/configuration.asciidoc

@@ -148,8 +148,7 @@ doesn't require a restart and ensures a setting's value is the same on all
 nodes.
 ====
 
-NOTE: Transient settings are deprecated and will be removed in a future release.
-Use persistent cluster settings instead.
+include::{es-repo-dir}/cluster/update-settings.asciidoc[tag=transient-settings-deprecation]
 --
 
 [[static-cluster-setting]]