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 org.apache.hadoop.classification.InterfaceAudience.Public; 022 import org.apache.hadoop.classification.InterfaceStability.Stable; 023 024 import org.apache.hadoop.yarn.api.protocolrecords.GetDelegationTokenRequest; 025 import org.apache.hadoop.yarn.api.protocolrecords.GetDelegationTokenResponse; 026 import org.apache.hadoop.yarn.api.protocolrecords.KillApplicationRequest; 027 import org.apache.hadoop.yarn.api.protocolrecords.KillApplicationResponse; 028 import org.apache.hadoop.yarn.api.protocolrecords.GetAllApplicationsRequest; 029 import org.apache.hadoop.yarn.api.protocolrecords.GetAllApplicationsResponse; 030 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportRequest; 031 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportResponse; 032 import org.apache.hadoop.yarn.api.protocolrecords.GetClusterMetricsRequest; 033 import org.apache.hadoop.yarn.api.protocolrecords.GetClusterMetricsResponse; 034 import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodesRequest; 035 import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodesResponse; 036 import org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationRequest; 037 import org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationResponse; 038 import org.apache.hadoop.yarn.api.protocolrecords.GetQueueInfoRequest; 039 import org.apache.hadoop.yarn.api.protocolrecords.GetQueueInfoResponse; 040 import org.apache.hadoop.yarn.api.protocolrecords.GetQueueUserAclsInfoRequest; 041 import org.apache.hadoop.yarn.api.protocolrecords.GetQueueUserAclsInfoResponse; 042 import org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationRequest; 043 import org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationResponse; 044 import org.apache.hadoop.yarn.api.records.ApplicationId; 045 import org.apache.hadoop.yarn.api.records.ApplicationReport; 046 import org.apache.hadoop.yarn.api.records.ContainerLaunchContext; 047 import org.apache.hadoop.yarn.api.records.NodeReport; 048 import org.apache.hadoop.yarn.api.records.DelegationToken; 049 import org.apache.hadoop.yarn.api.records.Resource; 050 import org.apache.hadoop.yarn.api.records.YarnClusterMetrics; 051 import org.apache.hadoop.yarn.exceptions.YarnRemoteException; 052 053 /** 054 * <p>The protocol between clients and the <code>ResourceManager</code> 055 * to submit/abort jobs and to get information on applications, cluster metrics, 056 * nodes, queues and ACLs.</p> 057 */ 058 @Public 059 @Stable 060 public interface ClientRMProtocol { 061 /** 062 * <p>The interface used by clients to obtain a new {@link ApplicationId} for 063 * submitting new applications.</p> 064 * 065 * <p>The <code>ResourceManager</code> responds with a new, monotonically 066 * increasing, {@link ApplicationId} which is used by the client to submit 067 * a new application.</p> 068 * 069 * <p>The <code>ResourceManager</code> also responds with details such 070 * as minimum and maximum resource capabilities in the cluster as specified in 071 * {@link GetNewApplicationResponse}.</p> 072 * 073 * @param request request to get a new <code>ApplicationId</code> 074 * @return response containing the new <code>ApplicationId</code> to be used 075 * to submit an application 076 * @throws YarnRemoteException 077 * @see #submitApplication(SubmitApplicationRequest) 078 */ 079 public GetNewApplicationResponse getNewApplication( 080 GetNewApplicationRequest request) 081 throws YarnRemoteException; 082 083 /** 084 * <p>The interface used by clients to submit a new application to the 085 * <code>ResourceManager.</code></p> 086 * 087 * <p>The client is required to provide details such as queue, 088 * {@link Resource} required to run the <code>ApplicationMaster</code>, 089 * the equivalent of {@link ContainerLaunchContext} for launching 090 * the <code>ApplicationMaster</code> etc. via the 091 * {@link SubmitApplicationRequest}.</p> 092 * 093 * <p>Currently the <code>ResourceManager</code> sends an immediate (empty) 094 * {@link SubmitApplicationResponse} on accepting the submission and throws 095 * an exception if it rejects the submission.</p> 096 * 097 * <p> In secure mode,the <code>ResourceManager</code> verifies access to 098 * queues etc. before accepting the application submission.</p> 099 * 100 * @param request request to submit a new application 101 * @return (empty) response on accepting the submission 102 * @throws YarnRemoteException 103 * @see #getNewApplication(GetNewApplicationRequest) 104 */ 105 public SubmitApplicationResponse submitApplication( 106 SubmitApplicationRequest request) 107 throws YarnRemoteException; 108 109 /** 110 * <p>The interface used by clients to request the 111 * <code>ResourceManager</code> to abort submitted application.</p> 112 * 113 * <p>The client, via {@link KillApplicationRequest} provides the 114 * {@link ApplicationId} of the application to be aborted.</p> 115 * 116 * <p> In secure mode,the <code>ResourceManager</code> verifies access to the 117 * application, queue etc. before terminating the application.</p> 118 * 119 * <p>Currently, the <code>ResourceManager</code> returns an empty response 120 * on success and throws an exception on rejecting the request.</p> 121 * 122 * @param request request to abort a submited application 123 * @return <code>ResourceManager</code> returns an empty response 124 * on success and throws an exception on rejecting the request 125 * @throws YarnRemoteException 126 * @see #getQueueUserAcls(GetQueueUserAclsInfoRequest) 127 */ 128 public KillApplicationResponse forceKillApplication( 129 KillApplicationRequest request) 130 throws YarnRemoteException; 131 132 /** 133 * <p>The interface used by clients to get a report of an Application from 134 * the <code>ResourceManager</code>.</p> 135 * 136 * <p>The client, via {@link GetApplicationReportRequest} provides the 137 * {@link ApplicationId} of the application.</p> 138 * 139 * <p> In secure mode,the <code>ResourceManager</code> verifies access to the 140 * application, queue etc. before accepting the request.</p> 141 * 142 * <p>The <code>ResourceManager</code> responds with a 143 * {@link GetApplicationReportResponse} which includes the 144 * {@link ApplicationReport} for the application.</p> 145 * 146 * @param request request for an application report 147 * @return application report 148 * @throws YarnRemoteException 149 */ 150 public GetApplicationReportResponse getApplicationReport( 151 GetApplicationReportRequest request) 152 throws YarnRemoteException; 153 154 /** 155 * <p>The interface used by clients to get metrics about the cluster from 156 * the <code>ResourceManager</code>.</p> 157 * 158 * <p>The <code>ResourceManager</code> responds with a 159 * {@link GetClusterMetricsResponse} which includes the 160 * {@link YarnClusterMetrics} with details such as number of current 161 * nodes in the cluster.</p> 162 * 163 * @param request request for cluster metrics 164 * @return cluster metrics 165 * @throws YarnRemoteException 166 */ 167 public GetClusterMetricsResponse getClusterMetrics( 168 GetClusterMetricsRequest request) 169 throws YarnRemoteException; 170 171 /** 172 * <p>The interface used by clients to get a report of all Applications 173 * in the cluster from the <code>ResourceManager</code>.</p> 174 * 175 * <p>The <code>ResourceManager</code> responds with a 176 * {@link GetAllApplicationsResponse} which includes the 177 * {@link ApplicationReport} for all the applications.</p> 178 * 179 * @param request request for report on all running applications 180 * @return report on all running applications 181 * @throws YarnRemoteException 182 */ 183 public GetAllApplicationsResponse getAllApplications( 184 GetAllApplicationsRequest request) 185 throws YarnRemoteException; 186 187 /** 188 * <p>The interface used by clients to get a report of all nodes 189 * in the cluster from the <code>ResourceManager</code>.</p> 190 * 191 * <p>The <code>ResourceManager</code> responds with a 192 * {@link GetClusterNodesResponse} which includes the 193 * {@link NodeReport} for all the nodes in the cluster.</p> 194 * 195 * @param request request for report on all nodes 196 * @return report on all nodes 197 * @throws YarnRemoteException 198 */ 199 public GetClusterNodesResponse getClusterNodes( 200 GetClusterNodesRequest request) 201 throws YarnRemoteException; 202 203 /** 204 * <p>The interface used by clients to get information about <em>queues</em> 205 * from the <code>ResourceManager</code>.</p> 206 * 207 * <p>The client, via {@link GetQueueInfoRequest}, can ask for details such 208 * as used/total resources, child queues, running applications etc.</p> 209 * 210 * <p> In secure mode,the <code>ResourceManager</code> verifies access before 211 * providing the information.</p> 212 * 213 * @param request request to get queue information 214 * @return queue information 215 * @throws YarnRemoteException 216 */ 217 public GetQueueInfoResponse getQueueInfo( 218 GetQueueInfoRequest request) 219 throws YarnRemoteException; 220 221 /** 222 * <p>The interface used by clients to get information about <em>queue 223 * acls</em> for <em>current user</em> from the <code>ResourceManager</code>. 224 * </p> 225 * 226 * <p>The <code>ResourceManager</code> responds with queue acls for all 227 * existing queues.</p> 228 * 229 * @param request request to get queue acls for <em>current user</em> 230 * @return queue acls for <em>current user</em> 231 * @throws YarnRemoteException 232 */ 233 public GetQueueUserAclsInfoResponse getQueueUserAcls( 234 GetQueueUserAclsInfoRequest request) 235 throws YarnRemoteException; 236 237 /** 238 * <p>The interface used by clients to get delegation token, enabling the 239 * containers to be able to talk to the service using those tokens. 240 * 241 * <p> The <code>ResourceManager</code> responds with the delegation token 242 * {@link DelegationToken} that can be used by the client to speak to this 243 * service. 244 * @param request request to get a delegation token for the client. 245 * @return delegation token that can be used to talk to this service 246 * @throws YarnRemoteException 247 */ 248 public GetDelegationTokenResponse getDelegationToken( 249 GetDelegationTokenRequest request) 250 throws YarnRemoteException; 251 }