From 7f05ff7a4e654693eaaa216ee5fc6e24112e0e23 Mon Sep 17 00:00:00 2001 From: Varun Vasudev Date: Wed, 17 Aug 2016 15:34:58 +0530 Subject: [PATCH] YARN-5455. Update Javadocs for LinuxContainerExecutor. Contributed by Daniel Templeton. --- .../nodemanager/LinuxContainerExecutor.java | 80 +++++++++- .../runtime/DefaultLinuxContainerRuntime.java | 20 ++- .../DelegatingLinuxContainerRuntime.java | 10 ++ .../runtime/DockerLinuxContainerRuntime.java | 143 +++++++++++++++--- .../linux/runtime/LinuxContainerRuntime.java | 10 +- .../runtime/ContainerRuntime.java | 40 ++++- 6 files changed, 267 insertions(+), 36 deletions(-) diff --git a/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/LinuxContainerExecutor.java b/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/LinuxContainerExecutor.java index 8f5ee6b92cf..2c27f6c52cc 100644 --- a/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/LinuxContainerExecutor.java +++ b/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/LinuxContainerExecutor.java @@ -38,7 +38,9 @@ import org.apache.hadoop.yarn.server.nodemanager.containermanager.linux.resources.ResourceHandler; import org.apache.hadoop.yarn.server.nodemanager.containermanager.linux.resources.ResourceHandlerException; import org.apache.hadoop.yarn.server.nodemanager.containermanager.linux.resources.ResourceHandlerModule; +import org.apache.hadoop.yarn.server.nodemanager.containermanager.linux.runtime.DefaultLinuxContainerRuntime; import org.apache.hadoop.yarn.server.nodemanager.containermanager.linux.runtime.DelegatingLinuxContainerRuntime; +import org.apache.hadoop.yarn.server.nodemanager.containermanager.linux.runtime.DockerLinuxContainerRuntime; import org.apache.hadoop.yarn.server.nodemanager.containermanager.linux.runtime.LinuxContainerRuntime; import org.apache.hadoop.yarn.server.nodemanager.containermanager.localizer.ContainerLocalizer; import org.apache.hadoop.yarn.server.nodemanager.containermanager.runtime.ContainerExecutionException; @@ -64,11 +66,36 @@ import static org.apache.hadoop.yarn.server.nodemanager.containermanager.linux.runtime.LinuxContainerRuntimeConstants.*; -/** Container execution for Linux. Provides linux-specific localization - * mechanisms, resource management via cgroups and can switch between multiple - * container runtimes - e.g Standard "Process Tree", Docker etc +/** + *

This class provides {@link Container} execution using a native + * {@code container-executor} binary. By using a helper written it native code, + * this class is able to do several things that the + * {@link DefaultContainerExecutor} cannot, such as execution of applications + * as the applications' owners, provide localization that takes advantage of + * mapping the application owner to a UID on the execution host, resource + * management through Linux CGROUPS, and Docker support.

+ * + *

If {@code hadoop.security.authetication} is set to {@code simple}, + * then the + * {@code yarn.nodemanager.linux-container-executor.nonsecure-mode.limit-users} + * property will determine whether the {@code LinuxContainerExecutor} runs + * processes as the application owner or as the default user, as set in the + * {@code yarn.nodemanager.linux-container-executor.nonsecure-mode.local-user} + * property.

+ * + *

The {@code LinuxContainerExecutor} will manage applications through an + * appropriate {@link LinuxContainerRuntime} instance. This class uses a + * {@link DelegatingLinuxContainerRuntime} instance, which will delegate calls + * to either a {@link DefaultLinuxContainerRuntime} instance or a + * {@link DockerLinuxContainerRuntime} instance, depending on the job's + * configuration.

+ * + * @see LinuxContainerRuntime + * @see DelegatingLinuxContainerRuntime + * @see DefaultLinuxContainerRuntime + * @see DockerLinuxContainerRuntime + * @see DockerLinuxContainerRuntime#isDockerContainerRequested */ - public class LinuxContainerExecutor extends ContainerExecutor { private static final Log LOG = LogFactory @@ -83,10 +110,18 @@ public class LinuxContainerExecutor extends ContainerExecutor { private ResourceHandler resourceHandlerChain; private LinuxContainerRuntime linuxContainerRuntime; + /** + * Default constructor to allow for creation through reflection. + */ public LinuxContainerExecutor() { } - // created primarily for testing + /** + * Create a LinuxContainerExecutor with a provided + * {@link LinuxContainerRuntime}. Used primarily for testing. + * + * @param linuxContainerRuntime the runtime to use + */ public LinuxContainerExecutor(LinuxContainerRuntime linuxContainerRuntime) { this.linuxContainerRuntime = linuxContainerRuntime; } @@ -154,6 +189,13 @@ String getRunAsUser(String user) { } } + /** + * Get the path to the {@code container-executor} binary. The path will + * be absolute. + * + * @param conf the {@link Configuration} + * @return the path to the {@code container-executor} binary + */ protected String getContainerExecutorExecutablePath(Configuration conf) { String yarnHomeEnvVar = System.getenv(ApplicationConstants.Environment.HADOOP_YARN_HOME.key()); @@ -166,6 +208,14 @@ protected String getContainerExecutorExecutablePath(Configuration conf) { defaultPath); } + /** + * Add a niceness level to the process that will be executed. Adds + * {@code -n } to the given command. The niceness level will be + * taken from the + * {@code yarn.nodemanager.container-executer.os.sched.prioity} property. + * + * @param command the command to which to add the niceness setting. + */ protected void addSchedPriorityCommand(List command) { if (containerSchedPriorityIsSet) { command.addAll(Arrays.asList("nice", "-n", @@ -294,6 +344,17 @@ public void startLocalizer(LocalizerStartContext ctx) } } + /** + * Set up the {@link ContainerLocalizer}. + * + * @param command the current ShellCommandExecutor command line + * @param user localization user + * @param appId localized app id + * @param locId localizer id + * @param nmAddr nodemanager address + * @param localDirs list of local dirs + * @see ContainerLocalizer#buildMainArgs + */ @VisibleForTesting public void buildMainArgs(List command, String user, String appId, String locId, InetSocketAddress nmAddr, List localDirs) { @@ -594,6 +655,15 @@ public boolean isContainerAlive(ContainerLivenessContext ctx) .build()); } + /** + * Mount a CGROUPS controller at the requested mount point and create + * a hierarchy for the NodeManager to manage. + * + * @param cgroupKVs a key-value pair of the form + * {@code controller=mount-path} + * @param hierarchy the top directory of the hierarchy for the NodeManager + * @throws IOException if there is a problem mounting the CGROUPS + */ public void mountCgroups(List cgroupKVs, String hierarchy) throws IOException { try { diff --git a/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/containermanager/linux/runtime/DefaultLinuxContainerRuntime.java b/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/containermanager/linux/runtime/DefaultLinuxContainerRuntime.java index e78f4606b3a..57e3cc263eb 100644 --- a/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/containermanager/linux/runtime/DefaultLinuxContainerRuntime.java +++ b/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/containermanager/linux/runtime/DefaultLinuxContainerRuntime.java @@ -31,20 +31,34 @@ import org.apache.hadoop.yarn.server.nodemanager.containermanager.linux.privileged.PrivilegedOperationException; import org.apache.hadoop.yarn.server.nodemanager.containermanager.linux.privileged.PrivilegedOperationExecutor; import org.apache.hadoop.yarn.server.nodemanager.containermanager.runtime.ContainerExecutionException; +import org.apache.hadoop.yarn.server.nodemanager.containermanager.runtime.ContainerRuntime; import org.apache.hadoop.yarn.server.nodemanager.containermanager.runtime.ContainerRuntimeContext; import java.util.List; import static org.apache.hadoop.yarn.server.nodemanager.containermanager.linux.runtime.LinuxContainerRuntimeConstants.*; +/** + * This class is a {@link ContainerRuntime} implementation that uses the + * native {@code container-executor} binary via a + * {@link PrivilegedOperationExecutor} instance to launch processes using the + * standard process model. + */ @InterfaceAudience.Private @InterfaceStability.Unstable public class DefaultLinuxContainerRuntime implements LinuxContainerRuntime { - private static final Log LOG = LogFactory - .getLog(DefaultLinuxContainerRuntime.class); - private Configuration conf; + private static final Log LOG = + LogFactory.getLog(DefaultLinuxContainerRuntime.class); private final PrivilegedOperationExecutor privilegedOperationExecutor; + private Configuration conf; + /** + * Create an instance using the given {@link PrivilegedOperationExecutor} + * instance for performing operations. + * + * @param privilegedOperationExecutor the {@link PrivilegedOperationExecutor} + * instance + */ public DefaultLinuxContainerRuntime(PrivilegedOperationExecutor privilegedOperationExecutor) { this.privilegedOperationExecutor = privilegedOperationExecutor; diff --git a/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/containermanager/linux/runtime/DelegatingLinuxContainerRuntime.java b/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/containermanager/linux/runtime/DelegatingLinuxContainerRuntime.java index 975bb9bdbd7..faa7522d019 100644 --- a/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/containermanager/linux/runtime/DelegatingLinuxContainerRuntime.java +++ b/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/containermanager/linux/runtime/DelegatingLinuxContainerRuntime.java @@ -28,10 +28,20 @@ import org.apache.hadoop.yarn.server.nodemanager.containermanager.container.Container; import org.apache.hadoop.yarn.server.nodemanager.containermanager.linux.privileged.PrivilegedOperationExecutor; import org.apache.hadoop.yarn.server.nodemanager.containermanager.runtime.ContainerExecutionException; +import org.apache.hadoop.yarn.server.nodemanager.containermanager.runtime.ContainerRuntime; import org.apache.hadoop.yarn.server.nodemanager.containermanager.runtime.ContainerRuntimeContext; import java.util.Map; +/** + * This class is a {@link ContainerRuntime} implementation that delegates all + * operations to either a {@link DefaultLinuxContainerRuntime} instance or a + * {@link DockerLinuxContainerRuntime} instance, depending on whether the + * {@link DockerLinuxContainerRuntime} instance believes the operation to be + * requesting a Docker container. + * + * @see DockerLinuxContainerRuntime#isDockerContainerRequested + */ @InterfaceAudience.Private @InterfaceStability.Unstable public class DelegatingLinuxContainerRuntime implements LinuxContainerRuntime { diff --git a/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/containermanager/linux/runtime/DockerLinuxContainerRuntime.java b/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/containermanager/linux/runtime/DockerLinuxContainerRuntime.java index dc56ab053a8..be17af9f2cb 100644 --- a/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/containermanager/linux/runtime/DockerLinuxContainerRuntime.java +++ b/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/containermanager/linux/runtime/DockerLinuxContainerRuntime.java @@ -43,6 +43,7 @@ import org.apache.hadoop.yarn.server.nodemanager.containermanager.linux.runtime.docker.DockerRunCommand; import org.apache.hadoop.yarn.server.nodemanager.containermanager.linux.runtime.docker.DockerStopCommand; import org.apache.hadoop.yarn.server.nodemanager.containermanager.runtime.ContainerExecutionException; +import org.apache.hadoop.yarn.server.nodemanager.containermanager.runtime.ContainerRuntime; import org.apache.hadoop.yarn.server.nodemanager.containermanager.runtime.ContainerRuntimeConstants; import org.apache.hadoop.yarn.server.nodemanager.containermanager.runtime.ContainerRuntimeContext; @@ -58,6 +59,68 @@ import static org.apache.hadoop.yarn.server.nodemanager.containermanager.linux.runtime.LinuxContainerRuntimeConstants.*; +/** + *

This class is a {@link ContainerRuntime} implementation that uses the + * native {@code container-executor} binary via a + * {@link PrivilegedOperationExecutor} instance to launch processes inside + * Docker containers.

+ * + *

The following environment variables are used to configure the Docker + * engine:

+ * + *
    + *
  • + * {@code YARN_CONTAINER_RUNTIME_TYPE} ultimately determines whether a + * Docker container will be used. If the value is {@code docker}, a Docker + * container will be used. Otherwise a regular process tree container will + * be used. This environment variable is checked by the + * {@link #isDockerContainerRequested} method, which is called by the + * {@link DelegatingLinuxContainerRuntime}. + *
    • + *
  • + * {@code YARN_CONTAINER_RUNTIME_DOCKER_IMAGE} names which image + * will be used to launch the Docker container. + *
    • + *
  • + * {@code YARN_CONTAINER_RUNTIME_DOCKER_IMAGE_FILE} is currently ignored. + *
    • + *
  • + * {@code YARN_CONTAINER_RUNTIME_DOCKER_RUN_OVERRIDE_DISABLE} controls + * whether the Docker container's default command is overridden. When set + * to {@code true}, the Docker container's command will be + * {@code bash }. When unset or set to {@code false} + * the Docker container's default command is used. + *
    • + *
  • + * {@code YARN_CONTAINER_RUNTIME_DOCKER_CONTAINER_NETWORK} sets the + * network type to be used by the Docker container. It must be a valid + * value as determined by the + * {@code yarn.nodemanager.runtime.linux.docker.allowed-container-networks} + * property. + *
    • + *
  • + * {@code YARN_CONTAINER_RUNTIME_DOCKER_RUN_PRIVILEGED_CONTAINER} + * controls whether the Docker container is a privileged container. In order + * to use privileged containers, the + * {@code yarn.nodemanager.runtime.linux.docker.privileged-containers.allowed} + * property must be set to {@code true}, and the application owner must + * appear in the value of the + * {@code yarn.nodemanager.runtime.linux.docker.privileged-containers.acl} + * property. If this environment variable is set to {@code true}, a + * privileged Docker container will be used if allowed. No other value is + * allowed, so the environment variable should be left unset rather than + * setting it to false. + *
    • + *
  • + * {@code YARN_CONTAINER_RUNTIME_DOCKER_LOCAL_RESOURCE_MOUNTS} adds + * additional volume mounts to the Docker container. The value of the + * environment variable should be a comma-separated list of mounts. + * All such mounts must be given as {@code source:dest}, where the + * source is an absolute path that is not a symlink and that points to a + * localized resource. + *
    • + *
+ */ @InterfaceAudience.Private @InterfaceStability.Unstable public class DockerLinuxContainerRuntime implements LinuxContainerRuntime { @@ -90,6 +153,15 @@ public class DockerLinuxContainerRuntime implements LinuxContainerRuntime { private CGroupsHandler cGroupsHandler; private AccessControlList privilegedContainersAcl; + /** + * Return whether the given environment variables indicate that the operation + * is requesting a Docker container. If the environment contains a key + * called {@code YARN_CONTAINER_RUNTIME_TYPE} whose value is {@code docker}, + * this method will return true. Otherwise it will return false. + * + * @param env the environment variable settings for the operation + * @return whether a Docker container is requested + */ public static boolean isDockerContainerRequested( Map env) { if (env == null) { @@ -101,13 +173,28 @@ public static boolean isDockerContainerRequested( return type != null && type.equals("docker"); } + /** + * Create an instance using the given {@link PrivilegedOperationExecutor} + * instance for performing operations. + * + * @param privilegedOperationExecutor the {@link PrivilegedOperationExecutor} + * instance + */ public DockerLinuxContainerRuntime(PrivilegedOperationExecutor privilegedOperationExecutor) { - this(privilegedOperationExecutor, ResourceHandlerModule - .getCGroupsHandler()); + this(privilegedOperationExecutor, + ResourceHandlerModule.getCGroupsHandler()); } - //A constructor with an injected cGroupsHandler primarily used for testing. + /** + * Create an instance using the given {@link PrivilegedOperationExecutor} + * instance for performing operations and the given {@link CGroupsHandler} + * instance. This constructor is intended for use in testing. + * + * @param privilegedOperationExecutor the {@link PrivilegedOperationExecutor} + * instance + * @param cGroupsHandler the {@link CGroupsHandler} instance + */ @VisibleForTesting public DockerLinuxContainerRuntime(PrivilegedOperationExecutor privilegedOperationExecutor, CGroupsHandler cGroupsHandler) { @@ -155,7 +242,6 @@ public void initialize(Configuration conf) @Override public void prepareContainer(ContainerRuntimeContext ctx) throws ContainerExecutionException { - } private void validateContainerNetworkType(String network) @@ -170,9 +256,17 @@ private void validateContainerNetworkType(String network) throw new ContainerExecutionException(msg); } - public void addCGroupParentIfRequired(String resourcesOptions, - String containerIdStr, DockerRunCommand runCommand) - throws ContainerExecutionException { + /** + * If CGROUPS in enabled and not set to none, then set the CGROUP parent for + * the command instance. + * + * @param resourcesOptions the resource options to check for "cgroups=none" + * @param containerIdStr the container ID + * @param runCommand the command to set with the CGROUP parent + */ + @VisibleForTesting + protected void addCGroupParentIfRequired(String resourcesOptions, + String containerIdStr, DockerRunCommand runCommand) { if (cGroupsHandler == null) { if (LOG.isDebugEnabled()) { LOG.debug("cGroupsHandler is null. cgroups are not in use. nothing to" @@ -181,9 +275,8 @@ public void addCGroupParentIfRequired(String resourcesOptions, return; } - if (resourcesOptions.equals( - (PrivilegedOperation.CGROUP_ARG_PREFIX + PrivilegedOperation - .CGROUP_ARG_NO_TASKS))) { + if (resourcesOptions.equals(PrivilegedOperation.CGROUP_ARG_PREFIX + + PrivilegedOperation.CGROUP_ARG_NO_TASKS)) { if (LOG.isDebugEnabled()) { LOG.debug("no resource restrictions specified. not using docker's " + "cgroup options"); @@ -193,8 +286,8 @@ public void addCGroupParentIfRequired(String resourcesOptions, LOG.debug("using docker's cgroups options"); } - String cGroupPath = "/" + cGroupsHandler.getRelativePathForCGroup( - containerIdStr); + String cGroupPath = "/" + + cGroupsHandler.getRelativePathForCGroup(containerIdStr); if (LOG.isDebugEnabled()) { LOG.debug("using cgroup parent: " + cGroupPath); @@ -204,14 +297,25 @@ public void addCGroupParentIfRequired(String resourcesOptions, } } + /** + * Return whether the YARN container is allowed to run in a privileged + * Docker container. For a privileged container to be allowed all of the + * following three conditions must be satisfied: + * + *
    + *
  1. Submitting user must request for a privileged container
    2. + *
  2. Privileged containers must be enabled on the cluster
    3. + *
  3. Submitting user must be white-listed to run a privileged + * container
    4. + *
+ * + * @param container the target YARN container + * @return whether privileged container execution is allowed + * @throws ContainerExecutionException if privileged container execution + * is requested but is not allowed + */ private boolean allowPrivilegedContainerExecution(Container container) throws ContainerExecutionException { - //For a privileged container to be run all of the following three conditions - // must be satisfied: - //1) Submitting user must request for a privileged container - //2) Privileged containers must be enabled on the cluster - //3) Submitting user must be whitelisted to run a privileged container - Map environment = container.getLaunchContext() .getEnvironment(); String runPrivilegedContainerEnvVar = environment @@ -379,7 +483,7 @@ public void launchContainer(ContainerRuntimeContext ctx) addCGroupParentIfRequired(resourcesOpts, containerIdStr, runCommand); - Path nmPrivateContainerScriptPath = ctx.getExecutionAttribute( + Path nmPrivateContainerScriptPath = ctx.getExecutionAttribute( NM_PRIVATE_CONTAINER_SCRIPT_PATH); String disableOverride = environment.get( @@ -487,6 +591,5 @@ public void signalContainer(ContainerRuntimeContext ctx) @Override public void reapContainer(ContainerRuntimeContext ctx) throws ContainerExecutionException { - } } diff --git a/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/containermanager/linux/runtime/LinuxContainerRuntime.java b/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/containermanager/linux/runtime/LinuxContainerRuntime.java index 38aea9d7ba8..cd7a2f3efee 100644 --- a/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/containermanager/linux/runtime/LinuxContainerRuntime.java +++ b/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/containermanager/linux/runtime/LinuxContainerRuntime.java @@ -26,13 +26,21 @@ import org.apache.hadoop.yarn.server.nodemanager.containermanager.runtime.ContainerExecutionException; import org.apache.hadoop.yarn.server.nodemanager.containermanager.runtime.ContainerRuntime; -/** Linux-specific container runtime implementations must implement this +/** + * Linux-specific container runtime implementations must implement this * interface. */ @InterfaceAudience.Private @InterfaceStability.Unstable public interface LinuxContainerRuntime extends ContainerRuntime { + /** + * Initialize the runtime. + * + * @param conf the {@link Configuration} to use + * @throws ContainerExecutionException if an error occurs while initializing + * the runtime + */ void initialize(Configuration conf) throws ContainerExecutionException; } diff --git a/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/containermanager/runtime/ContainerRuntime.java b/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/containermanager/runtime/ContainerRuntime.java index e05f3fcb12c..653a4c28edb 100644 --- a/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/containermanager/runtime/ContainerRuntime.java +++ b/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/containermanager/runtime/ContainerRuntime.java @@ -23,28 +23,54 @@ import org.apache.hadoop.classification.InterfaceAudience; import org.apache.hadoop.classification.InterfaceStability; -/** An abstraction for various container runtime implementations. Examples - * include Process Tree, Docker, Appc runtimes etc., These implementations +/** + * An abstraction for various container runtime implementations. Examples + * include Process Tree, Docker, Appc runtimes etc. These implementations * are meant for low-level OS container support - dependencies on - * higher-level nodemananger constructs should be avoided. + * higher-level node mananger constructs should be avoided. */ @InterfaceAudience.Private @InterfaceStability.Unstable public interface ContainerRuntime { - /** Prepare a container to be ready for launch */ + /** + * Prepare a container to be ready for launch. + * + * @param ctx the {@link ContainerRuntimeContext} + * @throws ContainerExecutionException if an error occurs while preparing + * the container + */ void prepareContainer(ContainerRuntimeContext ctx) throws ContainerExecutionException; - /** Launch a container. */ + /** + * Launch a container. + * + * @param ctx the {@link ContainerRuntimeContext} + * @throws ContainerExecutionException if an error occurs while launching + * the container + */ void launchContainer(ContainerRuntimeContext ctx) throws ContainerExecutionException; - /** Signal a container - request to terminate, status check etc., */ + /** + * Signal a container. Signals may be a request to terminate, a status check, + * etc. + * + * @param ctx the {@link ContainerRuntimeContext} + * @throws ContainerExecutionException if an error occurs while signaling + * the container + */ void signalContainer(ContainerRuntimeContext ctx) throws ContainerExecutionException; - /** Any container cleanup that may be required. */ + /** + * Perform any container cleanup that may be required. + * + * @param ctx the {@link ContainerRuntimeContext} + * @throws ContainerExecutionException if an error occurs while reaping + * the container + */ void reapContainer(ContainerRuntimeContext ctx) throws ContainerExecutionException; } \ No newline at end of file