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 019package org.apache.hadoop.yarn.api; 020 021import java.io.IOException; 022 023import org.apache.hadoop.classification.InterfaceAudience.Public; 024import org.apache.hadoop.classification.InterfaceStability.Stable; 025import org.apache.hadoop.classification.InterfaceStability.Unstable; 026import org.apache.hadoop.io.retry.Idempotent; 027import org.apache.hadoop.yarn.api.protocolrecords.FailApplicationAttemptRequest; 028import org.apache.hadoop.yarn.api.protocolrecords.FailApplicationAttemptResponse; 029import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportRequest; 030import org.apache.hadoop.yarn.api.protocolrecords.GetClusterMetricsRequest; 031import org.apache.hadoop.yarn.api.protocolrecords.GetClusterMetricsResponse; 032import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodeLabelsRequest; 033import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodeLabelsResponse; 034import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodesRequest; 035import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodesResponse; 036import org.apache.hadoop.yarn.api.protocolrecords.GetLabelsToNodesRequest; 037import org.apache.hadoop.yarn.api.protocolrecords.GetLabelsToNodesResponse; 038import org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationRequest; 039import org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationResponse; 040import org.apache.hadoop.yarn.api.protocolrecords.GetNewReservationRequest; 041import org.apache.hadoop.yarn.api.protocolrecords.GetNewReservationResponse; 042import org.apache.hadoop.yarn.api.protocolrecords.GetNodesToLabelsRequest; 043import org.apache.hadoop.yarn.api.protocolrecords.GetNodesToLabelsResponse; 044import org.apache.hadoop.yarn.api.protocolrecords.GetQueueInfoRequest; 045import org.apache.hadoop.yarn.api.protocolrecords.GetQueueInfoResponse; 046import org.apache.hadoop.yarn.api.protocolrecords.GetQueueUserAclsInfoRequest; 047import org.apache.hadoop.yarn.api.protocolrecords.GetQueueUserAclsInfoResponse; 048import org.apache.hadoop.yarn.api.protocolrecords.KillApplicationRequest; 049import org.apache.hadoop.yarn.api.protocolrecords.KillApplicationResponse; 050import org.apache.hadoop.yarn.api.protocolrecords.MoveApplicationAcrossQueuesRequest; 051import org.apache.hadoop.yarn.api.protocolrecords.MoveApplicationAcrossQueuesResponse; 052import org.apache.hadoop.yarn.api.protocolrecords.ReservationDeleteRequest; 053import org.apache.hadoop.yarn.api.protocolrecords.ReservationDeleteResponse; 054import org.apache.hadoop.yarn.api.protocolrecords.ReservationListRequest; 055import org.apache.hadoop.yarn.api.protocolrecords.ReservationListResponse; 056import org.apache.hadoop.yarn.api.protocolrecords.ReservationSubmissionRequest; 057import org.apache.hadoop.yarn.api.protocolrecords.ReservationSubmissionResponse; 058import org.apache.hadoop.yarn.api.protocolrecords.ReservationUpdateRequest; 059import org.apache.hadoop.yarn.api.protocolrecords.ReservationUpdateResponse; 060import org.apache.hadoop.yarn.api.protocolrecords.UpdateApplicationPriorityRequest; 061import org.apache.hadoop.yarn.api.protocolrecords.UpdateApplicationPriorityResponse; 062import org.apache.hadoop.yarn.api.protocolrecords.SignalContainerRequest; 063import org.apache.hadoop.yarn.api.protocolrecords.SignalContainerResponse; 064import org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationRequest; 065import org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationResponse; 066import org.apache.hadoop.yarn.api.records.ApplicationAttemptId; 067import org.apache.hadoop.yarn.api.records.ApplicationId; 068import org.apache.hadoop.yarn.api.records.ApplicationSubmissionContext; 069import org.apache.hadoop.yarn.api.records.ContainerLaunchContext; 070import org.apache.hadoop.yarn.api.records.NodeReport; 071import org.apache.hadoop.yarn.api.records.ReservationId; 072import org.apache.hadoop.yarn.api.records.Resource; 073import org.apache.hadoop.yarn.api.records.YarnClusterMetrics; 074import org.apache.hadoop.yarn.exceptions.ApplicationNotFoundException; 075import org.apache.hadoop.yarn.exceptions.YarnException; 076 077/** 078 * <p>The protocol between clients and the <code>ResourceManager</code> 079 * to submit/abort jobs and to get information on applications, cluster metrics, 080 * nodes, queues and ACLs.</p> 081 */ 082@Public 083@Stable 084public interface ApplicationClientProtocol extends ApplicationBaseProtocol { 085 /** 086 * <p>The interface used by clients to obtain a new {@link ApplicationId} for 087 * submitting new applications.</p> 088 * 089 * <p>The <code>ResourceManager</code> responds with a new, monotonically 090 * increasing, {@link ApplicationId} which is used by the client to submit 091 * a new application.</p> 092 * 093 * <p>The <code>ResourceManager</code> also responds with details such 094 * as maximum resource capabilities in the cluster as specified in 095 * {@link GetNewApplicationResponse}.</p> 096 * 097 * @param request request to get a new <code>ApplicationId</code> 098 * @return response containing the new <code>ApplicationId</code> to be used 099 * to submit an application 100 * @throws YarnException 101 * @throws IOException 102 * @see #submitApplication(SubmitApplicationRequest) 103 */ 104 @Public 105 @Stable 106 @Idempotent 107 public GetNewApplicationResponse getNewApplication( 108 GetNewApplicationRequest request) 109 throws YarnException, IOException; 110 111 /** 112 * <p>The interface used by clients to submit a new application to the 113 * <code>ResourceManager.</code></p> 114 * 115 * <p>The client is required to provide details such as queue, 116 * {@link Resource} required to run the <code>ApplicationMaster</code>, 117 * the equivalent of {@link ContainerLaunchContext} for launching 118 * the <code>ApplicationMaster</code> etc. via the 119 * {@link SubmitApplicationRequest}.</p> 120 * 121 * <p>Currently the <code>ResourceManager</code> sends an immediate (empty) 122 * {@link SubmitApplicationResponse} on accepting the submission and throws 123 * an exception if it rejects the submission. However, this call needs to be 124 * followed by {@link #getApplicationReport(GetApplicationReportRequest)} 125 * to make sure that the application gets properly submitted - obtaining a 126 * {@link SubmitApplicationResponse} from ResourceManager doesn't guarantee 127 * that RM 'remembers' this application beyond failover or restart. If RM 128 * failover or RM restart happens before ResourceManager saves the 129 * application's state successfully, the subsequent 130 * {@link #getApplicationReport(GetApplicationReportRequest)} will throw 131 * a {@link ApplicationNotFoundException}. The Clients need to re-submit 132 * the application with the same {@link ApplicationSubmissionContext} when 133 * it encounters the {@link ApplicationNotFoundException} on the 134 * {@link #getApplicationReport(GetApplicationReportRequest)} call.</p> 135 * 136 * <p>During the submission process, it checks whether the application 137 * already exists. If the application exists, it will simply return 138 * SubmitApplicationResponse</p> 139 * 140 * <p> In secure mode,the <code>ResourceManager</code> verifies access to 141 * queues etc. before accepting the application submission.</p> 142 * 143 * @param request request to submit a new application 144 * @return (empty) response on accepting the submission 145 * @throws YarnException 146 * @throws IOException 147 * @see #getNewApplication(GetNewApplicationRequest) 148 */ 149 @Public 150 @Stable 151 @Idempotent 152 public SubmitApplicationResponse submitApplication( 153 SubmitApplicationRequest request) 154 throws YarnException, IOException; 155 156 /** 157 * <p>The interface used by clients to request the 158 * <code>ResourceManager</code> to fail an application attempt.</p> 159 * 160 * <p>The client, via {@link FailApplicationAttemptRequest} provides the 161 * {@link ApplicationAttemptId} of the attempt to be failed.</p> 162 * 163 * <p> In secure mode,the <code>ResourceManager</code> verifies access to the 164 * application, queue etc. before failing the attempt.</p> 165 * 166 * <p>Currently, the <code>ResourceManager</code> returns an empty response 167 * on success and throws an exception on rejecting the request.</p> 168 * 169 * @param request request to fail an attempt 170 * @return <code>ResourceManager</code> returns an empty response 171 * on success and throws an exception on rejecting the request 172 * @throws YarnException 173 * @throws IOException 174 * @see #getQueueUserAcls(GetQueueUserAclsInfoRequest) 175 */ 176 @Public 177 @Unstable 178 public FailApplicationAttemptResponse failApplicationAttempt( 179 FailApplicationAttemptRequest request) 180 throws YarnException, IOException; 181 182 /** 183 * <p>The interface used by clients to request the 184 * <code>ResourceManager</code> to abort submitted application.</p> 185 * 186 * <p>The client, via {@link KillApplicationRequest} provides the 187 * {@link ApplicationId} of the application to be aborted.</p> 188 * 189 * <p> In secure mode,the <code>ResourceManager</code> verifies access to the 190 * application, queue etc. before terminating the application.</p> 191 * 192 * <p>Currently, the <code>ResourceManager</code> returns an empty response 193 * on success and throws an exception on rejecting the request.</p> 194 * 195 * @param request request to abort a submitted application 196 * @return <code>ResourceManager</code> returns an empty response 197 * on success and throws an exception on rejecting the request 198 * @throws YarnException 199 * @throws IOException 200 * @see #getQueueUserAcls(GetQueueUserAclsInfoRequest) 201 */ 202 @Public 203 @Stable 204 @Idempotent 205 public KillApplicationResponse forceKillApplication( 206 KillApplicationRequest request) 207 throws YarnException, IOException; 208 209 /** 210 * <p>The interface used by clients to get metrics about the cluster from 211 * the <code>ResourceManager</code>.</p> 212 * 213 * <p>The <code>ResourceManager</code> responds with a 214 * {@link GetClusterMetricsResponse} which includes the 215 * {@link YarnClusterMetrics} with details such as number of current 216 * nodes in the cluster.</p> 217 * 218 * @param request request for cluster metrics 219 * @return cluster metrics 220 * @throws YarnException 221 * @throws IOException 222 */ 223 @Public 224 @Stable 225 @Idempotent 226 public GetClusterMetricsResponse getClusterMetrics( 227 GetClusterMetricsRequest request) 228 throws YarnException, IOException; 229 230 /** 231 * <p>The interface used by clients to get a report of all nodes 232 * in the cluster from the <code>ResourceManager</code>.</p> 233 * 234 * <p>The <code>ResourceManager</code> responds with a 235 * {@link GetClusterNodesResponse} which includes the 236 * {@link NodeReport} for all the nodes in the cluster.</p> 237 * 238 * @param request request for report on all nodes 239 * @return report on all nodes 240 * @throws YarnException 241 * @throws IOException 242 */ 243 @Public 244 @Stable 245 @Idempotent 246 public GetClusterNodesResponse getClusterNodes( 247 GetClusterNodesRequest request) 248 throws YarnException, IOException; 249 250 /** 251 * <p>The interface used by clients to get information about <em>queues</em> 252 * from the <code>ResourceManager</code>.</p> 253 * 254 * <p>The client, via {@link GetQueueInfoRequest}, can ask for details such 255 * as used/total resources, child queues, running applications etc.</p> 256 * 257 * <p> In secure mode,the <code>ResourceManager</code> verifies access before 258 * providing the information.</p> 259 * 260 * @param request request to get queue information 261 * @return queue information 262 * @throws YarnException 263 * @throws IOException 264 */ 265 @Public 266 @Stable 267 @Idempotent 268 public GetQueueInfoResponse getQueueInfo( 269 GetQueueInfoRequest request) 270 throws YarnException, IOException; 271 272 /** 273 * <p>The interface used by clients to get information about <em>queue 274 * acls</em> for <em>current user</em> from the <code>ResourceManager</code>. 275 * </p> 276 * 277 * <p>The <code>ResourceManager</code> responds with queue acls for all 278 * existing queues.</p> 279 * 280 * @param request request to get queue acls for <em>current user</em> 281 * @return queue acls for <em>current user</em> 282 * @throws YarnException 283 * @throws IOException 284 */ 285 @Public 286 @Stable 287 @Idempotent 288 public GetQueueUserAclsInfoResponse getQueueUserAcls( 289 GetQueueUserAclsInfoRequest request) 290 throws YarnException, IOException; 291 292 /** 293 * Move an application to a new queue. 294 * 295 * @param request the application ID and the target queue 296 * @return an empty response 297 * @throws YarnException 298 * @throws IOException 299 */ 300 @Public 301 @Unstable 302 @Idempotent 303 public MoveApplicationAcrossQueuesResponse moveApplicationAcrossQueues( 304 MoveApplicationAcrossQueuesRequest request) throws YarnException, IOException; 305 306 /** 307 * <p>The interface used by clients to obtain a new {@link ReservationId} for 308 * submitting new reservations.</p> 309 * 310 * <p>The <code>ResourceManager</code> responds with a new, unique, 311 * {@link ReservationId} which is used by the client to submit 312 * a new reservation.</p> 313 * 314 * @param request to get a new <code>ReservationId</code> 315 * @return response containing the new <code>ReservationId</code> to be used 316 * to submit a new reservation 317 * @throws YarnException if the reservation system is not enabled. 318 * @throws IOException on IO failures. 319 * @see #submitReservation(ReservationSubmissionRequest) 320 */ 321 @Public 322 @Unstable 323 @Idempotent 324 GetNewReservationResponse getNewReservation( 325 GetNewReservationRequest request) 326 throws YarnException, IOException; 327 328 /** 329 * <p> 330 * The interface used by clients to submit a new reservation to the 331 * {@code ResourceManager}. 332 * </p> 333 * 334 * <p> 335 * The client packages all details of its request in a 336 * {@link ReservationSubmissionRequest} object. This contains information 337 * about the amount of capacity, temporal constraints, and concurrency needs. 338 * Furthermore, the reservation might be composed of multiple stages, with 339 * ordering dependencies among them. 340 * </p> 341 * 342 * <p> 343 * In order to respond, a new admission control component in the 344 * {@code ResourceManager} performs an analysis of the resources that have 345 * been committed over the period of time the user is requesting, verify that 346 * the user requests can be fulfilled, and that it respect a sharing policy 347 * (e.g., {@code CapacityOverTimePolicy}). Once it has positively determined 348 * that the ReservationSubmissionRequest is satisfiable the 349 * {@code ResourceManager} answers with a 350 * {@link ReservationSubmissionResponse} that include a non-null 351 * {@link ReservationId}. Upon failure to find a valid allocation the response 352 * is an exception with the reason. 353 * 354 * On application submission the client can use this {@link ReservationId} to 355 * obtain access to the reserved resources. 356 * </p> 357 * 358 * <p> 359 * The system guarantees that during the time-range specified by the user, the 360 * reservationID will be corresponding to a valid reservation. The amount of 361 * capacity dedicated to such queue can vary overtime, depending of the 362 * allocation that has been determined. But it is guaranteed to satisfy all 363 * the constraint expressed by the user in the 364 * {@link ReservationSubmissionRequest}. 365 * </p> 366 * 367 * @param request the request to submit a new Reservation 368 * @return response the {@link ReservationId} on accepting the submission 369 * @throws YarnException if the request is invalid or reservation cannot be 370 * created successfully 371 * @throws IOException 372 * 373 */ 374 @Public 375 @Unstable 376 @Idempotent 377 public ReservationSubmissionResponse submitReservation( 378 ReservationSubmissionRequest request) throws YarnException, IOException; 379 380 /** 381 * <p> 382 * The interface used by clients to update an existing Reservation. This is 383 * referred to as a re-negotiation process, in which a user that has 384 * previously submitted a Reservation. 385 * </p> 386 * 387 * <p> 388 * The allocation is attempted by virtually substituting all previous 389 * allocations related to this Reservation with new ones, that satisfy the new 390 * {@link ReservationUpdateRequest}. Upon success the previous allocation is 391 * substituted by the new one, and on failure (i.e., if the system cannot find 392 * a valid allocation for the updated request), the previous allocation 393 * remains valid. 394 * 395 * The {@link ReservationId} is not changed, and applications currently 396 * running within this reservation will automatically receive the resources 397 * based on the new allocation. 398 * </p> 399 * 400 * @param request to update an existing Reservation (the ReservationRequest 401 * should refer to an existing valid {@link ReservationId}) 402 * @return response empty on successfully updating the existing reservation 403 * @throws YarnException if the request is invalid or reservation cannot be 404 * updated successfully 405 * @throws IOException 406 * 407 */ 408 @Public 409 @Unstable 410 public ReservationUpdateResponse updateReservation( 411 ReservationUpdateRequest request) throws YarnException, IOException; 412 413 /** 414 * <p> 415 * The interface used by clients to remove an existing Reservation. 416 * 417 * Upon deletion of a reservation applications running with this reservation, 418 * are automatically downgraded to normal jobs running without any dedicated 419 * reservation. 420 * </p> 421 * 422 * @param request to remove an existing Reservation (the ReservationRequest 423 * should refer to an existing valid {@link ReservationId}) 424 * @return response empty on successfully deleting the existing reservation 425 * @throws YarnException if the request is invalid or reservation cannot be 426 * deleted successfully 427 * @throws IOException 428 * 429 */ 430 @Public 431 @Unstable 432 public ReservationDeleteResponse deleteReservation( 433 ReservationDeleteRequest request) throws YarnException, IOException; 434 435 /** 436 * <p> 437 * The interface used by clients to get the list of reservations in a plan. 438 * The reservationId will be used to search for reservations to list if it is 439 * provided. Otherwise, it will select active reservations within the 440 * startTime and endTime (inclusive). 441 * </p> 442 * 443 * @param request to list reservations in a plan. Contains fields to select 444 * String queue, ReservationId reservationId, long startTime, 445 * long endTime, and a bool includeReservationAllocations. 446 * 447 * queue: Required. Cannot be null or empty. Refers to the 448 * reservable queue in the scheduler that was selected when 449 * creating a reservation submission 450 * {@link ReservationSubmissionRequest}. 451 * 452 * reservationId: Optional. If provided, other fields will 453 * be ignored. 454 * 455 * startTime: Optional. If provided, only reservations that 456 * end after the startTime will be selected. This defaults 457 * to 0 if an invalid number is used. 458 * 459 * endTime: Optional. If provided, only reservations that 460 * start on or before endTime will be selected. This defaults 461 * to Long.MAX_VALUE if an invalid number is used. 462 * 463 * includeReservationAllocations: Optional. Flag that 464 * determines whether the entire reservation allocations are 465 * to be returned. Reservation allocations are subject to 466 * change in the event of re-planning as described by 467 * {@code ReservationDefinition}. 468 * 469 * @return response that contains information about reservations that are 470 * being searched for. 471 * @throws YarnException if the request is invalid 472 * @throws IOException on IO failures 473 * 474 */ 475 @Public 476 @Unstable 477 ReservationListResponse listReservations( 478 ReservationListRequest request) throws YarnException, IOException; 479 480 /** 481 * <p> 482 * The interface used by client to get node to labels mappings in existing cluster 483 * </p> 484 * 485 * @param request 486 * @return node to labels mappings 487 * @throws YarnException 488 * @throws IOException 489 */ 490 @Public 491 @Unstable 492 public GetNodesToLabelsResponse getNodeToLabels( 493 GetNodesToLabelsRequest request) throws YarnException, IOException; 494 495 /** 496 * <p> 497 * The interface used by client to get labels to nodes mappings 498 * in existing cluster 499 * </p> 500 * 501 * @param request 502 * @return labels to nodes mappings 503 * @throws YarnException 504 * @throws IOException 505 */ 506 @Public 507 @Unstable 508 public GetLabelsToNodesResponse getLabelsToNodes( 509 GetLabelsToNodesRequest request) throws YarnException, IOException; 510 511 /** 512 * <p> 513 * The interface used by client to get node labels in the cluster 514 * </p> 515 * 516 * @param request to get node labels collection of this cluster 517 * @return node labels collection of this cluster 518 * @throws YarnException 519 * @throws IOException 520 */ 521 @Public 522 @Unstable 523 public GetClusterNodeLabelsResponse getClusterNodeLabels( 524 GetClusterNodeLabelsRequest request) throws YarnException, IOException; 525 526 /** 527 * <p> 528 * The interface used by client to set priority of an application. 529 * </p> 530 * @param request to set priority of an application 531 * @return an empty response 532 * @throws YarnException 533 * @throws IOException 534 */ 535 @Public 536 @Unstable 537 @Idempotent 538 public UpdateApplicationPriorityResponse updateApplicationPriority( 539 UpdateApplicationPriorityRequest request) throws YarnException, 540 IOException; 541 542 /** 543 * <p>The interface used by clients to request the 544 * <code>ResourceManager</code> to signal a container. For example, 545 * the client can send command OUTPUT_THREAD_DUMP to dump threads of the 546 * container.</p> 547 * 548 * <p>The client, via {@link SignalContainerRequest} provides the 549 * id of the container and the signal command. </p> 550 * 551 * <p> In secure mode,the <code>ResourceManager</code> verifies access to the 552 * application before signaling the container. 553 * The user needs to have <code>MODIFY_APP</code> permission.</p> 554 * 555 * <p>Currently, the <code>ResourceManager</code> returns an empty response 556 * on success and throws an exception on rejecting the request.</p> 557 * 558 * @param request request to signal a container 559 * @return <code>ResourceManager</code> returns an empty response 560 * on success and throws an exception on rejecting the request 561 * @throws YarnException 562 * @throws IOException 563 */ 564 @Public 565 @Unstable 566 SignalContainerResponse signalToContainer( 567 SignalContainerRequest request) throws YarnException, 568 IOException; 569}