From c4db09ea76802df22f52826e228f9d15c0cf13d9 Mon Sep 17 00:00:00 2001 From: Andy Konwinski Date: Wed, 12 Sep 2012 20:56:32 -0700 Subject: Adds ec2-scripts.md back (it was mistakenly removed earlier due to git weirdness). --- docs/ec2-scripts.md | 146 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 docs/ec2-scripts.md diff --git a/docs/ec2-scripts.md b/docs/ec2-scripts.md new file mode 100644 index 0000000000..73578c8457 --- /dev/null +++ b/docs/ec2-scripts.md @@ -0,0 +1,146 @@ +--- +layout: global +title: Using the Spark EC2 Scripts +--- +The `spark-ec2` script located in the Spark's `ec2` directory allows you +to launch, manage and shut down Spark clusters on Amazon EC2. It builds +on the [Mesos EC2 script](https://github.com/mesos/mesos/wiki/EC2-Scripts) +in Apache Mesos. + +`spark-ec2` is designed to manage multiple named clusters. You can +launch a new cluster (telling the script its size and giving it a name), +shutdown an existing cluster, or log into a cluster. Each cluster is +identified by placing its machines into EC2 security groups whose names +are derived from the name of the cluster. For example, a cluster named +`test` will contain a master node in a security group called +`test-master`, and a number of slave nodes in a security group called +`test-slaves`. The `spark-ec2` script will create these security groups +for you based on the cluster name you request. You can also use them to +identify machines belonging to each cluster in the EC2 Console or +ElasticFox. + +This guide describes how to get set up to run clusters, how to launch +clusters, how to run jobs on them, and how to shut them down. + +Before You Start +================ + +- Create an Amazon EC2 key pair for yourself. This can be done by + logging into your Amazon Web Services account through the [AWS + console](http://aws.amazon.com/console/), clicking Key Pairs on the + left sidebar, and creating and downloading a key. Make sure that you + set the permissions for the private key file to `600` (i.e. only you + can read and write it) so that `ssh` will work. +- Whenever you want to use the `spark-ec2` script, set the environment + variables `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` to your + Amazon EC2 access key ID and secret access key. These can be + obtained from the [AWS homepage](http://aws.amazon.com/) by clicking + Account \> Security Credentials \> Access Credentials. + +Launching a Cluster +=================== + +- Go into the `ec2` directory in the release of Spark you downloaded. +- Run + `./spark-ec2 -k -i -s launch `, + where `` is the name of your EC2 key pair (that you gave it + when you created it), `` is the private key file for your + key pair, `` is the number of slave nodes to launch (try + 1 at first), and `` is the name to give to your + cluster. +- After everything launches, check that Mesos is up and sees all the + slaves by going to the Mesos Web UI link printed at the end of the + script (`http://:8080`). + +You can also run `./spark-ec2 --help` to see more usage options. The +following options are worth pointing out: + +- `--instance-type=` can be used to specify an EC2 +instance type to use. For now, the script only supports 64-bit instance +types, and the default type is `m1.large` (which has 2 cores and 7.5 GB +RAM). Refer to the Amazon pages about [EC2 instance +types](http://aws.amazon.com/ec2/instance-types) and [EC2 +pricing](http://aws.amazon.com/ec2/#pricing) for information about other +instance types. +- `--zone=` can be used to specify an EC2 availability zone +to launch instances in. Sometimes, you will get an error because there +is not enough capacity in one zone, and you should try to launch in +another. This happens mostly with the `m1.large` instance types; +extra-large (both `m1.xlarge` and `c1.xlarge`) instances tend to be more +available. +- `--ebs-vol-size=GB` will attach an EBS volume with a given amount + of space to each node so that you can have a persistent HDFS cluster + on your nodes across cluster restarts (see below). +- If one of your launches fails due to e.g. not having the right +permissions on your private key file, you can run `launch` with the +`--resume` option to restart the setup process on an existing cluster. + +Running Jobs +============ + +- Go into the `ec2` directory in the release of Spark you downloaded. +- Run `./spark-ec2 -k -i login ` to + SSH into the cluster, where `` and `` are as + above. (This is just for convenience; you could also use + the EC2 console.) +- To deploy code or data within your cluster, you can log in and use the + provided script `~/mesos-ec2/copy-dir`, which, + given a directory path, RSYNCs it to the same location on all the slaves. +- If your job needs to access large datasets, the fastest way to do + that is to load them from Amazon S3 or an Amazon EBS device into an + instance of the Hadoop Distributed File System (HDFS) on your nodes. + The `spark-ec2` script already sets up a HDFS instance for you. It's + installed in `/root/ephemeral-hdfs`, and can be accessed using the + `bin/hadoop` script in that directory. Note that the data in this + HDFS goes away when you stop and restart a machine. +- There is also a *persistent HDFS* instance in + `/root/presistent-hdfs` that will keep data across cluster restarts. + Typically each node has relatively little space of persistent data + (about 3 GB), but you can use the `--ebs-vol-size` option to + `spark-ec2` to attach a persistent EBS volume to each node for + storing the persistent HDFS. +- Finally, if you get errors while running your jobs, look at the slave's logs + for that job using the Mesos web UI (`http://:8080`). + +Terminating a Cluster +===================== + +***Note that there is no way to recover data on EC2 nodes after shutting +them down! Make sure you have copied everything important off the nodes +before stopping them.*** + +- Go into the `ec2` directory in the release of Spark you downloaded. +- Run `./spark-ec2 destroy `. + +Pausing and Restarting Clusters +=============================== + +The `spark-ec2` script also supports pausing a cluster. In this case, +the VMs are stopped but not terminated, so they +***lose all data on ephemeral disks*** but keep the data in their +root partitions and their `persistent-hdfs`. Stopped machines will not +cost you any EC2 cycles, but ***will*** continue to cost money for EBS +storage. + +- To stop one of your clusters, go into the `ec2` directory and run +`./spark-ec2 stop `. +- To restart it later, run +`./spark-ec2 -i start `. +- To ultimately destroy the cluster and stop consuming EBS space, run +`./spark-ec2 destroy ` as described in the previous +section. + +Limitations +=========== + +- `spark-ec2` currently only launches machines in the US-East region of EC2. + It should not be hard to make it launch VMs in other zones, but you will need + to create your own AMIs in them. +- Support for "cluster compute" nodes is limited -- there's no way to specify a + locality group. However, you can launch slave nodes in your + `-slaves` group manually and then use `spark-ec2 launch + --resume` to start a cluster with them. +- Support for spot instances is limited. + +If you have a patch or suggestion for one of these limitations, feel free to +[contribute]({{HOME_PATH}}contributing-to-spark.html) it! -- cgit v1.2.3 From ca2c999e0fd97a29b20bd3990b6e57d9e0db5d0a Mon Sep 17 00:00:00 2001 From: Andy Konwinski Date: Wed, 12 Sep 2012 23:05:47 -0700 Subject: Making the link to api scaladocs work and migrating other code snippets to use pygments syntax highlighting. --- docs/_layouts/global.html | 2 +- docs/api.md | 11 +++ docs/bagel-programming-guide.md | 163 ++++++++++++++++++++++------------------ docs/running-on-mesos.md | 23 ++++-- docs/spark-debugger.md | 99 +++++++++++++----------- 5 files changed, 175 insertions(+), 123 deletions(-) create mode 100644 docs/api.md diff --git a/docs/_layouts/global.html b/docs/_layouts/global.html index 8bfd0e7284..7286d589a8 100755 --- a/docs/_layouts/global.html +++ b/docs/_layouts/global.html @@ -44,7 +44,7 @@
  • Home
  • Programming Guide
    • -
  • API (Scaladoc)
    • +
  • API (Scaladoc)
    • diff --git a/docs/css/main.css b/docs/css/main.css index fdc0872279..957e9a6285 100755 --- a/docs/css/main.css +++ b/docs/css/main.css @@ -1,15 +1,13 @@ ---- ---- /* ========================================================================== Author's custom styles ========================================================================== */ -/*.brand { - background: url({{HOME_PATH}}img/spark-logo.jpg) no-repeat left center; +.navbar .brand { + background: url(../img/spark-logo-100x40px.png) no-repeat left center; height: 40px; width: 100px; + padding: 0px; } -*/ body #content { line-height: 1.6; /* Inspired by Github's wiki style */ diff --git a/docs/img/spark-logo-100x40px.png b/docs/img/spark-logo-100x40px.png new file mode 100644 index 0000000000..54c3187bbd Binary files /dev/null and b/docs/img/spark-logo-100x40px.png differ -- cgit v1.2.3 From 5ec7a6665bda7a17b254a86e95a47606e24aeb7e Mon Sep 17 00:00:00 2001 From: Andy Konwinski Date: Thu, 13 Sep 2012 15:27:33 -0700 Subject: More crisp logo created from vector source (ai) and disabled responsive css (so nav menu doesn't switch to collapsed version for narrow viewports). --- docs/_layouts/global.html | 5 +++-- docs/css/main.css | 9 +++++++-- docs/img/spark-logo-77x40px-hd.png | Bin 0 -> 1904 bytes 3 files changed, 10 insertions(+), 4 deletions(-) create mode 100644 docs/img/spark-logo-77x40px-hd.png diff --git a/docs/_layouts/global.html b/docs/_layouts/global.html index 94d0deb27f..2ef06bfe67 100755 --- a/docs/_layouts/global.html +++ b/docs/_layouts/global.html @@ -8,7 +8,6 @@ {{ page.title }} - - + + + diff --git a/docs/css/main.css b/docs/css/main.css index 957e9a6285..e6e9cd6755 100755 --- a/docs/css/main.css +++ b/docs/css/main.css @@ -3,12 +3,17 @@ ========================================================================== */ .navbar .brand { - background: url(../img/spark-logo-100x40px.png) no-repeat left center; + background: url(../img/spark-logo-77x40px-hd.png) no-repeat left center; height: 40px; - width: 100px; + width: 77px; padding: 0px; } +.navbar-inner { + padding-top: 5px; + padding-bottom: 5px; +} + body #content { line-height: 1.6; /* Inspired by Github's wiki style */ } diff --git a/docs/img/spark-logo-77x40px-hd.png b/docs/img/spark-logo-77x40px-hd.png new file mode 100644 index 0000000000..270402f100 Binary files /dev/null and b/docs/img/spark-logo-77x40px-hd.png differ -- cgit v1.2.3 From 462cd8be60bcd78180a31641b20c6d313e91f56d Mon Sep 17 00:00:00 2001 From: Andy Konwinski Date: Thu, 13 Sep 2012 15:35:47 -0700 Subject: Re-enabling responsive for better looking padding and more sane resizing, but removed the collapsable stuff from the nav bar. --- docs/_layouts/global.html | 48 ++++++++++++++++++++--------------------------- docs/css/main.css | 2 +- 2 files changed, 21 insertions(+), 29 deletions(-) diff --git a/docs/_layouts/global.html b/docs/_layouts/global.html index 2ef06bfe67..9393ad3cd0 100755 --- a/docs/_layouts/global.html +++ b/docs/_layouts/global.html @@ -16,9 +16,8 @@ padding-bottom: 40px; } - - - + + @@ -34,32 +33,25 @@
    - - - - - -
    - -
    +
    diff --git a/docs/css/main.css b/docs/css/main.css index e6e9cd6755..263c8ef8ea 100755 --- a/docs/css/main.css +++ b/docs/css/main.css @@ -6,7 +6,7 @@ background: url(../img/spark-logo-77x40px-hd.png) no-repeat left center; height: 40px; width: 77px; - padding: 0px; + padding: 0 10px 0 0; } .navbar-inner { -- cgit v1.2.3 From 6765d9727e6e374a8fc6a361c43e3ddc5c8e12db Mon Sep 17 00:00:00 2001 From: Andy Konwinski Date: Thu, 13 Sep 2012 16:52:53 -0700 Subject: Adds a jekyll plugin (written in Ruby) to the _plugins directory which generates scala doc by calling `sbt/sbt doc`, copies it over to docs, and updates the links from the api webpage to now point to the copied over scaladoc (making the _site directory easy to just copy over to a public website). --- docs/README.md | 12 ++++++++---- docs/_plugins/copy_api_dirs.rb | 28 ++++++++++++++++++++++++++++ docs/api.md | 8 ++++---- 3 files changed, 40 insertions(+), 8 deletions(-) create mode 100644 docs/_plugins/copy_api_dirs.rb diff --git a/docs/README.md b/docs/README.md index 9f179a437a..91862b50d4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,19 +2,21 @@ Welcome to the Spark documentation! This readme will walk you through navigating and building the Spark documentation, which is included here with the Spark source code. You can also find documentation specific to release versions of Spark at http://spark-project.org/documentation.html. -Read on to learn more about viewing documentation in plain text (i.e., markdown) or building the documentation yourself that corresponds to whichever version of Spark you currently have checked out of revision control. +Read on to learn more about viewing documentation in plain text (i.e., markdown) or building the documentation yourself. Why build it yourself? So that you have the docs that corresponds to whichever version of Spark you currently have checked out of revision control. ## Generating the Documentation HTML -We include the Spark documentation as part of the source (as opposed to using a hosted wiki as the definitive documentation) to enable the documentation to evolve along with the source code and be captured by revision control (currently git). This way the code automatically includes the version of the documentation that is relevant regardless of which version or release you have checked out or downloaded. +We include the Spark documentation as part of the source (as opposed to using a hosted wiki, such as the github wiki, as the definitive documentation) to enable the documentation to evolve along with the source code and be captured by revision control (currently git). This way the code automatically includes the version of the documentation that is relevant regardless of which version or release you have checked out or downloaded. In this directory you will find textfiles formatted using Markdown, with an ".md" suffix. You can read those text files directly if you want. Start with index.md. -To make things quite a bit prettier and make the links easier to follow, generate the html version of the documentation based on the src directory by running `jekyll` in the docs directory (You will need to have Jekyll installed, the easiest way to do this is via a Ruby Gem). This will create a directory called _site which will contain index.html as well as the rest of the compiled files. Read more about Jekyll at https://github.com/mojombo/jekyll/wiki. +To make things quite a bit prettier and make the links easier to follow, generate the html version of the documentation based on the src directory by running `jekyll` in the docs directory. To do so, you will need to have Jekyll installed, the easiest way to do this is via a Ruby Gem, see the [jekyll installation instructions](https://github.com/mojombo/jekyll/wiki/install). This will create a directory called _site containing index.html as well as the rest of the compiled files. Read more about Jekyll at https://github.com/mojombo/jekyll/wiki. + +In addition to generating the site as html from the markdown files, jekyll can serve up the site via a webserver. To build and run a webserver use the command `jekyll --server` which (currently) runs the webserver on port 4000, then visit the site at http://localhost:4000. ## Pygments -We also use pygments (http://pygments.org) for syntax highlighting, so you will also need to install that (it requires Python) by running `sudo easy_install Pygments`. +We also use pygments (http://pygments.org) for syntax highlighting in documentation markdown pages, so you will also need to install that (it requires Python) by running `sudo easy_install Pygments`. To mark a block of code in your markdown to be syntax highlighted by jekyll during the compile phase, use the following sytax: @@ -26,3 +28,5 @@ To mark a block of code in your markdown to be syntax highlighted by jekyll duri ## Scaladoc You can build just the Spark scaladoc by running `sbt/sbt doc` from the SPARK_PROJECT_ROOT directory. + +When you run `jekyll` in the docs directory, it will also copy over the scala doc for the various Spark subprojects into the docs directory (and then also into the _site directory). We use a jekyll plugin to run `sbt/sbt doc` before building the site so if you haven't run it (recently) it may take some time as it generates all of the scaladoc. diff --git a/docs/_plugins/copy_api_dirs.rb b/docs/_plugins/copy_api_dirs.rb new file mode 100644 index 0000000000..84f5e59fde --- /dev/null +++ b/docs/_plugins/copy_api_dirs.rb @@ -0,0 +1,28 @@ +require 'fileutils' +include FileUtils + +projects = ["core", "examples", "repl", "bagel"] + +puts "Moving to project root and building scaladoc." +curr_dir = pwd +cd("..") + +puts "Running sbt/sbt doc from " + pwd + "; this may take a few minutes..." +puts `sbt/sbt doc` + +puts "moving back into docs dir." +cd("docs") + +# Copy over the scaladoc from each project into the docs directory. +# This directory will be copied over to _site when `jekyll` command is run. +projects.each do |project_name| + source = "../" + project_name + "/target/scala-2.9.1/api" + dest = "api/" + project_name + + puts "echo making directory " + dest + mkdir_p dest + + # From the rubydoc: cp_r('src', 'dest') makes src/dest, but this doesn't. + puts "cp -r " + source + "/. " + dest + cp_r(source + "/.", dest) +end diff --git a/docs/api.md b/docs/api.md index b0acbe34c5..8a01023ad4 100644 --- a/docs/api.md +++ b/docs/api.md @@ -5,7 +5,7 @@ title: Spark API documentation (Scaladoc) Here you can find links to the Scaladoc generated for the Spark sbt subprojects. If the following links don't work, try running `sbt/sbt doc` from the Spark project home directory. -- [Core]({{HOME_PATH}}../../core/target/scala-2.9.1/api/index.html) -- [Examples]({{HOME_PATH}}../../examples/target/scala-2.9.1/api/index.html) -- [Repl]({{HOME_PATH}}../../repl/target/scala-2.9.1/api/index.html) -- [Bagel]({{HOME_PATH}}../../bagel/target/scala-2.9.1/api/index.html) +- [Core](api/core/index.html) +- [Examples](api/examples/index.html) +- [Repl](api/repl/index.html) +- [Bagel](api/bagel/index.html) -- cgit v1.2.3