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.api;
020
021 import java.io.IOException;
022
023 import org.apache.hadoop.classification.InterfaceAudience.Private;
024 import org.apache.hadoop.classification.InterfaceAudience.Public;
025 import org.apache.hadoop.classification.InterfaceStability.Stable;
026 import org.apache.hadoop.classification.InterfaceStability.Unstable;
027 import org.apache.hadoop.io.retry.Idempotent;
028 import org.apache.hadoop.yarn.api.protocolrecords.CancelDelegationTokenRequest;
029 import org.apache.hadoop.yarn.api.protocolrecords.CancelDelegationTokenResponse;
030 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationAttemptReportRequest;
031 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationAttemptReportResponse;
032 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationAttemptsRequest;
033 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationAttemptsResponse;
034 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationsRequest;
035 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationsResponse;
036 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportRequest;
037 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportResponse;
038 import org.apache.hadoop.yarn.api.protocolrecords.GetClusterMetricsRequest;
039 import org.apache.hadoop.yarn.api.protocolrecords.GetClusterMetricsResponse;
040 import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodesRequest;
041 import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodesResponse;
042 import org.apache.hadoop.yarn.api.protocolrecords.GetContainerReportRequest;
043 import org.apache.hadoop.yarn.api.protocolrecords.GetContainerReportResponse;
044 import org.apache.hadoop.yarn.api.protocolrecords.GetContainersRequest;
045 import org.apache.hadoop.yarn.api.protocolrecords.GetContainersResponse;
046 import org.apache.hadoop.yarn.api.protocolrecords.GetDelegationTokenRequest;
047 import org.apache.hadoop.yarn.api.protocolrecords.GetDelegationTokenResponse;
048 import org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationRequest;
049 import org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationResponse;
050 import org.apache.hadoop.yarn.api.protocolrecords.GetQueueInfoRequest;
051 import org.apache.hadoop.yarn.api.protocolrecords.GetQueueInfoResponse;
052 import org.apache.hadoop.yarn.api.protocolrecords.GetQueueUserAclsInfoRequest;
053 import org.apache.hadoop.yarn.api.protocolrecords.GetQueueUserAclsInfoResponse;
054 import org.apache.hadoop.yarn.api.protocolrecords.KillApplicationRequest;
055 import org.apache.hadoop.yarn.api.protocolrecords.KillApplicationResponse;
056 import org.apache.hadoop.yarn.api.protocolrecords.MoveApplicationAcrossQueuesRequest;
057 import org.apache.hadoop.yarn.api.protocolrecords.MoveApplicationAcrossQueuesResponse;
058 import org.apache.hadoop.yarn.api.protocolrecords.RenewDelegationTokenRequest;
059 import org.apache.hadoop.yarn.api.protocolrecords.RenewDelegationTokenResponse;
060 import org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationRequest;
061 import org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationResponse;
062 import org.apache.hadoop.yarn.api.records.ApplicationAttemptId;
063 import org.apache.hadoop.yarn.api.records.ApplicationAttemptReport;
064 import org.apache.hadoop.yarn.api.records.ApplicationId;
065 import org.apache.hadoop.yarn.api.records.ApplicationReport;
066 import org.apache.hadoop.yarn.api.records.ContainerId;
067 import org.apache.hadoop.yarn.api.records.ContainerLaunchContext;
068 import org.apache.hadoop.yarn.api.records.ContainerReport;
069 import org.apache.hadoop.yarn.api.records.NodeReport;
070 import org.apache.hadoop.yarn.api.records.Resource;
071 import org.apache.hadoop.yarn.api.records.ResourceRequest;
072 import org.apache.hadoop.yarn.api.records.Token;
073 import org.apache.hadoop.yarn.api.records.YarnClusterMetrics;
074 import org.apache.hadoop.yarn.api.records.ApplicationSubmissionContext;
075 import org.apache.hadoop.yarn.exceptions.YarnException;
076 import org.apache.hadoop.yarn.exceptions.ApplicationNotFoundException;
077
078 /**
079 * <p>The protocol between clients and the <code>ResourceManager</code>
080 * to submit/abort jobs and to get information on applications, cluster metrics,
081 * nodes, queues and ACLs.</p>
082 */
083 @Public
084 @Stable
085 public interface ApplicationClientProtocol {
086 /**
087 * <p>The interface used by clients to obtain a new {@link ApplicationId} for
088 * submitting new applications.</p>
089 *
090 * <p>The <code>ResourceManager</code> responds with a new, monotonically
091 * increasing, {@link ApplicationId} which is used by the client to submit
092 * a new application.</p>
093 *
094 * <p>The <code>ResourceManager</code> also responds with details such
095 * as maximum resource capabilities in the cluster as specified in
096 * {@link GetNewApplicationResponse}.</p>
097 *
098 * @param request request to get a new <code>ApplicationId</code>
099 * @return response containing the new <code>ApplicationId</code> to be used
100 * to submit an application
101 * @throws YarnException
102 * @throws IOException
103 * @see #submitApplication(SubmitApplicationRequest)
104 */
105 @Public
106 @Stable
107 @Idempotent
108 public GetNewApplicationResponse getNewApplication(
109 GetNewApplicationRequest request)
110 throws YarnException, IOException;
111
112 /**
113 * <p>The interface used by clients to submit a new application to the
114 * <code>ResourceManager.</code></p>
115 *
116 * <p>The client is required to provide details such as queue,
117 * {@link Resource} required to run the <code>ApplicationMaster</code>,
118 * the equivalent of {@link ContainerLaunchContext} for launching
119 * the <code>ApplicationMaster</code> etc. via the
120 * {@link SubmitApplicationRequest}.</p>
121 *
122 * <p>Currently the <code>ResourceManager</code> sends an immediate (empty)
123 * {@link SubmitApplicationResponse} on accepting the submission and throws
124 * an exception if it rejects the submission. However, this call needs to be
125 * followed by {@link #getApplicationReport(GetApplicationReportRequest)}
126 * to make sure that the application gets properly submitted - obtaining a
127 * {@link SubmitApplicationResponse} from ResourceManager doesn't guarantee
128 * that RM 'remembers' this application beyond failover or restart. If RM
129 * failover or RM restart happens before ResourceManager saves the
130 * application's state successfully, the subsequent
131 * {@link #getApplicationReport(GetApplicationReportRequest)} will throw
132 * a {@link ApplicationNotFoundException}. The Clients need to re-submit
133 * the application with the same {@link ApplicationSubmissionContext} when
134 * it encounters the {@link ApplicationNotFoundException} on the
135 * {@link #getApplicationReport(GetApplicationReportRequest)} call.</p>
136 *
137 * <p>During the submission process, it checks whether the application
138 * already exists. If the application exists, it will simply return
139 * SubmitApplicationResponse</p>
140 *
141 * <p> In secure mode,the <code>ResourceManager</code> verifies access to
142 * queues etc. before accepting the application submission.</p>
143 *
144 * @param request request to submit a new application
145 * @return (empty) response on accepting the submission
146 * @throws YarnException
147 * @throws IOException
148 * @throws InvalidResourceRequestException
149 * The exception is thrown when a {@link ResourceRequest} is out of
150 * the range of the configured lower and upper resource boundaries.
151 * @see #getNewApplication(GetNewApplicationRequest)
152 */
153 @Public
154 @Stable
155 @Idempotent
156 public SubmitApplicationResponse submitApplication(
157 SubmitApplicationRequest request)
158 throws YarnException, IOException;
159
160 /**
161 * <p>The interface used by clients to request the
162 * <code>ResourceManager</code> to abort submitted application.</p>
163 *
164 * <p>The client, via {@link KillApplicationRequest} provides the
165 * {@link ApplicationId} of the application to be aborted.</p>
166 *
167 * <p> In secure mode,the <code>ResourceManager</code> verifies access to the
168 * application, queue etc. before terminating the application.</p>
169 *
170 * <p>Currently, the <code>ResourceManager</code> returns an empty response
171 * on success and throws an exception on rejecting the request.</p>
172 *
173 * @param request request to abort a submitted application
174 * @return <code>ResourceManager</code> returns an empty response
175 * on success and throws an exception on rejecting the request
176 * @throws YarnException
177 * @throws IOException
178 * @see #getQueueUserAcls(GetQueueUserAclsInfoRequest)
179 */
180 @Public
181 @Stable
182 @Idempotent
183 public KillApplicationResponse forceKillApplication(
184 KillApplicationRequest request)
185 throws YarnException, IOException;
186
187 /**
188 * <p>The interface used by clients to get a report of an Application from
189 * the <code>ResourceManager</code>.</p>
190 *
191 * <p>The client, via {@link GetApplicationReportRequest} provides the
192 * {@link ApplicationId} of the application.</p>
193 *
194 * <p> In secure mode,the <code>ResourceManager</code> verifies access to the
195 * application, queue etc. before accepting the request.</p>
196 *
197 * <p>The <code>ResourceManager</code> responds with a
198 * {@link GetApplicationReportResponse} which includes the
199 * {@link ApplicationReport} for the application.</p>
200 *
201 * <p>If the user does not have <code>VIEW_APP</code> access then the
202 * following fields in the report will be set to stubbed values:
203 * <ul>
204 * <li>host - set to "N/A"</li>
205 * <li>RPC port - set to -1</li>
206 * <li>client token - set to "N/A"</li>
207 * <li>diagnostics - set to "N/A"</li>
208 * <li>tracking URL - set to "N/A"</li>
209 * <li>original tracking URL - set to "N/A"</li>
210 * <li>resource usage report - all values are -1</li>
211 * </ul></p>
212 *
213 * @param request request for an application report
214 * @return application report
215 * @throws YarnException
216 * @throws IOException
217 */
218 @Public
219 @Stable
220 @Idempotent
221 public GetApplicationReportResponse getApplicationReport(
222 GetApplicationReportRequest request)
223 throws YarnException, IOException;
224
225 /**
226 * <p>The interface used by clients to get metrics about the cluster from
227 * the <code>ResourceManager</code>.</p>
228 *
229 * <p>The <code>ResourceManager</code> responds with a
230 * {@link GetClusterMetricsResponse} which includes the
231 * {@link YarnClusterMetrics} with details such as number of current
232 * nodes in the cluster.</p>
233 *
234 * @param request request for cluster metrics
235 * @return cluster metrics
236 * @throws YarnException
237 * @throws IOException
238 */
239 @Public
240 @Stable
241 @Idempotent
242 public GetClusterMetricsResponse getClusterMetrics(
243 GetClusterMetricsRequest request)
244 throws YarnException, IOException;
245
246 /**
247 * <p>The interface used by clients to get a report of Applications
248 * matching the filters defined by {@link GetApplicationsRequest}
249 * in the cluster from the <code>ResourceManager</code>.</p>
250 *
251 * <p>The <code>ResourceManager</code> responds with a
252 * {@link GetApplicationsResponse} which includes the
253 * {@link ApplicationReport} for the applications.</p>
254 *
255 * <p>If the user does not have <code>VIEW_APP</code> access for an
256 * application then the corresponding report will be filtered as
257 * described in {@link #getApplicationReport(GetApplicationReportRequest)}.
258 * </p>
259 *
260 * @param request request for report on applications
261 * @return report on applications matching the given application types
262 * defined in the request
263 * @throws YarnException
264 * @throws IOException
265 * @see GetApplicationsRequest
266 */
267 @Public
268 @Stable
269 @Idempotent
270 public GetApplicationsResponse getApplications(
271 GetApplicationsRequest request)
272 throws YarnException, IOException;
273
274 /**
275 * <p>The interface used by clients to get a report of all nodes
276 * in the cluster from the <code>ResourceManager</code>.</p>
277 *
278 * <p>The <code>ResourceManager</code> responds with a
279 * {@link GetClusterNodesResponse} which includes the
280 * {@link NodeReport} for all the nodes in the cluster.</p>
281 *
282 * @param request request for report on all nodes
283 * @return report on all nodes
284 * @throws YarnException
285 * @throws IOException
286 */
287 @Public
288 @Stable
289 @Idempotent
290 public GetClusterNodesResponse getClusterNodes(
291 GetClusterNodesRequest request)
292 throws YarnException, IOException;
293
294 /**
295 * <p>The interface used by clients to get information about <em>queues</em>
296 * from the <code>ResourceManager</code>.</p>
297 *
298 * <p>The client, via {@link GetQueueInfoRequest}, can ask for details such
299 * as used/total resources, child queues, running applications etc.</p>
300 *
301 * <p> In secure mode,the <code>ResourceManager</code> verifies access before
302 * providing the information.</p>
303 *
304 * @param request request to get queue information
305 * @return queue information
306 * @throws YarnException
307 * @throws IOException
308 */
309 @Public
310 @Stable
311 @Idempotent
312 public GetQueueInfoResponse getQueueInfo(
313 GetQueueInfoRequest request)
314 throws YarnException, IOException;
315
316 /**
317 * <p>The interface used by clients to get information about <em>queue
318 * acls</em> for <em>current user</em> from the <code>ResourceManager</code>.
319 * </p>
320 *
321 * <p>The <code>ResourceManager</code> responds with queue acls for all
322 * existing queues.</p>
323 *
324 * @param request request to get queue acls for <em>current user</em>
325 * @return queue acls for <em>current user</em>
326 * @throws YarnException
327 * @throws IOException
328 */
329 @Public
330 @Stable
331 @Idempotent
332 public GetQueueUserAclsInfoResponse getQueueUserAcls(
333 GetQueueUserAclsInfoRequest request)
334 throws YarnException, IOException;
335
336 /**
337 * <p>The interface used by clients to get delegation token, enabling the
338 * containers to be able to talk to the service using those tokens.
339 *
340 * <p> The <code>ResourceManager</code> responds with the delegation
341 * {@link Token} that can be used by the client to speak to this
342 * service.
343 * @param request request to get a delegation token for the client.
344 * @return delegation token that can be used to talk to this service
345 * @throws YarnException
346 * @throws IOException
347 */
348 @Public
349 @Stable
350 @Idempotent
351 public GetDelegationTokenResponse getDelegationToken(
352 GetDelegationTokenRequest request)
353 throws YarnException, IOException;
354
355 /**
356 * Renew an existing delegation {@link Token}.
357 *
358 * @param request the delegation token to be renewed.
359 * @return the new expiry time for the delegation token.
360 * @throws YarnException
361 * @throws IOException
362 */
363 @Private
364 @Unstable
365 @Idempotent
366 public RenewDelegationTokenResponse renewDelegationToken(
367 RenewDelegationTokenRequest request) throws YarnException,
368 IOException;
369
370 /**
371 * Cancel an existing delegation {@link Token}.
372 *
373 * @param request the delegation token to be cancelled.
374 * @return an empty response.
375 * @throws YarnException
376 * @throws IOException
377 */
378 @Private
379 @Unstable
380 @Idempotent
381 public CancelDelegationTokenResponse cancelDelegationToken(
382 CancelDelegationTokenRequest request) throws YarnException,
383 IOException;
384
385 /**
386 * Move an application to a new queue.
387 *
388 * @param request the application ID and the target queue
389 * @return an empty response
390 * @throws YarnException
391 * @throws IOException
392 */
393 @Public
394 @Unstable
395 @Idempotent
396 public MoveApplicationAcrossQueuesResponse moveApplicationAcrossQueues(
397 MoveApplicationAcrossQueuesRequest request) throws YarnException, IOException;
398
399 /**
400 * <p>
401 * The interface used by clients to get a report of an Application Attempt
402 * from the <code>ResourceManager</code>
403 * </p>
404 *
405 * <p>
406 * The client, via {@link GetApplicationAttemptReportRequest} provides the
407 * {@link ApplicationAttemptId} of the application attempt.
408 * </p>
409 *
410 * <p>
411 * In secure mode,the <code>ResourceManager</code> verifies access to
412 * the method before accepting the request.
413 * </p>
414 *
415 * <p>
416 * The <code>ResourceManager</code> responds with a
417 * {@link GetApplicationAttemptReportResponse} which includes the
418 * {@link ApplicationAttemptReport} for the application attempt.
419 * </p>
420 *
421 * <p>
422 * If the user does not have <code>VIEW_APP</code> access then the following
423 * fields in the report will be set to stubbed values:
424 * <ul>
425 * <li>host</li>
426 * <li>RPC port</li>
427 * <li>client token</li>
428 * <li>diagnostics - set to "N/A"</li>
429 * <li>tracking URL</li>
430 * </ul>
431 * </p>
432 *
433 * @param request
434 * request for an application attempt report
435 * @return application attempt report
436 * @throws YarnException
437 * @throws IOException
438 */
439 @Public
440 @Unstable
441 @Idempotent
442 public GetApplicationAttemptReportResponse getApplicationAttemptReport(
443 GetApplicationAttemptReportRequest request) throws YarnException,
444 IOException;
445
446 /**
447 * <p>
448 * The interface used by clients to get a report of all Application attempts
449 * in the cluster from the <code>ResourceManager</code>
450 * </p>
451 *
452 * <p>
453 * The <code>ResourceManager</code> responds with a
454 * {@link GetApplicationAttemptsRequest} which includes the
455 * {@link ApplicationAttemptReport} for all the applications attempts of a
456 * specified application attempt.
457 * </p>
458 *
459 * <p>
460 * If the user does not have <code>VIEW_APP</code> access for an application
461 * then the corresponding report will be filtered as described in
462 * {@link #getApplicationAttemptReport(GetApplicationAttemptReportRequest)}.
463 * </p>
464 *
465 * @param request
466 * request for reports on all application attempts of an application
467 * @return reports on all application attempts of an application
468 * @throws YarnException
469 * @throws IOException
470 */
471 @Public
472 @Unstable
473 @Idempotent
474 public GetApplicationAttemptsResponse getApplicationAttempts(
475 GetApplicationAttemptsRequest request) throws YarnException, IOException;
476
477 /**
478 * <p>
479 * The interface used by clients to get a report of an Container from the
480 * <code>ResourceManager</code>
481 * </p>
482 *
483 * <p>
484 * The client, via {@link GetContainerReportRequest} provides the
485 * {@link ContainerId} of the container.
486 * </p>
487 *
488 * <p>
489 * In secure mode,the <code>ResourceManager</code> verifies access to the
490 * method before accepting the request.
491 * </p>
492 *
493 * <p>
494 * The <code>ResourceManager</code> responds with a
495 * {@link GetContainerReportResponse} which includes the
496 * {@link ContainerReport} for the container.
497 * </p>
498 *
499 * @param request
500 * request for a container report
501 * @return container report
502 * @throws YarnException
503 * @throws IOException
504 */
505 @Public
506 @Unstable
507 @Idempotent
508 public GetContainerReportResponse getContainerReport(
509 GetContainerReportRequest request) throws YarnException, IOException;
510
511 /**
512 * <p>
513 * The interface used by clients to get a report of Containers for an
514 * application attempt from the <code>ResourceManager</code>
515 * </p>
516 *
517 * <p>
518 * The client, via {@link GetContainersRequest} provides the
519 * {@link ApplicationAttemptId} of the application attempt.
520 * </p>
521 *
522 * <p>
523 * In secure mode,the <code>ResourceManager</code> verifies access to the
524 * method before accepting the request.
525 * </p>
526 *
527 * <p>
528 * The <code>ResourceManager</code> responds with a
529 * {@link GetContainersResponse} which includes a list of
530 * {@link ContainerReport} for all the containers of a specific application
531 * attempt.
532 * </p>
533 *
534 * @param request
535 * request for a list of container reports of an application attempt.
536 * @return reports on all containers of an application attempt
537 * @throws YarnException
538 * @throws IOException
539 */
540 @Public
541 @Unstable
542 @Idempotent
543 public GetContainersResponse getContainers(GetContainersRequest request)
544 throws YarnException, IOException;
545
546 }