Skip to content

Latest commit

 

History

History
286 lines (211 loc) · 11.8 KB

spark-submit.adoc

File metadata and controls

286 lines (211 loc) · 11.8 KB

spark-submit script

spark-submit script allows you to manage your Spark applications. You can submit your Spark application to a Spark deployment environment, kill or request status of Spark applications.

You can find spark-submit script in bin directory of the Spark distribution.

$ ./bin/spark-submit
Usage: spark-submit [options] <app jar | python file> [app arguments]
Usage: spark-submit --kill [submission ID] --master [spark://...]
Usage: spark-submit --status [submission ID] --master [spark://...]
Usage: spark-submit run-example [options] example-class [example args]
...

Actions

Submitting Applications for Execution

The default action is to submit a Spark application to a deployment environment for execution.

Internally, spark-submit executes SparkSubmit.submit. It first checks whether proxyUser is set and…​FIXME

Caution
 FIXME Review why and when to use proxyUser. See SparkSubmit.submit.

It then passes the call to the main class that understands the target deployment environment (aka submission gateway).

Tip
 Use --verbose to know the main class to be executed, arguments, system properties, and classpath.

All jars included in the classpath are added to the context classloader that loads the main class. Before the main class is loaded, system properties are set using System.setProperty.

The main method of the main class is invoked with arguments.

Killing Applications (--kill switch)

--kill

Requesting Application Status (--status switch)

--status

Command-line Options

Execute spark-submit --help to know about the command-line options supported.

➜  spark git:(master) ✗ ./bin/spark-submit --help
Usage: spark-submit [options] <app jar | python file> [app arguments]
Usage: spark-submit --kill [submission ID] --master [spark://...]
Usage: spark-submit --status [submission ID] --master [spark://...]
Usage: spark-submit run-example [options] example-class [example args]

Options:
  --master MASTER_URL         spark://host:port, mesos://host:port, yarn, or local.
  --deploy-mode DEPLOY_MODE   Whether to launch the driver program locally ("client") or
                              on one of the worker machines inside the cluster ("cluster")
                              (Default: client).
  --class CLASS_NAME          Your application's main class (for Java / Scala apps).
  --name NAME                 A name of your application.
  --jars JARS                 Comma-separated list of local jars to include on the driver
                              and executor classpaths.
  --packages                  Comma-separated list of maven coordinates of jars to include
                              on the driver and executor classpaths. Will search the local
                              maven repo, then maven central and any additional remote
                              repositories given by --repositories. The format for the
                              coordinates should be groupId:artifactId:version.
  --exclude-packages          Comma-separated list of groupId:artifactId, to exclude while
                              resolving the dependencies provided in --packages to avoid
                              dependency conflicts.
  --repositories              Comma-separated list of additional remote repositories to
                              search for the maven coordinates given with --packages.
  --py-files PY_FILES         Comma-separated list of .zip, .egg, or .py files to place
                              on the PYTHONPATH for Python apps.
  --files FILES               Comma-separated list of files to be placed in the working
                              directory of each executor.

  --conf PROP=VALUE           Arbitrary Spark configuration property.
  --properties-file FILE      Path to a file from which to load extra properties. If not
                              specified, this will look for conf/spark-defaults.conf.

  --driver-memory MEM         Memory for driver (e.g. 1000M, 2G) (Default: 1024M).
  --driver-java-options       Extra Java options to pass to the driver.
  --driver-library-path       Extra library path entries to pass to the driver.
  --driver-class-path         Extra class path entries to pass to the driver. Note that
                              jars added with --jars are automatically included in the
                              classpath.

  --executor-memory MEM       Memory per executor (e.g. 1000M, 2G) (Default: 1G).

  --proxy-user NAME           User to impersonate when submitting the application.
                              This argument does not work with --principal / --keytab.

  --help, -h                  Show this help message and exit.
  --verbose, -v               Print additional debug output.
  --version,                  Print the version of current Spark.

 Spark standalone with cluster deploy mode only:
  --driver-cores NUM          Cores for driver (Default: 1).

 Spark standalone or Mesos with cluster deploy mode only:
  --supervise                 If given, restarts the driver on failure.
  --kill SUBMISSION_ID        If given, kills the driver specified.
  --status SUBMISSION_ID      If given, requests the status of the driver specified.

 Spark standalone and Mesos only:
  --total-executor-cores NUM  Total cores for all executors.

 Spark standalone and YARN only:
  --executor-cores NUM        Number of cores per executor. (Default: 1 in YARN mode,
                              or all available cores on the worker in standalone mode)

 YARN-only:
  --driver-cores NUM          Number of cores used by the driver, only in cluster mode
                              (Default: 1).
  --queue QUEUE_NAME          The YARN queue to submit to (Default: "default").
  --num-executors NUM         Number of executors to launch (Default: 2).
  --archives ARCHIVES         Comma separated list of archives to be extracted into the
                              working directory of each executor.
  --principal PRINCIPAL       Principal to be used to login to KDC, while running on
                              secure HDFS.
  --keytab KEYTAB             The full path to the file that contains the keytab for the
                              principal specified above. This keytab will be copied to
                              the node running the Application Master via the Secure
                              Distributed Cache, for renewing the login tickets and the
                              delegation tokens periodically.

  • --class

  • --conf or -c

  • --deploy-mode (see Deploy Mode)

  • --driver-class-path

  • --driver-cores for Standalone cluster mode only

  • --driver-java-options

  • --driver-library-path

  • --driver-memory

  • --executor-memory

  • --files

  • --jars

  • --kill for Standalone cluster mode only

  • --master

  • --name

  • --packages

  • --exclude-packages

  • --properties-file

  • --proxy-user

  • --py-files

  • --repositories

  • --status for Standalone cluster mode only

  • --total-executor-cores

List of switches, i.e. command-line options that do not take parameters:

YARN-only options:

  • --archives

  • --executor-cores

  • --keytab

  • --num-executors

  • --principal

  • --queue

Version (--version switch)

$ ./bin/spark-submit --version
Welcome to
      ____              __
     / __/__  ___ _____/ /__
    _\ \/ _ \/ _ `/ __/  '_/
   /___/ .__/\_,_/_/ /_/\_\   version 2.0.0-SNAPSHOT
      /_/

Type --help for more information.

Verbose Mode (--verbose switch)

When spark-submit is executed with --verbose command-line switch, it enters verbose mode.

In verbose mode, the parsed arguments are printed out to the System error output.

FIXME

It also prints out propertiesFile and the properties from the file.

FIXME

Deploy Mode (--deploy-mode switch)

You use spark-submit’s --deploy-mode command-line option to specify the deploy mode for a Spark application.

Environment Variables

The following is the list of environment variables that are considered when command-line options are not specified:

  • MASTER for --master

  • SPARK_DRIVER_MEMORY for --driver-memory

  • SPARK_EXECUTOR_MEMORY (see Environment Variables in the SparkContext document)

  • SPARK_EXECUTOR_CORES

  • DEPLOY_MODE

  • SPARK_YARN_APP_NAME

  • _SPARK_CMD_USAGE

External packages and custom repositories

The spark-submit utility supports specifying external packages using Maven coordinates using --packages and custom repositories using --repositories.

./bin/spark-submit \
  --packages my:awesome:package \
  --repositories s3n://$aws_ak:$aws_sak@bucket/path/to/repo

FIXME Why should I care?

Launching SparkSubmit (main method)

Note

Set SPARK_PRINT_LAUNCH_COMMAND to see the final command to be executed, e.g.

SPARK_PRINT_LAUNCH_COMMAND=1 ./bin/spark-shell
Tip
 The source code of the script lives in https://github.com/apache/spark/blob/master/bin/spark-submit.

When executed, spark-submit script simply passes the call to spark-class with org.apache.spark.deploy.SparkSubmit class followed by command-line arguments.

It creates an instance of SparkSubmitArguments.

If in verbose mode, it prints out the application arguments.

It then relays the execution to action-specific internal methods (with the application arguments):

  • When no action was explicitly given, it is assumed submit action.

  • kill (when --kill switch is used)

  • requestStatus (when --status switch is used)

Note
 The action can only have one of the three available values: SUBMIT, KILL, or REQUEST_STATUS.

SparkSubmitArguments

SparkSubmitArguments is a private[deploy] class to handle the command-line arguments and environment of spark-submit script that the actions use for their execution.

SparkSubmitArguments(
  args: Seq[String],
  env: Map[String, String] = sys.env)
Note
 SparkSubmitArguments is created when launching spark-submit script with only args passed in.

spark-env.sh - load additional environment settings

  • spark-env.sh consists of environment settings to configure Spark for your site.

    export JAVA_HOME=/your/directory/java
export HADOOP_HOME=/usr/lib/hadoop
export SPARK_WORKER_CORES=2
export SPARK_WORKER_MEMORY=1G

  • spark-env.sh is loaded at the startup of Spark’s command line scripts.

  • SPARK_ENV_LOADED env var is to ensure the spark-env.sh script is loaded once.

  • SPARK_CONF_DIR points at the directory with spark-env.sh or $SPARK_HOME/conf is used.

  • spark-env.sh is executed if it exists.

  • $SPARK_HOME/conf directory has spark-env.sh.template file that serves as a template for your own custom configuration.

Consult Environment Variables in the official documentation.