Warn of change of default of wait_for_active_shards

In 7.x the close indices API defaults to `?wait_for_active_shards=0` but
from 8.0 it will default to respecting the index settings instead. This
commit introduces the `index-setting` value for this parameter on this
API allowing users to opt-in to the future behaviour today, and starts
to emit a deprecation warning for users that use the default.

Relates elastic#67158
Closes elastic#66419

Author: DaveCTurner

docs/reference/indices/close.asciidoc

@@ -52,7 +52,18 @@ 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=wait_for_active_shards]
+`wait_for_active_shards`::
++
+--
+(Optional, string) The number of shard copies that must be active before
+proceeding with the operation. Set to `all`, `index-setting`, or any positive
+integer up to the total number of shards in the index (`number_of_replicas+1`).
+The value `index-setting` means to wait according to the index setting
+`index.write.wait_for_active_shards`. Default: `0`, meaning do not wait for any
+shards to be ready.
+
+See <<index-wait-for-active-shards>>.
+--
 
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
 

plugins/repository-hdfs/src/test/resources/rest-api-spec/test/hdfs_repository/40_restore.yml

@@ -46,6 +46,7 @@
   # Close index
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index : test_index
 
   # Restore index

plugins/repository-hdfs/src/test/resources/rest-api-spec/test/secure_hdfs_repository/40_restore.yml

@@ -48,6 +48,7 @@
   # Close index
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index : test_index
 
   # Restore index

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

@@ -56,7 +56,7 @@
       },
       "wait_for_active_shards":{
         "type":"string",
-        "description":"Sets the number of active shards to wait for before the operation returns."
+        "description":"Sets the number of active shards to wait for before the operation returns. Set to `index-setting` to wait according to the index setting `index.write.wait_for_active_shards`, or `all` to wait for all shards, or an integer. Defaults to `0`."
       }
     }
   }

rest-api-spec/src/main/resources/rest-api-spec/test/cat.aliases/10_basic.yml

@@ -398,6 +398,7 @@
 
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: test_index
 
   - do:
@@ -431,6 +432,7 @@
 
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: test_index
 
   - do:

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

@@ -65,6 +65,7 @@
 
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: index-2
   - is_true: acknowledged
 
@@ -106,6 +107,7 @@
 
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: index-2
   - is_true: acknowledged
 
@@ -248,6 +250,7 @@
 
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: bar
 
   - do:

rest-api-spec/src/main/resources/rest-api-spec/test/cat.recovery/10_basic.yml

@@ -92,6 +92,7 @@
 
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: index2
   - is_true: acknowledged
 

rest-api-spec/src/main/resources/rest-api-spec/test/cat.segments/10_basic.yml

@@ -94,6 +94,7 @@
 
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: index1
 
   - do:

rest-api-spec/src/main/resources/rest-api-spec/test/cluster.allocation_explain/10_basic.yml

@@ -67,6 +67,7 @@
 
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: test_closed
 
   - match: { acknowledged: true }

rest-api-spec/src/main/resources/rest-api-spec/test/cluster.health/10_basic.yml

@@ -182,6 +182,7 @@
 
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: index-2
   - is_true: acknowledged
 
@@ -257,6 +258,7 @@
   # closing the index-2 does not change the cluster health with replicated closed indices
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: index-2
   - is_true: acknowledged
 

rest-api-spec/src/main/resources/rest-api-spec/test/cluster.health/30_indices_options.yml

@@ -22,6 +22,7 @@ setup:
 
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: index-2
 
   - do:

rest-api-spec/src/main/resources/rest-api-spec/test/cluster.state/30_expand_wildcards.yml

@@ -24,6 +24,7 @@ setup:
 
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: test_close_index
 
 ---

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

@@ -37,6 +37,7 @@ setup:
 
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: test_index_3
 
   - do:

rest-api-spec/src/main/resources/rest-api-spec/test/indices.get/11_basic_with_types.yml

@@ -36,6 +36,7 @@ setup:
 
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: test_index_3
 
   - do:

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

@@ -306,6 +306,7 @@ setup:
 
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: test_index_2
 
   - do:

rest-api-spec/src/main/resources/rest-api-spec/test/indices.get_mapping/50_wildcard_expansion.yml

@@ -51,6 +51,7 @@ setup:
 
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: test-xyy
 
   - do:

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

@@ -13,6 +13,7 @@
 
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: test_index
   - is_true: acknowledged
 
@@ -51,6 +52,7 @@
 
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: test_index
   - is_true: acknowledged
 
@@ -111,10 +113,54 @@
 
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: "index_*"
 
   - match: { acknowledged: true }
   - match: { shards_acknowledged: true }
   - match: { indices.index_1.closed: true }
   - match: { indices.index_2.closed: true }
   - match: { indices.index_3.closed: true }
+
+---
+"?wait_for_active_shards=index-setting":
+  - skip:
+      version: " - 7.11.99"
+      reason: "?wait_for_active_shards=index-setting support added in 7.12"
+      features: ["node_selector"]
+
+  - do:
+      indices.create:
+        index: index_1
+        body:
+          settings:
+            number_of_replicas: 0
+
+  - do:
+      indices.close:
+        index: "index_*"
+        wait_for_active_shards: "index-setting"
+      node_selector:
+        version: "7.12.0 - "
+
+---
+"?wait_for_active_shards default is deprecated":
+  - skip:
+      version: " - 7.11.99"
+      reason: "required deprecation warning is only emitted in 7.12 and later"
+      features: ["warnings", "node_selector"]
+
+  - do:
+      indices.create:
+        index: index_1
+        body:
+          settings:
+            number_of_replicas: 0
+
+  - do:
+      indices.close:
+        index: "index_*"
+      node_selector:
+        version: "7.12.0 - "
+      warnings:
+        - "the default value for the ?wait_for_active_shards parameter will change from '0' to 'index-setting' in version 8; specify '?wait_for_active_shards=index-setting' to adopt the future default behaviour, or '?wait_for_active_shards=0' to preserve today's behaviour"

