Remove deprecated local parameter from alias APIs (#115393)

PeteGillinElastic · web-flow · commit d7a9575d0314 · 2024-10-24T15:58:24.000+01:00
This removes the `local` parameter from the `GET /_alias`, `HEAD /_alias`, and `GET /_cat/aliases` APIs. This option became a no-op and was deprecated in 8.12 by #101815. We continue to accept the parameter (deprecated, with no other effect) in v8 compatibility mode for `GET /_alias` and `HEAD /_alias`. We don't do this for `GET /_cat/aliases` where the [compatibility policy does not apply](https://github.com/elastic/elasticsearch/blob/main/REST_API_COMPATIBILITY.md#when-not-to-apply).
diff --git a/docs/changelog/115393.yaml b/docs/changelog/115393.yaml
@@ -0,0 +1,18 @@
+pr: 115393
+summary: Remove deprecated local attribute from alias APIs
+area: Indices APIs
+type: breaking
+issues: []
+breaking:
+  title: Remove deprecated local attribute from alias APIs
+  area: REST API
+  details: >-
+    The following APIs no longer accept the `?local` query parameter:
+    `GET /_alias`, `GET /_aliases`, `GET /_alias/{name}`,
+    `HEAD /_alias/{name}`, `GET /{index}/_alias`, `HEAD /{index}/_alias`,
+    `GET /{index}/_alias/{name}`, `HEAD /{index}/_alias/{name}`,
+    `GET /_cat/aliases`, and `GET /_cat/aliases/{alias}`. This parameter
+    has been deprecated and ignored since version 8.12.
+  impact: >-
+    Cease usage of the `?local` query parameter when calling the listed APIs.
+  notable: false
diff --git a/docs/reference/cat/alias.asciidoc b/docs/reference/cat/alias.asciidoc
@@ -6,8 +6,8 @@
 
 [IMPORTANT]
 ====
-cat APIs are only intended for human consumption using the command line or the 
-{kib} console. They are _not_ intended for use by applications. For application 
+cat APIs are only intended for human consumption using the command line or the
+{kib} console. They are _not_ intended for use by applications. For application
 consumption, use the <<aliases,aliases API>>.
 ====
 
@@ -45,8 +45,6 @@ include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=cat-h]
 
 include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=help]
 
-include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=local]
-
 include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=cat-s]
 
 include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=cat-v]
@@ -104,6 +102,6 @@ alias4 test1 -      2            1,2            -
 This response shows that `alias2` has configured a filter, and specific routing
 configurations in `alias3` and `alias4`.
 
-If you only want to get information about specific aliases, you can specify 
-the aliases in comma-delimited format as a URL parameter, e.g., 
+If you only want to get information about specific aliases, you can specify
+the aliases in comma-delimited format as a URL parameter, e.g.,
 /_cat/aliases/alias1,alias2.
diff --git a/docs/reference/indices/alias-exists.asciidoc b/docs/reference/indices/alias-exists.asciidoc
@@ -52,8 +52,6 @@ Defaults to `all`.
 (Optional, Boolean) If `false`, requests that include a missing data stream or
 index in the `<target>` return an error. Defaults to `false`.
 
-include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=local]
-
 [[alias-exists-api-response-codes]]
 ==== {api-response-codes-title}
 
diff --git a/docs/reference/indices/get-alias.asciidoc b/docs/reference/indices/get-alias.asciidoc
@@ -58,5 +58,3 @@ Defaults to `all`.
 `ignore_unavailable`::
 (Optional, Boolean) If `false`, requests that include a missing data stream or
 index in the `<target>` return an error. Defaults to `false`.
-
-include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=local]
diff --git a/rest-api-spec/build.gradle b/rest-api-spec/build.gradle
@@ -60,4 +60,5 @@ tasks.named("yamlRestCompatTestTransform").configure ({ task ->
   task.skipTest("indices.sort/10_basic/Index Sort", "warning does not exist for compatibility")
   task.skipTest("search/330_fetch_fields/Test search rewrite", "warning does not exist for compatibility")
   task.skipTest("indices.create/21_synthetic_source_stored/object param - nested object with stored array", "temporary until backported")
+  task.skipTest("cat.aliases/10_basic/Deprecated local parameter", "CAT APIs not covered by compatibility policy")
 })
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/cat.aliases.json b/rest-api-spec/src/main/resources/rest-api-spec/api/cat.aliases.json
@@ -36,10 +36,6 @@
         "type":"string",
         "description":"a short version of the Accept header, e.g. json, yaml"
       },
-      "local":{
-        "type":"boolean",
-        "description":"Return local information, do not retrieve the state from master node (default: false)"
-      },
       "h":{
         "type":"list",
         "description":"Comma-separated list of column names to display"
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/indices.exists_alias.json b/rest-api-spec/src/main/resources/rest-api-spec/api/indices.exists_alias.json
@@ -61,10 +61,6 @@
         ],
         "default":"all",
         "description":"Whether to expand wildcard expression to concrete indices that are open, closed or both."
