Deprecate freeze index API (#72618)

Author: danhermann

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

@@ -139,6 +139,9 @@ public class IndicesClientIT extends ESRestHighLevelClientTestCase {
     public static final RequestOptions LEGACY_TEMPLATE_OPTIONS = RequestOptions.DEFAULT.toBuilder()
         .setWarningsHandler(warnings -> List.of(RestPutIndexTemplateAction.DEPRECATION_WARNING).equals(warnings) == false).build();
 
+    public static final String FROZEN_INDICES_DEPRECATION_WARNING = "Frozen indices are deprecated because they provide no benefit given " +
+        "improvements in heap memory utilization. They will be removed in a future release.";
+
     public void testIndicesExists() throws IOException {
         // Index present
         {
@@ -1530,13 +1533,16 @@ public void testFreezeAndUnfreeze() throws IOException {
         createIndex("test", Settings.EMPTY);
         RestHighLevelClient client = highLevelClient();
 
+        final RequestOptions freezeIndexOptions = RequestOptions.DEFAULT.toBuilder()
+            .setWarningsHandler(warnings -> List.of(FROZEN_INDICES_DEPRECATION_WARNING).equals(warnings) == false).build();
+
         ShardsAcknowledgedResponse freeze = execute(new FreezeIndexRequest("test"), client.indices()::freeze,
-            client.indices()::freezeAsync);
+            client.indices()::freezeAsync, freezeIndexOptions);
         assertTrue(freeze.isShardsAcknowledged());
         assertTrue(freeze.isAcknowledged());
 
         ShardsAcknowledgedResponse unfreeze = execute(new UnfreezeIndexRequest("test"), client.indices()::unfreeze,
-            client.indices()::unfreezeAsync);
+            client.indices()::unfreezeAsync, freezeIndexOptions);
         assertTrue(unfreeze.isShardsAcknowledged());
         assertTrue(unfreeze.isAcknowledged());
     }

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

@@ -107,6 +107,7 @@
 import java.util.concurrent.CountDownLatch;
 import java.util.concurrent.TimeUnit;
 
+import static org.elasticsearch.client.IndicesClientIT.FROZEN_INDICES_DEPRECATION_WARNING;
 import static org.elasticsearch.client.IndicesClientIT.LEGACY_TEMPLATE_OPTIONS;
 import static org.hamcrest.Matchers.containsInAnyOrder;
 import static org.hamcrest.Matchers.equalTo;
@@ -2885,8 +2886,11 @@ public void testFreezeIndex() throws Exception {
             request.setIndicesOptions(IndicesOptions.strictExpandOpen()); // <1>
             // end::freeze-index-request-indicesOptions
 
+            final RequestOptions freezeIndexOptions = RequestOptions.DEFAULT.toBuilder()
+                .setWarningsHandler(warnings -> List.of(FROZEN_INDICES_DEPRECATION_WARNING).equals(warnings) == false).build();
+
             // tag::freeze-index-execute
-            ShardsAcknowledgedResponse openIndexResponse = client.indices().freeze(request, RequestOptions.DEFAULT);
+            ShardsAcknowledgedResponse openIndexResponse = client.indices().freeze(request, freezeIndexOptions);
             // end::freeze-index-execute
 
             // tag::freeze-index-response
@@ -2964,7 +2968,9 @@ public void testUnfreezeIndex() throws Exception {
             // end::unfreeze-index-request-indicesOptions
 
             // tag::unfreeze-index-execute
-            ShardsAcknowledgedResponse openIndexResponse = client.indices().unfreeze(request, RequestOptions.DEFAULT);
+            final RequestOptions unfreezeIndexOptions = RequestOptions.DEFAULT.toBuilder()
+                .setWarningsHandler(warnings -> List.of(FROZEN_INDICES_DEPRECATION_WARNING).equals(warnings) == false).build();
+            ShardsAcknowledgedResponse openIndexResponse = client.indices().unfreeze(request, unfreezeIndexOptions);
             // end::unfreeze-index-execute
 
             // tag::unfreeze-index-response

docs/reference/indices/apis/freeze.asciidoc

@@ -57,5 +57,6 @@ The following example freezes and unfreezes an index:
 POST /my-index-000001/_freeze
 POST /my-index-000001/_unfreeze
 --------------------------------------------------
+// TEST[skip:unable to ignore deprecation warning]
 // TEST[s/^/PUT my-index-000001\n/]
 

docs/reference/indices/apis/unfreeze.asciidoc

@@ -22,7 +22,7 @@ Unfreezes an index.
 [[unfreeze-index-api-desc]]
 ==== {api-description-title}
 
-When a frozen index is unfrozen, the index goes through the normal recovery 
+When a frozen index is unfrozen, the index goes through the normal recovery
 process and becomes writeable again. See <<freeze-index-api>>.
 
 IMPORTANT: Freezing an index will close the index and reopen it within the same
@@ -47,3 +47,4 @@ POST /my-index-000001/_freeze
 POST /my-index-000001/_unfreeze
 --------------------------------------------------
 // TEST[s/^/PUT my-index-000001\n/]
+// TEST[skip:unable to ignore deprecation warning]

docs/reference/indices/resolve.asciidoc

@@ -49,6 +49,7 @@ DELETE /_index_template/foo_data_stream
 ----
 GET /_resolve/index/my-index-*
 ----
+// TEST[skip:unable to ignore deprecation warning]
 
 [[resolve-index-api-request]]
 ==== {api-request-title}

x-pack/plugin/build.gradle

@@ -103,6 +103,10 @@ tasks.named("yamlRestCompatTest").configure {
 
   //TODO: blacklist specific to REST API compatibility
   restTestBlacklist.addAll([
+    'indices.freeze/10_basic/Basic',
+    'indices.freeze/10_basic/Test index options',
+    'indices.freeze/20_stats/Translog stats on frozen indices',
+    'indices.freeze/30_usage/Usage stats on frozen indices',
     'license/30_enterprise_license/Installing enterprise license',
     'ml/data_frame_analytics_cat_apis/Test cat data frame analytics all jobs with header and column selection',
     'ml/data_frame_analytics_cat_apis/Test cat data frame analytics all jobs with header',

x-pack/plugin/frozen-indices/src/main/java/org/elasticsearch/xpack/frozen/rest/action/RestFreezeIndexAction.java

@@ -9,6 +9,7 @@
 import org.elasticsearch.action.support.ActiveShardCount;
 import org.elasticsearch.action.support.IndicesOptions;
 import org.elasticsearch.client.node.NodeClient;
+import org.elasticsearch.common.RestApiVersion;
 import org.elasticsearch.common.Strings;
 import org.elasticsearch.protocol.xpack.frozen.FreezeRequest;
 import org.elasticsearch.rest.BaseRestHandler;
@@ -22,11 +23,20 @@
 
 public final class RestFreezeIndexAction extends BaseRestHandler {
 
+    public static final String DEPRECATION_WARNING = "Frozen indices are deprecated because they provide no benefit given improvements " +
+        "in heap memory utilization. They will be removed in a future release.";
+    private static final RestApiVersion DEPRECATION_VERSION = RestApiVersion.V_8;
+
     @Override
     public List<Route> routes() {
         return List.of(
-            new Route(POST, "/{index}/_freeze"),
-            new Route(POST, "/{index}/_unfreeze"));
+            Route.builder(POST, "/{index}/_freeze")
+                .deprecated(DEPRECATION_WARNING, DEPRECATION_VERSION)
+                .build(),
+            Route.builder(POST, "/{index}/_unfreeze")
+                .deprecated(DEPRECATION_WARNING, DEPRECATION_VERSION)
+                .build()
+        );
     }
 
     @Override

x-pack/plugin/searchable-snapshots/src/test/java/org/elasticsearch/xpack/searchablesnapshots/AbstractSearchableSnapshotsRestTestCase.java

@@ -45,6 +45,9 @@
 
 public abstract class AbstractSearchableSnapshotsRestTestCase extends ESRestTestCase {
 
+    public static final String FROZEN_INDICES_WARNING = "Frozen indices are deprecated because they provide no benefit given "
+        + "improvements in heap memory utilization. They will be removed in a future release.";
+
     private static final String WRITE_REPOSITORY_NAME = "repository";
     private static final String READ_REPOSITORY_NAME = "read-repository";
     private static final String SNAPSHOT_NAME = "searchable-snapshot";
@@ -173,6 +176,7 @@ public void testSearchResults() throws Exception {
     public void testSearchResultsWhenFrozen() throws Exception {
         runSearchableSnapshotsTest((restoredIndexName, numDocs) -> {
             final Request freezeRequest = new Request(HttpPost.METHOD_NAME, restoredIndexName + "/_freeze");
+            freezeRequest.setOptions(expectWarnings(FROZEN_INDICES_WARNING));
             assertOK(client().performRequest(freezeRequest));
             ensureGreen(restoredIndexName);
             assertSearchResults(restoredIndexName, numDocs, Boolean.FALSE);
@@ -182,6 +186,7 @@ public void testSearchResultsWhenFrozen() throws Exception {
             assertThat(Boolean.valueOf(extractValue(frozenIndexSettings, "index.blocks.write")), equalTo(true));
 
             final Request unfreezeRequest = new Request(HttpPost.METHOD_NAME, restoredIndexName + "/_unfreeze");
+            unfreezeRequest.setOptions(expectWarnings(FROZEN_INDICES_WARNING));
             assertOK(client().performRequest(unfreezeRequest));
             ensureGreen(restoredIndexName);
             assertSearchResults(restoredIndexName, numDocs, Boolean.FALSE);
@@ -285,6 +290,7 @@ public void testSnapshotOfSearchableSnapshot() throws Exception {
             if (frozen) {
                 logger.info("--> freezing index [{}]", restoredIndexName);
                 final Request freezeRequest = new Request(HttpPost.METHOD_NAME, restoredIndexName + "/_freeze");
+                freezeRequest.setOptions(expectWarnings(FROZEN_INDICES_WARNING));
                 assertOK(client().performRequest(freezeRequest));
             }
 

x-pack/plugin/sql/qa/server/src/main/java/org/elasticsearch/xpack/sql/qa/jdbc/DataLoader.java

@@ -28,6 +28,8 @@
 import java.util.List;
 import java.util.Map;
 
+import static org.elasticsearch.test.rest.ESRestTestCase.expectWarnings;
+
 public class DataLoader {
 
     public static void main(String[] args) throws Exception {
@@ -393,7 +395,14 @@ public static void makeAlias(RestClient client, String aliasName, String... indi
 
     protected static void freeze(RestClient client, String... indices) throws Exception {
         for (String index : indices) {
-            client.performRequest(new Request("POST", "/" + index + "/_freeze"));
+            Request freezeRequest = new Request("POST", "/" + index + "/_freeze");
+            freezeRequest.setOptions(
+                expectWarnings(
+                    "Frozen indices are deprecated because they provide no benefit given improvements in "
+                        + "heap memory utilization. They will be removed in a future release."
+                )
+            );
+            client.performRequest(freezeRequest);
         }
     }
 

x-pack/plugin/src/yamlRestTest/resources/rest-api-spec/test/indices.freeze/10_basic.yml

@@ -1,5 +1,8 @@
 ---
 "Basic":
+- skip:
+    features: [ "warnings" ]
+
 - do:
     index:
       index: test
@@ -12,6 +15,8 @@
       body:  { "foo": "Hello: 2" }
 
 - do:
+    warnings:
+      - "Frozen indices are deprecated because they provide no benefit given improvements in heap memory utilization. They will be removed in a future release."
     indices.freeze:
       index: test
 
@@ -29,6 +34,8 @@
 
 # unfreeze
 - do:
+    warnings:
+      - "Frozen indices are deprecated because they provide no benefit given improvements in heap memory utilization. They will be removed in a future release."
     indices.unfreeze:
       index: test
 
@@ -51,6 +58,8 @@
 
 
 - do:
+    warnings:
+      - "Frozen indices are deprecated because they provide no benefit given improvements in heap memory utilization. They will be removed in a future release."
     indices.freeze:
       index: test*
 
@@ -81,7 +90,7 @@
 "Test index options":
 
 - skip:
-    features: ["allowed_warnings"]
+    features: ["allowed_warnings", "warnings"]
 
 - do:
     index:
@@ -102,6 +111,8 @@
       - "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"
 
 - do:
+    warnings:
+      - "Frozen indices are deprecated because they provide no benefit given improvements in heap memory utilization. They will be removed in a future release."
     indices.freeze:
       index: test*,not_available
       ignore_unavailable: true

x-pack/plugin/src/yamlRestTest/resources/rest-api-spec/test/indices.freeze/20_stats.yml

@@ -10,6 +10,7 @@ setup:
 ---
 "Translog stats on frozen indices":
   - skip:
+      features: warnings
       version: " - 7.3.99"
       reason:  "start ignoring translog retention policy with soft-deletes enabled in 7.4"
 
@@ -39,6 +40,8 @@ setup:
 
   # freeze index
   - do:
+      warnings:
+        - "Frozen indices are deprecated because they provide no benefit given improvements in heap memory utilization. They will be removed in a future release."
       indices.freeze:
         index: test
   - is_true: acknowledged
@@ -51,6 +54,8 @@ setup:
 
   # unfreeze index
   - do:
+      warnings:
+        - "Frozen indices are deprecated because they provide no benefit given improvements in heap memory utilization. They will be removed in a future release."
       indices.unfreeze:
         index: test
   - is_true: acknowledged

x-pack/plugin/src/yamlRestTest/resources/rest-api-spec/test/indices.freeze/30_usage.yml

@@ -10,6 +10,7 @@ setup:
 ---
 "Usage stats on frozen indices":
   - skip:
+      features: [ "warnings" ]
       version: " - 7.3.99"
       reason:  "frozen indices have usage stats starting in version 7.4"
 
@@ -38,6 +39,8 @@ setup:
 
   # freeze index
   - do:
+      warnings:
+        - "Frozen indices are deprecated because they provide no benefit given improvements in heap memory utilization. They will be removed in a future release."
       indices.freeze:
         index: test
   - is_true: acknowledged
@@ -50,6 +53,8 @@ setup:
 
   # unfreeze index
   - do:
+      warnings:
+        - "Frozen indices are deprecated because they provide no benefit given improvements in heap memory utilization. They will be removed in a future release."
       indices.unfreeze:
         index: test
   - is_true: acknowledged

x-pack/qa/full-cluster-restart/src/test/java/org/elasticsearch/xpack/restart/FullClusterRestartIT.java

@@ -681,14 +681,28 @@ public void testFrozenIndexAfterRestarted() throws Exception {
             ensureGreen(index);
             final int totalHits = (int) XContentMapValues.extractValue("hits.total.value",
                 entityAsMap(client().performRequest(new Request("GET", "/" + index + "/_search"))));
-            assertOK(client().performRequest(new Request("POST", index + "/_freeze")));
+            Request freezeRequest = new Request("POST", index + "/_freeze");
+            freezeRequest.setOptions(
+                expectWarnings(
+                    "Frozen indices are deprecated because they provide no benefit given "
+                        + "improvements in heap memory utilization. They will be removed in a future release."
+                )
+            );
+            assertOK(client().performRequest(freezeRequest));
             ensureGreen(index);
             assertNoFileBasedRecovery(index, n -> true);
             final Request request = new Request("GET", "/" + index + "/_search");
             request.addParameter("ignore_throttled", "false");
             assertThat(XContentMapValues.extractValue("hits.total.value", entityAsMap(client().performRequest(request))),
                 equalTo(totalHits));
-            assertOK(client().performRequest(new Request("POST", index + "/_unfreeze")));
+            final Request unfreezeRequest = new Request("POST", index + "/_unfreeze");
+            unfreezeRequest.setOptions(
+                expectWarnings(
+                    "Frozen indices are deprecated because they provide no benefit given "
+                        + "improvements in heap memory utilization. They will be removed in a future release."
+                )
+            );
+            assertOK(client().performRequest(unfreezeRequest));
             ensureGreen(index);
             assertNoFileBasedRecovery(index, n -> true);
         }