rest-api-spec/src/main/resources/rest-api-spec/test/indices.open/20_multiple_indices.yml

@@ -25,6 +25,7 @@ setup:
 "All indices":
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: _all
   - is_true: acknowledged
 
@@ -52,6 +53,7 @@ setup:
 "Trailing wildcard":
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: test_*
   - is_true: acknowledged
 
@@ -79,6 +81,7 @@ setup:
 "Only wildcard":
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: '*'
   - is_true: acknowledged
 

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

@@ -88,6 +88,7 @@ setup:
 
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: test-index
 
   - do:

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

@@ -55,6 +55,7 @@
 
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: test_2
   - is_true: acknowledged
 

rest-api-spec/src/main/resources/rest-api-spec/test/indices.resolve_index/10_basic_resolve_index.yml

@@ -23,6 +23,7 @@ setup:
 
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: test_index2
 
   - do:

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

@@ -59,6 +59,7 @@
 
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: index1
 
   - do:

rest-api-spec/src/main/resources/rest-api-spec/test/search/80_indices_options.yml

@@ -33,6 +33,7 @@
 
   - do:
       indices.close:
+          wait_for_active_shards: 0
           index:  index_closed
 
   - do:

rest-api-spec/src/main/resources/rest-api-spec/test/snapshot.restore/10_basic.yml

@@ -39,6 +39,7 @@ setup:
 
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index : test_index
 
   - do:

server/src/main/java/org/elasticsearch/rest/action/admin/indices/RestCloseIndexAction.java

@@ -24,6 +24,7 @@
 import org.elasticsearch.action.support.IndicesOptions;
 import org.elasticsearch.client.node.NodeClient;
 import org.elasticsearch.common.Strings;
+import org.elasticsearch.common.logging.DeprecationLogger;
 import org.elasticsearch.rest.BaseRestHandler;
 import org.elasticsearch.rest.RestRequest;
 import org.elasticsearch.rest.action.RestToXContentListener;
@@ -37,6 +38,8 @@
 
 public class RestCloseIndexAction extends BaseRestHandler {
 
+    private static final DeprecationLogger deprecationLogger = DeprecationLogger.getLogger(RestCloseIndexAction.class);
+
     @Override
     public List<Route> routes() {
         return unmodifiableList(asList(
@@ -56,7 +59,13 @@ public RestChannelConsumer prepareRequest(final RestRequest request, final NodeC
         closeIndexRequest.timeout(request.paramAsTime("timeout", closeIndexRequest.timeout()));
         closeIndexRequest.indicesOptions(IndicesOptions.fromRequest(request, closeIndexRequest.indicesOptions()));
         String waitForActiveShards = request.param("wait_for_active_shards");
-        if (waitForActiveShards != null) {
+        if (waitForActiveShards == null) {
+            deprecationLogger.deprecate("close-index-wait_for_active_shards-default", "the default value for the ?wait_for_active_shards " +
+                    "parameter will change from '0' to 'index-setting' in version 8; specify '?wait_for_active_shards=index-setting' " +
+                    "to adopt the future default behaviour, or '?wait_for_active_shards=0' to preserve today's behaviour");
+        } else if ("index-setting".equalsIgnoreCase(waitForActiveShards)) {
+            closeIndexRequest.waitForActiveShards(ActiveShardCount.DEFAULT);
+        } else {
             closeIndexRequest.waitForActiveShards(ActiveShardCount.parseString(waitForActiveShards));
         }
         return channel -> client.admin().indices().close(closeIndexRequest, new RestToXContentListener<>(channel));

test/framework/src/main/java/org/elasticsearch/test/rest/ESRestTestCase.java

@@ -1256,8 +1256,9 @@ protected static boolean indexExists(String index) throws IOException {
     }
 
     protected static void closeIndex(String index) throws IOException {
-        Response response = client().performRequest(new Request("POST", "/" + index + "/_close"));
-        assertThat(response.getStatusLine().getStatusCode(), equalTo(RestStatus.OK.getStatus()));
+        final Request closeRequest = new Request("POST", "/" + index + "/_close");
+        closeRequest.addParameter("wait_for_active_shards", "0");
+        assertOK(client().performRequest(closeRequest));
     }
 
     protected static void openIndex(String index) throws IOException {

x-pack/plugin/ccr/qa/rest/src/yamlRestTest/resources/rest-api-spec/test/ccr/follow_and_unfollow.yml

@@ -61,6 +61,7 @@
 
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: bar
   - is_true: acknowledged
 

x-pack/plugin/ccr/qa/rest/src/yamlRestTest/resources/rest-api-spec/test/ccr/forget_follower.yml

@@ -71,6 +71,7 @@
 
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: follower_index
   - is_true: acknowledged
 

x-pack/plugin/ccr/qa/rest/src/yamlRestTest/resources/rest-api-spec/test/ccr/index_directly_into_follower_index.yml

@@ -57,6 +57,7 @@
 
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: bar
   - is_true: acknowledged
 

x-pack/plugin/src/test/resources/rest-api-spec/test/data_stream/20_unsupported_apis.yml

@@ -44,6 +44,7 @@
   # close request will not fail but will not match any data streams
   - do:
       indices.close:
+        wait_for_active_shards: 0
         index: logs-*
   - is_true: acknowledged
   - length: { indices: 0 }
@@ -164,6 +165,7 @@
   - do:
       catch: bad_request
       indices.close:
+        wait_for_active_shards: 0
         index: ".ds-simple-data-stream1-*000001"
 
   - do: