Package org.apache.hadoop.yarn.api

Interface ContainerManagementProtocol

@Public
@Stable
public interface ContainerManagementProtocol

The protocol between an ApplicationMaster and a NodeManager to start/stop and increase resource of containers and to get status of running containers.

If security is enabled the NodeManager verifies that the ApplicationMaster has truly been allocated the container by the ResourceManager and also verifies all interactions such as stopping the container or obtaining status information for the container.

Method Summary

Modifier and Type	Method	Description
CommitResponse	commitLastReInitialization(ContainerId containerId)	Commit the Last ReInitialization if possible.
GetContainerStatusesResponse	getContainerStatuses(GetContainerStatusesRequest request)	The API used by the ApplicationMaster to request for current statuses of Containers from the NodeManager.
GetLocalizationStatusesResponse	getLocalizationStatuses(GetLocalizationStatusesRequest request)	API to request for the localization statuses of requested containers from the Node Manager.
IncreaseContainersResourceResponse	increaseContainersResource(IncreaseContainersResourceRequest request)	Deprecated.
ResourceLocalizationResponse	localize(ResourceLocalizationRequest request)	Localize resources required by the container.
ReInitializeContainerResponse	reInitializeContainer(ReInitializeContainerRequest request)	ReInitialize the Container with a new Launch Context.
RestartContainerResponse	restartContainer(ContainerId containerId)	Restart the container.
RollbackResponse	rollbackLastReInitialization(ContainerId containerId)	Rollback the Last ReInitialization if possible.
SignalContainerResponse	signalToContainer(SignalContainerRequest request)
StartContainersResponse	startContainers(StartContainersRequest request)	The ApplicationMaster provides a list of StartContainerRequests to a NodeManager to start Containers allocated to it using this interface.
StopContainersResponse	stopContainers(StopContainersRequest request)	The ApplicationMaster requests a NodeManager to stop a list of Containers allocated to it using this interface.
ContainerUpdateResponse	updateContainer(ContainerUpdateRequest request)	The API used by the ApplicationMaster to request for resource update of running containers on the NodeManager.

Method Details

startContainers

@Public
@Stable
StartContainersResponse startContainers(StartContainersRequest request)
                                 throws YarnException,
IOException

The ApplicationMaster provides a list of StartContainerRequests to a NodeManager to start Containers allocated to it using this interface.

The ApplicationMaster has to provide details such as allocated resource capability, security tokens (if enabled), command to be executed to start the container, environment for the process, necessary binaries/jar/shared-objects etc. via the ContainerLaunchContext in the StartContainerRequest.

The NodeManager sends a response via StartContainersResponse which includes a list of Containers of successfully launched Containers, a containerId-to-exception map for each failed StartContainerRequest in which the exception indicates errors from per container and a allServicesMetaData map between the names of auxiliary services and their corresponding meta-data. Note: None-container-specific exceptions will still be thrown by the API method itself.

The ApplicationMaster can use getContainerStatuses(GetContainerStatusesRequest) to get updated statuses of the to-be-launched or launched containers.

Parameters:

request - request to start a list of containers

Returns:

response including conatinerIds of all successfully launched containers, a containerId-to-exception map for failed requests and a allServicesMetaData map.

Throws:

YarnException - exceptions from yarn servers.

IOException - io error occur.

stopContainers

@Public
@Stable
StopContainersResponse stopContainers(StopContainersRequest request)
                               throws YarnException,
IOException

The ApplicationMaster requests a NodeManager to stop a list of Containers allocated to it using this interface.

The ApplicationMaster sends a StopContainersRequest which includes the ContainerIds of the containers to be stopped.

The NodeManager sends a response via StopContainersResponse which includes a list of ContainerId s of successfully stopped containers, a containerId-to-exception map for each failed request in which the exception indicates errors from per container. Note: None-container-specific exceptions will still be thrown by the API method itself. ApplicationMaster can use getContainerStatuses(GetContainerStatusesRequest) to get updated statuses of the containers.

Parameters:

request - request to stop a list of containers

Returns:

response which includes a list of containerIds of successfully stopped containers, a containerId-to-exception map for failed requests.

Throws:

YarnException - exceptions from yarn servers.

IOException - io error occur.

getContainerStatuses

@Public
@Stable
GetContainerStatusesResponse getContainerStatuses(GetContainerStatusesRequest request)
                                           throws YarnException,
IOException

The API used by the ApplicationMaster to request for current statuses of Containers from the NodeManager.

