From 007afb58fd0b1b466759e687a9742265f66372a5 Mon Sep 17 00:00:00 2001
From: Kostas Krikellas <kostas.krikellas@elastic.co>
Date: Mon, 10 Feb 2025 14:37:24 +0200
Subject: [PATCH 1/2] Troubleshoot source mode deprecation warnings

---
 docs/reference/troubleshooting.asciidoc       |  1 +
 .../data/source-mode-setting.asciidoc         | 52 +++++++++++++++++++
 2 files changed, 53 insertions(+)
 create mode 100644 docs/reference/troubleshooting/data/source-mode-setting.asciidoc

diff --git a/docs/reference/troubleshooting.asciidoc b/docs/reference/troubleshooting.asciidoc
index 75cd0c1be49fc..cf617ed25d099 100644
--- a/docs/reference/troubleshooting.asciidoc
+++ b/docs/reference/troubleshooting.asciidoc
@@ -25,6 +25,7 @@ If you're using Elastic Cloud Hosted, then you can use AutoOps to monitor your c
 * <<allow-all-cluster-allocation,Allow Elasticsearch to allocate the data in the system>>
 * <<allow-all-index-allocation,Allow Elasticsearch to allocate the index>>
 * <<troubleshoot-migrate-to-tiers,Indices mix index allocation filters with data tiers node roles to move through data tiers>>
+* <<troubleshoot-migrate-source-mode,Configuring source mode in mappings is deprecated and replaced by an index setting>>
 * <<increase-tier-capacity,Not enough nodes to allocate all shard replicas>>
 * <<increase-shard-limit,Total number of shards for an index on a single node exceeded>>
 * <<increase-cluster-shard-limit,Total number of shards per node has been reached>>
diff --git a/docs/reference/troubleshooting/data/source-mode-setting.asciidoc b/docs/reference/troubleshooting/data/source-mode-setting.asciidoc
new file mode 100644
index 0000000000000..22a1e7ba5a6cb
--- /dev/null
+++ b/docs/reference/troubleshooting/data/source-mode-setting.asciidoc
@@ -0,0 +1,52 @@
+[[troubleshoot-migrate-source-mode]]
+== Configuring source mode in mappings is deprecated and replaced by an index setting
+
+Index <<mapping-source-field,source>> mode was previously configured in mappings as follows:
+
+[source,js]
+----
+"mappings": {
+    "source": {
+        "mode": "synthetic"
+    },
+    "foo": {
+        "type": "keyword"
+    },
+    "bar": {
+        "type": "keyword"
+    }
+}
+----
+// NOTCONSOLE
+
+Starting with version 8.18, this method for configuring the source mode is considered
+deprecated and replaced by index setting `index.mapping.source.mode` that accepts the
+same values: `stored` (default), `synthetic` and `disabled`. The index setting can be
+used as follows:
+
+[source,js]
+----
+"settings": {
+    "index.mapping.source.mode": "synthetic"
+}
+"mappings": {
+    "foo": {
+        "type": "keyword"
+    },
+    "bar": {
+        "type": "keyword"
+    }
+}
+----
+// NOTCONSOLE
+
+Existing indexes using the deprecated method for configuring the source mode are not
+affected, but creating new indexes raises warnings and will not be supported in a future
+release. This can be an issue for data streams and other indexes that get regularly
+generated using component templates. To avoid these problems, identify all affected
+component templates, as shown in the <<migration-api-deprecation,deprecation info API>>,
+and update them to use setting `index.mapping.source.mode` instead of
+`mappings.source.mode`, according to the examples above.
+
+
+

From b70e4dad8a0c8d812d5dd62ab5ea78803b26cf74 Mon Sep 17 00:00:00 2001
From: Kostas Krikellas <kostas.krikellas@elastic.co>
Date: Mon, 10 Feb 2025 14:40:39 +0200
Subject: [PATCH 2/2] trim whitespace

---
 .../troubleshooting/data/source-mode-setting.asciidoc          | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/docs/reference/troubleshooting/data/source-mode-setting.asciidoc b/docs/reference/troubleshooting/data/source-mode-setting.asciidoc
index 22a1e7ba5a6cb..79c2d8d064d1c 100644
--- a/docs/reference/troubleshooting/data/source-mode-setting.asciidoc
+++ b/docs/reference/troubleshooting/data/source-mode-setting.asciidoc
@@ -47,6 +47,3 @@ generated using component templates. To avoid these problems, identify all affec
 component templates, as shown in the <<migration-api-deprecation,deprecation info API>>,
 and update them to use setting `index.mapping.source.mode` instead of
 `mappings.source.mode`, according to the examples above.
-
-
-