001/* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, software 013 * distributed under the License is distributed on an "AS IS" BASIS, 014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 015 * See the License for the specific language governing permissions and 016 * limitations under the License. 017 */ 018package org.apache.hadoop.hbase.master; 019 020import edu.umd.cs.findbugs.annotations.NonNull; 021import java.io.IOException; 022import java.util.List; 023import java.util.Map; 024import org.apache.hadoop.conf.Configuration; 025import org.apache.hadoop.hbase.ClusterMetrics; 026import org.apache.hadoop.hbase.HBaseIOException; 027import org.apache.hadoop.hbase.ServerName; 028import org.apache.hadoop.hbase.Stoppable; 029import org.apache.hadoop.hbase.TableName; 030import org.apache.hadoop.hbase.client.RegionInfo; 031import org.apache.hadoop.hbase.conf.ConfigurationObserver; 032import org.apache.yetus.audience.InterfaceAudience; 033 034/** 035 * Makes decisions about the placement and movement of Regions across RegionServers. 036 * <p/> 037 * Cluster-wide load balancing will occur only when there are no regions in transition and according 038 * to a fixed period of a time using {@link #balanceCluster(Map)}. 039 * <p/> 040 * On cluster startup, bulk assignment can be used to determine locations for all Regions in a 041 * cluster. 042 * <p/> 043 * This class produces plans for the {@code AssignmentManager} to execute. 044 * <p/> 045 * About locking: 046 * <ul> 047 * <li>We will first call {@link #setMasterServices(MasterServices)} and then {@link #initialize()} 048 * to initialize the balancer, and before calling {@link #initialize()}, we will never call any 049 * methods of this balancer. So these two methods do not need to be synchronized.</li> 050 * <li>The {@link #balanceCluster(Map)} method will use the {@link ClusterMetrics} which is set by 051 * {@link #updateClusterMetrics(ClusterMetrics)}, and also lots of configurations, which could be 052 * changed by {@link #onConfigurationChange(Configuration)}, so the easier way is to make these 053 * three methods synchronized. And since there will be only one balancing thread, this will not 054 * impact performance too much.</li> 055 * <li>The {@link #roundRobinAssignment(List, List)}, {@link #retainAssignment(Map, List)} and 056 * {@link #randomAssignment(RegionInfo, List)} could be called from multiple threads concurrently, 057 * so these three methods should not be synchronized, the implementation classes need to make sure 058 * that they are thread safe.</li> 059 * </ul> 060 */ 061@InterfaceAudience.Private 062public interface LoadBalancer extends Stoppable, ConfigurationObserver { 063 /** 064 * Master can carry regions as of hbase-2.0.0. By default, it carries no tables. TODO: Add any | 065 * system as flags to indicate what it can do. 066 * @deprecated since 2.4.0, will be removed in 3.0.0. 067 * @see <a href="https://issues.apache.org/jira/browse/HBASE-15549">HBASE-15549</a> 068 */ 069 @Deprecated 070 String TABLES_ON_MASTER = "hbase.balancer.tablesOnMaster"; 071 072 /** 073 * Master carries system tables. 074 * @deprecated since 2.4.0, will be removed in 3.0.0. 075 * @see <a href="https://issues.apache.org/jira/browse/HBASE-15549">HBASE-15549</a> 076 */ 077 @Deprecated 078 String SYSTEM_TABLES_ON_MASTER = "hbase.balancer.tablesOnMaster.systemTablesOnly"; 079 080 // Used to signal to the caller that the region(s) cannot be assigned 081 // We deliberately use 'localhost' so the operation will fail fast 082 ServerName BOGUS_SERVER_NAME = ServerName.valueOf("localhost,1,1"); 083 084 /** 085 * Set the current cluster status. This allows a LoadBalancer to map host name to a server 086 */ 087 void updateClusterMetrics(ClusterMetrics metrics); 088 089 /** 090 * Set the master service. n 091 */ 092 void setMasterServices(MasterServices masterServices); 093 094 /** 095 * Perform the major balance operation for cluster. 096 * @param loadOfAllTable region load of servers for all table 097 * @return a list of regions to be moved, including source and destination, or null if cluster is 098 * already balanced 099 */ 100 List<RegionPlan> balanceCluster(Map<TableName, Map<ServerName, List<RegionInfo>>> loadOfAllTable) 101 throws IOException; 102 103 /** 104 * Perform a Round Robin assignment of regions. nn * @return Map of servername to regioninfos 105 */ 106 @NonNull 107 Map<ServerName, List<RegionInfo>> roundRobinAssignment(List<RegionInfo> regions, 108 List<ServerName> servers) throws HBaseIOException; 109 110 /** 111 * Assign regions to the previously hosting region server nn * @return List of plans 112 */ 113 @NonNull 114 Map<ServerName, List<RegionInfo>> retainAssignment(Map<RegionInfo, ServerName> regions, 115 List<ServerName> servers) throws HBaseIOException; 116 117 /** 118 * Get a random region server from the list 119 * @param regionInfo Region for which this selection is being done. nn 120 */ 121 ServerName randomAssignment(RegionInfo regionInfo, List<ServerName> servers) 122 throws HBaseIOException; 123 124 /** 125 * Initialize the load balancer. Must be called after setters. n 126 */ 127 void initialize() throws HBaseIOException; 128 129 /** 130 * Marks the region as online at balancer. nn 131 */ 132 void regionOnline(RegionInfo regionInfo, ServerName sn); 133 134 /** 135 * Marks the region as offline at balancer. n 136 */ 137 void regionOffline(RegionInfo regionInfo); 138 139 /* 140 * Notification that config has changed n 141 */ 142 @Override 143 void onConfigurationChange(Configuration conf); 144 145 /** 146 * If balancer needs to do initialization after Master has started up, lets do that here. 147 */ 148 void postMasterStartupInitialize(); 149 150 /* Updates balancer status tag reported to JMX */ 151 void updateBalancerStatus(boolean status); 152 153 /** 154 * In some scenarios, Balancer needs to update internal status or information according to the 155 * current tables load 156 * @param loadOfAllTable region load of servers for all table 157 */ 158 default void 159 updateBalancerLoadInfo(Map<TableName, Map<ServerName, List<RegionInfo>>> loadOfAllTable) { 160 } 161 162 /** 163 * @return true if Master carries regions 164 * @deprecated since 2.4.0, will be removed in 3.0.0. 165 * @see <a href="https://issues.apache.org/jira/browse/HBASE-15549">HBASE-15549</a> 166 */ 167 @Deprecated 168 static boolean isTablesOnMaster(Configuration conf) { 169 return conf.getBoolean(TABLES_ON_MASTER, false); 170 } 171 172 /** 173 * @deprecated since 2.4.0, will be removed in 3.0.0. 174 * @see <a href="https://issues.apache.org/jira/browse/HBASE-15549">HBASE-15549</a> 175 */ 176 @Deprecated 177 static boolean isSystemTablesOnlyOnMaster(Configuration conf) { 178 return conf.getBoolean(SYSTEM_TABLES_ON_MASTER, false); 179 } 180 181 /** 182 * @deprecated since 2.4.0, will be removed in 3.0.0. 183 * @see <a href="https://issues.apache.org/jira/browse/HBASE-15549">HBASE-15549</a> 184 */ 185 @Deprecated 186 static boolean isMasterCanHostUserRegions(Configuration conf) { 187 return isTablesOnMaster(conf) && !isSystemTablesOnlyOnMaster(conf); 188 } 189}