1 /** 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an "AS IS" BASIS, 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 */ 18 package org.apache.hadoop.ha; 19 20 import org.apache.hadoop.classification.InterfaceAudience; 21 import org.apache.hadoop.classification.InterfaceStability; 22 import org.apache.hadoop.fs.CommonConfigurationKeys; 23 import org.apache.hadoop.io.retry.Idempotent; 24 import org.apache.hadoop.security.AccessControlException; 25 import org.apache.hadoop.security.KerberosInfo; 26 27 import java.io.IOException; 28 29 /** 30 * Protocol interface that provides High Availability related primitives to 31 * monitor and fail-over the service. 32 * 33 * This interface could be used by HA frameworks to manage the service. 34 */ 35 @KerberosInfo( 36 serverPrincipal=CommonConfigurationKeys.HADOOP_SECURITY_SERVICE_USER_NAME_KEY) 37 @InterfaceAudience.Public 38 @InterfaceStability.Evolving 39 public interface HAServiceProtocol { 40 /** 41 * Initial version of the protocol 42 */ 43 public static final long versionID = 1L; 44 45 /** 46 * An HA service may be in active or standby state. During startup, it is in 47 * an unknown INITIALIZING state. During shutdown, it is in the STOPPING state 48 * and can no longer return to active/standby states. 49 */ 50 public enum HAServiceState { 51 INITIALIZING("initializing"), 52 ACTIVE("active"), 53 STANDBY("standby"), 54 STOPPING("stopping"); 55 56 private String name; 57 HAServiceState(String name)58 HAServiceState(String name) { 59 this.name = name; 60 } 61 62 @Override toString()63 public String toString() { 64 return name; 65 } 66 } 67 68 public static enum RequestSource { 69 REQUEST_BY_USER, 70 REQUEST_BY_USER_FORCED, 71 REQUEST_BY_ZKFC; 72 } 73 74 /** 75 * Information describing the source for a request to change state. 76 * This is used to differentiate requests from automatic vs CLI 77 * failover controllers, and in the future may include epoch 78 * information. 79 */ 80 public static class StateChangeRequestInfo { 81 private final RequestSource source; 82 StateChangeRequestInfo(RequestSource source)83 public StateChangeRequestInfo(RequestSource source) { 84 super(); 85 this.source = source; 86 } 87 getSource()88 public RequestSource getSource() { 89 return source; 90 } 91 } 92 93 /** 94 * Monitor the health of service. This periodically called by the HA 95 * frameworks to monitor the health of the service. 96 * 97 * Service is expected to perform checks to ensure it is functional. 98 * If the service is not healthy due to failure or partial failure, 99 * it is expected to throw {@link HealthCheckFailedException}. 100 * The definition of service not healthy is left to the service. 101 * 102 * Note that when health check of an Active service fails, 103 * failover to standby may be done. 104 * 105 * @throws HealthCheckFailedException 106 * if the health check of a service fails. 107 * @throws AccessControlException 108 * if access is denied. 109 * @throws IOException 110 * if other errors happen 111 */ 112 @Idempotent monitorHealth()113 public void monitorHealth() throws HealthCheckFailedException, 114 AccessControlException, 115 IOException; 116 117 /** 118 * Request service to transition to active state. No operation, if the 119 * service is already in active state. 120 * 121 * @throws ServiceFailedException 122 * if transition from standby to active fails. 123 * @throws AccessControlException 124 * if access is denied. 125 * @throws IOException 126 * if other errors happen 127 */ 128 @Idempotent transitionToActive(StateChangeRequestInfo reqInfo)129 public void transitionToActive(StateChangeRequestInfo reqInfo) 130 throws ServiceFailedException, 131 AccessControlException, 132 IOException; 133 134 /** 135 * Request service to transition to standby state. No operation, if the 136 * service is already in standby state. 137 * 138 * @throws ServiceFailedException 139 * if transition from active to standby fails. 140 * @throws AccessControlException 141 * if access is denied. 142 * @throws IOException 143 * if other errors happen 144 */ 145 @Idempotent transitionToStandby(StateChangeRequestInfo reqInfo)146 public void transitionToStandby(StateChangeRequestInfo reqInfo) 147 throws ServiceFailedException, 148 AccessControlException, 149 IOException; 150 151 /** 152 * Return the current status of the service. The status indicates 153 * the current <em>state</em> (e.g ACTIVE/STANDBY) as well as 154 * some additional information. {@see HAServiceStatus} 155 * 156 * @throws AccessControlException 157 * if access is denied. 158 * @throws IOException 159 * if other errors happen 160 */ 161 @Idempotent getServiceStatus()162 public HAServiceStatus getServiceStatus() throws AccessControlException, 163 IOException; 164 } 165