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 * <p>If the user does not have <code>VIEW_APP</code> access then the
147 * following fields in the report will be set to stubbed values:
148 * <ul>
149 * <li>host - set to "N/A"</li>
150 * <li>RPC port - set to -1</li>
151 * <li>client token - set to "N/A"</li>
152 * <li>diagnostics - set to "N/A"</li>
153 * <li>tracking URL - set to "N/A"</li>
154 * <li>original tracking URL - set to "N/A"</li>
155 * <li>resource usage report - all values are -1</li>
156 * </ul></p>
157 *
158 * @param request request for an application report
159 * @return application report
160 * @throws YarnRemoteException
161 */
162 public GetApplicationReportResponse getApplicationReport(
163 GetApplicationReportRequest request)
164 throws YarnRemoteException;
165
166 /**
167 * <p>The interface used by clients to get metrics about the cluster from
168 * the <code>ResourceManager</code>.</p>
169 *
170 * <p>The <code>ResourceManager</code> responds with a
171 * {@link GetClusterMetricsResponse} which includes the
172 * {@link YarnClusterMetrics} with details such as number of current
173 * nodes in the cluster.</p>
174 *
175 * @param request request for cluster metrics
176 * @return cluster metrics
177 * @throws YarnRemoteException
178 */
179 public GetClusterMetricsResponse getClusterMetrics(
180 GetClusterMetricsRequest request)
181 throws YarnRemoteException;
182
183 /**
184 * <p>The interface used by clients to get a report of all Applications
185 * in the cluster from the <code>ResourceManager</code>.</p>
186 *
187 * <p>The <code>ResourceManager</code> responds with a
188 * {@link GetAllApplicationsResponse} which includes the
189 * {@link ApplicationReport} for all the applications.</p>
190 *
191 * <p>If the user does not have <code>VIEW_APP</code> access for an
192 * application then the corresponding report will be filtered as
193 * described in {@link #getApplicationReport(GetApplicationReportRequest)}.
194 * </p>
195 *
196 * @param request request for report on all running applications
197 * @return report on all running applications
198 * @throws YarnRemoteException
199 */
200 public GetAllApplicationsResponse getAllApplications(
201 GetAllApplicationsRequest request)
202 throws YarnRemoteException;
203
204 /**
205 * <p>The interface used by clients to get a report of all nodes
206 * in the cluster from the <code>ResourceManager</code>.</p>
207 *
208 * <p>The <code>ResourceManager</code> responds with a
209 * {@link GetClusterNodesResponse} which includes the
210 * {@link NodeReport} for all the nodes in the cluster.</p>
211 *
212 * @param request request for report on all nodes
213 * @return report on all nodes
214 * @throws YarnRemoteException
215 */
216 public GetClusterNodesResponse getClusterNodes(
217 GetClusterNodesRequest request)
218 throws YarnRemoteException;
219
220 /**
221 * <p>The interface used by clients to get information about <em>queues</em>
222 * from the <code>ResourceManager</code>.</p>
223 *
224 * <p>The client, via {@link GetQueueInfoRequest}, can ask for details such
225 * as used/total resources, child queues, running applications etc.</p>
226 *
227 * <p> In secure mode,the <code>ResourceManager</code> verifies access before
228 * providing the information.</p>
229 *
230 * @param request request to get queue information
231 * @return queue information
232 * @throws YarnRemoteException
233 */
234 public GetQueueInfoResponse getQueueInfo(
235 GetQueueInfoRequest request)
236 throws YarnRemoteException;
237
238 /**
239 * <p>The interface used by clients to get information about <em>queue
240 * acls</em> for <em>current user</em> from the <code>ResourceManager</code>.
241 * </p>
242 *
243 * <p>The <code>ResourceManager</code> responds with queue acls for all
244 * existing queues.</p>
245 *
246 * @param request request to get queue acls for <em>current user</em>
247 * @return queue acls for <em>current user</em>
248 * @throws YarnRemoteException
249 */
250 public GetQueueUserAclsInfoResponse getQueueUserAcls(
251 GetQueueUserAclsInfoRequest request)
252 throws YarnRemoteException;
253
254 /**
255 * <p>The interface used by clients to get delegation token, enabling the
256 * containers to be able to talk to the service using those tokens.
257 *
258 * <p> The <code>ResourceManager</code> responds with the delegation token
259 * {@link DelegationToken} that can be used by the client to speak to this
260 * service.
261 * @param request request to get a delegation token for the client.
262 * @return delegation token that can be used to talk to this service
263 * @throws YarnRemoteException
264 */
265 public GetDelegationTokenResponse getDelegationToken(
266 GetDelegationTokenRequest request)
267 throws YarnRemoteException;
268 }