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 */ 018 019 package org.apache.hadoop.yarn.client.api; 020 021 import java.io.IOException; 022 import java.util.List; 023 import java.util.Set; 024 025 import org.apache.hadoop.classification.InterfaceAudience; 026 import org.apache.hadoop.classification.InterfaceAudience.Private; 027 import org.apache.hadoop.classification.InterfaceAudience.Public; 028 import org.apache.hadoop.classification.InterfaceStability; 029 import org.apache.hadoop.io.Text; 030 import org.apache.hadoop.service.AbstractService; 031 import org.apache.hadoop.yarn.api.records.ApplicationId; 032 import org.apache.hadoop.yarn.api.records.ApplicationReport; 033 import org.apache.hadoop.yarn.api.records.ApplicationSubmissionContext; 034 import org.apache.hadoop.yarn.api.records.NodeReport; 035 import org.apache.hadoop.yarn.api.records.NodeState; 036 import org.apache.hadoop.yarn.api.records.QueueInfo; 037 import org.apache.hadoop.yarn.api.records.QueueUserACLInfo; 038 import org.apache.hadoop.yarn.api.records.Token; 039 import org.apache.hadoop.yarn.api.records.YarnClusterMetrics; 040 import org.apache.hadoop.yarn.client.api.impl.YarnClientImpl; 041 import org.apache.hadoop.yarn.exceptions.YarnException; 042 import org.apache.hadoop.yarn.security.AMRMTokenIdentifier; 043 044 @InterfaceAudience.Public 045 @InterfaceStability.Stable 046 public abstract class YarnClient extends AbstractService { 047 048 /** 049 * Create a new instance of YarnClient. 050 */ 051 @Public 052 public static YarnClient createYarnClient() { 053 YarnClient client = new YarnClientImpl(); 054 return client; 055 } 056 057 @Private 058 protected YarnClient(String name) { 059 super(name); 060 } 061 062 /** 063 * <p> 064 * Obtain a {@link YarnClientApplication} for a new application, 065 * which in turn contains the {@link ApplicationSubmissionContext} and 066 * {@link org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationResponse} 067 * objects. 068 * </p> 069 * 070 * @return {@link YarnClientApplication} built for a new application 071 * @throws YarnException 072 * @throws IOException 073 */ 074 public abstract YarnClientApplication createApplication() 075 throws YarnException, IOException; 076 077 /** 078 * <p> 079 * Submit a new application to <code>YARN.</code> It is a blocking call, such 080 * that it will not return {@link ApplicationId} until the submitted 081 * application has been submitted and accepted by the ResourceManager. 082 * </p> 083 * 084 * @param appContext 085 * {@link ApplicationSubmissionContext} containing all the details 086 * needed to submit a new application 087 * @return {@link ApplicationId} of the accepted application 088 * @throws YarnException 089 * @throws IOException 090 * @see #createApplication() 091 */ 092 public abstract ApplicationId submitApplication(ApplicationSubmissionContext appContext) 093 throws YarnException, IOException; 094 095 /** 096 * <p> 097 * Kill an application identified by given ID. 098 * </p> 099 * 100 * @param applicationId 101 * {@link ApplicationId} of the application that needs to be killed 102 * @throws YarnException 103 * in case of errors or if YARN rejects the request due to 104 * access-control restrictions. 105 * @throws IOException 106 * @see #getQueueAclsInfo() 107 */ 108 public abstract void killApplication(ApplicationId applicationId) throws YarnException, 109 IOException; 110 111 /** 112 * <p> 113 * Get a report of the given Application. 114 * </p> 115 * 116 * <p> 117 * In secure mode, <code>YARN</code> verifies access to the application, queue 118 * etc. before accepting the request. 119 * </p> 120 * 121 * <p> 122 * If the user does not have <code>VIEW_APP</code> access then the following 123 * fields in the report will be set to stubbed values: 124 * <ul> 125 * <li>host - set to "N/A"</li> 126 * <li>RPC port - set to -1</li> 127 * <li>client token - set to "N/A"</li> 128 * <li>diagnostics - set to "N/A"</li> 129 * <li>tracking URL - set to "N/A"</li> 130 * <li>original tracking URL - set to "N/A"</li> 131 * <li>resource usage report - all values are -1</li> 132 * </ul> 133 * </p> 134 * 135 * @param appId 136 * {@link ApplicationId} of the application that needs a report 137 * @return application report 138 * @throws YarnException 139 * @throws IOException 140 */ 141 public abstract ApplicationReport getApplicationReport(ApplicationId appId) 142 throws YarnException, IOException; 143 144 /** 145 * Get the AMRM token of the application. 146 * <p/> 147 * The AMRM token is required for AM to RM scheduling operations. For 148 * managed Application Masters Yarn takes care of injecting it. For unmanaged 149 * Applications Masters, the token must be obtained via this method and set 150 * in the {@link org.apache.hadoop.security.UserGroupInformation} of the 151 * current user. 152 * <p/> 153 * The AMRM token will be returned only if all the following conditions are 154 * met: 155 * <li> 156 * <ul>the requester is the owner of the ApplicationMaster</ul> 157 * <ul>the application master is an unmanaged ApplicationMaster</ul> 158 * <ul>the application master is in ACCEPTED state</ul> 159 * </li> 160 * Else this method returns NULL. 161 * 162 * @param appId {@link ApplicationId} of the application to get the AMRM token 163 * @return the AMRM token if available 164 * @throws YarnException 165 * @throws IOException 166 */ 167 public abstract org.apache.hadoop.security.token.Token<AMRMTokenIdentifier> 168 getAMRMToken(ApplicationId appId) throws YarnException, IOException; 169 170 /** 171 * <p> 172 * Get a report (ApplicationReport) of all Applications in the cluster. 173 * </p> 174 * 175 * <p> 176 * If the user does not have <code>VIEW_APP</code> access for an application 177 * then the corresponding report will be filtered as described in 178 * {@link #getApplicationReport(ApplicationId)}. 179 * </p> 180 * 181 * @return a list of reports of all running applications 182 * @throws YarnException 183 * @throws IOException 184 */ 185 public abstract List<ApplicationReport> getApplications() 186 throws YarnException, IOException; 187 188 /** 189 * <p> 190 * Get a report (ApplicationReport) of Applications 191 * matching the given application types in the cluster. 192 * </p> 193 * 194 * <p> 195 * If the user does not have <code>VIEW_APP</code> access for an application 196 * then the corresponding report will be filtered as described in 197 * {@link #getApplicationReport(ApplicationId)}. 198 * </p> 199 * 200 * @param applicationTypes 201 * @return a list of reports of applications 202 * @throws YarnException 203 * @throws IOException 204 */ 205 public abstract List<ApplicationReport> getApplications( 206 Set<String> applicationTypes) throws YarnException, IOException; 207 208 /** 209 * <p> 210 * Get metrics ({@link YarnClusterMetrics}) about the cluster. 211 * </p> 212 * 213 * @return cluster metrics 214 * @throws YarnException 215 * @throws IOException 216 */ 217 public abstract YarnClusterMetrics getYarnClusterMetrics() throws YarnException, 218 IOException; 219 220 /** 221 * <p> 222 * Get a report of nodes ({@link NodeReport}) in the cluster. 223 * </p> 224 * 225 * @param states The {@link NodeState}s to filter on. If no filter states are 226 * given, nodes in all states will be returned. 227 * @return A list of node reports 228 * @throws YarnException 229 * @throws IOException 230 */ 231 public abstract List<NodeReport> getNodeReports(NodeState... states) 232 throws YarnException, IOException; 233 234 /** 235 * <p> 236 * Get a delegation token so as to be able to talk to YARN using those tokens. 237 * 238 * @param renewer 239 * Address of the renewer who can renew these tokens when needed by 240 * securely talking to YARN. 241 * @return a delegation token ({@link Token}) that can be used to 242 * talk to YARN 243 * @throws YarnException 244 * @throws IOException 245 */ 246 public abstract Token getRMDelegationToken(Text renewer) 247 throws YarnException, IOException; 248 249 /** 250 * <p> 251 * Get information ({@link QueueInfo}) about a given <em>queue</em>. 252 * </p> 253 * 254 * @param queueName 255 * Name of the queue whose information is needed 256 * @return queue information 257 * @throws YarnException 258 * in case of errors or if YARN rejects the request due to 259 * access-control restrictions. 260 * @throws IOException 261 */ 262 public abstract QueueInfo getQueueInfo(String queueName) throws YarnException, 263 IOException; 264 265 /** 266 * <p> 267 * Get information ({@link QueueInfo}) about all queues, recursively if there 268 * is a hierarchy 269 * </p> 270 * 271 * @return a list of queue-information for all queues 272 * @throws YarnException 273 * @throws IOException 274 */ 275 public abstract List<QueueInfo> getAllQueues() throws YarnException, IOException; 276 277 /** 278 * <p> 279 * Get information ({@link QueueInfo}) about top level queues. 280 * </p> 281 * 282 * @return a list of queue-information for all the top-level queues 283 * @throws YarnException 284 * @throws IOException 285 */ 286 public abstract List<QueueInfo> getRootQueueInfos() throws YarnException, IOException; 287 288 /** 289 * <p> 290 * Get information ({@link QueueInfo}) about all the immediate children queues 291 * of the given queue 292 * </p> 293 * 294 * @param parent 295 * Name of the queue whose child-queues' information is needed 296 * @return a list of queue-information for all queues who are direct children 297 * of the given parent queue. 298 * @throws YarnException 299 * @throws IOException 300 */ 301 public abstract List<QueueInfo> getChildQueueInfos(String parent) throws YarnException, 302 IOException; 303 304 /** 305 * <p> 306 * Get information about <em>acls</em> for <em>current user</em> on all the 307 * existing queues. 308 * </p> 309 * 310 * @return a list of queue acls ({@link QueueUserACLInfo}) for 311 * <em>current user</em> 312 * @throws YarnException 313 * @throws IOException 314 */ 315 public abstract List<QueueUserACLInfo> getQueueAclsInfo() throws YarnException, 316 IOException; 317 }