HBASE-26147: Add dry_run_balancer and related Admin interfaces for running the balancer without executing any region moves

hbase-client/src/main/java/org/apache/hadoop/hbase/client/Admin.java

@@ -1251,7 +1251,20 @@ default boolean balancer() throws IOException {
    * @return <code>true</code> if balancer ran, <code>false</code> otherwise.
    * @throws IOException if a remote or network exception occurs
    */
-  boolean balance() throws IOException;
+  default boolean balance() throws IOException {
+    return balance(BalanceRequest.defaultInstance())
+      .isBalancerRan();
+  }
+
+  /**
+   * Invoke the balancer with the given balance request.  The BalanceRequest defines how the
+   * balancer will run. See {@link BalanceRequest} for more details.
+   *
+   * @param request defines how the balancer should run
+   * @return {@link BalanceResponse} with details about the results of the invocation.
+   * @throws IOException if a remote or network exception occurs
+   */
+  BalanceResponse balance(BalanceRequest request) throws IOException;
 
   /**
    * Invoke the balancer.  Will run the balancer and if regions to move, it will
@@ -1262,7 +1275,7 @@ default boolean balancer() throws IOException {
    * @return <code>true</code> if balancer ran, <code>false</code> otherwise.
    * @throws IOException if a remote or network exception occurs
    * @deprecated Since 2.0.0. Will be removed in 3.0.0.
-   * Use {@link #balance(boolean)} instead.
+   * Use {@link #balance(BalanceRequest)} instead.
    */
   @Deprecated
   default boolean balancer(boolean force) throws IOException {
@@ -1277,8 +1290,17 @@ default boolean balancer(boolean force) throws IOException {
    * @param force whether we should force balance even if there is region in transition
    * @return <code>true</code> if balancer ran, <code>false</code> otherwise.
    * @throws IOException if a remote or network exception occurs
+   * @deprecated Since 2.5.0. Will be removed in 4.0.0.
+   * Use {@link #balance(BalanceRequest)} instead.
    */
-  boolean balance(boolean force) throws IOException;
+  @Deprecated
+  default boolean balance(boolean force) throws IOException {
+    return balance(
+      BalanceRequest.newBuilder()
+      .setIgnoreRegionsInTransition(force)
+      .build()
+    ).isBalancerRan();
+  }
 
   /**
    * Query the current state of the balancer.

hbase-client/src/main/java/org/apache/hadoop/hbase/client/AsyncAdmin.java

@@ -1257,7 +1257,8 @@ default CompletableFuture<Boolean> balancerSwitch(boolean on) {
    *         {@link CompletableFuture}.
    */
   default CompletableFuture<Boolean> balance() {
-    return balance(false);
+    return balance(BalanceRequest.defaultInstance())
+      .thenApply(BalanceResponse::isBalancerRan);
   }
 
   /**
@@ -1267,8 +1268,25 @@ default CompletableFuture<Boolean> balance() {
    * @param forcible whether we should force balance even if there is region in transition.
    * @return True if balancer ran, false otherwise. The return value will be wrapped by a
    *         {@link CompletableFuture}.
+   * @deprecated Since 2.5.0. Will be removed in 4.0.0.
+   *  Use {@link #balance(BalanceRequest)} instead.
+   */
+  default CompletableFuture<Boolean> balance(boolean forcible) {
+    return balance(
+      BalanceRequest.newBuilder()
+        .setIgnoreRegionsInTransition(forcible)
+        .build()
+    ).thenApply(BalanceResponse::isBalancerRan);
+  }
+
+  /**
+   * Invoke the balancer with the given balance request.  The BalanceRequest defines how the
+   * balancer will run. See {@link BalanceRequest} for more details.
+   *
+   * @param request defines how the balancer should run
+   * @return {@link BalanceResponse} with details about the results of the invocation.
    */
-  CompletableFuture<Boolean> balance(boolean forcible);
+  CompletableFuture<BalanceResponse> balance(BalanceRequest request);
 
   /**
    * Query the current state of the balancer.

hbase-client/src/main/java/org/apache/hadoop/hbase/client/AsyncHBaseAdmin.java

@@ -684,8 +684,8 @@ public CompletableFuture<Boolean> balancerSwitch(boolean on, boolean drainRITs)
   }
 
   @Override
-  public CompletableFuture<Boolean> balance(boolean forcible) {
-    return wrap(rawAdmin.balance(forcible));
+  public CompletableFuture<BalanceResponse> balance(BalanceRequest request) {
+    return wrap(rawAdmin.balance(request));
   }
 
   @Override

hbase-client/src/main/java/org/apache/hadoop/hbase/client/BalanceRequest.java

@@ -0,0 +1,114 @@
+/*
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.hadoop.hbase.client;
+
+import org.apache.yetus.audience.InterfaceAudience;
+
+/**
+ * Encapsulates options for executing a run of the Balancer.
+ */
+@InterfaceAudience.Public
+public final class BalanceRequest {
+  private static final BalanceRequest DEFAULT = BalanceRequest.newBuilder().build();
+
+  /**
+   * Builder for constructing a {@link BalanceRequest}
+   */
+  @InterfaceAudience.Public
+  public final static class Builder {
+    private boolean dryRun = false;
+    private boolean ignoreRegionsInTransition = false;
+
+    private Builder() {}
+
+    /**
+     * Creates a BalancerRequest which runs the balancer in dryRun mode.
+     * In this mode, the balancer will try to find a plan but WILL NOT
+     * execute any region moves or call any coprocessors.
+     *
+     * You can run in dryRun mode regardless of whether the balancer switch
+     * is enabled or disabled, but dryRun mode will not run over an existing
+     * request or chore.
+     *
+     * Dry run is useful for testing out new balance configs. See the logs
+     * on the active HMaster for the results of the dry run.
+     */
+    public Builder setDryRun(boolean dryRun) {
+      this.dryRun = dryRun;
+      return this;
+    }
+
+    /**
+     * Creates a BalancerRequest to cause the balancer to run even if there
+     * are regions in transition.
+     *
+     * WARNING: Advanced usage only, this could cause more issues than it fixes.
+     */
+    public Builder setIgnoreRegionsInTransition(boolean ignoreRegionsInTransition) {
+      this.ignoreRegionsInTransition = ignoreRegionsInTransition;
+      return this;
+    }
+
+    /**
+     * Build the {@link BalanceRequest}
+     */
+    public BalanceRequest build() {
+      return new BalanceRequest(dryRun, ignoreRegionsInTransition);
+    }
+  }
+
+  /**
+   * Create a builder to construct a custom {@link BalanceRequest}.
+   */
+  public static Builder newBuilder() {
+    return new Builder();
+  }
+
+  /**
+   * Get a BalanceRequest for a default run of the balancer. The default mode executes
+   * any moves calculated and will not run if regions are already in transition.
+   */
+  public static BalanceRequest defaultInstance() {
+    return DEFAULT;
+  }
+
+  private final boolean dryRun;
+  private final boolean ignoreRegionsInTransition;
+
+  private BalanceRequest(boolean dryRun, boolean ignoreRegionsInTransition) {
+    this.dryRun = dryRun;
+    this.ignoreRegionsInTransition = ignoreRegionsInTransition;
+  }
+
+  /**
+   * Returns true if the balancer should run in dry run mode, otherwise false. In
+   * dry run mode, moves will be calculated but not executed.
+   */
+  public boolean isDryRun() {
+    return dryRun;
+  }
+
+  /**
+   * Returns true if the balancer should execute even if regions are in transition, otherwise
+   * false. This is an advanced usage feature, as it can cause more issues than it fixes.
+   */
+  public boolean isIgnoreRegionsInTransition() {
+    return ignoreRegionsInTransition;
+  }
+}

hbase-client/src/main/java/org/apache/hadoop/hbase/client/BalanceResponse.java

@@ -0,0 +1,126 @@
+/*
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.hadoop.hbase.client;
+
+import org.apache.yetus.audience.InterfaceAudience;
+
+/**
+ * Response returned from a balancer invocation
+ */
+@InterfaceAudience.Public
+public final class BalanceResponse {
+
+  /**
+   * Builds a {@link BalanceResponse} for returning results of a balance invocation to callers
+   */
+  @InterfaceAudience.Public
+  public final static class Builder {
+    private boolean balancerRan;
+    private int movesCalculated;
+    private int movesExecuted;
+
+    private Builder() {}
+
+    /**
+     * Set true if the balancer ran, otherwise false. The balancer may not run in some
+     * circumstances, such as if a balance is already running or there are regions already
+     * in transition.
+     *
+     * @param balancerRan true if balancer ran, false otherwise
+     */
+    public Builder setBalancerRan(boolean balancerRan) {
+      this.balancerRan = balancerRan;
+      return this;
+    }
+
+    /**
+     * Set how many moves were calculated by the balancer. This will be zero if the cluster is
+     * already balanced.
+     *
+     * @param movesCalculated moves calculated by the balance run
+     */
+    public Builder setMovesCalculated(int movesCalculated) {
+      this.movesCalculated = movesCalculated;
+      return this;
+    }
+
+    /**
+     * Set how many of the calculated moves were actually executed by the balancer. This should be
+     * zero if the balancer is run with {@link BalanceRequest#isDryRun()}. It may also not equal
+     * movesCalculated if the balancer ran out of time while executing the moves.
+     *
+     * @param movesExecuted moves executed by the balance run
+     */
+    public Builder setMovesExecuted(int movesExecuted) {
+      this.movesExecuted = movesExecuted;
+      return this;
+    }
+
+    /**
+     * Build the {@link BalanceResponse}
+     */
+    public BalanceResponse build() {
+      return new BalanceResponse(balancerRan, movesCalculated, movesExecuted);
+    }
+  }
+
+  /**
+   * Creates a new {@link BalanceResponse.Builder}
+   */
+  public static Builder newBuilder() {
+    return new Builder();
+  }
+
+  private final boolean balancerRan;
+  private final int movesCalculated;
+  private final int movesExecuted;
+
+  private BalanceResponse(boolean balancerRan, int movesCalculated, int movesExecuted) {
+    this.balancerRan = balancerRan;
+    this.movesCalculated = movesCalculated;
+    this.movesExecuted = movesExecuted;
+  }
+
+  /**
+   * Returns true if the balancer ran, otherwise false. The balancer may not run for a
+   * variety of reasons, such as: another balance is running, there are regions in
+   * transition, the cluster is in maintenance mode, etc.
+   */
+  public boolean isBalancerRan() {
+    return balancerRan;
+  }
+
+  /**
+   * The number of moves calculated by the balancer if {@link #isBalancerRan()} is true. This will
+   * be zero if no better balance could be found.
+   */
+  public int getMovesCalculated() {
+    return movesCalculated;
+  }
+
+  /**
+   * The number of moves actually executed by the balancer if it ran. This will be
+   * zero if {@link #getMovesCalculated()} is zero or if {@link BalanceRequest#isDryRun()}
+   * was true. It may also not be equal to {@link #getMovesCalculated()} if the balancer
+   * was interrupted midway through executing the moves due to max run time.
+   */
+  public int getMovesExecuted() {
+    return movesExecuted;
+  }
+}