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 java.io.IOException; 022 023import org.apache.hadoop.classification.InterfaceAudience.Public; 024import org.apache.hadoop.classification.InterfaceStability.Stable; 025import org.apache.hadoop.classification.InterfaceStability.Unstable; 026import org.apache.hadoop.yarn.api.protocolrecords.IncreaseContainersResourceRequest; 027import org.apache.hadoop.yarn.api.protocolrecords.IncreaseContainersResourceResponse; 028import org.apache.hadoop.yarn.api.protocolrecords.GetContainerStatusesRequest; 029import org.apache.hadoop.yarn.api.protocolrecords.GetContainerStatusesResponse; 030import org.apache.hadoop.yarn.api.protocolrecords.SignalContainerRequest; 031import org.apache.hadoop.yarn.api.protocolrecords.SignalContainerResponse; 032import org.apache.hadoop.yarn.api.protocolrecords.StartContainerRequest; 033import org.apache.hadoop.yarn.api.protocolrecords.StartContainersRequest; 034import org.apache.hadoop.yarn.api.protocolrecords.StartContainersResponse; 035import org.apache.hadoop.yarn.api.protocolrecords.StopContainersRequest; 036import org.apache.hadoop.yarn.api.protocolrecords.StopContainersResponse; 037import org.apache.hadoop.yarn.api.records.Container; 038import org.apache.hadoop.yarn.api.records.ContainerId; 039import org.apache.hadoop.yarn.api.records.ContainerLaunchContext; 040import org.apache.hadoop.yarn.api.records.ContainerStatus; 041import org.apache.hadoop.yarn.exceptions.NMNotYetReadyException; 042import org.apache.hadoop.yarn.exceptions.YarnException; 043 044/** 045 * <p>The protocol between an <code>ApplicationMaster</code> and a 046 * <code>NodeManager</code> to start/stop and increase resource of containers 047 * and to get status of running containers.</p> 048 * 049 * <p>If security is enabled the <code>NodeManager</code> verifies that the 050 * <code>ApplicationMaster</code> has truly been allocated the container 051 * by the <code>ResourceManager</code> and also verifies all interactions such 052 * as stopping the container or obtaining status information for the container. 053 * </p> 054 */ 055@Public 056@Stable 057public interface ContainerManagementProtocol { 058 059 /** 060 * <p> 061 * The <code>ApplicationMaster</code> provides a list of 062 * {@link StartContainerRequest}s to a <code>NodeManager</code> to 063 * <em>start</em> {@link Container}s allocated to it using this interface. 064 * </p> 065 * 066 * <p> 067 * The <code>ApplicationMaster</code> has to provide details such as allocated 068 * resource capability, security tokens (if enabled), command to be executed 069 * to start the container, environment for the process, necessary 070 * binaries/jar/shared-objects etc. via the {@link ContainerLaunchContext} in 071 * the {@link StartContainerRequest}. 072 * </p> 073 * 074 * <p> 075 * The <code>NodeManager</code> sends a response via 076 * {@link StartContainersResponse} which includes a list of 077 * {@link Container}s of successfully launched {@link Container}s, a 078 * containerId-to-exception map for each failed {@link StartContainerRequest} in 079 * which the exception indicates errors from per container and a 080 * allServicesMetaData map between the names of auxiliary services and their 081 * corresponding meta-data. Note: None-container-specific exceptions will 082 * still be thrown by the API method itself. 083 * </p> 084 * <p> 085 * The <code>ApplicationMaster</code> can use 086 * {@link #getContainerStatuses(GetContainerStatusesRequest)} to get updated 087 * statuses of the to-be-launched or launched containers. 088 * </p> 089 * 090 * @param request 091 * request to start a list of containers 092 * @return response including conatinerIds of all successfully launched 093 * containers, a containerId-to-exception map for failed requests and 094 * a allServicesMetaData map. 095 * @throws YarnException 096 * @throws IOException 097 * @throws NMNotYetReadyException 098 * This exception is thrown when NM starts from scratch but has not 099 * yet connected with RM. 100 */ 101 @Public 102 @Stable 103 StartContainersResponse startContainers(StartContainersRequest request) 104 throws YarnException, IOException; 105 106 /** 107 * <p> 108 * The <code>ApplicationMaster</code> requests a <code>NodeManager</code> to 109 * <em>stop</em> a list of {@link Container}s allocated to it using this 110 * interface. 111 * </p> 112 * 113 * <p> 114 * The <code>ApplicationMaster</code> sends a {@link StopContainersRequest} 115 * which includes the {@link ContainerId}s of the containers to be stopped. 116 * </p> 117 * 118 * <p> 119 * The <code>NodeManager</code> sends a response via 120 * {@link StopContainersResponse} which includes a list of {@link ContainerId} 121 * s of successfully stopped containers, a containerId-to-exception map for 122 * each failed request in which the exception indicates errors from per 123 * container. Note: None-container-specific exceptions will still be thrown by 124 * the API method itself. <code>ApplicationMaster</code> can use 125 * {@link #getContainerStatuses(GetContainerStatusesRequest)} to get updated 126 * statuses of the containers. 127 * </p> 128 * 129 * @param request 130 * request to stop a list of containers 131 * @return response which includes a list of containerIds of successfully 132 * stopped containers, a containerId-to-exception map for failed 133 * requests. 134 * @throws YarnException 135 * @throws IOException 136 */ 137 @Public 138 @Stable 139 StopContainersResponse stopContainers(StopContainersRequest request) 140 throws YarnException, IOException; 141 142 /** 143 * <p> 144 * The API used by the <code>ApplicationMaster</code> to request for current 145 * statuses of <code>Container</code>s from the <code>NodeManager</code>. 146 * </p> 147 * 148 * <p> 149 * The <code>ApplicationMaster</code> sends a 150 * {@link GetContainerStatusesRequest} which includes the {@link ContainerId}s 151 * of all containers whose statuses are needed. 152 * </p> 153 * 154 * <p> 155 * The <code>NodeManager</code> responds with 156 * {@link GetContainerStatusesResponse} which includes a list of 157 * {@link ContainerStatus} of the successfully queried containers and a 158 * containerId-to-exception map for each failed request in which the exception 159 * indicates errors from per container. Note: None-container-specific 160 * exceptions will still be thrown by the API method itself. 161 * </p> 162 * 163 * @param request 164 * request to get <code>ContainerStatus</code>es of containers with 165 * the specified <code>ContainerId</code>s 166 * @return response containing the list of <code>ContainerStatus</code> of the 167 * successfully queried containers and a containerId-to-exception map 168 * for failed requests. 169 * 170 * @throws YarnException 171 * @throws IOException 172 */ 173 @Public 174 @Stable 175 GetContainerStatusesResponse getContainerStatuses( 176 GetContainerStatusesRequest request) throws YarnException, 177 IOException; 178 179 /** 180 * <p> 181 * The API used by the <code>ApplicationMaster</code> to request for 182 * resource increase of running containers on the <code>NodeManager</code>. 183 * </p> 184 * 185 * @param request 186 * request to increase resource of a list of containers 187 * @return response which includes a list of containerIds of containers 188 * whose resource has been successfully increased and a 189 * containerId-to-exception map for failed requests. 190 * 191 * @throws YarnException 192 * @throws IOException 193 */ 194 @Public 195 @Unstable 196 IncreaseContainersResourceResponse increaseContainersResource( 197 IncreaseContainersResourceRequest request) throws YarnException, 198 IOException; 199 200 SignalContainerResponse signalToContainer(SignalContainerRequest request) 201 throws YarnException, IOException; 202}