Deprecate Migration Assistance and Upgrade APIs

client/rest-high-level/src/main/java/org/elasticsearch/client/MigrationClient.java

@@ -19,15 +19,14 @@
 
 package org.elasticsearch.client;
 
+import org.elasticsearch.action.ActionListener;
 import org.elasticsearch.client.migration.DeprecationInfoRequest;
 import org.elasticsearch.client.migration.DeprecationInfoResponse;
 import org.elasticsearch.client.migration.IndexUpgradeInfoRequest;
 import org.elasticsearch.client.migration.IndexUpgradeInfoResponse;
-import org.elasticsearch.action.ActionListener;
+import org.elasticsearch.client.migration.IndexUpgradeRequest;
 import org.elasticsearch.client.tasks.TaskSubmissionResponse;
 import org.elasticsearch.index.reindex.BulkByScrollResponse;
-import org.elasticsearch.client.migration.IndexUpgradeRequest;
-
 
 import java.io.IOException;
 import java.util.Collections;
@@ -54,22 +53,49 @@ public final class MigrationClient {
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
      * @throws IOException in case there is a problem sending the request or parsing back the response
+     * @deprecated Use {@link MigrationClient#getDeprecationInfo} instead
      */
+    @Deprecated
     public IndexUpgradeInfoResponse getAssistance(IndexUpgradeInfoRequest request, RequestOptions options) throws IOException {
         return restHighLevelClient.performRequestAndParseEntity(request, MigrationRequestConverters::getMigrationAssistance, options,
             IndexUpgradeInfoResponse::fromXContent, Collections.emptySet());
     }
 
+    /**
+     *
+     * @param request the request
+     * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
+     * @return the response
+     * @throws IOException in case there is a problem sending the request or parsing back the response
+     * @deprecated The Migration Upgrade API is deprecated, use the Kibana Upgrade Assistant or Reindex API instead.
+     */
+    @Deprecated
     public BulkByScrollResponse upgrade(IndexUpgradeRequest request, RequestOptions options) throws IOException {
         return restHighLevelClient.performRequestAndParseEntity(request, MigrationRequestConverters::migrate, options,
             BulkByScrollResponse::fromXContent, Collections.emptySet());
     }
 
+    /**
+     *
+     * @param request the request
+     * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
+     * @return the response
+     * @throws IOException in case there is a problem sending the request or parsing back the response
+     * @deprecated The Migration Upgrade API is deprecated, use the Kibana Upgrade Assistant or Reindex API instead.
+     */
+    @Deprecated
     public TaskSubmissionResponse submitUpgradeTask(IndexUpgradeRequest request, RequestOptions options) throws IOException {
         return restHighLevelClient.performRequestAndParseEntity(request, MigrationRequestConverters::submitMigrateTask, options,
             TaskSubmissionResponse::fromXContent, Collections.emptySet());
     }
 
+    /**
+     *
+     * @param request the request
+     * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
+     * @deprecated The Migration Upgrade API is deprecated, use the Kibana Upgrade Assistant or Reindex API instead.
+     */
+    @Deprecated
     public void upgradeAsync(IndexUpgradeRequest request, RequestOptions options, ActionListener<BulkByScrollResponse> listener)  {
         restHighLevelClient.performRequestAsyncAndParseEntity(request, MigrationRequestConverters::migrate, options,
             BulkByScrollResponse::fromXContent, listener, Collections.emptySet());

client/rest-high-level/src/main/java/org/elasticsearch/client/migration/IndexUpgradeInfoRequest.java

@@ -29,7 +29,9 @@
 /**
  * A request for retrieving upgrade information
  * Part of Migration API
+ * @deprecated Use the Deprecation Info API, which uses {@link DeprecationInfoRequest} instead.
  */
+@Deprecated
 public class IndexUpgradeInfoRequest extends TimedRequest implements IndicesRequest.Replaceable {
 
     private String[] indices = Strings.EMPTY_ARRAY;

client/rest-high-level/src/main/java/org/elasticsearch/client/migration/IndexUpgradeInfoResponse.java

@@ -30,7 +30,9 @@
 
 /**
  * Response object that contains information about indices to be upgraded
+ * @deprecated Use the Deprecation Info API which returns {@link DeprecationInfoResponse} instead.
  */
+@Deprecated
 public class IndexUpgradeInfoResponse {
 
     private static final ParseField INDICES = new ParseField("indices");

client/rest-high-level/src/main/java/org/elasticsearch/client/migration/IndexUpgradeRequest.java

@@ -25,7 +25,9 @@
 /**
  * A request for performing Upgrade on Index
  * Part of Migration API
+ * @deprecated The Migration Upgrade API is deprecated, use the Kibana Upgrade Assistant or Reindex API instead.
  */
+@Deprecated
 public class IndexUpgradeRequest implements Validatable {
 
     private String index;

client/rest-high-level/src/main/java/org/elasticsearch/client/migration/UpgradeActionRequired.java

@@ -22,7 +22,9 @@
 
 /**
  * Indicates the type of the upgrade required for the index
+ * @deprecated The Migration Assistance API is deprecated, use the Deprecation Info API instead.
  */
+@Deprecated
 public enum UpgradeActionRequired {
     NOT_APPLICABLE,   // Indicates that the check is not applicable to this index type, the next check will be performed
     UP_TO_DATE,       // Indicates that the check finds this index to be up to date - no additional checks are required

docs/reference/migration/apis/assistance.asciidoc

@@ -6,8 +6,13 @@
 <titleabbrev>Migration assistance</titleabbrev>
 ++++
 
-The Migration Assistance API analyzes existing indices in the cluster and
-returns the information about indices that require some changes before the
+IMPORTANT: The Migration Assistance API is deprecated, use the
+<<migration-api-deprecation,deprecation info API>> instead, which provides more
+complete and detailed information about actions necessary prior to upgrade.
+
+deprecated[6.7, Use the <<migration-api-deprecation,Deprecation Info API>>
+instead.] The migration assistance API analyzes existing indices in the cluster
+and returns the information about indices that require some changes before the
 cluster can be upgraded to the next major version.
 
 [float]

docs/reference/migration/apis/upgrade.asciidoc

@@ -6,8 +6,14 @@
 <titleabbrev>Migration upgrade</titleabbrev>
 ++++
 
-The Migration Upgrade API performs the upgrade of internal indices to make them
-compatible with the next major version.
+IMPORTANT: To prepare a cluster for an upgrade to Elasticsearch version 7, use
+the {kibana-ref}/upgrade-assistant.html[{kib} Upgrade Assistant] or
+<<reindex-upgrade,reindex manually>> before upgrading.
+
+deprecated[6.7, Use the {kibana-ref}/upgrade-assistant.html[{kib} Upgrade
+Assistant] or <<reindex-upgrade,reindex manually>> before upgrading.] The
+migration upgrade API performs the upgrade of internal indices to make them
+compatible with version 6 of Elasticsearch.
 
 [float]
 ==== Request

x-pack/plugin/src/test/resources/rest-api-spec/test/upgrade/10_basic.yml

@@ -26,7 +26,13 @@ setup:
 
 ---
 "Upgrade info - all":
+  - skip:
+      version: " - 6.6.99"
+      reason: Deprecated in 6.7.0, will not issue warnings before 6.7.0
+      features: "warnings"
   - do:
+      warnings:
+        - "[GET _xpack/migration/assistance/{index}] is deprecated. Use [GET _xpack/migration/deprecations?index={index}] instead."
       xpack.migration.get_assistance: { index: _all }
 
   - length: { indices: 0 }
@@ -39,8 +45,13 @@ setup:
 
 ---
 "Upgrade test - wait_for_completion:false":
-
+  - skip:
+      version: " - 6.6.99"
+      reason: Deprecated in 6.7.0, will not issue warnings before 6.7.0
+      features: "warnings"
   - do:
+      warnings:
+        - "[_xpack/migration/upgrade] is deprecated. Use the Kibana Upgrade Assistant or the Reindex API instead."
       xpack.migration.upgrade:
         index: test1
         wait_for_completion: false

x-pack/plugin/upgrade/src/main/java/org/elasticsearch/xpack/upgrade/IndexUpgradeService.java

@@ -78,7 +78,7 @@ private UpgradeActionRequired upgradeInfo(IndexMetaData indexMetaData, String in
             }
         }
         // Catch all check for all indices that didn't match the specific checks
-        if (indexMetaData.getCreationVersion().before(Version.V_5_0_0)) {
+        if (indexMetaData.getCreationVersion().before(Version.V_6_0_0)) {
             return UpgradeActionRequired.REINDEX;
         } else {
             return null;

x-pack/plugin/upgrade/src/main/java/org/elasticsearch/xpack/upgrade/Upgrade.java

@@ -52,16 +52,16 @@
 import org.elasticsearch.xpack.core.template.TemplateUtils;
 import org.elasticsearch.xpack.core.upgrade.actions.IndexUpgradeAction;
 import org.elasticsearch.xpack.core.upgrade.actions.IndexUpgradeInfoAction;
-import org.elasticsearch.xpack.upgrade.actions.TransportIndexUpgradeAction;
-import org.elasticsearch.xpack.upgrade.actions.TransportIndexUpgradeInfoAction;
-import org.elasticsearch.xpack.upgrade.rest.RestIndexUpgradeAction;
-import org.elasticsearch.xpack.upgrade.rest.RestIndexUpgradeInfoAction;
 import org.elasticsearch.xpack.core.watcher.WatcherState;
 import org.elasticsearch.xpack.core.watcher.client.WatcherClient;
 import org.elasticsearch.xpack.core.watcher.execution.TriggeredWatchStoreField;
 import org.elasticsearch.xpack.core.watcher.support.WatcherIndexTemplateRegistryField;
 import org.elasticsearch.xpack.core.watcher.transport.actions.service.WatcherServiceRequest;
 import org.elasticsearch.xpack.core.watcher.transport.actions.stats.WatcherStatsResponse;
+import org.elasticsearch.xpack.upgrade.actions.TransportIndexUpgradeAction;
+import org.elasticsearch.xpack.upgrade.actions.TransportIndexUpgradeInfoAction;
+import org.elasticsearch.xpack.upgrade.rest.RestIndexUpgradeAction;
+import org.elasticsearch.xpack.upgrade.rest.RestIndexUpgradeInfoAction;
 
 import java.nio.charset.StandardCharsets;
 import java.util.ArrayList;
@@ -152,7 +152,7 @@ static BiFunction<Client, ClusterService, IndexUpgradeCheck> getSecurityUpgradeC
                                 || indexMetaData.getAliases().containsKey(".security")) {
 
                             if (checkInternalIndexFormat(indexMetaData)) {
-                                return UpgradeActionRequired.UP_TO_DATE;
+                                return checkIndexNeedsReindex(indexMetaData);
                             } else {
                                 return UpgradeActionRequired.UPGRADE;
                             }
@@ -257,7 +257,7 @@ static BiFunction<Client, ClusterService, IndexUpgradeCheck> getWatchesIndexUpgr
                     indexMetaData -> {
                         if (indexOrAliasExists(indexMetaData, ".watches")) {
                             if (checkInternalIndexFormat(indexMetaData)) {
-                                return UpgradeActionRequired.UP_TO_DATE;
+                                return checkIndexNeedsReindex(indexMetaData);
                             } else {
                                 return UpgradeActionRequired.UPGRADE;
                             }
@@ -285,7 +285,7 @@ static BiFunction<Client, ClusterService, IndexUpgradeCheck> getTriggeredWatches
                     indexMetaData -> {
                         if (indexOrAliasExists(indexMetaData, TriggeredWatchStoreField.INDEX_NAME)) {
                             if (checkInternalIndexFormat(indexMetaData)) {
-                                return UpgradeActionRequired.UP_TO_DATE;
+                                return checkIndexNeedsReindex(indexMetaData);
                             } else {
                                 return UpgradeActionRequired.UPGRADE;
                             }
@@ -302,6 +302,14 @@ static BiFunction<Client, ClusterService, IndexUpgradeCheck> getTriggeredWatches
         };
     }
 
+    private static UpgradeActionRequired checkIndexNeedsReindex(IndexMetaData indexMetaData) {
+        if (indexMetaData.getCreationVersion().before(Version.V_6_0_0)) {
+            return UpgradeActionRequired.REINDEX;
+        } else {
+            return UpgradeActionRequired.UP_TO_DATE;
+        }
+    }
+
     private static boolean indexOrAliasExists(IndexMetaData indexMetaData, String name) {
         return name.equals(indexMetaData.getIndex().getName()) || indexMetaData.getAliases().containsKey(name);
     }

x-pack/plugin/upgrade/src/main/java/org/elasticsearch/xpack/upgrade/rest/RestIndexUpgradeAction.java

@@ -5,10 +5,13 @@
  */
 package org.elasticsearch.xpack.upgrade.rest;
 
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
 import org.elasticsearch.ExceptionsHelper;
 import org.elasticsearch.action.ActionRequestValidationException;
 import org.elasticsearch.action.bulk.BulkItemResponse;
 import org.elasticsearch.client.node.NodeClient;
+import org.elasticsearch.common.logging.DeprecationLogger;
 import org.elasticsearch.common.settings.Settings;
 import org.elasticsearch.common.xcontent.ToXContent;
 import org.elasticsearch.common.xcontent.XContentBuilder;
@@ -32,9 +35,14 @@
 import java.util.Map;
 
 public class RestIndexUpgradeAction extends BaseRestHandler {
+    private static final Logger logger = LogManager.getLogger(RestIndexUpgradeAction.class);
+    private static final DeprecationLogger deprecationLogger = new DeprecationLogger(logger);
+
     public RestIndexUpgradeAction(Settings settings, RestController controller) {
         super(settings);
-        controller.registerHandler(RestRequest.Method.POST, "_xpack/migration/upgrade/{index}", this);
+        controller.registerAsDeprecatedHandler(RestRequest.Method.POST, "_xpack/migration/upgrade/{index}", this,
+            "[_xpack/migration/upgrade] is deprecated. Use the Kibana Upgrade Assistant or the Reindex API instead.",
+            deprecationLogger);
     }
 
     @Override

x-pack/plugin/upgrade/src/main/java/org/elasticsearch/xpack/upgrade/rest/RestIndexUpgradeInfoAction.java

@@ -5,9 +5,12 @@
  */
 package org.elasticsearch.xpack.upgrade.rest;
 
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
 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.common.settings.Settings;
 import org.elasticsearch.protocol.xpack.migration.IndexUpgradeInfoRequest;
 import org.elasticsearch.rest.BaseRestHandler;
@@ -19,11 +22,17 @@
 import java.io.IOException;
 
 public class RestIndexUpgradeInfoAction extends BaseRestHandler {
+    private static final Logger logger = LogManager.getLogger(RestIndexUpgradeInfoAction.class);
+    private static final DeprecationLogger deprecationLogger = new DeprecationLogger(logger);
 
     public RestIndexUpgradeInfoAction(Settings settings, RestController controller) {
         super(settings);
-        controller.registerHandler(RestRequest.Method.GET, "/_xpack/migration/assistance", this);
-        controller.registerHandler(RestRequest.Method.GET, "/_xpack/migration/assistance/{index}", this);
+        controller.registerAsDeprecatedHandler(RestRequest.Method.GET, "/_xpack/migration/assistance", this,
+            "[GET _xpack/migration/assistance] is deprecated. " +
+                "Use [GET _xpack/migration/deprecations] instead.", deprecationLogger);
+        controller.registerAsDeprecatedHandler(RestRequest.Method.GET, "/_xpack/migration/assistance/{index}", this,
+            "[GET _xpack/migration/assistance/{index}] is deprecated. " +
+                "Use [GET _xpack/migration/deprecations?index={index}] instead.", deprecationLogger);
     }
 
     @Override

x-pack/plugin/upgrade/src/test/java/org/elasticsearch/xpack/upgrade/IndexUpgradeServiceTests.java

@@ -149,7 +149,6 @@ public void testGenericTest() throws Exception {
 
     }
 
-
     private ClusterState mockClusterState(IndexMetaData... indices) {
         MetaData.Builder metaDataBuilder = MetaData.builder();
         for (IndexMetaData indexMetaData : indices) {