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