Add index block api (elastic#58094)

Adds an API for putting an index block in place, which also ensures for write blocks that, once successfully returning to
the user, all shards of the index are properly accounting for the block, for example that all in-flight writes to an index have
been completed after adding the write block.

This API allows coordinating more complex workflows, where it is crucial that an index is no longer receiving writes after
the API completes, useful for example when marking an index as read-only during an upgrade in order to reindex its
documents.

client/rest-high-level/src/test/java/org/elasticsearch/client/RestHighLevelClientTests.java

@@ -802,7 +802,8 @@ public void testApiNamingConventions() throws Exception {
             "render_search_template",
             "scripts_painless_execute",
             "indices.simulate_template",
-            "indices.resolve_index"
+            "indices.resolve_index",
+            "indices.add_block"
         };
         //These API are not required for high-level client feature completeness
         String[] notRequiredApi = new String[] {

docs/reference/index-modules.asciidoc

@@ -173,35 +173,6 @@ specific index module:
     for the <<analysis-shingle-tokenfilter,`shingle` token filter>>. Defaults to
     `3`.
 
-`index.blocks.read_only`::
-
-    Set to `true` to make the index and index metadata read only, `false` to
-    allow writes and metadata changes.
-
-`index.blocks.read_only_allow_delete`::
-
-    Similar to `index.blocks.read_only`, but also allows deleting the index to
-    make more resources available. The <<shard-allocation-awareness,disk-based shard
-    allocator>> may add and remove this block automatically.
-
-Deleting documents from an index to release resources - rather than deleting the index itself - can increase the index size over time. When `index.blocks.read_only_allow_delete` is set to `true`, deleting documents is not permitted. However, deleting the index itself releases the read-only index block and makes resources available almost immediately.
-
-IMPORTANT: {es} adds and removes the read-only index block automatically when the disk utilization falls below the high watermark, controlled by <<cluster-routing-flood_stage,cluster.routing.allocation.disk.watermark.flood_stage>>.
-
-`index.blocks.read`::
-
-    Set to `true` to disable read operations against the index.
-
-`index.blocks.write`::
-
-    Set to `true` to disable data write operations against the index. Unlike `read_only`,
-    this setting does not affect metadata. For instance, you can close an index with a `write`
-    block, but not an index with a `read_only` block.
-
-`index.blocks.metadata`::
-
-    Set to `true` to disable index metadata reads and writes.
-
 `index.max_refresh_listeners`::
 
     Maximum number of refresh listeners available on each shard of the index.
@@ -321,6 +292,8 @@ include::index-modules/analysis.asciidoc[]
 
 include::index-modules/allocation.asciidoc[]
 
+include::index-modules/blocks.asciidoc[]
+
 include::index-modules/mapper.asciidoc[]
 
 include::index-modules/merge.asciidoc[]

docs/reference/index-modules/blocks.asciidoc

@@ -0,0 +1,146 @@
+[[index-modules-blocks]]
+== Index blocks
+
+Index blocks limit the kind of operations that are available on a certain
+index. The blocks come in different flavours, allowing to block write,
+read, or metadata operations. The blocks can be set / removed using dynamic
+index settings, or can be added using a dedicated API, which also ensures
+for write blocks that, once successfully returning to the user, all shards
+of the index are properly accounting for the block, for example that all
+in-flight writes to an index have been completed after adding the write
+block.
+
+[discrete]
+[[index-block-settings]]
+=== Index block settings
+
+The following _dynamic_ index settings determine the blocks present on an
+index:
+
+`index.blocks.read_only`::
+
+    Set to `true` to make the index and index metadata read only, `false` to
+    allow writes and metadata changes.
+
+`index.blocks.read_only_allow_delete`::
+
+    Similar to `index.blocks.read_only`, but also allows deleting the index to
+    make more resources available. The <<shard-allocation-awareness,disk-based shard
+    allocator>> may add and remove this block automatically.
+
+Deleting documents from an index to release resources - rather than deleting the index itself - can increase the index size over time. When `index.blocks.read_only_allow_delete` is set to `true`, deleting documents is not permitted. However, deleting the index itself releases the read-only index block and makes resources available almost immediately.
+
+IMPORTANT: {es} adds and removes the read-only index block automatically when the disk utilization falls below the high watermark, controlled by <<cluster-routing-flood_stage,cluster.routing.allocation.disk.watermark.flood_stage>>.
+
+`index.blocks.read`::
+
+    Set to `true` to disable read operations against the index.
+
+`index.blocks.write`::
+
+    Set to `true` to disable data write operations against the index. Unlike `read_only`,
+    this setting does not affect metadata. For instance, you can close an index with a `write`
+    block, but not an index with a `read_only` block.
+
+`index.blocks.metadata`::
+
+    Set to `true` to disable index metadata reads and writes.
+
+[discrete]
+[[add-index-block]]
+=== Add index block API
+
+Adds an index block to an index.
+
+[source,console]
+--------------------------------------------------
+PUT /twitter/_block/write
+--------------------------------------------------
+// TEST[setup:twitter]
+
+
+[discrete]
+[[add-index-block-api-request]]
+==== {api-request-title}
+
+`PUT /<index>/_block/<block>`
+
+
+[discrete]
+[role="child_attributes"]
+[[add-index-block-api-path-params]]
+==== {api-path-parms-title}
+
+include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index]
++
+To add blocks to all indices, use `_all` or `*`. To disallow the adding
+of blocks to indices with `_all` or wildcard expressions,
+change the `action.destructive_requires_name` cluster setting to `true`.
+You can update this setting in the `elasticsearch.yml` file
+or using the <<cluster-update-settings,cluster update settings>> API.
+`<block>`::
+(Required, string)
+Block type to add to the index.
++
+.Valid values for `<block>`
+[%collapsible%open]
+====
+`metadata`::
+Disable metadata changes, such as closing the index.
+
+`read`::
+Disable read operations.
+
+`read_only`::
+Disable write operations and metadata changes.
+
+`read_only_allow_delete`::
+Disable write operations and metadata changes.
+Document deletion is disabled.
+However, index deletion is still allowed.
+
+`write`::
+Disable write operations. However, metadata changes are still allowed.
+====
+[discrete]
+[[add-index-block-api-query-params]]
+==== {api-query-parms-title}
+
+include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
++
+Defaults to `true`.
+
+include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
++
+Defaults to `open`.
+
+include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
+
+include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
+
+[discrete]
+[[add-index-block-api-example]]
+==== {api-examples-title}
+
+The following example shows how to add an index block:
+
+[source,console]
+--------------------------------------------------
+PUT /my_index/_block/write
+--------------------------------------------------
+// TEST[s/^/PUT my_index\n/]
+
+The API returns following response:
+
+[source,console-result]
+--------------------------------------------------
+{
+    "acknowledged" : true,
+    "shards_acknowledged" : true,
+    "indices" : [ {
+        "name" : "my_index",
+        "blocked" : true
+    } ]
+}
+--------------------------------------------------
+

docs/reference/indices/open-close.asciidoc

@@ -61,13 +61,20 @@ the current write index, the data stream must first be
 <<rollover-data-stream-ex,rolled over>> so that a new write index is created
 and then the previous write index can be closed.
 
+// end::closed-index[]
+
+[[open-index-api-wait-for-active-shards]]
 ===== Wait For active shards
 
+// tag::wait-for-active-shards[]
+
 Because opening or closing an index allocates its shards, the
 <<create-index-wait-for-active-shards,`wait_for_active_shards`>> setting on
 index creation applies to the `_open` and `_close` index actions as well.
 
-// end::closed-index[]
+// end::wait-for-active-shards[]
+
+
 
 
 [[open-index-api-path-params]]

rest-api-spec/src/main/resources/rest-api-spec/api/indices.add_block.json

@@ -0,0 +1,59 @@
+{
+  "indices.add_block":{
+    "documentation":{
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-blocks.html",
+      "description":"Adds a block to an index."
+    },
+    "stability":"stable",
+    "url":{
+      "paths":[
+        {
+          "path":"/{index}/_block/{block}",
+          "methods":[
+            "PUT"
+          ],
+          "parts":{
+            "index":{
+              "type":"list",
+              "description":"A comma separated list of indices to add a block to"
+            },
+            "block":{
+              "type":"string",
+              "description":"The block to add (one of read, write, read_only, metadata, read_only_allow_delete)"
+            }
+          }
+        }
+      ]
+    },
+    "params":{
+      "timeout":{
+        "type":"time",
+        "description":"Explicit operation timeout"
+      },
+      "master_timeout":{
+        "type":"time",
+        "description":"Specify timeout for connection to master"
+      },
+      "ignore_unavailable":{
+        "type":"boolean",
+        "description":"Whether specified concrete indices should be ignored when unavailable (missing or closed)"
+      },
+      "allow_no_indices":{
+        "type":"boolean",
+        "description":"Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices have been specified)"
+      },
+      "expand_wildcards":{
+        "type":"enum",
+        "options":[
+          "open",
+          "closed",
+          "hidden",
+          "none",
+          "all"
+        ],
+        "default":"open",
+        "description":"Whether to expand wildcard expression to concrete indices that are open, closed or both."
+      }
+    }
+  }
+}

rest-api-spec/src/main/resources/rest-api-spec/test/indices.blocks/10_basic.yml

@@ -0,0 +1,33 @@
+---
+"Basic test for index blocks":
+  - skip:
+      version: " - 7.8.99"
+      reason:  "index block APIs have only been made available in 7.9.0"
+  - do:
+      indices.create:
+        index: test_index
+        body:
+          settings:
+            number_of_replicas: 0
+
+  - do:
+      indices.add_block:
+        index: test_index
+        block: write
+  - is_true: acknowledged
+
+  - do:
+      catch: /cluster_block_exception/
+      index:
+        index:  test_index
+        body:   { foo: bar }
+
+  - do:
+      search:
+        index: test_index
+
+  - do:
+      indices.put_settings:
+        index: test_index
+        body:
+          index.blocks.write: false