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 }