From 9e2e6646ee44577efee881e460fe232ea2200cf3 Mon Sep 17 00:00:00 2001
From: Lee Hinman <dakrone@users.noreply.github.com>
Date: Wed, 6 Mar 2024 18:07:21 +0100
Subject: [PATCH] Use index block API in shrink/split/clone docs (#105997)
 (#106035)

This uses the dedicated index block API in the docs for the shrink, split, and clone APIs, rather than putting the block in as a setting directly. The specialized API will wait for ongoing operations to finish, which is better during indexing operations.

Resolves #105831
---
 docs/reference/indices/clone-index.asciidoc  | 10 +++-------
 docs/reference/indices/shrink-index.asciidoc | 18 +++++++++++-------
 docs/reference/indices/split-index.asciidoc  | 14 +++-----------
 3 files changed, 17 insertions(+), 25 deletions(-)

diff --git a/docs/reference/indices/clone-index.asciidoc b/docs/reference/indices/clone-index.asciidoc
index 748b3adddd528..ef8ed28c6ac05 100644
--- a/docs/reference/indices/clone-index.asciidoc
+++ b/docs/reference/indices/clone-index.asciidoc
@@ -31,17 +31,13 @@ POST /my-index-000001/_clone/cloned-my-index-000001
 
 For example,
 the following request prevents write operations on `my_source_index`
-so it can be cloned.
+so it can be cloned using the
+<<add-index-block,add index block>> API.
 Metadata changes like deleting the index are still allowed.
 
 [source,console]
 --------------------------------------------------
-PUT /my_source_index/_settings
-{
-  "settings": {
-    "index.blocks.write": true
-  }
-}
+PUT /my_source_index/_block/write
 --------------------------------------------------
 // TEST[s/^/PUT my_source_index\n/]
 
diff --git a/docs/reference/indices/shrink-index.asciidoc b/docs/reference/indices/shrink-index.asciidoc
index 388344123b964..5d5e6c24d9e83 100644
--- a/docs/reference/indices/shrink-index.asciidoc
+++ b/docs/reference/indices/shrink-index.asciidoc
@@ -39,8 +39,8 @@ replica shards. You can later re-add replica shards as part of the shrink
 operation.
 
 You can use the following <<indices-update-settings,update index settings API>>
-request to remove an index's replica shards, relocates the index's remaining
-shards to the same node, and make the index read-only.
+request to remove an index's replica shards, and relocate the index's remaining
+shards to the same node.
 
 [source,console]
 --------------------------------------------------
@@ -48,8 +48,7 @@ PUT /my_source_index/_settings
 {
   "settings": {
     "index.number_of_replicas": 0,                                <1>
-    "index.routing.allocation.require._name": "shrink_node_name", <2>
-    "index.blocks.write": true                                    <3>
+    "index.routing.allocation.require._name": "shrink_node_name"  <2>
   }
 }
 --------------------------------------------------
@@ -58,15 +57,20 @@ PUT /my_source_index/_settings
 <1> Removes replica shards for the index.
 <2> Relocates the index's shards to the `shrink_node_name` node.
     See <<shard-allocation-filtering>>.
-<3> Prevents write operations to this index. Metadata changes, such as deleting
-    the index, are still allowed.
-
 
 It can take a while to relocate the source index. Progress can be tracked
 with the <<cat-recovery,`_cat recovery` API>>, or the <<cluster-health,
 `cluster health` API>> can be used to wait until all shards have relocated
 with the `wait_for_no_relocating_shards` parameter.
 
+You can then make the index read-only with the following request using the
+<<add-index-block,add index block>> API:
+
+[source,console]
+--------------------------------------------------
+PUT /my_source_index/_block/write
+--------------------------------------------------
+// TEST[continued]
 
 [[shrink-index-api-desc]]
 ==== {api-description-title}
diff --git a/docs/reference/indices/split-index.asciidoc b/docs/reference/indices/split-index.asciidoc
index 06f048856348e..26ae0f19b177c 100644
--- a/docs/reference/indices/split-index.asciidoc
+++ b/docs/reference/indices/split-index.asciidoc
@@ -37,23 +37,15 @@ POST /my-index-000001/_split/split-my-index-000001
 ** The index must be read-only.
 ** The <<cluster-health, cluster health>> status must be green.
 
-You can do make an index read-only
-with the following request:
+You can do make an index read-only with the following request using the
+<<add-index-block,add index block>> API:
 
 [source,console]
 --------------------------------------------------
-PUT /my_source_index/_settings
-{
-  "settings": {
-    "index.blocks.write": true <1>
-  }
-}
+PUT /my_source_index/_block/write
 --------------------------------------------------
 // TEST[s/^/PUT my_source_index\n/]
 
-<1> Prevents write operations to this index while still allowing metadata
-    changes like deleting the index.
-
 The current write index on a data stream cannot be split. In order to split
 the current write index, the data stream must first be
 <<data-streams-rollover,rolled over>> so that a new write index is created