documentation

Author: ifilonenko

docs/running-on-kubernetes.md

@@ -768,6 +768,53 @@ from the other deployment modes. See the [configuration page](configuration.html
     <code>myIdentifier</code>. Multiple node selector keys can be added by setting multiple configurations with this prefix.
   </td>
 </tr>
+<tr>
+  <td><code>spark.kubernetes.kerberos</code></td> 
+  <td>false</td>
+  <td>
+    Specify whether your job is a job that will require a Delegation Token to access HDFS. By default, we
+    will assume that you will not require secure HDFS access. 
+  </td>
+</tr>
+<tr>
+  <td><code>spark.kubernetes.kerberos.keytab</code></td> 
+  <td>(none)</td>
+  <td>
+    Assuming you have set <code>spark.kubernetes.kerberos</code> to be true. This will let you specify 
+    the location of your Kerberos keytab to be used in order to access Secure HDFS. This is optional as you 
+    may login by running <code>kinit -kt</code> before running the spark-submit, and the submission client
+    will look within your local TGT cache to resolve this. 
+  </td>
+</tr>
+<tr>
+  <td><code>spark.kubernetes.kerberos.principal</code></td> 
+  <td>(none)</td>
+  <td>
+    Assuming you have set <code>spark.kubernetes.kerberos</code> to be true. This will let you specify 
+    your Kerberos principal that you wish to use to access Secure HDFS. This is optional as you 
+    may login by running <code>kinit -kt</code> before running the spark-submit, and the submission client
+    will look within your local TGT cache to resolve this. 
+  </td>
+</tr>
+<tr>
+  <td><code>spark.kubernetes.kerberos.tokensecret.name</code></td> 
+  <td>(none)</td>
+  <td>
+    Assuming you have set <code>spark.kubernetes.kerberos</code> to be true. This will let you specify 
+    the name of the secret where your existing delegation token data is stored. You must also specify the 
+    label <code>spark.kubernetes.kerberos.tokensecret.name</code> where your data is stored on the secret. 
+  </td>
+</tr>
+<tr>
+  <td><code>spark.kubernetes.kerberos.tokensecret.label</code></td> 
+  <td>spark.kubernetes.kerberos.dt.label</td>
+  <td>
+    Assuming you have set <code>spark.kubernetes.kerberos</code> to be true. This will let you specify 
+    the label within the pre-specified secret where the data of your existing delegation token data is stored. 
+    We have a default value of <code>spark.kubernetes.kerberos.dt.label</code> should you not include it. But
+    you should always include this if you are proposing a pre-existing secret contain the delegation token data.
+  </td>
+</tr>
 </table>
 
 

resource-managers/kubernetes/core/src/main/scala/org/apache/spark/deploy/kubernetes/HadoopConfBootstrap.scala

@@ -28,7 +28,7 @@ import org.apache.spark.internal.Logging
 
 /**
  * This is separated out from the HadoopConf steps API because this component can be reused to
- * set up the hadoop-conf for executors as well.
+ * set up the Hadoop Configuration for executors as well.
  */
 private[spark] trait HadoopConfBootstrap {
  /**

resource-managers/kubernetes/core/src/main/scala/org/apache/spark/deploy/kubernetes/KerberosConfBootstrap.scala

@@ -19,12 +19,18 @@ package org.apache.spark.deploy.kubernetes
 import io.fabric8.kubernetes.api.model.ContainerBuilder
 
 import org.apache.spark.deploy.kubernetes.constants._
-
+ /**
+  * This is separated out from hadoopsteps because this component can be reused to
+  * set up the Kerberos logic for executors as well.
+  */
 private[spark] trait KerberosConfBootstrap {
+   /**
+     * Bootstraps a main container with an ENV variable
+     * pointing to the data storing the DT in the secret
+     */
   def bootstrapMainContainerAndVolumes(originalPodWithMainContainer: PodWithMainContainer)
     : PodWithMainContainer
 }
-
 private[spark] class KerberosConfBootstrapImpl(
   delegationTokenLabelName: String) extends KerberosConfBootstrap{
   override def bootstrapMainContainerAndVolumes(

resource-managers/kubernetes/core/src/main/scala/org/apache/spark/deploy/kubernetes/PodWithMainContainer.scala

@@ -18,6 +18,11 @@ package org.apache.spark.deploy.kubernetes
 
 import io.fabric8.kubernetes.api.model.{Container, Pod}
 
+ /**
+  * The purpose of this case class is so that we can package together
+  * the driver pod with its container so we can bootstrap and modify
+  * the class instead of each component seperately
+  */
 private[spark] case class PodWithMainContainer(
     pod: Pod,
     mainContainer: Container)

resource-managers/kubernetes/core/src/main/scala/org/apache/spark/deploy/kubernetes/config.scala

@@ -510,6 +510,7 @@ package object config extends Logging {
       .createOptional
 
   private[spark] val KUBERNETES_NODE_SELECTOR_PREFIX = "spark.kubernetes.node.selector."
+
   private[spark] val KUBERNETES_KERBEROS_SUPPORT =
     ConfigBuilder("spark.kubernetes.kerberos")
       .doc("Specify whether your job is a job that will require a Delegation Token to access HDFS")
@@ -530,14 +531,22 @@ package object config extends Logging {
       .stringConf
       .createOptional
 
-  private[spark] val KUBERNETES_KERBEROS_DT_SECRET =
-    ConfigBuilder("spark.kubernetes.kerberos.tokensecret")
-      .doc("Specify the label of the secret where " +
+  private[spark] val KUBERNETES_KERBEROS_DT_SECRET_NAME =
+    ConfigBuilder("spark.kubernetes.kerberos.tokensecret.name")
+      .doc("Specify the name of the secret where " +
         " your existing delegation token is stored. This removes the need" +
         " for the job user to provide any keytab for launching a job")
       .stringConf
       .createOptional
 
+  private[spark] val KUBERNETES_KERBEROS_DT_SECRET_LABEL =
+    ConfigBuilder("spark.kubernetes.kerberos.tokensecret.label")
+      .doc("Specify the label of the data where " +
+        " your existing delegation token is stored. This removes the need" +
+        " for the job user to provide any keytab for launching a job")
+      .stringConf
+      .createWithDefault("spark.kubernetes.kerberos.dt.label")
+
   private[spark] def resolveK8sMaster(rawMasterString: String): String = {
     if (!rawMasterString.startsWith("k8s://")) {
       throw new IllegalArgumentException("Master URL should start with k8s:// in Kubernetes mode.")

resource-managers/kubernetes/core/src/main/scala/org/apache/spark/deploy/kubernetes/constants.scala

@@ -99,12 +99,15 @@ package object constants {
   private[spark] val DEFAULT_SHUFFLE_MOUNT_NAME = "shuffle"
   private[spark] val INIT_CONTAINER_SECRET_VOLUME_NAME = "spark-init-secret"
 
+  // Hadoop Configuration
   private[spark] val HADOOP_FILE_VOLUME = "hadoop-properties"
   private[spark] val HADOOP_FILE_DIR = "/etc/hadoop"
   private[spark] val HADOOP_CONF_DIR = "HADOOP_CONF_DIR"
   private[spark] val HADOOP_CONF_DIR_LOC = "spark.kubernetes.hadoop.conf.dir"
   private[spark] val HADOOP_CONFIG_MAP_SPARK_CONF_NAME =
     "spark.kubernetes.hadoop.executor.hadoopconfigmapname"
+
+  // Kerberos Configuration
   private[spark] val HADOOP_KERBEROS_SECRET_NAME =
     "spark.kubernetes.kerberos.dt"
   private[spark] val KERBEROS_SPARK_CONF_NAME =

resource-managers/kubernetes/core/src/main/scala/org/apache/spark/deploy/kubernetes/submit/Client.scala

@@ -198,6 +198,8 @@ private[spark] object Client {
   def main(args: Array[String]): Unit = {
     val parsedArguments = ClientArguments.fromCommandLineArgs(args)
     val sparkConf = new SparkConf()
+    // hadoopConfDir is passed into Client#run() to allow for us to
+    // test this env variable within the integration test environment
     val hadoopConfDir = sys.env.get("HADOOP_CONF_DIR")
     run(sparkConf, parsedArguments, hadoopConfDir)
   }

resource-managers/kubernetes/core/src/main/scala/org/apache/spark/deploy/kubernetes/submit/submitsteps/HadoopConfigBootstrapStep.scala

@@ -23,9 +23,11 @@ import io.fabric8.kubernetes.api.model.ConfigMapBuilder
 import org.apache.spark.deploy.kubernetes.constants._
 import org.apache.spark.deploy.kubernetes.submit.submitsteps.hadoopsteps.{HadoopConfigSpec, HadoopConfigurationStep}
 
-
  /**
-  * Configures the driverSpec that bootstraps dependencies into the driver pod.
+  * This class configures the driverSpec with hadoop configuration logic which includes
+  * volume mounts, config maps, and environment variable manipulation. The steps are
+  * resolved with the orchestrator and they are run modifying the HadoopSpec with each
+  * step. The final HadoopSpec's contents will be appended to the driverSpec.
   */
 private[spark] class HadoopConfigBootstrapStep(
   hadoopConfigurationSteps: Seq[HadoopConfigurationStep],

resource-managers/kubernetes/core/src/main/scala/org/apache/spark/deploy/kubernetes/submit/submitsteps/hadoopsteps/HDFSDelegationToken.scala

@@ -16,4 +16,8 @@
  */
 package org.apache.spark.deploy.kubernetes.submit.submitsteps.hadoopsteps
 
+ /**
+  * This case class contain the information that is important to be stored for
+  * delegation token logic
+  */
 private[spark] case class HDFSDelegationToken(bytes: Array[Byte], renewal: Long)

resource-managers/kubernetes/core/src/main/scala/org/apache/spark/deploy/kubernetes/submit/submitsteps/hadoopsteps/HadoopConfMounterStep.scala

@@ -24,7 +24,11 @@ import org.apache.spark.deploy.kubernetes.{HadoopConfBootstrap, PodWithMainConta
 import org.apache.spark.deploy.kubernetes.constants._
 
  /**
-  * Step that configures the ConfigMap + Volumes for the driver
+  * This step is responsible for taking the contents from each file in
+  * HADOOP_CONF_DIR, grabbing its contents as a string and storing each of them
+  * as a key-value pair in a configmap. Each key-value pair will be stored
+  * as a file, via Volume Mounts, later. The HADOOP_CONF_DIR_LOC is passed into the
+  * SchedulerBackend via sparkConf.
   */
 private[spark] class HadoopConfMounterStep(
     hadoopConfigMapName: String,