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 }