hbase-server/src/main/java/org/apache/hadoop/hbase/master/LoadBalancer.java

   1 /**
   2  *
   3  * Licensed to the Apache Software Foundation (ASF) under one
   4  * or more contributor license agreements.  See the NOTICE file
   5  * distributed with this work for additional information
   6  * regarding copyright ownership.  The ASF licenses this file
   7  * to you under the Apache License, Version 2.0 (the
   8  * "License"); you may not use this file except in compliance
   9  * with the License.  You may obtain a copy of the License at
  10  *
  11  *     http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  */
  19 package org.apache.hadoop.hbase.master;
  20
  21 import edu.umd.cs.findbugs.annotations.Nullable;
  22 import java.util.List;
  23 import java.util.Map;
  24 import org.apache.hadoop.conf.Configurable;
  25 import org.apache.hadoop.conf.Configuration;
  26 import org.apache.hadoop.hbase.ClusterMetrics;
  27 import org.apache.hadoop.hbase.HBaseIOException;
  28 import org.apache.hadoop.hbase.ServerName;
  29 import org.apache.hadoop.hbase.Stoppable;
  30 import org.apache.hadoop.hbase.TableName;
  31 import org.apache.hadoop.hbase.client.RegionInfo;
  32 import org.apache.hadoop.hbase.conf.ConfigurationObserver;
  33 import org.apache.yetus.audience.InterfaceAudience;
  34
  35 /**
  36  * Makes decisions about the placement and movement of Regions across
  37  * RegionServers.
  38  *
  39  * <p>Cluster-wide load balancing will occur only when there are no regions in
  40  * transition and according to a fixed period of a time using {@link #balanceCluster(Map)}.
  41  *
  42  * <p>On cluster startup, bulk assignment can be used to determine
  43  * locations for all Regions in a cluster.
  44  *
  45  * <p>This class produces plans for the
  46  * {@link org.apache.hadoop.hbase.master.assignment.AssignmentManager}
  47  * to execute.
  48  */
  49 @InterfaceAudience.Private
  50 public interface LoadBalancer extends Configurable, Stoppable, ConfigurationObserver {
  51   /**
  52    * Master can carry regions as of hbase-2.0.0.
  53    * By default, it carries no tables.
  54    * TODO: Add any | system as flags to indicate what it can do.
  55    */
  56   String TABLES_ON_MASTER = "hbase.balancer.tablesOnMaster";
  57
  58   /**
  59    * Master carries system tables.
  60    */
  61   String SYSTEM_TABLES_ON_MASTER = "hbase.balancer.tablesOnMaster.systemTablesOnly";
  62
  63   // Used to signal to the caller that the region(s) cannot be assigned
  64   // We deliberately use 'localhost' so the operation will fail fast
  65   ServerName BOGUS_SERVER_NAME = ServerName.valueOf("localhost,1,1");
  66
  67   /**
  68    * Set the current cluster status.  This allows a LoadBalancer to map host name to a server
  69    * @param st
  70    */
  71   void setClusterMetrics(ClusterMetrics st);
  72
  73   /**
  74    * Pass RegionStates and allow balancer to set the current cluster load.
  75    * @param ClusterLoad
  76    */
  77   void setClusterLoad(Map<TableName, Map<ServerName, List<RegionInfo>>> ClusterLoad);
  78
  79   /**
  80    * Set the master service.
  81    * @param masterServices
  82    */
  83   void setMasterServices(MasterServices masterServices);
  84
  85   /**
  86    * Perform the major balance operation
  87    * @param tableName
  88    * @param clusterState
  89    * @return List of plans
  90    */
  91   List<RegionPlan> balanceCluster(TableName tableName, Map<ServerName,
  92       List<RegionInfo>> clusterState) throws HBaseIOException;
  93
  94   /**
  95    * Perform the major balance operation
  96    * @param clusterState
  97    * @return List of plans
  98    */
  99   List<RegionPlan> balanceCluster(Map<ServerName,
 100       List<RegionInfo>> clusterState) throws HBaseIOException;
 101
 102   /**
 103    * Perform a Round Robin assignment of regions.
 104    * @param regions
 105    * @param servers
 106    * @return Map of servername to regioninfos
 107    */
 108   Map<ServerName, List<RegionInfo>> roundRobinAssignment(
 109     List<RegionInfo> regions,
 110     List<ServerName> servers
 111   ) throws HBaseIOException;
 112
 113   /**
 114    * Assign regions to the previously hosting region server
 115    * @param regions
 116    * @param servers
 117    * @return List of plans
 118    */
 119   @Nullable
 120   Map<ServerName, List<RegionInfo>> retainAssignment(
 121     Map<RegionInfo, ServerName> regions,
 122     List<ServerName> servers
 123   ) throws HBaseIOException;
 124
 125   /**
 126    * Get a random region server from the list
 127    * @param regionInfo Region for which this selection is being done.
 128    * @param servers
 129    * @return Servername
 130    */
 131   ServerName randomAssignment(
 132     RegionInfo regionInfo, List<ServerName> servers
 133   ) throws HBaseIOException;
 134
 135   /**
 136    * Initialize the load balancer. Must be called after setters.
 137    * @throws HBaseIOException
 138    */
 139   void initialize() throws HBaseIOException;
 140
 141   /**
 142    * Marks the region as online at balancer.
 143    * @param regionInfo
 144    * @param sn
 145    */
 146   void regionOnline(RegionInfo regionInfo, ServerName sn);
 147
 148   /**
 149    * Marks the region as offline at balancer.
 150    * @param regionInfo
 151    */
 152   void regionOffline(RegionInfo regionInfo);
 153
 154   /*
 155    * Notification that config has changed
 156    * @param conf
 157    */
 158   @Override
 159   void onConfigurationChange(Configuration conf);
 160
 161   /**
 162    * If balancer needs to do initialization after Master has started up, lets do that here.
 163    */
 164   void postMasterStartupInitialize();
 165
 166   /*Updates balancer status tag reported to JMX*/
 167   void updateBalancerStatus(boolean status);
 168
 169   /**
 170    * @return true if Master carries regions
 171    */
 172   static boolean isTablesOnMaster(Configuration conf) {
 173     return conf.getBoolean(TABLES_ON_MASTER, false);
 174   }
 175
 176   static boolean isSystemTablesOnlyOnMaster(Configuration conf) {
 177     return conf.getBoolean(SYSTEM_TABLES_ON_MASTER, false);
 178   }
 179
 180   static boolean isMasterCanHostUserRegions(Configuration conf) {
 181     return isTablesOnMaster(conf) && !isSystemTablesOnlyOnMaster(conf);
 182   }
 183 }