-      },
-      "local":{
-        "type":"boolean",
-        "description":"Return local information, do not retrieve the state from master node (default: false)"
       }
     }
   }
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_alias.json b/rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_alias.json
@@ -79,10 +79,6 @@
         ],
         "default": "all",
         "description":"Whether to expand wildcard expression to concrete indices that are open, closed or both."
-      },
-      "local":{
-        "type":"boolean",
-        "description":"Return local information, do not retrieve the state from master node (default: false)"
       }
     }
   }
diff --git a/rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/cat.aliases/10_basic.yml b/rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/cat.aliases/10_basic.yml
@@ -484,16 +484,3 @@
                 test_alias \s+ test_index\n
                 my_alias \s+ test_index\n
             $/
-
----
-"Deprecated local parameter":
-  - requires:
-      cluster_features: ["gte_v8.12.0"]
-      test_runner_features: ["warnings"]
-      reason: verifying deprecation warnings from 8.12.0 onwards
-
-  - do:
-      cat.aliases:
-        local: true
-      warnings:
-        - "the [?local=true] query parameter to cat-aliases requests has no effect and will be removed in a future version"
diff --git a/rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/indices.exists_alias/10_basic.yml b/rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/indices.exists_alias/10_basic.yml
@@ -34,17 +34,3 @@
         name: test_alias
 
   - is_false: ''
-
----
-"Test indices.exists_alias with local flag":
-  - skip:
-      features: ["allowed_warnings"]
-
-  - do:
-      indices.exists_alias:
-        name: test_alias
-        local: true
-      allowed_warnings:
-        - "the [?local=true] query parameter to get-aliases requests has no effect and will be removed in a future version"
-
-  - is_false: ''
diff --git a/rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/indices.get_alias/10_basic.yml b/rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/indices.get_alias/10_basic.yml
@@ -289,21 +289,6 @@ setup:
         index: non-existent
         name: foo
 
----
-"Get alias with local flag":
-  - skip:
-      features: ["allowed_warnings"]
-
-  - do:
-      indices.get_alias:
-        local: true
-      allowed_warnings:
-        - "the [?local=true] query parameter to get-aliases requests has no effect and will be removed in a future version"
-
-  - is_true: test_index
-
-  - is_true: test_index_2
-
 ---
 "Get alias against closed indices":
   - skip:
@@ -329,17 +314,3 @@ setup:
 
   - is_true: test_index
   - is_false: test_index_2
-
-
----
-"Deprecated local parameter":
-  - requires:
-      cluster_features: "gte_v8.12.0"
-      test_runner_features: ["warnings"]
-      reason: verifying deprecation warnings from 8.12.0 onwards
-
-  - do:
-      indices.get_alias:
-        local: true
-      warnings:
-        - "the [?local=true] query parameter to get-aliases requests has no effect and will be removed in a future version"
diff --git a/server/src/main/java/org/elasticsearch/rest/action/admin/indices/RestGetAliasesAction.java b/server/src/main/java/org/elasticsearch/rest/action/admin/indices/RestGetAliasesAction.java
@@ -22,7 +22,7 @@
 import org.elasticsearch.common.regex.Regex;
 import org.elasticsearch.common.xcontent.XContentHelper;
 import org.elasticsearch.core.RestApiVersion;
-import org.elasticsearch.core.UpdateForV9;
+import org.elasticsearch.core.UpdateForV10;
 import org.elasticsearch.rest.BaseRestHandler;
 import org.elasticsearch.rest.RestRequest;
 import org.elasticsearch.rest.RestResponse;
