You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@aurora.apache.org by jf...@apache.org on 2014/12/17 19:30:29 UTC
[04/18] incubator-aurora-website git commit: Initial move of website
over to git
http://git-wip-us.apache.org/repos/asf/incubator-aurora-website/blob/c43a3a2d/source/blog.html.erb
----------------------------------------------------------------------
diff --git a/source/blog.html.erb b/source/blog.html.erb
new file mode 100644
index 0000000..7c5b7f1
--- /dev/null
+++ b/source/blog.html.erb
@@ -0,0 +1,18 @@
+---
+title: Apache Aurora | Blog
+breadcrumb: Blog
+---
+<div class="row-fluid">
+ <div class="col-md-3">
+ <h4>Apache Aurora Blog</h4>
+ <p>The Aurora blog is a place for release announcements and for project committers to highlight features of the software.</p>
+ </div>
+ <div class="col-md-9">
+ <% blog.articles.each do |post| %>
+ <article>
+ <h2><%= link_to(post.title, post.url)%></h2>
+ <p><em>Posted by <%= post.data.post_author.display_name %>, <%= post.date.strftime("%B %e, %Y") %></em></p>
+ </article>
+ <% end %>
+ </div>
+</div>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-aurora-website/blob/c43a3a2d/source/blog/2014-12-08-aurora-0-6-0-incubating-released.md
----------------------------------------------------------------------
diff --git a/source/blog/2014-12-08-aurora-0-6-0-incubating-released.md b/source/blog/2014-12-08-aurora-0-6-0-incubating-released.md
new file mode 100644
index 0000000..9114159
--- /dev/null
+++ b/source/blog/2014-12-08-aurora-0-6-0-incubating-released.md
@@ -0,0 +1,54 @@
+---
+layout: post
+title: Aurora 0.6.0-incubating Released
+permalink: /blog/aurora-0-6-0-incubating-released/
+published: true
+post_author:
+ display_name: Bill Farner
+ twitter: wfarner
+tags: Release
+---
+
+The latest Apache Aurora release, 0.6.0-incubating, is now available for download. This version marks the second Aurora release since becoming part of the [Apache Incubator](http://incubator.apache.org), and includes the following features and improvements:
+
+ * Introduced highly-available, scheduler-driven job updates in beta ([AURORA-610](https://issues.apache.org/jira/browse/AURORA-610))
+ * Improvements to the Aurora web UI, including visualization of job updates
+ * Added automatic service registration in ZooKeeper ([AURORA-587](https://issues.apache.org/jira/browse/AURORA-587))
+ * Updates to Aurora client version two, deprecation of v1 coming in future release
+ * Lots of new [documentation](http://aurora.incubator.apache.org/documentation/latest/). Documentation now includes pages for [deploying the Aurora scheduler](http://aurora.incubator.apache.org/documentation/latest/deploying-aurora-scheduler/), [cron jobs](http://aurora.incubator.apache.org/documentation/latest/cron-jobs/), [SLA measurement](http://aurora.incubator.apache.org/documentation/latest/sla/), [storage](http://aurora.incubator.apache.org/documentation/latest/storage/), and [storage configuration and measurement](http://aurora.incubator.apache.org/documentation/latest/storage-config/).
+
+Full release notes are available in the release [CHANGELOG](https://git-wip-us.apache.org/repos/asf?p=incubator-aurora.git&f=CHANGELOG&hb=0.6.0-rc2).
+
+## Highly-available, scheduler-driven updates
+Rolling updates of services is a crucial feature in Aurora. As such, we
+want to take great care when changing its behavior. Previously, Aurora operated
+by delegating this functionality to the client (or any API client, for that
+matter). In this version, the scheduler can take over the
+responsibility of application update orchestration. Further details were discussed on the [Aurora mailing list](http://mail-archives.apache.org/mod_mbox/incubator-aurora-dev/201407.mbox/%3CCAGRA8uMxwVDokp_iHXhNru2gd-x_nM%2BDYAurpfAO6wuX7%3DnHFw%40mail.gmail.com%3E).
+
+## Aurora Web UI Improvements
+Since the scheduler can now orchestrate job updates, it has awareness of the progress and outcome of updates. This means you can see a progress bar for in-flight updates, and the history of updates for your jobs. Additionally, the performance of the UI was improved, especially for large roles and jobs [AURORA-458](https://issues.apache.org/jira/browse/AURORA-458).
+
+## Service Announcement and Management
+Job configurations can now supply an [`announce` parameter](http://aurora.incubator.apache.org/documentation/latest/configuration-reference/#announcer-objects), which is meant to be a way to opt-in for registration in a service discovery system. This has been implemented in the Aurora executor, and will automatically announce tasks via ZooKeeper.
+
+## Aurora Client Improvements
+Progress was made in features to [v2](http://aurora.incubator.apache.org/documentation/latest/clientv2/) of the [Aurora client](http://aurora.incubator.apache.org/documentation/latest/client-commands/). We will support version 1 and version 2 for 0.6.0, with version 1 to be removed in 0.7.0.
+
+## Improved Project Documentation
+New documentation pages including:
+
+ * [Deploying the Aurora scheduler](http://aurora.incubator.apache.org/documentation/latest/deploying-aurora-scheduler/)
+ * [Cron jobs](http://aurora.incubator.apache.org/documentation/latest/cron-jobs/)
+ * [SLA measurement](http://aurora.incubator.apache.org/documentation/latest/sla/)
+ * [Storage](http://aurora.incubator.apache.org/documentation/latest/storage/)
+ * [Storage configuration and measurement](http://aurora.incubator.apache.org/documentation/latest/storage-config/)
+ * [Monitoring](http://aurora.incubator.apache.org/documentation/latest/monitoring/)
+
+## Getting Involved
+We encourage you to try out this release and let us know what you think. If you run into any issues, please let us know on the [user mailing list and IRC](https://aurora.apache.org/community). The community also holds weekly IRC meetings at 11AM Pacific every Monday that you are welcome to join.
+
+## Thanks
+Thanks to the 16 contributors who made 0.6.0-incubating possible:
+
+Bill Farner, Maxim Khutornenko, Kevin Sweeney, Mark Chu-Carroll, Joshua Cohen, Zameer Manji, David McLaughlin, Brian Wickman, Joe Smith, Jake Farrell, Matthew Jeffryes, Dominic Hamon, Bjoern Metzdorf, Joseph Glanville, David Robinson, David Pan.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-aurora-website/blob/c43a3a2d/source/blog/feed.xml.erb
----------------------------------------------------------------------
diff --git a/source/blog/feed.xml.erb b/source/blog/feed.xml.erb
new file mode 100644
index 0000000..51bc2b9
--- /dev/null
+++ b/source/blog/feed.xml.erb
@@ -0,0 +1,25 @@
+<% coder = HTMLEntities.new %>
+
+<feed xmlns="http://www.w3.org/2005/Atom">
+ <title>Apache Aurora Blog</title>
+ <id>http://aurora.incubator.apache.org/blog</id>
+ <link href="http://aurora.incubator.apache.org/blog" />
+ <link href="http://aurora.incubator.apache.org/blog/feed.xml" rel="self"/>
+ <updated><%= blog.articles.first.date.to_time.iso8601 %></updated>
+ <% blog.articles.each do |article| %>
+ <entry>
+ <id>http://aurora.incubator.apache.org<%= article.url %></id>
+ <link href="<%= article.url %>" />
+ <title>
+ <%= article.title %>
+ </title>
+ <updated><%= article.date.to_time.iso8601 %></updated>
+ <author>
+ <name><%= article.data.post_author.display_name %></name>
+ </author>
+ <content type="html">
+ <%= coder.encode(article.body) %>
+ </content>
+ </entry>
+ <% end %>
+</feed>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-aurora-website/blob/c43a3a2d/source/community.html.md
----------------------------------------------------------------------
diff --git a/source/community.html.md b/source/community.html.md
new file mode 100644
index 0000000..7abc682
--- /dev/null
+++ b/source/community.html.md
@@ -0,0 +1,34 @@
+# Community
+
+<div class="row-fluid">
+ <div class="col-md-4">
+ <h3>Contributing to Aurora</h3>
+ <h4 name="reportbugs">Report or track a bug</h4>
+ <p>Bugs can be reported on our <a href="http://issues.apache.org/jira/browse/AURORA">JIRA issue tracker</a>. In order to create a new issue, you'll need register for an account.</p>
+
+ <h4 name="contribute">Submit a core patch</h4>
+ <p>Please follow our <a href="/docs/howtocontribute/">contribution guidelines</a> when submitting a patch. We welcome them!</p>
+ </div>
+ <div class="col-md-4">
+ <h3>Stay in Touch</h3>
+ <h4>Mailing lists</h4>
+ <p><strong>Developers</strong> - <a href="mailto:dev-subscribe@aurora.incubator.apache.org">Subscribe</a> | <a href="mailto:dev-unsubscribe@aurora.incubator.apache.org">Unsubscribe</a> | <a href="http://mail-archives.apache.org/mod_mbox/incubator-aurora-dev/">Archive</a><br />
+
+ <strong>Issues</strong> - <a href="mailto:issues-subscribe@aurora.incubator.apache.org">Subscribe</a> | <a href="mailto:issues-unsubscribe@aurora.incubator.apache.org">Unsubscribe</a> | <a href="http://mail-archives.apache.org/mod_mbox/incubator-aurora-issues/">Archive</a><br />
+
+ <strong>Commits</strong> - <a href="mailto:commits-subscribe@aurora.incubator.apache.org">Subscribe</a> | <a href="mailto:commits-unsubscribe@aurora.incubator.apache.org">Unsubscribe</a> | <a href="http://mail-archives.apache.org/mod_mbox/incubator-aurora-commits/">Archive</a><br />
+
+ <strong>Reviews</strong> - <a href="mailto:reviews-subscribe@aurora.incubator.apache.org">Subscribe</a> | <a href="mailto:reviews-unsubscribe@aurora.incubator.apache.org">Unsubscribe</a> | <a href="http://mail-archives.apache.org/mod_mbox/incubator-aurora-reviews/">Archive</a></p>
+
+ <h4 name="ircchannel">IRC</h4>
+ <p>Developers and users hang out in <code>#aurora</code> on <code>irc.freenode.net</code>. If you're new to IRC, we suggest trying a <a href="http://webchat.freenode.net/?channels=#aurora">web-based client</a>.</p>
+
+ <h4>Join our weekly IRC meetings</h4>
+ <p>We hold weekly IRC meetings as an opportunity for users and developers to engage. Meetings are every Monday at <a href="http://www.timeanddate.com/worldclock/fixedtime.html?msg=Aurora+Weekly+Meeting&iso=20140421T11&p1=224&ah=1">11AM Pacific Time</a>.</p>
+ </div>
+ <div class="col-md-4">
+ <h3>Follow the Project</h3>
+ <a class="twitter-timeline" href="https://twitter.com/ApacheAurora" data-widget-id="512693636127920129">Tweets by @ApacheMesos</a>
+ <script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+"://platform.twitter.com/widgets.js";fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");</script>
+ </div>
+</div>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-aurora-website/blob/c43a3a2d/source/developers.html.md
----------------------------------------------------------------------
diff --git a/source/developers.html.md b/source/developers.html.md
new file mode 100644
index 0000000..4fe641b
--- /dev/null
+++ b/source/developers.html.md
@@ -0,0 +1,13 @@
+# Developers
+<div class="row-fluid">
+ <h4 name="reportbugs">Report or track a bug</h4>
+ <p>New bugs can be reported on our <a href="http://issues.apache.org/jira/browse/AURORA">Jira issue tracker</a>. In order to create a new issue, you'll need to signup for an account.</p>
+
+ <h4 name="contribute">Contribute a core patch</h4>
+ <p>Follow our <a href="/docs/howtocontribute/">contribution guidelines</a> when submitting a patch.</p>
+
+ <h4 name="ircchannel">IRC Channel</h4>
+ <p>Many of the Aurora developers and users chat in the #aurora channel on irc.freenode.net.</p>
+
+ <p>If you are new to IRC, you can use a <a href="http://webchat.freenode.net/?channels=#aurora">web-based client</a>.</p>
+</div>
http://git-wip-us.apache.org/repos/asf/incubator-aurora-website/blob/c43a3a2d/source/docs/gettingstarted.html.md
----------------------------------------------------------------------
diff --git a/source/docs/gettingstarted.html.md b/source/docs/gettingstarted.html.md
new file mode 100644
index 0000000..6355e7c
--- /dev/null
+++ b/source/docs/gettingstarted.html.md
@@ -0,0 +1,3 @@
+# Getting Started
+
+The Aurora 'Getting Started' guide is [currently available on github](https://github.com/apache/incubator-aurora/blob/master/README.md) while the project moves its documentation to the Apache Software Foundation.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-aurora-website/blob/c43a3a2d/source/docs/howtocontribute.html.md
----------------------------------------------------------------------
diff --git a/source/docs/howtocontribute.html.md b/source/docs/howtocontribute.html.md
new file mode 100644
index 0000000..f20db29
--- /dev/null
+++ b/source/docs/howtocontribute.html.md
@@ -0,0 +1,50 @@
+How To Contribute
+=================
+
+Getting your ReviewBoard Account
+--------------------------------
+Go to https://reviews.apache.org and create an account.
+
+Setting up your ReviewBoard Environment
+---------------------------------------
+Run `./rbt status`. The first time this runs it will bootstrap and you will be asked to login.
+Subsequent runs will cache your login credentials.
+
+Submitting a Patch for Review
+-----------------------------
+Post a review with `rbt`, fill out the fields in your browser and hit Publish.
+
+ ./rbt post -o -g
+
+Updating an Existing Review
+---------------------------
+Incorporate review feedback, make some more commits, update your existing review, fill out the
+fields in your browser and hit Publish.
+
+ ./rbt post -o -r <RB_ID>
+
+Merging Your Own Review (Committers)
+------------------------------------
+Once you have shipits from the right committers, merge your changes in a single commit and mark
+the review as submitted. The typical workflow is:
+
+ git checkout master
+ git pull origin master
+ ./rbt patch -c <RB_ID> # Verify the automatically-generated commit message looks sane,
+ # editing if necessary.
+ git show master # Verify everything looks sane
+ git push origin master
+ ./rbt close <RB_ID>
+
+Note that even if you're developing using feature branches you will not use `git merge` - each
+commit will be an atomic change accompanied by a ReviewBoard entry.
+
+Merging Someone Else's Review
+-----------------------------
+Sometimes you'll need to merge someone else's RB. The typical workflow for this is
+
+ git checkout master
+ git pull origin master
+ ./rbt patch -c <RB_ID>
+ git show master # Verify everything looks sane, author is correct
+ git push origin master
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-aurora-website/blob/c43a3a2d/source/documentation/latest.html.md
----------------------------------------------------------------------
diff --git a/source/documentation/latest.html.md b/source/documentation/latest.html.md
new file mode 100644
index 0000000..fe20536
--- /dev/null
+++ b/source/documentation/latest.html.md
@@ -0,0 +1,36 @@
+# Documentation
+
+## Introduction
+Apache Aurora is a service scheduler that runs on top of Apache Mesos, enabling you to run long-running services that take advantage of Apache Mesos' scalability, fault-tolerance, and resource isolation. This documentation has been organized into sections with three audiences in mind:
+
+ * Users: General information about the project and to learn how to run an Aurora job.
+ * Operators: For those that wish to manage and fine-tune an Aurora cluster.
+ * Developers: All the information you need to start modifying Aurora and contributing back to the project.
+
+This documentation is a work in progress, and we encourage you to ask questions on the [Aurora developer list](http://aurora.incubator.apache.org/community/) or the `#aurora` IRC channel on `irc.freenode.net`.
+
+## Users
+ * [Install Aurora on virtual machines on your private machine](/documentation/latest/vagrant/)
+ * [Hello World Tutorial](/documentation/latest/tutorial/)
+ * [User Guide](/documentation/latest/user-guide/)
+ * [Configuration Tutorial](/documentation/latest/configuration-tutorial/)
+ * [Aurora + Thermos Reference](/documentation/latest/configuration-reference/)
+ * [Command Line Client](/documentation/latest/client-commands/)
+ * [Aurora Client v2](/documentation/latest/clientv2/)
+ * [Cron Jobs](/documentation/latest/cron-jobs/)
+
+## Operators
+ * [Deploy Aurora](/documentation/latest/deploying-aurora-scheduler/)
+ * [Monitoring](/documentation/latest/monitoring/)
+ * [Hooks for Aurora Client API](/documentation/latest/hooks/)
+ * [Scheduler Storage](/documentation/latest/storage/)
+ * [Scheduler Storage and Maintenance](/documentation/latest/storage-config/)
+ * [SLA Measurement](/documentation/latest/sla/)
+ * [Resource Isolation and Sizing](/documentation/latest/resource-isolation/)
+ * [Generating test resources](/documentation/latest/test-resource-generation/)
+
+## Developers
+ * [Contributing to the project](/documentation/latest/contributing/)
+ * [Developing the Aurora Scheduler](/documentation/latest/developing-aurora-scheduler/)
+ * [Developing the Aurora Client](/documentation/latest/developing-aurora-client/)
+ * [Committers Guide](/documentation/latest/committers/)
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-aurora-website/blob/c43a3a2d/source/documentation/latest/client-cluster-configuration.md
----------------------------------------------------------------------
diff --git a/source/documentation/latest/client-cluster-configuration.md b/source/documentation/latest/client-cluster-configuration.md
new file mode 100644
index 0000000..86bd17c
--- /dev/null
+++ b/source/documentation/latest/client-cluster-configuration.md
@@ -0,0 +1,71 @@
+# Client Cluster Configuration
+
+A cluster configuration file is used by the Aurora client to describe the Aurora clusters with
+which it can communicate. Ultimately this allows client users to reference clusters with short names
+like us-east and eu. The following properties may be set:
+
+ **Property** | **Type** | **Description**
+ :------------------------| :------- | :--------------
+ **name** | String | Cluster name (Required)
+ **slave_root** | String | Path to mesos slave work dir (Required)
+ **slave_run_directory** | String | Name of mesos slave run dir (Required)
+ **zk** | String | Hostname of ZooKeeper instance used to resolve Aurora schedulers.
+ **zk_port** | Integer | Port of ZooKeeper instance used to locate Aurora schedulers (Default: 2181)
+ **scheduler_zk_path** | String | ZooKeeper path under which scheduler instances are registered.
+ **scheduler_uri** | String | URI of Aurora scheduler instance.
+ **proxy_url** | String | Used by the client to format URLs for display.
+ **auth_mechanism** | String | The authentication mechanism to use when communicating with the scheduler. (Default: UNAUTHENTICATED)
+
+#### name
+
+The name of the Aurora cluster represented by this entry. This name will be the `cluster` portion of
+any job keys identifying jobs running within the cluster.
+
+#### slave_root
+
+The path on the mesos slaves where executing tasks can be found. It is used in combination with the
+`slave_run_directory` property by `aurora task run` and `aurora task ssh` to change into the sandbox
+directory after connecting to the host. This value should match the value passed to `mesos-slave`
+as `-work_dir`.
+
+#### slave_run_directory
+
+The name of the directory where the task run can be found. This is used in combination with the
+`slave_root` property by `aurora task run` and `aurora task ssh` to change into the sandbox
+directory after connecting to the host. This should almost always be set to `latest`.
+
+#### zk
+
+The hostname of the ZooKeeper instance used to resolve the Aurora scheduler. Aurora uses ZooKeeper
+to elect a leader. The client will connect to this ZooKeeper instance to determine the current
+leader. This host should match the host passed to the scheduler as `-zk_endpoints`.
+
+#### zk_port
+
+The port on which the ZooKeeper instance is running. If not set this will default to the standard
+ZooKeeper port of 2181. This port should match the port in the host passed to the scheduler as
+`-zk_endpoints`.
+
+#### scheduler_zk_path
+
+The path on the ZooKeeper instance under which the Aurora serverset is registered. This value should
+match the value passed to the scheduler as `-serverset_path`.
+
+#### scheduler_uri
+
+The URI of the scheduler. This would be used in place of the ZooKeeper related configuration above
+in circumstances where direct communication with a single scheduler is needed (e.g. testing
+environments). It is strongly advised to **never** use this property for production deploys.
+
+#### proxy_url
+
+Instead of using the hostname of the leading scheduler as the base url, if `proxy_url` is set, its
+value will be used instead. In that scenario the value for `proxy_url` would be, for example, the
+URL of your VIP in a loadbalancer or a roundrobin DNS name.
+
+#### auth_mechanism
+
+The identifier of an authentication mechanism that the client should use when communicating with the
+scheduler. Support for values other than `UNAUTHENTICATED` is currently not available, however work
+is [in progress](https://issues.apache.org/jira/browse/AURORA-720) to add federated authentication
+to Aurora which will allow for more robust configuration of client/scheduler authentication.
http://git-wip-us.apache.org/repos/asf/incubator-aurora-website/blob/c43a3a2d/source/documentation/latest/client-commands.md
----------------------------------------------------------------------
diff --git a/source/documentation/latest/client-commands.md b/source/documentation/latest/client-commands.md
new file mode 100644
index 0000000..809239f
--- /dev/null
+++ b/source/documentation/latest/client-commands.md
@@ -0,0 +1,516 @@
+Aurora Client Commands
+======================
+
+The most up-to-date reference is in the client itself: use the
+`aurora help` subcommand (for example, `aurora help` or
+`aurora help create`) to find the latest information on parameters and
+functionality. Note that `aurora help open` does not work, due to underlying issues with
+reflection.
+
+- [Introduction](#introduction)
+- [Cluster Configuration](#cluster-configuration)
+- [Job Keys](#job-keys)
+- [Modifying Aurora Client Commands](#modifying-aurora-client-commands)
+- [Regular Jobs](#regular-jobs)
+ - [Creating and Running a Job](#creating-and-running-a-job)
+ - [Running a Command On a Running Job](#running-a-command-on-a-running-job)
+ - [Killing a Job](#killing-a-job)
+ - [Updating a Job](#updating-a-job)
+ - [Asynchronous job updates (beta)](#user-content-asynchronous-job-updates-beta)
+ - [Renaming a Job](#renaming-a-job)
+ - [Restarting Jobs](#restarting-jobs)
+- [Cron Jobs](#cron-jobs)
+- [Comparing Jobs](#comparing-jobs)
+- [Viewing/Examining Jobs](#viewingexamining-jobs)
+ - [Listing Jobs](#listing-jobs)
+ - [Inspecting a Job](#inspecting-a-job)
+ - [Versions](#versions)
+ - [Checking Your Quota](#checking-your-quota)
+ - [Finding a Job on Web UI](#finding-a-job-on-web-ui)
+ - [Getting Job Status](#getting-job-status)
+ - [Opening the Web UI](#opening-the-web-ui)
+ - [SSHing to a Specific Task Machine](#sshing-to-a-specific-task-machine)
+ - [Templating Command Arguments](#templating-command-arguments)
+
+Introduction
+------------
+
+Once you have written an `.aurora` configuration file that describes
+your Job and its parameters and functionality, you interact with Aurora
+using Aurora Client commands. This document describes all of these commands
+and how and when to use them. All Aurora Client commands start with
+`aurora`, followed by the name of the specific command and its
+arguments.
+
+*Job keys* are a very common argument to Aurora commands, as well as the
+gateway to useful information about a Job. Before using Aurora, you
+should read the next section which describes them in detail. The section
+after that briefly describes how you can modify the behavior of certain
+Aurora Client commands, linking to a detailed document about how to do
+that.
+
+This is followed by the Regular Jobs section, which describes the basic
+Client commands for creating, running, and manipulating Aurora Jobs.
+After that are sections on Comparing Jobs and Viewing/Examining Jobs. In
+other words, various commands for getting information and metadata about
+Aurora Jobs.
+
+Cluster Configuration
+---------------------
+
+The client must be able to find a configuration file that specifies available clusters. This file
+declares shorthand names for clusters, which are in turn referenced by job configuration files
+and client commands.
+
+The client will load at most two configuration files, making both of their defined clusters
+available. The first is intended to be a system-installed cluster, using the path specified in
+the environment variable `AURORA_CONFIG_ROOT`, defaulting to `/etc/aurora/clusters.json` if the
+environment variable is not set. The second is a user-installed file, located at
+`~/.aurora/clusters.json`.
+
+A cluster configuration is formatted as JSON. The simplest cluster configuration is one that
+communicates with a single (non-leader-elected) scheduler. For example:
+
+```javascript
+[{
+ "name": "example",
+ "scheduler_uri": "localhost:55555",
+}]
+```
+
+A configuration for a leader-elected scheduler would contain something like:
+
+```javascript
+[{
+ "name": "example",
+ "zk": "192.168.33.7",
+ "scheduler_zk_path": "/aurora/scheduler"
+}]
+```
+
+For more details on cluster configuration see the
+[Client Cluster Configuration](/documentation/latest/client-cluster-configuration/) documentation.
+
+Job Keys
+--------
+
+A job key is a unique system-wide identifier for an Aurora-managed
+Job, for example `cluster1/web-team/test/experiment204`. It is a 4-tuple
+consisting of, in order, *cluster*, *role*, *environment*, and
+*jobname*, separated by /s. Cluster is the name of an Aurora
+cluster. Role is the Unix service account under which the Job
+runs. Environment is a namespace component like `devel`, `test`,
+`prod`, or `stagingN.` Jobname is the Job's name.
+
+The combination of all four values uniquely specifies the Job. If any
+one value is different from that of another job key, the two job keys
+refer to different Jobs. For example, job key
+`cluster1/tyg/prod/workhorse` is different from
+`cluster1/tyg/prod/workcamel` is different from
+`cluster2/tyg/prod/workhorse` is different from
+`cluster2/foo/prod/workhorse` is different from
+`cluster1/tyg/test/workhorse.`
+
+Role names are user accounts existing on the slave machines. If you don't know what accounts
+are available, contact your sysadmin.
+
+Environment names are namespaces; you can count on `prod`, `devel` and `test` existing.
+
+Modifying Aurora Client Commands
+--------------------------------
+
+For certain Aurora Client commands, you can define hook methods that run
+either before or after an action that takes place during the command's
+execution, as well as based on whether the action finished successfully or failed
+during execution. Basically, a hook is code that lets you extend the
+command's actions. The hook executes on the client side, specifically on
+the machine executing Aurora commands.
+
+Hooks can be associated with these Aurora Client commands.
+
+ - `cancel_update`
+ - `create`
+ - `kill`
+ - `restart`
+ - `update`
+
+The process for writing and activating them is complex enough
+that we explain it in a devoted document, [Hooks for Aurora Client API](/documentation/latest/hooks/).
+
+Regular Jobs
+------------
+
+This section covers Aurora commands related to running, killing,
+renaming, updating, and restarting a basic Aurora Job.
+
+### Creating and Running a Job
+
+ aurora create <job key> <configuration file>
+
+Creates and then runs a Job with the specified job key based on a `.aurora` configuration file.
+The configuration file may also contain and activate hook definitions.
+
+`create` can take four named parameters:
+
+- `-E NAME=VALUE` Bind a Thermos mustache variable name to a
+ value. Multiple flags specify multiple values. Defaults to `[]`.
+- ` -o, --open_browser` Open a browser window to the scheduler UI Job
+ page after a job changing operation happens. When `False`, the Job
+ URL prints on the console and the user has to copy/paste it
+ manually. Defaults to `False`. Does not work when running in Vagrant.
+- ` -j, --json` If specified, configuration argument is read as a
+ string in JSON format. Defaults to False.
+- ` --wait_until=STATE` Block the client until all the Tasks have
+ transitioned into the requested state. Possible values are: `PENDING`,
+ `RUNNING`, `FINISHED`. Default: `PENDING`
+
+### Running a Command On a Running Job
+
+ aurora run <job_key> <cmd>
+
+Runs a shell command on all machines currently hosting shards of a
+single Job.
+
+`run` supports the same command line wildcards used to populate a Job's
+commands; i.e. anything in the `{{mesos.*}}` and `{{thermos.*}}`
+namespaces.
+
+`run` can take three named parameters:
+
+- `-t NUM_THREADS`, `--threads=NUM_THREADS `The number of threads to
+ use, defaulting to `1`.
+- `--user=SSH_USER` ssh as this user instead of the given role value.
+ Defaults to None.
+- `-e, --executor_sandbox` Run the command in the executor sandbox
+ instead of the Task sandbox. Defaults to False.
+
+### Killing a Job
+
+ aurora kill <job key> <configuration file>
+
+Kills all Tasks associated with the specified Job, blocking until all
+are terminated. Defaults to killing all shards in the Job.
+
+The `<configuration file>` argument for `kill` is optional. Use it only
+if it contains hook definitions and activations that affect the
+kill command.
+
+`kill` can take two named parameters:
+
+- `-o, --open_browser` Open a browser window to the scheduler UI Job
+ page after a job changing operation happens. When `False`, the Job
+ URL prints on the console and the user has to copy/paste it
+ manually. Defaults to `False`. Does not work when running in Vagrant.
+- `--shards=SHARDS` A list of shard ids to act on. Can either be a
+ comma-separated list (e.g. 0,1,2) or a range (e.g. 0-2) or any
+ combination of the two (e.g. 0-2,5,7-9). Defaults to acting on all
+ shards.
+
+### Updating a Job
+
+ aurora update [--shards=ids] <job key> <configuration file>
+ aurora cancel_update <job key> <configuration file>
+
+Given a running job, does a rolling update to reflect a new
+configuration version. Only updates Tasks in the Job with a changed
+configuration. You can further restrict the operated on Tasks by
+using `--shards` and specifying a comma-separated list of job shard ids.
+
+You may want to run `aurora diff` beforehand to validate which Tasks
+have different configurations.
+
+Updating jobs are locked to be sure the update finishes without
+disruption. If the update abnormally terminates, the lock may stay
+around and cause failure of subsequent update attempts.
+ `aurora cancel_update `unlocks the Job specified by
+its `job_key` argument. Be sure you don't issue `cancel_update` when
+another user is working with the specified Job.
+
+The `<configuration file>` argument for `cancel_update` is optional. Use
+it only if it contains hook definitions and activations that affect the
+`cancel_update` command. The `<configuration file>` argument for
+`update` is required, but in addition to a new configuration it can be
+used to define and activate hooks for `update`.
+
+`update` can take four named parameters:
+
+- `--shards=SHARDS` A list of shard ids to update. Can either be a
+ comma-separated list (e.g. 0,1,2) or a range (e.g. 0-2) or any
+ combination of the two (e.g. 0-2,5,7-9). If not set, all shards are
+ acted on. Defaults to None.
+- `-E NAME=VALUE` Binds a Thermos mustache variable name to a value.
+ Use multiple flags to specify multiple values. Defaults to `[]`.
+- `-j, --json` If specified, configuration is read in JSON format.
+ Defaults to `False`.
+- `--updater_health_check_interval_seconds=HEALTH_CHECK_INTERVAL_SECONDS`
+ Time interval between subsequent shard status checks. Defaults to `3`.
+
+#### Asynchronous job updates (beta)
+
+As of 0.6.0, Aurora will coordinate updates (and rollbacks) within the
+scheduler. Performing updates this way also allows the scheduler to display
+update progress and job update history in the browser.
+
+There are several sub-commands to manage job updates:
+
+ aurora2 beta-update start <job key> <configuration file
+ aurora2 beta-update status <job key>
+ aurora2 beta-update pause <job key>
+ aurora2 beta-update resume <job key>
+ aurora2 beta-update abort <job key>
+ aurora2 beta-update list <cluster>
+
+When you `start` a job update, the command will return once it has sent the
+instructions to the scheduler. At that point, you may view detailed
+progress for the update with the `status` subcommand, in addition to viewing
+graphical progress in the web browser. You may also get a full listing of
+in-progress updates in a cluster with `list`.
+
+Once an update has been started, you can `pause` to keep the update but halt
+progress. This can be useful for doing things like debug a partially-updated
+job to determine whether you would like to proceed. You can `resume` to
+proceed.
+
+You may `abort` a job update regardless of the state it is in. This will
+instruct the scheduler to completely abandon the job update and leave the job
+in the current (possibly partially-updated) state.
+
+### Renaming a Job
+
+Renaming is a tricky operation as downstream clients must be informed of
+the new name. A conservative approach
+to renaming suitable for production services is:
+
+1. Modify the Aurora configuration file to change the role,
+ environment, and/or name as appropriate to the standardized naming
+ scheme.
+2. Check that only these naming components have changed
+ with `aurora diff`.
+
+ aurora diff <job_key> <job_configuration>
+
+3. Create the (identical) job at the new key. You may need to request a
+ temporary quota increase.
+
+ aurora create <new_job_key> <job_configuration>
+
+4. Migrate all clients over to the new job key. Update all links and
+ dashboards. Ensure that both job keys run identical versions of the
+ code while in this state.
+5. After verifying that all clients have successfully moved over, kill
+ the old job.
+
+ aurora kill <old_job_key>
+
+6. If you received a temporary quota increase, be sure to let the
+ powers that be know you no longer need the additional capacity.
+
+### Restarting Jobs
+
+`restart` restarts all of a job key identified Job's shards:
+
+ aurora restart <job_key> <configuration file>
+
+Restarts are controlled on the client side, so aborting
+the `restart` command halts the restart operation.
+
+`restart` does a rolling restart. You almost always want to do this, but
+not if all shards of a service are misbehaving and are
+completely dysfunctional. To not do a rolling restart, use
+the `-shards` option described below.
+
+**Note**: `restart` only applies its command line arguments and does not
+use or is affected by `update.config`. Restarting
+does ***not*** involve a configuration change. To update the
+configuration, use `update.config`.
+
+The `<configuration file>` argument for restart is optional. Use it only
+if it contains hook definitions and activations that affect the
+`restart` command.
+
+In addition to the required job key argument, there are eight
+`restart` specific optional arguments:
+
+- `--updater_health_check_interval_seconds`: Defaults to `3`, the time
+ interval between subsequent shard status checks.
+- `--shards=SHARDS`: Defaults to None, which restarts all shards.
+ Otherwise, only the specified-by-id shards restart. They can be
+ comma-separated `(0, 8, 9)`, a range `(3-5)` or a
+ combination `(0, 3-5, 8, 9-11)`.
+- `--batch_size`: Defaults to `1`, the number of shards to be started
+ in one iteration. So, for example, for value 3, it tries to restart
+ the first three shards specified by `--shards` simultaneously, then
+ the next three, and so on.
+- `--max_per_shard_failures=MAX_PER_SHARD_FAILURES`: Defaults to `0`,
+ the maximum number of restarts per shard during restart. When
+ exceeded, it increments the total failure count.
+- `--max_total_failures=MAX_TOTAL_FAILURES`: Defaults to `0`, the
+ maximum total number of shard failures tolerated during restart.
+- `-o, --open_browser` Open a browser window to the scheduler UI Job
+ page after a job changing operation happens. When `False`, the Job
+ url prints on the console and the user has to copy/paste it
+ manually. Defaults to `False`. Does not work when running in Vagrant.
+- `--restart_threshold`: Defaults to `60`, the maximum number of
+ seconds before a shard must move into the `RUNNING` state before
+ it's considered a failure.
+- `--watch_secs`: Defaults to `45`, the minimum number of seconds a
+ shard must remain in `RUNNING` state before considered a success.
+
+Cron Jobs
+---------
+
+You will see various commands and options relating to cron jobs in
+`aurora -help` and similar. Ignore them, as they're not yet implemented.
+You might be able to use them without causing an error, but nothing happens
+if you do.
+
+Comparing Jobs
+--------------
+
+ aurora diff <job_key> config
+
+Compares a job configuration against a running job. By default the diff
+is determined using `diff`, though you may choose an alternate
+ diff program by specifying the `DIFF_VIEWER` environment variable.
+
+There are two named parameters:
+
+- `-E NAME=VALUE` Bind a Thermos mustache variable name to a
+ value. Multiple flags may be used to specify multiple values.
+ Defaults to `[]`.
+- `-j, --json` Read the configuration argument in JSON format.
+ Defaults to `False`.
+
+Viewing/Examining Jobs
+----------------------
+
+Above we discussed creating, killing, and updating Jobs. Here we discuss
+how to view and examine Jobs.
+
+### Listing Jobs
+
+ aurora list_jobs
+ Usage: `aurora list_jobs cluster/role
+
+Lists all Jobs registered with the Aurora scheduler in the named cluster for the named role.
+
+It has two named parameters:
+
+- `--pretty`: Displays job information in prettyprinted format.
+ Defaults to `False`.
+- `-c`, `--show-cron`: Shows cron schedule for jobs. Defaults to
+ `False`. Do not use, as it's not yet implemented.
+
+### Inspecting a Job
+
+ aurora inspect <job_key> config
+
+`inspect` verifies that its specified job can be parsed from a
+configuration file, and displays the parsed configuration. It has four
+named parameters:
+
+- `--local`: Inspect the configuration that the `spawn` command would
+ create, defaulting to `False`.
+- `--raw`: Shows the raw configuration. Defaults to `False`.
+- `-j`, `--json`: If specified, configuration is read in JSON format.
+ Defaults to `False`.
+- `-E NAME=VALUE`: Bind a Thermos Mustache variable name to a value.
+ You can use multiple flags to specify multiple values. Defaults
+ to `[]`
+
+### Versions
+
+ aurora version
+
+Lists client build information and what Aurora API version it supports.
+
+### Checking Your Quota
+
+ aurora get_quota --cluster=CLUSTER role
+
+ Prints the production quota allocated to the role's value at the given
+cluster.
+
+### Finding a Job on Web UI
+
+When you create a job, part of the output response contains a URL that goes
+to the job's scheduler UI page. For example:
+
+ vagrant@precise64:~$ aurora create devcluster/www-data/prod/hello /vagrant/examples/jobs/hello_world.aurora
+ INFO] Creating job hello
+ INFO] Response from scheduler: OK (message: 1 new tasks pending for job www-data/prod/hello)
+ INFO] Job url: http://precise64:8081/scheduler/www-data/prod/hello
+
+You can go to the scheduler UI page for this job via `http://precise64:8081/scheduler/www-data/prod/hello`
+You can go to the overall scheduler UI page by going to the part of that URL that ends at `scheduler`; `http://precise64:8081/scheduler`
+
+Once you click through to a role page, you see Jobs arranged
+separately by pending jobs, active jobs and finished jobs.
+Jobs are arranged by role, typically a service account for
+production jobs and user accounts for test or development jobs.
+
+### Getting Job Status
+
+ aurora status <job_key>
+
+Returns the status of recent tasks associated with the
+`job_key` specified Job in its supplied cluster. Typically this includes
+a mix of active tasks (running or assigned) and inactive tasks
+(successful, failed, and lost.)
+
+### Opening the Web UI
+
+Use the Job's web UI scheduler URL or the `aurora status` command to find out on which
+machines individual tasks are scheduled. You can open the web UI via the
+`open` command line command if invoked from your machine:
+
+ aurora open [<cluster>[/<role>[/<env>/<job_name>]]]
+
+If only the cluster is specified, it goes directly to that cluster's
+scheduler main page. If the role is specified, it goes to the top-level
+role page. If the full job key is specified, it goes directly to the job
+page where you can inspect individual tasks.
+
+### SSHing to a Specific Task Machine
+
+ aurora ssh <job_key> <shard number>
+
+You can have the Aurora client ssh directly to the machine that has been
+assigned a particular Job/shard number. This may be useful for quickly
+diagnosing issues such as performance issues or abnormal behavior on a
+particular machine.
+
+It can take three named parameters:
+
+- `-e`, `--executor_sandbox`: Run `ssh` in the executor sandbox
+ instead of the task sandbox. Defaults to `False`.
+- `--user=SSH_USER`: `ssh` as the given user instead of as the role in
+ the `job_key` argument. Defaults to none.
+- `-L PORT:NAME`: Add tunnel from local port `PORT` to the remote
+ named port `NAME`. Defaults to `[]`.
+
+### Templating Command Arguments
+
+ aurora run [-e] [-t THREADS] <job_key> -- <<command-line>>
+
+Given a job specification, run the supplied command on all hosts and
+return the output. You may use the standard Mustache templating rules:
+
+- `{{thermos.ports[name]}}` substitutes the specific named port of the
+ task assigned to this machine
+- `{{mesos.instance}}` substitutes the shard id of the job's task
+ assigned to this machine
+- `{{thermos.task_id}}` substitutes the task id of the job's task
+ assigned to this machine
+
+For example, the following type of pattern can be a powerful diagnostic
+tool:
+
+ aurora run -t5 cluster1/tyg/devel/seizure -- \
+ 'curl -s -m1 localhost:{{thermos.ports[http]}}/vars | grep uptime'
+
+By default, the command runs in the Task's sandbox. The `-e` option can
+run the command in the executor's sandbox. This is mostly useful for
+Aurora administrators.
+
+You can parallelize the runs by using the `-t` option.
http://git-wip-us.apache.org/repos/asf/incubator-aurora-website/blob/c43a3a2d/source/documentation/latest/clientv2.md
----------------------------------------------------------------------
diff --git a/source/documentation/latest/clientv2.md b/source/documentation/latest/clientv2.md
new file mode 100644
index 0000000..471d80c
--- /dev/null
+++ b/source/documentation/latest/clientv2.md
@@ -0,0 +1,406 @@
+Aurora Client v2
+=================
+
+Overview
+-----------
+
+Our goal is to replace the current Aurora command-line client. The
+current client suffers from an early monolithic structure, and a long
+development history of rapid unplanned evolution.
+
+In addition to its internal problems, the current Aurora client is
+confusing for users. There are several different kinds of objects
+manipulated by the Aurora command line, and the difference between
+them is often not clear. (What's the difference between a job and a
+configuration?) For each type of object, there are different commands,
+and it's hard to remember which command should be used for which kind
+of object.
+
+Instead of continuing to let the Aurora client develop and evolve
+randomly, it's time to take a principled look at the Aurora command
+line, and figure out how to make our command line processing make
+sense. At the same time, the code needs to be cleaned up, and divided
+into small comprehensible units based on a plugin architecture.
+
+Doing this now will give us a more intuitive, consistent, and easy to
+use client, as well as a sound platform for future development.
+
+Goals
+-------
+
+* A command line tool for interacting with Aurora that is easy for
+ users to understand.
+* A noun/verb command model.
+* A modular source-code architecture.
+* Non-disruptive transition for users.
+
+Non-Goals
+----------
+
+* The most important non-goal is that we're not trying to redesign the
+ Aurora scheduler, the Aurora executor, or any of the peripheral tools
+ that the Aurora command line interacts with; we only want to create a
+ better command line client.
+* We do not want to change thermos, mesos, hadoop, etc.
+* We do not want to create new objects that users will work with to
+ interact with Mesos or Aurora.
+* We do not want to change Aurora job configuration files or file formats.
+* We do not want to change the Aurora API.
+* We don't want to boil the ocean: there are many things that we could
+ include in the scope of this project, but we don't want to be
+ distracted by re-implementing all of twitter.commons in order to
+ create a perfect Aurora client.
+
+
+Background
+-----------
+
+Aurora is a system that's used to run and manage services and
+service-like jobs running in a datacenter. Aurora takes care of
+allocating resources in order to schedule and run jobs without
+requiring teams to manage dedicated hardware. The heart of Aurora is
+called the scheduler, and is responsible for finding and assigning
+resources to tasks.
+
+The Aurora scheduler provides a thrift API. The scheduler API is
+low-level and difficult to interact with. Users do not interact
+directly with the Aurora API; instead, they use a command-line tool,
+which provides a collection of easy-to-use commands. This command-line
+tool, in turn, talks to the scheduler API to launch and manage jobs in
+datacenter clusters. The command-line tool is called the Aurora
+client.
+
+The current implementation of the Aurora client is haphazard,
+and really needs to be cleaned up:
+
+- The code is monolithic and hard to maintain. It's implemented using
+ `twitter.common.app`, which assumes that all of the command code lives
+ in a single source file. To work around this, and allow some
+ subdivision, it uses a hack of `twitter.common.app` to force
+ registration of commands from multiple modules. It's hard to
+ understand, and hard to modify.
+- The current code is very difficult to test. Because of the way it's
+ built, there is no consistent way of passing key application data
+ around. As a result, each unit test of client operations needs a
+ difficult-to-assemble custom setup of mock objects.
+- The current code handles errors poorly, and it is difficult to
+ fix. Many common errors produce unacceptable results. For example,
+ issuing an unknown command generates an error message "main takes 0
+ parameters but received 1"; passing an invalid parameter to other
+ commands frequently produces a stack trace.
+- The current command line is confusing for users. There are several
+ different kinds of objects manipulated by the Aurora command line,
+ and the difference between them is often not entirely clear. (What's
+ the difference between a job and a configuration?)
+ For each type of object, there are different
+ commands, and it's frequently not clear just which command should be
+ used for which object.
+
+
+Instead of continuing to let it develop and evolve randomly, it's time
+to take a principled look at the Aurora command line, and figure out
+how to make command line processing make sense. At the same time, the
+code needs to be cleaned up, and divided into small comprehensible
+units based on a plugin architecture.
+
+Requirements
+-------------
+
+Aurora is aimed at engineers who run jobs and services in a
+datacenter. As a result, the requirements for the aurora client are
+all engineering focused:
+
+* __Consistency__: commands should follow a consistent structure, so that
+ users can apply knowledge and intuition gained from working with
+ some aurora commands to new commands. This means that when commands
+ can re-use the same options, they should; that objects should be
+ referred to by consistent syntax throughout the tool.
+* __Helpfulness__: commands should be structured so that the system can
+ generate helpful error messages. If a user just runs "aurora", they
+ should get a basic usage message. If they try to run an invalid
+ command, they should get a message that the command is invalid, not
+ a stack dump or "command main() takes 0 parameters but received
+ 2". Commands should not generate extraneous output that obscures the
+ key facts that the user needs to know, and the default behavior of
+ commands should not generate outputs that will be routinely ignored
+ by users.
+* __Extensibility__: it should be easy to plug in new commands,
+ including custom commands, to adapt the Aurora client to new
+ environments.
+* __Script-friendly command output__: every command should at least include
+ an option that generates output that's script-friendly. Scripts should be
+ able to work with command-output without needing to do screen scraping.
+* __Scalability__: the tools should be usable for any foreseeable size
+ of Aurora datacenters and machine clusters.
+
+Design Overview
+-----------------
+
+The Aurora client will be reimplemented using a noun-verb model,
+similar to the cmdlet model used by Monad/Windows Powershell. Users
+will work by providing a noun for the type of object being operated
+on, and a verb for the specific operation being performed on the
+object, followed by parameters. For example, to create a job, the user
+would execute: "`aurora job create smfd/mchucarroll/devel/jobname
+job.aurora`". The noun is `job` and the verb is `create`.
+
+The client will be implemented following that noun-verb
+convention. Each noun will be a separate component, which can be
+registered into the command-line framework. Each verb will be
+implemented by a class that registers with the appropriate noun. Nouns
+and verbs will each provide methods that add their command line
+options and parameters to the options parser, using the Python
+argparse library.
+
+Detailed Design
+-----------------
+
+### Interface
+
+In this section, we'll walk through the types of objects that the
+client can manipulate, and the operations that need to be provided for
+each object. These form the primary interface that engineers will use
+to interact with Aurora.
+
+In the command-line, each of the object types will have an Aurora
+subcommand. The commands to manipulate the object type will follow the
+type. For example, here are several commands in the old syntax
+contrasted against the new noun/verb syntax.
+
+* Get quota for a role:
+ * Noun/Verb syntax: `aurora quota get west/www-data`
+ * Old syntax: `aurora get_quota --cluster=smf1 www-data`
+* Create job:
+ * Noun/Verb syntax: `aurora job create west/www-data/test/job job.aurora`
+ * Old syntax: `aurora create west/www-data/test/job job.aurora`
+* Schedule a job to run at a specific interval:
+ * Noun/verb: `aurora cron schedule east/www-data/test/job job.aurora`
+ * Old: `aurora create east/www-data/test/job job.aurora`
+
+As you can see in these examples, the new syntax is more consistent:
+you always specify the cluster where a command executes as part of an
+identifier, where in the old syntax, it was sometimes part of the
+jobkey and sometimes specified with a "--cluster" option.
+
+The new syntax is also more clear and explicit: even without knowing
+much about Aurora, it's clear what objects each command is acting on,
+where in the old syntax, commands like "create" are unclear.
+
+### The Job Noun
+
+A job is a configured program ready to run in Aurora. A job is,
+conceptually, a task factory: when a job is submitted to the Aurora
+scheduler, it creates a collection of tasks. The job contains a
+complete description of everything it needs to create a collection of
+tasks. (Note that this subsumes "service" commands. A service is just
+a task whose configuration sets the is_service flag, so we don't have
+separate commands for working with services.) Jobs are specified using
+`cluster/role/env/name` jobkey syntax.
+
+* `aurora job create *jobkey* *config*`: submits a job to a cluster, launching the task(s) specified by the job config.
+* `aurora job status *jobkey*`: query job status. Prints information about the job,
+ whether it's running, etc., to standard out. If jobkey includes
+ globs, it should list all jobs that match the glob
+* `aurora job kill *jobkey*/*instanceids*`: kill/stop some of a jobs instances. This stops a job' tasks; if the job
+ has service tasks, they'll be disabled, so that they won't restart.
+* `aurora job killall *jobkey*`: kill all of the instances of a job. This
+ is distinct from the *kill* command as a safety measure: omitting the
+ instances from a kill command shouldn't result in destroying the entire job.
+* `aurora job restart *jobkey*`: conceptually, this will kill a job, and then
+ launch it again. If the job does not exist, then fail with an error
+ message. In fact, the underlying implementation does the
+ kill/relaunch on a rolling basis - so it's not an immediate kill of
+ all shards/instances, followed by a delay as all instances relaunch,
+ but rather a controlled gradual process.
+* `aurora job list *jobkey*`: list all jobs that match the jobkey spec that are
+ registered with the scheduler. This will include both jobs that are
+ currently running, and jobs that are scheduled to run at a later
+ time. The job key can be partial: if it specifies cluster, all jobs
+ on the cluster will be listed; cluster/role, all jobs running on the cluster under the role will be listed, etc.
+
+The Schedule Noun (Cron)
+--------------------------
+
+Note (3/21/2014): The "cron" noun is _not_ implemented yet.
+
+Cron is a scheduler adjunct that periodically runs a job on a
+schedule. The cron commands all manipulate cron schedule entries. The
+schedules are specified as a part of the job configuration.
+
+* `aurora cron schedule jobkey config`: schedule a job to run by cron. If a cron job already exists
+replaces its template with a new one.
+* `aurora cron deschedule jobkey`: removes a jobs entry from the cron schedule.
+* `aurora cron status jobkey`: query for a scheduled job's status.
+
+The Quota Noun
+---------------
+
+A quota is a data object maintained by the scheduler that specifies the maximum
+resources that may be consumed by jobs owned by a particular role. In the future,
+we may add new quota types. At some point, we'll also probably add an administrators
+command to set quotas.
+
+* `aurora quota get *cluster/role*`
+
+
+Implementation
+---------------
+
+The current command line is monolithic. Every command on an Aurora
+object is a top-level command in the Aurora client. In the
+restructured command line, each of the primary object types
+manipulated by Aurora should have its own sub-command.
+
+* Advantages of this approach:
+ * Easier to detangle the command-line processing. The top-level
+ command-processing will be a small set of subcommand
+ processors. Option processing for each subcommand can be offloaded
+ to a separate module.
+ * The aurora top-level help command will be much more
+ comprehensible. Instead of giving a huge list of every possible
+ command, it will present the list of top-level object types, and
+ then users can request help on the commands for a specific type
+ of object.
+ * The sub-commands can be separated into distinct command-line
+ tools when appropriate.
+
+### Command Structure and Options Processing
+
+The implementation will follow closely on Pants goals. Pants goals use
+a static registration system to add new subcommands. In pants, each
+goal command is an implementation of a command interface, and provides
+implementations of methods to register options and parameters, and to
+actually execute the command. In this design, commands are modular and
+easy to implement, debug, and combine in different ways.
+
+For the Aurora client, we plan to use a two-level variation of the
+basic concept from pants. At the top-level we will have nouns. A noun
+will define some common command-line parameters required by all of its
+verbs, and will provide a registration hook for attaching verbs. Nouns
+will be implemented as a subclass of a basic Noun type.
+
+Each verb will, similarly, be implemented as a subclass of Verb. Verbs
+will be able to specify command-line options and parameters.
+
+Both `Noun` and `Verb` will be subclasses of a common base-class `AuroraCommand`:
+
+ class AuroraCommand(object):
+ def get_options(self):
+ """Gets the set of command-line options objects for this command.
+ The result is a list of CommandOption objects.
+ """
+ pass
+
+ @property
+ def help(self):
+ """Returns the help message for this command"""
+
+ @property
+ def usage(self):
+ """Returns a short usage description of the command"""
+
+ @property
+ def name(self):
+ """Returns the command name"""
+
+
+A command-line tool will be implemented as an instance of a `CommandLine`:
+
+ class CommandLine(object):
+ """The top-level object implementing a command-line application."""
+
+ @property
+ def name(self):
+ """Returns the name of this command-line tool"""
+
+ def print_out(self, str):
+ print(str)
+
+ def print_err(self, str):
+ print(str, file=sys.stderr)
+
+ def register_noun(self, noun):
+ """Adds a noun to the application"""
+
+ def register_plugin(self, plugin):
+ """Adds a configuration plugin to the system"""
+
+
+Nouns are registered into a command-line using the `register_noun`
+method. They are weakly coupled to the application, making it easy to
+use a single noun in several different command-line tools. Nouns allow
+the registration of verbs using the `register_verb` method.
+
+When commands execute, they're given an instance of a *context object*.
+The context object must be an instance of a subclass of `AuroraCommandContext`.
+Options, parameters, and IO are all accessed using the context object. The context
+is created dynamically by the noun object owning the verb being executed. Developers
+are strongly encouraged to implement custom contexts for their nouns, and move functionality
+shared by the noun's verbs into the context object. The context interface is:
+
+ class Context(object):
+ class Error(Exception): pass
+
+ class ArgumentException(Error): pass
+
+ class CommandError(Error):
+
+ @classmethod
+ def exit(cls, code, msg):
+ """Exit the application with an error message"""
+ raise cls.CommandError(code, msg)
+
+ def print_out(self, msg, indent=0):
+ """Prints a message to standard out, with an indent"""
+
+ def print_err(self, msg, indent=0):
+ """Prints a message to standard err, with an indent"""
+
+
+In addition to nouns and verbs, there's one more kind of registerable
+component, called a *configuration plugin*. These objects add a set of
+command-line options that can be passed to *all* of the commands
+implemented in the tool. Before the command is executed, the
+configuration plugin will be invoked, and will process its
+command-line arguments. This is useful for general configuration
+changes, like establish a secure tunnel to talk to machines in a
+datacenter. (A useful way to think of a plugin is as something like an
+aspect that can be woven in to aurora to provide environment-specific
+configuration.) A configuration plugin is implemented as an instance
+of class `ConfigurationPlugin`, and registered with the
+`register_plugin` method of the `CommandLine` object. The interface of
+a plugin is:
+
+ class ConfigurationPlugin(object):
+ """A component that can be plugged in to a command-line."""
+
+ @abstractmethod
+ def get_options(self):
+ """Return the set of options processed by this plugin"""
+
+ @abstractmethod
+ def execute(self, context):
+ """Run the context/command line initialization code for this plugin."""
+
+
+### Command Execution
+
+The options process and command execution is built as a facade over Python's
+standard argparse. All of the actual argument processing is done by the
+argparse library.
+
+Once the options are processed, the framework will start to execute the command. Command execution consists of:
+
+# Create a context object. The framework will use the argparse options to identify
+ which noun is being invoked, and will call that noun's `create_context` method.
+ The argparse options object will be stored in the context.
+# Execute any configuration plugins. Before any command is invoked, the framework
+ will first iterate over all of the registered configuration plugins. For each
+ plugin, it will invoke the `execute` method.
+# The noun will use the context to find out what verb is being invoked, and it will
+ then call that verb's `execute` method.
+# The command will exit. Its return code will be whatever was returned by the verb's
+ `execute` method.
+
+Commands are expected to return a code from a list of standard exit codes,
+which can be found in `src/main/python/apache/aurora/client/cli/__init__.py`.
http://git-wip-us.apache.org/repos/asf/incubator-aurora-website/blob/c43a3a2d/source/documentation/latest/committers.md
----------------------------------------------------------------------
diff --git a/source/documentation/latest/committers.md b/source/documentation/latest/committers.md
new file mode 100644
index 0000000..23a25c1
--- /dev/null
+++ b/source/documentation/latest/committers.md
@@ -0,0 +1,79 @@
+Setting up your email account
+-----------------------------
+Once your Apache ID has been set up you can configure your account and add ssh keys and setup an
+email forwarding address at
+
+ http://id.apache.org
+
+Additional instructions for setting up your new committer email can be found at
+
+ http://www.apache.org/dev/user-email.html
+
+The recommended setup is to configure all services (mailing lists, JIRA, ReviewBoard) to send
+emails to your @apache.org email address.
+
+
+Creating a gpg key for releases
+-------------------------------
+In order to create a release candidate you will need a gpg key published to an external key server
+and that key will need to be added to our KEYS file as well.
+
+1. Create a key:
+
+ gpg --gen-key
+
+2. Add your gpg key to the Apache Aurora KEYS file:
+
+ git clone https://git-wip-us.apache.org/repos/asf/incubator-aurora.git
+ (gpg --list-sigs <KEY ID> && gpg --armor --export <KEY ID>) >> KEYS
+ git add KEYS && git commit -m "Adding gpg key for <APACHE ID>"
+ ./rbt post -o -g
+
+3. Publish the key to an external key server:
+
+ gpg --keyserver pgp.mit.edu --send-keys <KEY ID>
+
+4. Update the changes to the KEYS file to the Apache Aurora svn dist locations listed below:
+
+ https://dist.apache.org/repos/dist/dev/incubator/aurora/KEYS
+ https://dist.apache.org/repos/dist/release/incubator/aurora/KEYS
+
+5. Add your key to git config for use with the release scripts:
+
+ git config --global user.signingkey <KEY ID>
+
+
+Creating a release
+------------------
+The following will guide you through the steps to create a release candidate, vote, and finally an
+official Apache Aurora release. Before starting your gpg key should be in the KEYS file and you
+must have access to commit to the dist.a.o repositories.
+
+1. Ensure that all issues resolved for this release candidate are tagged with the correct Fix
+Version in Jira, the changelog script will use this to generate the CHANGELOG in step #2.
+
+2. Create a release candidate. This will automatically update the CHANGELOG and commit it, create a
+branch and update the current version within the trunk. To create a minor version update and publish
+it run
+
+ ./build-support/release/release-candidate -l m -p
+
+3. Update, if necessary, the draft email created from the `release-candidate` script in step #2 and
+send the [VOTE] email to the dev@ and private@ mailing lists. You can verify the release signature
+and checksums by running
+
+ ./build-support/release/verify-release-candidate
+
+4. Wait for the vote to complete. If the vote fails address any issues and go back to step #1 and
+run again, this time you will use the -r flag to increment the release candidate version. This will
+automatically clean up the release candidate rc0 branch and source distribution.
+
+ ./build-support/release/release-candidate -l m -r 1 -p
+
+5. Once the vote has successfully passed create the release
+
+ ./build-support/release/release
+
+6. Update the draft email created fom the `release` script in step #5 to include the Apache ID's for
+all binding votes and send the [RESULT][VOTE] email to the dev@ and private@ mailing lists.
+