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.EnumSet;
023 import java.util.List;
024 import java.util.Set;
025
026 import org.apache.hadoop.classification.InterfaceAudience;
027 import org.apache.hadoop.classification.InterfaceAudience.Private;
028 import org.apache.hadoop.classification.InterfaceAudience.Public;
029 import org.apache.hadoop.classification.InterfaceStability;
030 import org.apache.hadoop.io.Text;
031 import org.apache.hadoop.service.AbstractService;
032 import org.apache.hadoop.yarn.api.ApplicationClientProtocol;
033 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportRequest;
034 import org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationRequest;
035 import org.apache.hadoop.yarn.api.records.ApplicationAttemptId;
036 import org.apache.hadoop.yarn.api.records.ApplicationAttemptReport;
037 import org.apache.hadoop.yarn.api.records.ApplicationId;
038 import org.apache.hadoop.yarn.api.records.ApplicationReport;
039 import org.apache.hadoop.yarn.api.records.ApplicationSubmissionContext;
040 import org.apache.hadoop.yarn.api.records.ContainerId;
041 import org.apache.hadoop.yarn.api.records.ContainerReport;
042 import org.apache.hadoop.yarn.api.records.NodeReport;
043 import org.apache.hadoop.yarn.api.records.NodeState;
044 import org.apache.hadoop.yarn.api.records.QueueInfo;
045 import org.apache.hadoop.yarn.api.records.QueueUserACLInfo;
046 import org.apache.hadoop.yarn.api.records.Token;
047 import org.apache.hadoop.yarn.api.records.YarnApplicationState;
048 import org.apache.hadoop.yarn.api.records.YarnClusterMetrics;
049 import org.apache.hadoop.yarn.client.api.impl.YarnClientImpl;
050 import org.apache.hadoop.yarn.exceptions.ApplicationIdNotProvidedException;
051 import org.apache.hadoop.yarn.exceptions.ApplicationNotFoundException;
052 import org.apache.hadoop.yarn.exceptions.YarnException;
053 import org.apache.hadoop.yarn.security.AMRMTokenIdentifier;
054
055 @InterfaceAudience.Public
056 @InterfaceStability.Stable
057 public abstract class YarnClient extends AbstractService {
058
059 /**
060 * Create a new instance of YarnClient.
061 */
062 @Public
063 public static YarnClient createYarnClient() {
064 YarnClient client = new YarnClientImpl();
065 return client;
066 }
067
068 @Private
069 protected YarnClient(String name) {
070 super(name);
071 }
072
073 /**
074 * <p>
075 * Obtain a {@link YarnClientApplication} for a new application,
076 * which in turn contains the {@link ApplicationSubmissionContext} and
077 * {@link org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationResponse}
078 * objects.
079 * </p>
080 *
081 * @return {@link YarnClientApplication} built for a new application
082 * @throws YarnException
083 * @throws IOException
084 */
085 public abstract YarnClientApplication createApplication()
086 throws YarnException, IOException;
087
088 /**
089 * <p>
090 * Submit a new application to <code>YARN.</code> It is a blocking call - it
091 * will not return {@link ApplicationId} until the submitted application is
092 * submitted successfully and accepted by the ResourceManager.
093 * </p>
094 *
095 * <p>
096 * Users should provide an {@link ApplicationId} as part of the parameter
097 * {@link ApplicationSubmissionContext} when submitting a new application,
098 * otherwise it will throw the {@link ApplicationIdNotProvidedException}.
099 * </p>
100 *
101 * <p>This internally calls {@link ApplicationClientProtocol#submitApplication
102 * (SubmitApplicationRequest)}, and after that, it internally invokes
103 * {@link ApplicationClientProtocol#getApplicationReport
104 * (GetApplicationReportRequest)} and waits till it can make sure that the
105 * application gets properly submitted. If RM fails over or RM restart
106 * happens before ResourceManager saves the application's state,
107 * {@link ApplicationClientProtocol
108 * #getApplicationReport(GetApplicationReportRequest)} will throw
109 * the {@link ApplicationNotFoundException}. This API automatically resubmits
110 * the application with the same {@link ApplicationSubmissionContext} when it
111 * catches the {@link ApplicationNotFoundException}</p>
112 *
113 * @param appContext
114 * {@link ApplicationSubmissionContext} containing all the details
115 * needed to submit a new application
116 * @return {@link ApplicationId} of the accepted application
117 * @throws YarnException
118 * @throws IOException
119 * @see #createApplication()
120 */
121 public abstract ApplicationId submitApplication(
122 ApplicationSubmissionContext appContext) throws YarnException,
123 IOException;
124
125 /**
126 * <p>
127 * Kill an application identified by given ID.
128 * </p>
129 *
130 * @param applicationId
131 * {@link ApplicationId} of the application that needs to be killed
132 * @throws YarnException
133 * in case of errors or if YARN rejects the request due to
134 * access-control restrictions.
135 * @throws IOException
136 * @see #getQueueAclsInfo()
137 */
138 public abstract void killApplication(ApplicationId applicationId) throws YarnException,
139 IOException;
140
141 /**
142 * <p>
143 * Get a report of the given Application.
144 * </p>
145 *
146 * <p>
147 * In secure mode, <code>YARN</code> verifies access to the application, queue
148 * etc. before accepting the request.
149 * </p>
150 *
151 * <p>
152 * If the user does not have <code>VIEW_APP</code> access then the following
153 * fields in the report will be set to stubbed values:
154 * <ul>
155 * <li>host - set to "N/A"</li>
156 * <li>RPC port - set to -1</li>
157 * <li>client token - set to "N/A"</li>
158 * <li>diagnostics - set to "N/A"</li>
159 * <li>tracking URL - set to "N/A"</li>
160 * <li>original tracking URL - set to "N/A"</li>
161 * <li>resource usage report - all values are -1</li>
162 * </ul>
163 * </p>
164 *
165 * @param appId
166 * {@link ApplicationId} of the application that needs a report
167 * @return application report
168 * @throws YarnException
169 * @throws IOException
170 */
171 public abstract ApplicationReport getApplicationReport(ApplicationId appId)
172 throws YarnException, IOException;
173
174 /**
175 * Get the AMRM token of the application.
176 * <p/>
177 * The AMRM token is required for AM to RM scheduling operations. For
178 * managed Application Masters Yarn takes care of injecting it. For unmanaged
179 * Applications Masters, the token must be obtained via this method and set
180 * in the {@link org.apache.hadoop.security.UserGroupInformation} of the
181 * current user.
182 * <p/>
183 * The AMRM token will be returned only if all the following conditions are
184 * met:
185 * <li>
186 * <ul>the requester is the owner of the ApplicationMaster</ul>
187 * <ul>the application master is an unmanaged ApplicationMaster</ul>
188 * <ul>the application master is in ACCEPTED state</ul>
189 * </li>
190 * Else this method returns NULL.
191 *
192 * @param appId {@link ApplicationId} of the application to get the AMRM token
193 * @return the AMRM token if available
194 * @throws YarnException
195 * @throws IOException
196 */
197 public abstract org.apache.hadoop.security.token.Token<AMRMTokenIdentifier>
198 getAMRMToken(ApplicationId appId) throws YarnException, IOException;
199
200 /**
201 * <p>
202 * Get a report (ApplicationReport) of all Applications in the cluster.
203 * </p>
204 *
205 * <p>
206 * If the user does not have <code>VIEW_APP</code> access for an application
207 * then the corresponding report will be filtered as described in
208 * {@link #getApplicationReport(ApplicationId)}.
209 * </p>
210 *
211 * @return a list of reports of all running applications
212 * @throws YarnException
213 * @throws IOException
214 */
215 public abstract List<ApplicationReport> getApplications()
216 throws YarnException, IOException;
217
218 /**
219 * <p>
220 * Get a report (ApplicationReport) of Applications
221 * matching the given application types in the cluster.
222 * </p>
223 *
224 * <p>
225 * If the user does not have <code>VIEW_APP</code> access for an application
226 * then the corresponding report will be filtered as described in
227 * {@link #getApplicationReport(ApplicationId)}.
228 * </p>
229 *
230 * @param applicationTypes
231 * @return a list of reports of applications
232 * @throws YarnException
233 * @throws IOException
234 */
235 public abstract List<ApplicationReport> getApplications(
236 Set<String> applicationTypes) throws YarnException, IOException;
237
238 /**
239 * <p>
240 * Get a report (ApplicationReport) of Applications matching the given
241 * application states in the cluster.
242 * </p>
243 *
244 * <p>
245 * If the user does not have <code>VIEW_APP</code> access for an application
246 * then the corresponding report will be filtered as described in
247 * {@link #getApplicationReport(ApplicationId)}.
248 * </p>
249 *
250 * @param applicationStates
251 * @return a list of reports of applications
252 * @throws YarnException
253 * @throws IOException
254 */
255 public abstract List<ApplicationReport>
256 getApplications(EnumSet<YarnApplicationState> applicationStates)
257 throws YarnException, IOException;
258
259 /**
260 * <p>
261 * Get a report (ApplicationReport) of Applications matching the given
262 * application types and application states in the cluster.
263 * </p>
264 *
265 * <p>
266 * If the user does not have <code>VIEW_APP</code> access for an application
267 * then the corresponding report will be filtered as described in
268 * {@link #getApplicationReport(ApplicationId)}.
269 * </p>
270 *
271 * @param applicationTypes
272 * @param applicationStates
273 * @return a list of reports of applications
274 * @throws YarnException
275 * @throws IOException
276 */
277 public abstract List<ApplicationReport> getApplications(
278 Set<String> applicationTypes,
279 EnumSet<YarnApplicationState> applicationStates) throws YarnException,
280 IOException;
281
282 /**
283 * <p>
284 * Get metrics ({@link YarnClusterMetrics}) about the cluster.
285 * </p>
286 *
287 * @return cluster metrics
288 * @throws YarnException
289 * @throws IOException
290 */
291 public abstract YarnClusterMetrics getYarnClusterMetrics() throws YarnException,
292 IOException;
293
294 /**
295 * <p>
296 * Get a report of nodes ({@link NodeReport}) in the cluster.
297 * </p>
298 *
299 * @param states The {@link NodeState}s to filter on. If no filter states are
300 * given, nodes in all states will be returned.
301 * @return A list of node reports
302 * @throws YarnException
303 * @throws IOException
304 */
305 public abstract List<NodeReport> getNodeReports(NodeState... states)
306 throws YarnException, IOException;
307
308 /**
309 * <p>
310 * Get a delegation token so as to be able to talk to YARN using those tokens.
311 *
312 * @param renewer
313 * Address of the renewer who can renew these tokens when needed by
314 * securely talking to YARN.
315 * @return a delegation token ({@link Token}) that can be used to
316 * talk to YARN
317 * @throws YarnException
318 * @throws IOException
319 */
320 public abstract Token getRMDelegationToken(Text renewer)
321 throws YarnException, IOException;
322
323 /**
324 * <p>
325 * Get information ({@link QueueInfo}) about a given <em>queue</em>.
326 * </p>
327 *
328 * @param queueName
329 * Name of the queue whose information is needed
330 * @return queue information
331 * @throws YarnException
332 * in case of errors or if YARN rejects the request due to
333 * access-control restrictions.
334 * @throws IOException
335 */
336 public abstract QueueInfo getQueueInfo(String queueName) throws YarnException,
337 IOException;
338
339 /**
340 * <p>
341 * Get information ({@link QueueInfo}) about all queues, recursively if there
342 * is a hierarchy
343 * </p>
344 *
345 * @return a list of queue-information for all queues
346 * @throws YarnException
347 * @throws IOException
348 */
349 public abstract List<QueueInfo> getAllQueues() throws YarnException, IOException;
350
351 /**
352 * <p>
353 * Get information ({@link QueueInfo}) about top level queues.
354 * </p>
355 *
356 * @return a list of queue-information for all the top-level queues
357 * @throws YarnException
358 * @throws IOException
359 */
360 public abstract List<QueueInfo> getRootQueueInfos() throws YarnException, IOException;
361
362 /**
363 * <p>
364 * Get information ({@link QueueInfo}) about all the immediate children queues
365 * of the given queue
366 * </p>
367 *
368 * @param parent
369 * Name of the queue whose child-queues' information is needed
370 * @return a list of queue-information for all queues who are direct children
371 * of the given parent queue.
372 * @throws YarnException
373 * @throws IOException
374 */
375 public abstract List<QueueInfo> getChildQueueInfos(String parent) throws YarnException,
376 IOException;
377
378 /**
379 * <p>
380 * Get information about <em>acls</em> for <em>current user</em> on all the
381 * existing queues.
382 * </p>
383 *
384 * @return a list of queue acls ({@link QueueUserACLInfo}) for
385 * <em>current user</em>
386 * @throws YarnException
387 * @throws IOException
388 */
389 public abstract List<QueueUserACLInfo> getQueueAclsInfo() throws YarnException,
390 IOException;
391
392 /**
393 * <p>
394 * Get a report of the given ApplicationAttempt.
395 * </p>
396 *
397 * <p>
398 * In secure mode, <code>YARN</code> verifies access to the application, queue
399 * etc. before accepting the request.
400 * </p>
401 *
402 * @param applicationAttemptId
403 * {@link ApplicationAttemptId} of the application attempt that needs
404 * a report
405 * @return application attempt report
406 * @throws YarnException
407 * @throws {@link ApplicationAttemptNotFoundException} if application attempt
408 * not found
409 * @throws IOException
410 */
411 public abstract ApplicationAttemptReport getApplicationAttemptReport(
412 ApplicationAttemptId applicationAttemptId) throws YarnException, IOException;
413
414 /**
415 * <p>
416 * Get a report of all (ApplicationAttempts) of Application in the cluster.
417 * </p>
418 *
419 * @param applicationId
420 * @return a list of reports for all application attempts for specified
421 * application.
422 * @throws YarnException
423 * @throws IOException
424 */
425 public abstract List<ApplicationAttemptReport> getApplicationAttempts(
426 ApplicationId applicationId) throws YarnException, IOException;
427
428 /**
429 * <p>
430 * Get a report of the given Container.
431 * </p>
432 *
433 * <p>
434 * In secure mode, <code>YARN</code> verifies access to the application, queue
435 * etc. before accepting the request.
436 * </p>
437 *
438 * @param containerId
439 * {@link ContainerId} of the container that needs a report
440 * @return container report
441 * @throws YarnException
442 * @throws {@link ContainerNotFoundException} if container not found.
443 * @throws IOException
444 */
445 public abstract ContainerReport getContainerReport(ContainerId containerId)
446 throws YarnException, IOException;
447
448 /**
449 * <p>
450 * Get a report of all (Containers) of ApplicationAttempt in the cluster.
451 * </p>
452 *
453 * @param applicationAttemptId
454 * @return a list of reports of all containers for specified application
455 * attempts
456 * @throws YarnException
457 * @throws IOException
458 */
459 public abstract List<ContainerReport> getContainers(
460 ApplicationAttemptId applicationAttemptId) throws YarnException,
461 IOException;
462
463 /**
464 * <p>
465 * Attempts to move the given application to the given queue.
466 * </p>
467 *
468 * @param appId
469 * Application to move.
470 * @param queue
471 * Queue to place it in to.
472 * @throws YarnException
473 * @throws IOException
474 */
475 public abstract void moveApplicationAcrossQueues(ApplicationId appId,
476 String queue) throws YarnException, IOException;
477 }