@@ -52,7 +52,7 @@
 @ServerlessScope(Scope.PUBLIC)
 public class RestGetAliasesAction extends BaseRestHandler {
 
-    @UpdateForV9(owner = UpdateForV9.Owner.DATA_MANAGEMENT) // reject the deprecated ?local parameter
+    @UpdateForV10(owner = UpdateForV10.Owner.DATA_MANAGEMENT) // remove the BWC support for the deprecated ?local parameter
     private static final DeprecationLogger DEPRECATION_LOGGER = DeprecationLogger.getLogger(RestGetAliasesAction.class);
 
     @Override
@@ -199,8 +199,7 @@ static RestResponse buildRestResponse(
     }
 
     @Override
-    @UpdateForV9(owner = UpdateForV9.Owner.DATA_MANAGEMENT)
-    // v7 REST API no longer exists: eliminate ref to RestApiVersion.V_7; reject local parameter in v9 too?
+    @UpdateForV10(owner = UpdateForV10.Owner.DATA_MANAGEMENT) // remove the BWC support for the deprecated ?local parameter
     public RestChannelConsumer prepareRequest(final RestRequest request, final NodeClient client) throws IOException {
         // The TransportGetAliasesAction was improved do the same post processing as is happening here.
         // We can't remove this logic yet to support mixed clusters. We should be able to remove this logic here
@@ -213,10 +212,10 @@ public RestChannelConsumer prepareRequest(final RestRequest request, final NodeC
         getAliasesRequest.indices(indices);
         getAliasesRequest.indicesOptions(IndicesOptions.fromRequest(request, getAliasesRequest.indicesOptions()));
 
-        if (request.hasParam("local")) {
-            // consume this param just for validation
-            final var localParam = request.paramAsBoolean("local", false);
-            if (request.getRestApiVersion() != RestApiVersion.V_7) {
+        if (request.getRestApiVersion() == RestApiVersion.V_8) {
+            if (request.hasParam("local")) {
+                // consume this param just for validation when in BWC mode for V_8
+                final var localParam = request.paramAsBoolean("local", false);
                 DEPRECATION_LOGGER.critical(
                     DeprecationCategory.API,
                     "get-aliases-local",
diff --git a/server/src/main/java/org/elasticsearch/rest/action/cat/RestAliasAction.java b/server/src/main/java/org/elasticsearch/rest/action/cat/RestAliasAction.java
@@ -15,10 +15,6 @@
 import org.elasticsearch.cluster.metadata.AliasMetadata;
 import org.elasticsearch.common.Strings;
 import org.elasticsearch.common.Table;
-import org.elasticsearch.common.logging.DeprecationCategory;
-import org.elasticsearch.common.logging.DeprecationLogger;
-import org.elasticsearch.core.RestApiVersion;
-import org.elasticsearch.core.UpdateForV9;
 import org.elasticsearch.rest.RestRequest;
 import org.elasticsearch.rest.RestResponse;
 import org.elasticsearch.rest.Scope;
@@ -34,8 +30,6 @@
 @ServerlessScope(Scope.PUBLIC)
 public class RestAliasAction extends AbstractCatAction {
 
-    private static final DeprecationLogger DEPRECATION_LOGGER = DeprecationLogger.getLogger(RestAliasAction.class);
-
     @Override
     public List<Route> routes() {
         return List.of(new Route(GET, "/_cat/aliases"), new Route(GET, "/_cat/aliases/{alias}"));
@@ -52,27 +46,11 @@ public boolean allowSystemIndexAccessByDefault() {
     }
 
     @Override
-    @UpdateForV9(owner = UpdateForV9.Owner.DATA_MANAGEMENT)
-    // v7 REST API no longer exists: eliminate ref to RestApiVersion.V_7; reject local parameter in v9 too?
     protected RestChannelConsumer doCatRequest(final RestRequest request, final NodeClient client) {
         final GetAliasesRequest getAliasesRequest = request.hasParam("alias")
             ? new GetAliasesRequest(Strings.commaDelimitedListToStringArray(request.param("alias")))
             : new GetAliasesRequest();
         getAliasesRequest.indicesOptions(IndicesOptions.fromRequest(request, getAliasesRequest.indicesOptions()));
-
-        if (request.hasParam("local")) {
-            // consume this param just for validation
-            final var localParam = request.paramAsBoolean("local", false);
-            if (request.getRestApiVersion() != RestApiVersion.V_7) {
-                DEPRECATION_LOGGER.critical(
-                    DeprecationCategory.API,
-                    "cat-aliases-local",
-                    "the [?local={}] query parameter to cat-aliases requests has no effect and will be removed in a future version",
-                    localParam
-                );
-            }
-        }
-
         return channel -> new RestCancellableNodeClient(client, request.getHttpChannel()).admin()
             .indices()
             .getAliases(getAliasesRequest, new RestResponseListener<>(channel) {

Original file line number	Diff line number	Diff line change
`@@ -61,10 +61,6 @@`
`61`	`61`	`],`
`62`	`62`	`"default":"all",`
`63`	`63`	`"description":"Whether to expand wildcard expression to concrete indices that are open, closed or both."`
`64`		`- },`
`65`		`- "local":{`
`66`		`- "type":"boolean",`
`67`		`- "description":"Return local information, do not retrieve the state from master node (default: false)"`
`68`	`64`	`}`
`69`	`65`	`}`
`70`	`66`	`}`
Original file line number	Diff line number	Diff line change
`@@ -79,10 +79,6 @@`
`79`	`79`	`],`
`80`	`80`	`"default": "all",`
`81`	`81`	`"description":"Whether to expand wildcard expression to concrete indices that are open, closed or both."`
`82`		`- },`
`83`		`- "local":{`
`84`		`- "type":"boolean",`
`85`		`- "description":"Return local information, do not retrieve the state from master node (default: false)"`
`86`	`82`	`}`
`87`	`83`	`}`
`88`	`84`	`}`