The ApplicationMaster sends a GetContainerStatusesRequest which includes the ContainerIds of all containers whose statuses are needed.

The NodeManager responds with GetContainerStatusesResponse which includes a list of ContainerStatus of the successfully queried containers and a containerId-to-exception map for each failed request in which the exception indicates errors from per container. Note: None-container-specific exceptions will still be thrown by the API method itself.

Parameters:

request - request to get ContainerStatuses of containers with the specified ContainerIds

Returns:

response containing the list of ContainerStatus of the successfully queried containers and a containerId-to-exception map for failed requests.

Throws:

YarnException - exceptions from yarn servers.

IOException - io error occur.

increaseContainersResource

@Public
@Unstable
@Deprecated
IncreaseContainersResourceResponse increaseContainersResource(IncreaseContainersResourceRequest request)
                                                       throws YarnException,
IOException

Deprecated.

The API used by the ApplicationMaster to request for resource increase of running containers on the NodeManager.

Parameters:

request - request to increase resource of a list of containers

Returns:

response which includes a list of containerIds of containers whose resource has been successfully increased and a containerId-to-exception map for failed requests.

Throws:

YarnException - exceptions from yarn servers.

IOException - io error occur.

updateContainer

@Public
@Unstable
ContainerUpdateResponse updateContainer(ContainerUpdateRequest request)
                                 throws YarnException,
IOException

The API used by the ApplicationMaster to request for resource update of running containers on the NodeManager.

Parameters:

request - request to update resource of a list of containers

Returns:

response which includes a list of containerIds of containers whose resource has been successfully updated and a containerId-to-exception map for failed requests.

Throws:

YarnException - Exception specific to YARN

IOException - IOException thrown from NodeManager

signalToContainer

SignalContainerResponse signalToContainer(SignalContainerRequest request)
                                   throws YarnException,
IOException

Throws:

YarnException

IOException

localize

@Public
@Unstable
ResourceLocalizationResponse localize(ResourceLocalizationRequest request)
                               throws YarnException,
IOException

Localize resources required by the container. Currently, this API only works for running containers.

Parameters:

request - Specify the resources to be localized.

Returns:

Response that the localize request is accepted.

Throws:

YarnException - Exception specific to YARN

IOException - IOException thrown from the RPC layer.

reInitializeContainer

@Public
@Unstable
ReInitializeContainerResponse reInitializeContainer(ReInitializeContainerRequest request)
                                             throws YarnException,
IOException

ReInitialize the Container with a new Launch Context.

Parameters:

request - Specify the new ContainerLaunchContext.

Returns:

Response that the ReInitialize request is accepted.

Throws:

YarnException - Exception specific to YARN.

IOException - IOException thrown from the RPC layer.

restartContainer

@Public
@Unstable
RestartContainerResponse restartContainer(ContainerId containerId)
                                   throws YarnException,
IOException

Restart the container.

Parameters:

containerId - Container Id.

Returns:

Response that the restart request is accepted.

Throws:

YarnException - Exception specific to YARN.

IOException - IOException thrown from the RPC layer.

rollbackLastReInitialization

@Public
@Unstable
RollbackResponse rollbackLastReInitialization(ContainerId containerId)
                                       throws YarnException,
IOException

Rollback the Last ReInitialization if possible.

Parameters:

containerId - Container Id.

Returns:

Response that the rollback request is accepted.

Throws:

YarnException - Exception specific to YARN.

IOException - IOException thrown from the RPC layer.

commitLastReInitialization

@Public
@Unstable
CommitResponse commitLastReInitialization(ContainerId containerId)
                                   throws YarnException,
IOException

Commit the Last ReInitialization if possible. Once the reinitialization has been committed, It cannot be rolled back.

Parameters:

containerId - Container Id.

Returns:

Response that the commit request is accepted.

Throws:

YarnException - Exception specific to YARN.

IOException - IOException thrown from the RPC layer.

getLocalizationStatuses

@Public
@Unstable
GetLocalizationStatusesResponse getLocalizationStatuses(GetLocalizationStatusesRequest request)
                                                 throws YarnException,
IOException

API to request for the localization statuses of requested containers from the Node Manager.

Parameters:

request - GetLocalizationStatusesRequest which includes the container ids of all the containers whose localization statuses are needed.

Returns:

GetLocalizationStatusesResponse which contains the localization statuses of all the requested containers.

Throws:

YarnException - Exception specific to YARN.

IOException - IOException thrown from the RPC layer.