YARN-5455. Update Javadocs for LinuxContainerExecutor. Contributed by Daniel Templeton.

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.privileg
 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 java.util.regex.Pattern;
 
 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
+/**
+ * <p>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.</p>
+ *
+ * <p>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.</p>
+ *
+ * <p>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.</p>
+ *
+ * @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 @@ public class LinuxContainerExecutor extends ContainerExecutor {
     }
   }
 
+  /**
+   * 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 @@ public class LinuxContainerExecutor extends ContainerExecutor {
         defaultPath);
   }
 
+  /**
+   * Add a niceness level to the process that will be executed.  Adds
+   * {@code -n <nice>} 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<String> command) {
     if (containerSchedPriorityIsSet) {
       command.addAll(Arrays.asList("nice", "-n",
@@ -294,6 +344,17 @@ public class LinuxContainerExecutor extends ContainerExecutor {
     }
   }
 
+  /**
+   * 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<String> command, String user, String appId,
       String locId, InetSocketAddress nmAddr, List<String> localDirs) {
@@ -594,6 +655,15 @@ public class LinuxContainerExecutor extends ContainerExecutor {
         .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<String> cgroupKVs, String hierarchy)
       throws IOException {
     try {

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.privileg
 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;

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.conf.Configuration;
 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 {

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.
 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 java.util.Set;
 
 import static org.apache.hadoop.yarn.server.nodemanager.containermanager.linux.runtime.LinuxContainerRuntimeConstants.*;
 
+/**
+ * <p>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.</p>
+ *
+ * <p>The following environment variables are used to configure the Docker
+ * engine:</p>
+ *
+ * <ul>
+ *   <li>
+ *     {@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}.
+ *   </li>
+ *   <li>
+ *     {@code YARN_CONTAINER_RUNTIME_DOCKER_IMAGE} names which image
+ *     will be used to launch the Docker container.
+ *   </li>
+ *   <li>
+ *     {@code YARN_CONTAINER_RUNTIME_DOCKER_IMAGE_FILE} is currently ignored.
+ *   </li>
+ *   <li>
+ *     {@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 <path_to_launch_script>}. When unset or set to {@code false}
+ *     the Docker container's default command is used.
+ *   </li>
+ *   <li>
+ *     {@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.
+ *   </li>
+ *   <li>
+ *     {@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.
+ *   </li>
+ *   <li>
+ *     {@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.
+ *   </li>
+ * </ul>
+ */
 @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<String, String> env) {
     if (env == null) {
@@ -101,13 +173,28 @@ public class DockerLinuxContainerRuntime implements LinuxContainerRuntime {
     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 class DockerLinuxContainerRuntime implements LinuxContainerRuntime {
   @Override
   public void prepareContainer(ContainerRuntimeContext ctx)
       throws ContainerExecutionException {
-
   }
 
   private void validateContainerNetworkType(String network)
@@ -170,9 +256,17 @@ public class DockerLinuxContainerRuntime implements LinuxContainerRuntime {
     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 class DockerLinuxContainerRuntime implements LinuxContainerRuntime {
       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 class DockerLinuxContainerRuntime implements LinuxContainerRuntime {
         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 class DockerLinuxContainerRuntime implements LinuxContainerRuntime {
     }
   }
 
+  /**
+   * 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:
+   *
+   * <ol>
+   *   <li>Submitting user must request for a privileged container</li>
+   *   <li>Privileged containers must be enabled on the cluster</li>
+   *   <li>Submitting user must be white-listed to run a privileged
+   *   container</li>
+   * </ol>
+   *
+   * @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<String, String> environment = container.getLaunchContext()
         .getEnvironment();
     String runPrivilegedContainerEnvVar = environment
@@ -379,7 +483,7 @@ public class DockerLinuxContainerRuntime implements LinuxContainerRuntime {
 
     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 class DockerLinuxContainerRuntime implements LinuxContainerRuntime {
   @Override
   public void reapContainer(ContainerRuntimeContext ctx)
       throws ContainerExecutionException {
-
   }
 }

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.conf.Configuration;
 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;
 }
 

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 @@ package org.apache.hadoop.yarn.server.nodemanager.containermanager.runtime;
 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;
 }