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 org.apache.hadoop.classification.InterfaceAudience.Private; 022import org.apache.hadoop.classification.InterfaceAudience.Public; 023import org.apache.hadoop.classification.InterfaceStability.Stable; 024import org.apache.hadoop.yarn.api.protocolrecords.CancelDelegationTokenRequest; 025import org.apache.hadoop.yarn.api.protocolrecords.CancelDelegationTokenResponse; 026import org.apache.hadoop.yarn.api.protocolrecords.GetAllApplicationsRequest; 027import org.apache.hadoop.yarn.api.protocolrecords.GetAllApplicationsResponse; 028import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportRequest; 029import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportResponse; 030import org.apache.hadoop.yarn.api.protocolrecords.GetClusterMetricsRequest; 031import org.apache.hadoop.yarn.api.protocolrecords.GetClusterMetricsResponse; 032import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodesRequest; 033import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodesResponse; 034import org.apache.hadoop.yarn.api.protocolrecords.GetDelegationTokenRequest; 035import org.apache.hadoop.yarn.api.protocolrecords.GetDelegationTokenResponse; 036import org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationRequest; 037import org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationResponse; 038import org.apache.hadoop.yarn.api.protocolrecords.GetQueueInfoRequest; 039import org.apache.hadoop.yarn.api.protocolrecords.GetQueueInfoResponse; 040import org.apache.hadoop.yarn.api.protocolrecords.GetQueueUserAclsInfoRequest; 041import org.apache.hadoop.yarn.api.protocolrecords.GetQueueUserAclsInfoResponse; 042import org.apache.hadoop.yarn.api.protocolrecords.KillApplicationRequest; 043import org.apache.hadoop.yarn.api.protocolrecords.KillApplicationResponse; 044import org.apache.hadoop.yarn.api.protocolrecords.RenewDelegationTokenRequest; 045import org.apache.hadoop.yarn.api.protocolrecords.RenewDelegationTokenResponse; 046import org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationRequest; 047import org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationResponse; 048import org.apache.hadoop.yarn.api.records.ApplicationId; 049import org.apache.hadoop.yarn.api.records.ApplicationReport; 050import org.apache.hadoop.yarn.api.records.ContainerLaunchContext; 051import org.apache.hadoop.yarn.api.records.DelegationToken; 052import org.apache.hadoop.yarn.api.records.NodeReport; 053import org.apache.hadoop.yarn.api.records.Resource; 054import org.apache.hadoop.yarn.api.records.YarnClusterMetrics; 055import 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 064public 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 renewed. 288 * @return 289 * @throws YarnRemoteException 290 */ 291 @Private 292 public CancelDelegationTokenResponse cancelDelegationToken( 293 CancelDelegationTokenRequest request) throws YarnRemoteException; 294}