aurora-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dles...@apache.org
Subject svn commit: r1633259 - in /incubator/aurora/site: publish/documentation/latest/client-cluster-configuration/ publish/documentation/latest/client-commands/ publish/documentation/latest/configuration-tutorial/ publish/documentation/latest/contributing/ p...
Date Tue, 21 Oct 2014 00:49:04 GMT
Author: dlester
Date: Tue Oct 21 00:49:03 2014
New Revision: 1633259

URL: http://svn.apache.org/r1633259
Log:
Adds Client Cluster Configuration docs, and updates other docs.

Added:
    incubator/aurora/site/publish/documentation/latest/client-cluster-configuration/
    incubator/aurora/site/publish/documentation/latest/client-cluster-configuration/index.html
    incubator/aurora/site/source/documentation/latest/client-cluster-configuration.md
Modified:
    incubator/aurora/site/publish/documentation/latest/client-commands/index.html
    incubator/aurora/site/publish/documentation/latest/configuration-tutorial/index.html
    incubator/aurora/site/publish/documentation/latest/contributing/index.html
    incubator/aurora/site/publish/documentation/latest/deploying-aurora-scheduler/index.html
    incubator/aurora/site/publish/documentation/latest/developing-aurora-client/index.html
    incubator/aurora/site/publish/documentation/latest/user-guide/index.html
    incubator/aurora/site/source/documentation/latest/client-commands.md
    incubator/aurora/site/source/documentation/latest/configuration-tutorial.md
    incubator/aurora/site/source/documentation/latest/contributing.md
    incubator/aurora/site/source/documentation/latest/deploying-aurora-scheduler.md
    incubator/aurora/site/source/documentation/latest/developing-aurora-client.md
    incubator/aurora/site/source/documentation/latest/user-guide.md

Added: incubator/aurora/site/publish/documentation/latest/client-cluster-configuration/index.html
URL: http://svn.apache.org/viewvc/incubator/aurora/site/publish/documentation/latest/client-cluster-configuration/index.html?rev=1633259&view=auto
==============================================================================
--- incubator/aurora/site/publish/documentation/latest/client-cluster-configuration/index.html (added)
+++ incubator/aurora/site/publish/documentation/latest/client-cluster-configuration/index.html Tue Oct 21 00:49:03 2014
@@ -0,0 +1,220 @@
+<html>
+    <head>
+        <meta charset="utf-8">
+        <title>Apache Aurora</title>
+		    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+		    <meta name="description" content="">
+		    <meta name="author" content="">
+
+		    <link href="/assets/css/bootstrap.css" rel="stylesheet">
+		    <link href="/assets/css/bootstrap-responsive.min.css" rel="stylesheet">
+		    <link href="/assets/css/main.css" rel="stylesheet">
+				
+		    <!-- JS -->
+		    <script type="text/javascript" src="/assets/js/jquery-1.10.1.min.js"></script>
+		    <script type="text/javascript" src="/assets/js/bootstrap-dropdown.js"></script>
+		
+				<!-- Analytics -->
+				<script type="text/javascript">
+					  var _gaq = _gaq || [];
+					  _gaq.push(['_setAccount', 'UA-45879646-1']);
+					  _gaq.push(['_setDomainName', 'apache.org']);
+					  _gaq.push(['_trackPageview']);
+
+					  (function() {
+					    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+					    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+					    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+					  })();
+				</script>
+	</head>
+    <body>	
+      <div class="navbar navbar-static-top">
+  <div class="navbar-inner">
+    <div class="container">
+	    <a href="/" class="logo"><img src="/assets/img/aurora_logo.png" alt="Apache Aurora logo" /></a>
+      <ul class="nav">
+				<li><a href="/documentation/latest/">Documentation</a></li>
+        <li><a href="/downloads/">Download</a></li>
+        <li><a href="/community">Community</a></li>
+      </ul>
+    </div>
+  </div>
+</div>
+
+<div class="container">
+<!-- magical breadcrumbs -->
+<ul class="breadcrumb">
+  <li>
+    <div class="dropdown">
+      <a class="dropdown-toggle" data-toggle="dropdown" href="#">Apache Software Foundation <b class="caret"></b></a>
+      <ul class="dropdown-menu" role="menu">
+        <li><a href="http://www.apache.org">Apache Homepage</a></li>
+        <li><a href="http://www.apache.org/licenses/">Apache License</a></li>
+        <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>  
+        <li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+        <li><a href="http://www.apache.org/security/">Security</a></li>
+      </ul>
+    </div>
+  </li>
+  <li><span class="divider">&bull;</span></li>
+  <li><a href="http://incubator.apache.org">Apache Incubator</a></li>
+  <li><span class="divider">&bull;</span></li>
+  <li><a href="http://aurora.incubator.apache.org">Apache Aurora</a></li>
+</ul>
+<!-- /breadcrumb -->
+	
+      <div class="container">
+        <h1 id="client-cluster-configuration">Client Cluster Configuration</h1>
+
+<p>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:</p>
+
+<table><thead>
+<tr>
+<th style="text-align: left"><strong>Property</strong></th>
+<th style="text-align: left"><strong>Type</strong></th>
+<th style="text-align: left"><strong>Description</strong></th>
+</tr>
+</thead><tbody>
+<tr>
+<td style="text-align: left"><strong>name</strong></td>
+<td style="text-align: left">String</td>
+<td style="text-align: left">Cluster name (Required)</td>
+</tr>
+<tr>
+<td style="text-align: left"><strong>slave_root</strong></td>
+<td style="text-align: left">String</td>
+<td style="text-align: left">Path to mesos slave work dir (Required)</td>
+</tr>
+<tr>
+<td style="text-align: left"><strong>slave<em>run</em>directory</strong></td>
+<td style="text-align: left">String</td>
+<td style="text-align: left">Name of mesos slave run dir (Required)</td>
+</tr>
+<tr>
+<td style="text-align: left"><strong>zk</strong></td>
+<td style="text-align: left">String</td>
+<td style="text-align: left">Hostname of ZooKeeper instance used to resolve Aurora schedulers.</td>
+</tr>
+<tr>
+<td style="text-align: left"><strong>zk_port</strong></td>
+<td style="text-align: left">Integer</td>
+<td style="text-align: left">Port of ZooKeeper instance used to locate Aurora schedulers (Default: 2181)</td>
+</tr>
+<tr>
+<td style="text-align: left"><strong>scheduler<em>zk</em>path</strong></td>
+<td style="text-align: left">String</td>
+<td style="text-align: left">ZooKeeper path under which scheduler instances are registered.</td>
+</tr>
+<tr>
+<td style="text-align: left"><strong>scheduler_uri</strong></td>
+<td style="text-align: left">String</td>
+<td style="text-align: left">URI of Aurora scheduler instance.</td>
+</tr>
+<tr>
+<td style="text-align: left"><strong>proxy_url</strong></td>
+<td style="text-align: left">String</td>
+<td style="text-align: left">Used by the client to format URLs for display.</td>
+</tr>
+<tr>
+<td style="text-align: left"><strong>auth_mechanism</strong></td>
+<td style="text-align: left">String</td>
+<td style="text-align: left">The authentication mechanism to use when communicating with the scheduler. (Default: UNAUTHENTICATED)</td>
+</tr>
+</tbody></table>
+
+<h4 id="name">name</h4>
+
+<p>The name of the Aurora cluster represented by this entry. This name will be the <code>cluster</code> portion of
+any job keys identifying jobs running within the cluster.</p>
+
+<h4 id="slave_root">slave_root</h4>
+
+<p>The path on the mesos slaves where executing tasks can be found. It is used in combination with the
+<code>slave_run_directory</code> property by <code>aurora task run</code> and <code>aurora task ssh</code> to change into the sandbox
+directory after connecting to the host. This value should match the value passed to <code>mesos-slave</code>
+as <code>-work_dir</code>.</p>
+
+<h4 id="slaverundirectory">slave<em>run</em>directory</h4>
+
+<p>The name of the directory where the task run can be found. This is used in combination with the
+<code>slave_root</code> property by <code>aurora task run</code> and <code>aurora task ssh</code> to change into the sandbox
+directory after connecting to the host. This should almost always be set to <code>latest</code>.</p>
+
+<h4 id="zk">zk</h4>
+
+<p>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 <code>-zk_endpoints</code>.</p>
+
+<h4 id="zk_port">zk_port</h4>
+
+<p>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
+<code>-zk_endpoints</code>.</p>
+
+<h4 id="schedulerzkpath">scheduler<em>zk</em>path</h4>
+
+<p>The path on the ZooKeeper instance under which the Aurora serverset is registered. This value should
+match the value passed to the scheduler as <code>-serverset_path</code>.</p>
+
+<h4 id="scheduler_uri">scheduler_uri</h4>
+
+<p>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 <strong>never</strong> use this property for production deploys.</p>
+
+<h4 id="proxy_url">proxy_url</h4>
+
+<p>Instead of using the hostname of the leading scheduler as the base url, if <code>proxy_url</code> is set, its
+value will be used instead. In that scenario the value for <code>proxy_url</code> would be, for example, the
+URL of your VIP in a loadbalancer or a roundrobin DNS name.</p>
+
+<h4 id="auth_mechanism">auth_mechanism</h4>
+
+<p>The identifier of an authentication mechanism that the client should use when communicating with the
+scheduler. Support for values other than <code>UNAUTHENTICATED</code> is currently not available, however work
+is <a href="https://issues.apache.org/jira/browse/AURORA-720">in progress</a> to add federated authentication
+to Aurora which will allow for more robust configuration of client/scheduler authentication.</p>
+
+	  </div>
+      <div class="container">
+    <hr>
+    <footer class="footer">
+        <div class="row-fluid">
+            <div class="span2 text-left">
+                <h3>Links</h3>
+                <ul class="unstyled">
+                    <li><a href="/downloads/">Downloads</a></li>
+                    <li><a href="/developers/">Developers</a></li>                    
+                </ul>
+            </div>
+            <div class="span3 text-left">
+                <h3>Community</h3>
+                <ul class="unstyled">
+                    <li><a href="/community/">Mailing Lists</a></li>
+                    <li><a href="http://issues.apache.org/jira/browse/aurora">Issue Tracking</a></li>
+                    <li><a href="/docs/howtocontribute/">How To Contribute</a></li>
+                </ul>
+            </div>
+            <div class="span7 text-left">
+            	<h3>Apache Software Foundation</h3>
+
+							<div class="span8">
+                Copyright 2014 <a href="http://www.apache.org/">Apache Software Foundation</a>. Licensed under the <a href="http://www.apache.org/licenses/">Apache License v2.0</a>. Apache, Apache Thrift, and the Apache feather logo are trademarks of The Apache Software Foundation. Currently part of the <a href="http://incubator.apache.org">Apache Incubator</a>.
+							</div>
+							<div class=" pull-right">
+								<a href="http://incubator.apache.org" class="logo"><img src="/assets/img/apache_incubator_logo.png" alt="Apache Incubator" class="pull-right"/></a>
+							</div>
+            </div>
+
+        </div>
+
+    </footer>
+</div>
+
+	</body>
+</html>
+

Modified: incubator/aurora/site/publish/documentation/latest/client-commands/index.html
URL: http://svn.apache.org/viewvc/incubator/aurora/site/publish/documentation/latest/client-commands/index.html?rev=1633259&r1=1633258&r2=1633259&view=diff
==============================================================================
--- incubator/aurora/site/publish/documentation/latest/client-commands/index.html (original)
+++ incubator/aurora/site/publish/documentation/latest/client-commands/index.html Tue Oct 21 00:49:03 2014
@@ -129,7 +129,7 @@ Aurora Jobs.</p>
 
 <h2 id="cluster-configuration">Cluster Configuration</h2>
 
-<p>The client must be able to find a configuration file that speciies available clusters. This file
+<p>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.</p>
 
@@ -153,6 +153,9 @@ communicates with a single (non-leader-e
   <span class="s2">&quot;scheduler_zk_path&quot;</span><span class="err">:</span> <span class="s2">&quot;/aurora/scheduler&quot;</span>
 <span class="p">}]</span>
 </pre>
+<p>For more details on cluster configuration see the
+<a href="/documentation/latest/client-cluster-configuration/">Client Cluster Configuration</a> documentation.</p>
+
 <h2 id="job-keys">Job Keys</h2>
 
 <p>A job key is a unique system-wide identifier for an Aurora-managed

Modified: incubator/aurora/site/publish/documentation/latest/configuration-tutorial/index.html
URL: http://svn.apache.org/viewvc/incubator/aurora/site/publish/documentation/latest/configuration-tutorial/index.html?rev=1633259&r1=1633258&r2=1633259&view=diff
==============================================================================
--- incubator/aurora/site/publish/documentation/latest/configuration-tutorial/index.html (original)
+++ incubator/aurora/site/publish/documentation/latest/configuration-tutorial/index.html Tue Oct 21 00:49:03 2014
@@ -75,32 +75,75 @@ configuration parses, then outputs it in
 
 <p>You should read this after going through the general <a href="/documentation/latest/tutorial/">Aurora Tutorial</a>.</p>
 
-<p><a href="#Basics">The Basics</a>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Bottom">Use Bottom-To-Top Object Ordering</a>
-<a href="#Example">An Example Configuration File</a>
-<a href="#Process">Defining Process Objects</a>
-<a href="#Sandbox">Getting Your Code Into The Sandbox</a>
-<a href="#Task">Defining Task Objects</a>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Sequential"><code>SequentialTask</code></a>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Simple"><code>SimpleTask</code></a>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Concat"><code>Tasks.concat</code> and <code>Tasks.combine</code></a>
-<a href="#Job">Defining <code>Job</code> Objects</a>
-<a href="#jobs">Defining The <code>jobs</code> List</a>
-<a href="#Templating">Templating</a>
-<a href="#Binding">Templating 1: Binding in Pystachio</a>
-<a href="#Structurals">Structurals in Pystachio / Aurora</a>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Mustaches">Mustaches Within Structurals</a>
-<a href="#Factories">Templating 2: Structurals Are Factories</a>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Second">A Second Way of Templating</a>
-<a href="#AdvancedBinding">Advanced Binding</a>
-<a href="#BindSyntax">Bind Syntax</a>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ComplexObjects">Binding Complex Objects</a>
-<a href="#StructuralBinding">Structural Binding</a>
-<a href="#Tips">Configuration File Writing Tips And Best Practices</a>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Few">Use As Few <code>.aurora</code> Files As Possible</a>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Boilerplate">Avoid Boilerplate</a>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Bash">Thermos Uses bash, But Thermos Is Not bash</a>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Functions">Rarely Use Functions In Your Configurations</a></p>
+<ul>
+<li><a href="#user-content-aurora-configuration-tutorial">Aurora Configuration Tutorial</a>
+
+<ul>
+<li><a href="#user-content-the-basics">The Basics</a>
+
+<ul>
+<li><a href="#user-content-use-bottom-to-top-object-ordering">Use Bottom-To-Top Object Ordering</a></li>
+</ul></li>
+<li><a href="#user-content-an-example-configuration-file">An Example Configuration File</a></li>
+<li><a href="#user-content-defining-process-objects">Defining Process Objects</a></li>
+<li><a href="#user-content-getting-your-code-into-the-sandbox">Getting Your Code Into The Sandbox</a></li>
+<li><a href="#user-content-defining-task-objects">Defining Task Objects</a>
+
+<ul>
+<li><a href="#user-content-sequentialtask-running-processes-in-parallel-or-sequentially">SequentialTask: Running Processes in Parallel or Sequentially</a></li>
+<li><a href="#user-content-simpletask">SimpleTask</a></li>
+<li><a href="#user-content-combining-tasks">Combining tasks</a></li>
+</ul></li>
+<li><a href="#user-content-defining-job-objects">Defining Job Objects</a></li>
+<li><a href="#user-content-the-jobs-list">The jobs List</a></li>
+<li><a href="#user-content-templating">Templating</a>
+
+<ul>
+<li><a href="#user-content-templating-1-binding-in-pystachio">Templating 1: Binding in Pystachio</a></li>
+<li><a href="#user-content-structurals-in-pystachio--aurora">Structurals in Pystachio / Aurora</a>
+
+<ul>
+<li><a href="#user-content-mustaches-within-structurals">Mustaches Within Structurals</a></li>
+</ul></li>
+<li><a href="#user-content-templating-2-structurals-are-factories">Templating 2: Structurals Are Factories</a>
+
+<ul>
+<li><a href="#user-content-a-second-way-of-templating">A Second Way of Templating</a></li>
+</ul></li>
+<li><a href="#user-content-advanced-binding">Advanced Binding</a>
+
+<ul>
+<li><a href="#user-content-bind-syntax">Bind Syntax</a></li>
+<li><a href="#user-content-binding-complex-objects">Binding Complex Objects</a>
+
+<ul>
+<li><a href="#user-content-lists"></a></li>
+<li><a href="#user-content-maps"></a></li>
+<li><a href="#user-content-structurals"></a></li>
+</ul></li>
+</ul></li>
+<li><a href="#user-content-structural-binding">Structural Binding</a></li>
+</ul></li>
+<li><a href="#user-content-configuration-file-writing-tips-and-best-practices">Configuration File Writing Tips And Best Practices</a>
+
+<ul>
+<li><a href="#user-content-use-as-few-aurora-files-as-possible">Use As Few .aurora Files As Possible</a></li>
+<li><a href="#user-content-avoid-boilerplate">Avoid Boilerplate</a></li>
+<li><a href="#user-content-thermos-uses-bash-but-thermos-is-not-bash">Thermos Uses bash, But Thermos Is Not bash</a>
+
+<ul>
+<li><a href="#user-content-bad">Bad</a></li>
+<li><a href="#user-content-good">Good</a></li>
+</ul></li>
+<li><a href="#user-content-rarely-use-functions-in-your-configurations">Rarely Use Functions In Your Configurations</a>
+
+<ul>
+<li><a href="#user-content-bad-1">Bad</a></li>
+<li><a href="#user-content-good-1">Good</a></li>
+</ul></li>
+</ul></li>
+</ul></li>
+</ul>
 
 <h2 id="the-basics">The Basics</h2>
 

Modified: incubator/aurora/site/publish/documentation/latest/contributing/index.html
URL: http://svn.apache.org/viewvc/incubator/aurora/site/publish/documentation/latest/contributing/index.html?rev=1633259&r1=1633258&r2=1633259&view=diff
==============================================================================
--- incubator/aurora/site/publish/documentation/latest/contributing/index.html (original)
+++ incubator/aurora/site/publish/documentation/latest/contributing/index.html Tue Oct 21 00:49:03 2014
@@ -65,7 +65,12 @@
 <!-- /breadcrumb -->
 	
       <div class="container">
-        <h2 id="find-something-to-do">Find Something to Do</h2>
+        <h2 id="get-the-source-code">Get the Source Code</h2>
+
+<p>First things first, you&rsquo;ll need the source! The Aurora source is available from Apache git:</p>
+<pre class="highlight text">git clone https://git-wip-us.apache.org/repos/asf/incubator-aurora
+</pre>
+<h2 id="find-something-to-do">Find Something to Do</h2>
 
 <p>There are issues in <a href="https://issues.apache.org/jira/browse/AURORA">Jira</a> with the
 <a href="https://issues.apache.org/jira/browse/AURORA-189?jql=project%20%3D%20AURORA%20AND%20resolution%20%3D%20Unresolved%20AND%20labels%20%3D%20newbie%20ORDER%20BY%20priority%20DESC">&ldquo;newbie&rdquo; tag</a>

Modified: incubator/aurora/site/publish/documentation/latest/deploying-aurora-scheduler/index.html
URL: http://svn.apache.org/viewvc/incubator/aurora/site/publish/documentation/latest/deploying-aurora-scheduler/index.html?rev=1633259&r1=1633258&r2=1633259&view=diff
==============================================================================
--- incubator/aurora/site/publish/documentation/latest/deploying-aurora-scheduler/index.html (original)
+++ incubator/aurora/site/publish/documentation/latest/deploying-aurora-scheduler/index.html Tue Oct 21 00:49:03 2014
@@ -65,16 +65,62 @@
 <!-- /breadcrumb -->
 	
       <div class="container">
-        <p>The Aurora scheduler is responsible for scheduling new jobs, rescheduling failed jobs, and killing
-old jobs.</p>
+        <h1 id="deploying-the-aurora-scheduler">Deploying the Aurora Scheduler</h1>
 
-<h1 id="installing-aurora">Installing Aurora</h1>
+<p>When setting up your cluster, you will install the scheduler on a small number (usually 3 or 5) of
+machines.  This guide helps you get the scheduler set up and troubleshoot some common hurdles.</p>
 
-<p>Aurora is a standalone Java server. As part of the build process it creates a bundle of all its
-dependencies, with the notable exceptions of the JVM and libmesos. Each target server should have
-a JVM (Java 7 or higher) and libmesos (0.18.0) installed.</p>
+<ul>
+<li><a href="#installing-aurora">Installing Aurora</a>
 
-<h2 id="creating-the-distribution-.zip-file-(optional)">Creating the Distribution .zip File (Optional)</h2>
+<ul>
+<li><a href="#creating-the-distribution-zip-file-optional">Creating the Distribution .zip File (Optional)</a></li>
+<li><a href="#installing-aurora-1">Installing Aurora</a></li>
+</ul></li>
+<li><a href="#configuring-aurora">Configuring Aurora</a>
+
+<ul>
+<li><a href="#a-note-on-configuration">A Note on Configuration</a></li>
+<li><a href="#replicated-log-configuration">Replicated Log Configuration</a></li>
+<li><a href="#initializing-the-replicated-log">Initializing the Replicated Log</a></li>
+<li><a href="#storage-performance-considerations">Storage Performance Considerations</a></li>
+<li><a href="#network-considerations">Network considerations</a></li>
+</ul></li>
+<li><a href="#running-aurora">Running Aurora</a>
+
+<ul>
+<li><a href="#maintaining-an-aurora-installation">Maintaining an Aurora Installation</a></li>
+<li><a href="#monitoring">Monitoring</a></li>
+<li><a href="#running-stateful-services">Running stateful services</a></li>
+<li><a href="#dedicated-attribute">Dedicated attribute</a>
+
+<ul>
+<li><a href="#syntax">Syntax</a></li>
+<li><a href="#example">Example</a></li>
+</ul></li>
+</ul></li>
+<li><a href="#common-problems">Common problems</a>
+
+<ul>
+<li><a href="#replicated-log-not-initialized">Replicated log not initialized</a></li>
+<li><a href="#symptoms">Symptoms</a></li>
+<li><a href="#solution">Solution</a></li>
+<li><a href="#scheduler-not-registered">Scheduler not registered</a></li>
+<li><a href="#symptoms-1">Symptoms</a></li>
+<li><a href="#solution-1">Solution</a></li>
+<li><a href="#tasks-are-stuck-in-pending-forever">Tasks are stuck in PENDING forever</a></li>
+<li><a href="#symptoms-2">Symptoms</a></li>
+<li><a href="#solution-2">Solution</a></li>
+</ul></li>
+</ul>
+
+<h2 id="installing-aurora">Installing Aurora</h2>
+
+<p>The Aurora scheduler is a standalone Java server. As part of the build process it creates a bundle
+of all its dependencies, with the notable exceptions of the JVM and libmesos. Each target server
+should have a JVM (Java 7 or higher) and libmesos (0.20.0) installed.</p>
+
+<h3 id="creating-the-distribution-.zip-file-(optional)">Creating the Distribution .zip File (Optional)</h3>
 
 <p>To create a distribution for installation you will need build tools installed. On Ubuntu this can be
 done with <code>sudo apt-get install build-essential default-jdk</code>.</p>
@@ -84,16 +130,16 @@ cd incubator-aurora
 </pre>
 <p>Copy the generated <code>dist/distributions/aurora-scheduler-*.zip</code> to each node that will run a scheduler.</p>
 
-<h2 id="installing-aurora">Installing Aurora</h2>
+<h3 id="installing-aurora">Installing Aurora</h3>
 
 <p>Extract the aurora-scheduler zip file. The example configurations assume it is extracted to
 <code>/usr/local/aurora-scheduler</code>.</p>
 <pre class="highlight text">sudo unzip dist/distributions/aurora-scheduler-*.zip -d /usr/local
 sudo ln -nfs &quot;$(ls -dt /usr/local/aurora-scheduler-* | head -1)&quot; /usr/local/aurora-scheduler
 </pre>
-<h1 id="configuring-aurora">Configuring Aurora</h1>
+<h2 id="configuring-aurora">Configuring Aurora</h2>
 
-<h2 id="a-note-on-configuration">A Note on Configuration</h2>
+<h3 id="a-note-on-configuration">A Note on Configuration</h3>
 
 <p>Like Mesos, Aurora uses command-line flags for runtime configuration. As such the Aurora
 &ldquo;configuration file&rdquo; is typically a <code>scheduler.sh</code> shell script of the form.</p>
@@ -126,7 +172,7 @@ sudo ln -nfs &quot;$(ls -dt /usr/local/a
 documentation run</p>
 <pre class="highlight text">/usr/local/aurora-scheduler/bin/aurora-scheduler -help
 </pre>
-<h2 id="replicated-log-configuration">Replicated Log Configuration</h2>
+<h3 id="replicated-log-configuration">Replicated Log Configuration</h3>
 
 <p>All Aurora state is persisted to a replicated log. This includes all jobs Aurora is running
 including where in the cluster they are being run and the configuration for running them, as
@@ -168,7 +214,7 @@ should be set to <code>2</code>, and in 
 
 <p><em>Incorrectly setting this flag will cause data corruption to occur!</em></p>
 
-<h2 id="initializing-the-replicated-log">Initializing the Replicated Log</h2>
+<h3 id="initializing-the-replicated-log">Initializing the Replicated Log</h3>
 
 <p>Before you start Aurora you will also need to initialize the log on the first master.</p>
 <pre class="highlight text">mesos-log initialize --path=&quot;$AURORA_HOME/scheduler/db&quot;
@@ -176,11 +222,11 @@ should be set to <code>2</code>, and in 
 <p>Failing to do this will result the following message when you try to start the scheduler.</p>
 <pre class="highlight text">Replica in EMPTY status received a broadcasted recover request
 </pre>
-<h2 id="storage-performance-considerations">Storage Performance Considerations</h2>
+<h3 id="storage-performance-considerations">Storage Performance Considerations</h3>
 
 <p>See <a href="/documentation/latest/scheduler-storage/">this document</a> for scheduler storage performance considerations.</p>
 
-<h2 id="network-considerations">Network considerations</h2>
+<h3 id="network-considerations">Network considerations</h3>
 
 <p>The Aurora scheduler listens on 2 ports - an HTTP port used for client RPCs and a web UI,
 and a libprocess (HTTP+Protobuf) port used to communicate with the Mesos master and for the log
@@ -196,7 +242,7 @@ AURORA_FLAGS=(
 export LIBPROCESS_PORT=8083
 # ...
 </pre>
-<h1 id="running-aurora">Running Aurora</h1>
+<h2 id="running-aurora">Running Aurora</h2>
 
 <p>Configure a supervisor like <a href="http://mmonit.com/monit/">Monit</a> or
 <a href="http://supervisord.org/">supervisord</a> to run the created <code>scheduler.sh</code> file and restart it
@@ -210,18 +256,18 @@ restarted.</p>
 </pre>
 <p>assuming you set <code>-http_port=8081</code>.</p>
 
-<h2 id="maintaining-an-aurora-installation">Maintaining an Aurora Installation</h2>
+<h3 id="maintaining-an-aurora-installation">Maintaining an Aurora Installation</h3>
 
-<h2 id="monitoring">Monitoring</h2>
+<h3 id="monitoring">Monitoring</h3>
 
 <p>Please see our dedicated <a href="/documentation/latest/monitoring/">monitoring guide</a> for in-depth discussion on monitoring.</p>
 
-<h2 id="running-stateful-services">Running stateful services</h2>
+<h3 id="running-stateful-services">Running stateful services</h3>
 
 <p>Aurora is best suited to run stateless applications, but it also accommodates for stateful services
 like databases, or services that otherwise need to always run on the same machines.</p>
 
-<h3 id="dedicated-attribute">Dedicated attribute</h3>
+<h4 id="dedicated-attribute">Dedicated attribute</h4>
 
 <p>The Mesos slave has the <code>--attributes</code> command line argument which can be used to mark a slave with
 static attributes (not to be confused with <code>--resources</code>, which are dynamic and accounted).</p>
@@ -232,7 +278,7 @@ constraints are arbitrary and available 
 <code>dedicated</code> attribute.  Aurora treats this specially, and only allows matching jobs to run on these
 machines, and will only schedule matching jobs on these machines.</p>
 
-<h4 id="syntax">Syntax</h4>
+<h5 id="syntax">Syntax</h5>
 
 <p>The dedicated attribute has semantic meaning. The format is <code>$role(/.*)?</code>. When a job is created,
 the scheduler requires that the <code>$role</code> component matches the <code>role</code> field in the job
@@ -240,7 +286,7 @@ configuration, and will reject the job c
 free-form. We&rsquo;ve developed the idiom of formatting this attribute as <code>$role/$job</code>, but do not
 enforce this.</p>
 
-<h4 id="example">Example</h4>
+<h5 id="example">Example</h5>
 
 <p>Consider the following slave command line:</p>
 <pre class="highlight text">mesos-slave --attributes=&quot;host:$HOST;rack:$RACK;dedicated:db_team/redis&quot; ...
@@ -259,6 +305,62 @@ enforce this.</p>
 <code>dedicated:dba_team/redis</code>.  Additionally, Aurora will prevent any tasks that do <em>not</em> have that
 constraint from running on those slaves.</p>
 
+<h2 id="common-problems">Common problems</h2>
+
+<p>So you&rsquo;ve started your first cluster and are running into some issues? We&rsquo;ve collected some common
+stumbling blocks and solutions here to help get you moving.</p>
+
+<h3 id="replicated-log-not-initialized">Replicated log not initialized</h3>
+
+<h4 id="symptoms">Symptoms</h4>
+
+<ul>
+<li>Scheduler RPCs and web interface claim <code>Storage is not READY</code></li>
+<li>Scheduler log repeatedly prints messages like</li>
+</ul>
+<pre class="highlight text">  I1016 16:12:27.234133 26081 replica.cpp:638] Replica in EMPTY status
+  received a broadcasted recover request
+  I1016 16:12:27.234256 26084 recover.cpp:188] Received a recover response
+  from a replica in EMPTY status
+</pre>
+<h4 id="solution">Solution</h4>
+
+<p>When you create a new cluster, you need to inform a quorum of schedulers that they are safe to
+consider their database to be empty by <a href="#initializing-the-replicated-log">initializing</a> the
+replicated log. This is done to prevent the scheduler from modifying the cluster state in the event
+of multiple simultaneous disk failures or, more likely, misconfiguration of the replicated log path.</p>
+
+<h3 id="scheduler-not-registered">Scheduler not registered</h3>
+
+<h4 id="symptoms">Symptoms</h4>
+
+<p>Scheduler log contains</p>
+<pre class="highlight text">Framework has not been registered within the tolerated delay.
+</pre>
+<h4 id="solution">Solution</h4>
+
+<p>Double-check that the scheduler is configured correctly to reach the master. If you are registering
+the master in ZooKeeper, make sure command line argument to the master:</p>
+<pre class="highlight text">--zk=zk://$ZK_HOST:2181/mesos/master
+</pre>
+<p>is the same as the one on the scheduler:</p>
+<pre class="highlight text">-mesos_master_address=zk://$ZK_HOST:2181/mesos/master
+</pre>
+<h3 id="tasks-are-stuck-in-pending-forever">Tasks are stuck in <code>PENDING</code> forever</h3>
+
+<h4 id="symptoms">Symptoms</h4>
+
+<p>The scheduler is registered, and (receiving offers](docs/monitoring.md#scheduler<em>resource</em>offers),
+but tasks are perpetually shown as <code>PENDING - Constraint not satisfied: host</code>.</p>
+
+<h4 id="solution">Solution</h4>
+
+<p>Check that your slaves are configured with <code>host</code> and <code>rack</code> attributes.  Aurora requires that
+slaves are tagged with these two common failure domains to ensure that it can safely place tasks
+such that jobs are resilient to failure.</p>
+
+<p>See our <a href="examples/vagrant/upstart/mesos-slave.conf">vagrant example</a> for details.</p>
+
 	  </div>
       <div class="container">
     <hr>

Modified: incubator/aurora/site/publish/documentation/latest/developing-aurora-client/index.html
URL: http://svn.apache.org/viewvc/incubator/aurora/site/publish/documentation/latest/developing-aurora-client/index.html?rev=1633259&r1=1633258&r2=1633259&view=diff
==============================================================================
--- incubator/aurora/site/publish/documentation/latest/developing-aurora-client/index.html (original)
+++ incubator/aurora/site/publish/documentation/latest/developing-aurora-client/index.html Tue Oct 21 00:49:03 2014
@@ -84,6 +84,14 @@ are fully self-contained executables: ju
 <p>To run all of the client tests:</p>
 <pre class="highlight text">$ ./pasts src/test/python/apache/aurora/client/:all
 </pre>
+<h1 id="client-configuration">Client Configuration</h1>
+
+<p>The client uses a configuration file that specifies available clusters. More information about the
+contents of this file can be found in the
+<a href="/documentation/latest/client-cluster-configuration/">Client Cluster Configuration</a> documentation. Information about
+how the client locates this file can be found in the
+<a href="client-commands.md#cluster-configuration">Client Commands</a> documentation.</p>
+
 <h1 id="client-versions">Client Versions</h1>
 
 <p>There are currently two versions of the aurora client, imaginatively known as v1 and v2. All new development is done entirely in v2, but we continue to support and fix bugs in v1, until we get to the point where v2 is feature-complete and tested, and aurora users have had some time at adapt and switch their processes to use v2.</p>

Modified: incubator/aurora/site/publish/documentation/latest/user-guide/index.html
URL: http://svn.apache.org/viewvc/incubator/aurora/site/publish/documentation/latest/user-guide/index.html?rev=1633259&r1=1633258&r2=1633259&view=diff
==============================================================================
--- incubator/aurora/site/publish/documentation/latest/user-guide/index.html (original)
+++ incubator/aurora/site/publish/documentation/latest/user-guide/index.html Tue Oct 21 00:49:03 2014
@@ -307,6 +307,18 @@ requests:</p>
 <a href="configuration-reference.md#user-content-healthcheckconfig-objects">configuration reference</a> for
 configuration options for this feature.</p>
 
+<h4 id="snoozing-health-checks">Snoozing Health Checks</h4>
+
+<p>If you need to pause your health check, you can do so by touching a file inside of your sandbox,
+named <code>.healthchecksnooze</code></p>
+
+<p>As long as that file is present, health checks will be disabled, enabling users to gather core dumps
+or other performance measurements without worrying about Aurora&rsquo;s health check killing their
+process.</p>
+
+<p>WARNING: Remember to remove this when you are done, otherwise your instance will have permanently
+disabled health checks.</p>
+
 <h4 id="tearing-a-task-down">Tearing a task down</h4>
 
 <p>The Executor follows an escalation sequence when killing a running task:</p>

Added: incubator/aurora/site/source/documentation/latest/client-cluster-configuration.md
URL: http://svn.apache.org/viewvc/incubator/aurora/site/source/documentation/latest/client-cluster-configuration.md?rev=1633259&view=auto
==============================================================================
--- incubator/aurora/site/source/documentation/latest/client-cluster-configuration.md (added)
+++ incubator/aurora/site/source/documentation/latest/client-cluster-configuration.md Tue Oct 21 00:49:03 2014
@@ -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.

Modified: incubator/aurora/site/source/documentation/latest/client-commands.md
URL: http://svn.apache.org/viewvc/incubator/aurora/site/source/documentation/latest/client-commands.md?rev=1633259&r1=1633258&r2=1633259&view=diff
==============================================================================
--- incubator/aurora/site/source/documentation/latest/client-commands.md (original)
+++ incubator/aurora/site/source/documentation/latest/client-commands.md Tue Oct 21 00:49:03 2014
@@ -57,7 +57,7 @@ Aurora Jobs.
 Cluster Configuration
 ---------------------
 
-The client must be able to find a configuration file that speciies available clusters. This file
+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.
 
@@ -87,6 +87,9 @@ A configuration for a leader-elected sch
 }]
 ```
 
+For more details on cluster configuration see the
+[Client Cluster Configuration](/documentation/latest/client-cluster-configuration/) documentation.
+
 Job Keys
 --------
 

Modified: incubator/aurora/site/source/documentation/latest/configuration-tutorial.md
URL: http://svn.apache.org/viewvc/incubator/aurora/site/source/documentation/latest/configuration-tutorial.md?rev=1633259&r1=1633258&r2=1633259&view=diff
==============================================================================
--- incubator/aurora/site/source/documentation/latest/configuration-tutorial.md (original)
+++ incubator/aurora/site/source/documentation/latest/configuration-tutorial.md Tue Oct 21 00:49:03 2014
@@ -9,32 +9,40 @@ configuration parses, then outputs it in
 
 You should read this after going through the general [Aurora Tutorial](/documentation/latest/tutorial/).
 
-[The Basics](#Basics)
-&nbsp;&nbsp;&nbsp;&nbsp;[Use Bottom-To-Top Object Ordering](#Bottom)
-[An Example Configuration File](#Example)
-[Defining Process Objects](#Process)
-[Getting Your Code Into The Sandbox](#Sandbox)
-[Defining Task Objects](#Task)
-&nbsp;&nbsp;&nbsp;&nbsp;[`SequentialTask`](#Sequential)
-&nbsp;&nbsp;&nbsp;&nbsp;[`SimpleTask`](#Simple)
-&nbsp;&nbsp;&nbsp;&nbsp;[`Tasks.concat` and `Tasks.combine`](#Concat)
-[Defining `Job` Objects](#Job)
-[Defining The `jobs` List](#jobs)
-[Templating](#Templating)
-[Templating 1: Binding in Pystachio](#Binding)
-[Structurals in Pystachio / Aurora](#Structurals)
-&nbsp;&nbsp;&nbsp;&nbsp;[Mustaches Within Structurals](#Mustaches)
-[Templating 2: Structurals Are Factories](#Factories)
-&nbsp;&nbsp;&nbsp;&nbsp;[A Second Way of Templating](#Second)
-[Advanced Binding](#AdvancedBinding)
-[Bind Syntax](#BindSyntax)
-&nbsp;&nbsp;&nbsp;&nbsp;[Binding Complex Objects](#ComplexObjects)
-[Structural Binding](#StructuralBinding)
-[Configuration File Writing Tips And Best Practices](#Tips)
-&nbsp;&nbsp;&nbsp;&nbsp;[Use As Few `.aurora` Files As Possible](#Few)
-&nbsp;&nbsp;&nbsp;&nbsp;[Avoid Boilerplate](#Boilerplate)
-&nbsp;&nbsp;&nbsp;&nbsp;[Thermos Uses bash, But Thermos Is Not bash](#Bash)
-&nbsp;&nbsp;&nbsp;&nbsp;[Rarely Use Functions In Your Configurations](#Functions)
+- [Aurora Configuration Tutorial](#user-content-aurora-configuration-tutorial)
+	- [The Basics](#user-content-the-basics)
+		- [Use Bottom-To-Top Object Ordering](#user-content-use-bottom-to-top-object-ordering)
+	- [An Example Configuration File](#user-content-an-example-configuration-file)
+	- [Defining Process Objects](#user-content-defining-process-objects)
+	- [Getting Your Code Into The Sandbox](#user-content-getting-your-code-into-the-sandbox)
+	- [Defining Task Objects](#user-content-defining-task-objects)
+		- [SequentialTask: Running Processes in Parallel or Sequentially](#user-content-sequentialtask-running-processes-in-parallel-or-sequentially)
+		- [SimpleTask](#user-content-simpletask)
+		- [Combining tasks](#user-content-combining-tasks)
+	- [Defining Job Objects](#user-content-defining-job-objects)
+	- [The jobs List](#user-content-the-jobs-list)
+	- [Templating](#user-content-templating)
+		- [Templating 1: Binding in Pystachio](#user-content-templating-1-binding-in-pystachio)
+		- [Structurals in Pystachio / Aurora](#user-content-structurals-in-pystachio--aurora)
+			- [Mustaches Within Structurals](#user-content-mustaches-within-structurals)
+		- [Templating 2: Structurals Are Factories](#user-content-templating-2-structurals-are-factories)
+			- [A Second Way of Templating](#user-content-a-second-way-of-templating)
+		- [Advanced Binding](#user-content-advanced-binding)
+			- [Bind Syntax](#user-content-bind-syntax)
+			- [Binding Complex Objects](#user-content-binding-complex-objects)
+				- [Lists](#user-content-lists)
+				- [Maps](#user-content-maps)
+				- [Structurals](#user-content-structurals)
+		- [Structural Binding](#user-content-structural-binding)
+	- [Configuration File Writing Tips And Best Practices](#user-content-configuration-file-writing-tips-and-best-practices)
+		- [Use As Few .aurora Files As Possible](#user-content-use-as-few-aurora-files-as-possible)
+		- [Avoid Boilerplate](#user-content-avoid-boilerplate)
+		- [Thermos Uses bash, But Thermos Is Not bash](#user-content-thermos-uses-bash-but-thermos-is-not-bash)
+			- [Bad](#user-content-bad)
+			- [Good](#user-content-good)
+		- [Rarely Use Functions In Your Configurations](#user-content-rarely-use-functions-in-your-configurations)
+			- [Bad](#user-content-bad-1)
+			- [Good](#user-content-good-1)
 
 The Basics
 ----------

Modified: incubator/aurora/site/source/documentation/latest/contributing.md
URL: http://svn.apache.org/viewvc/incubator/aurora/site/source/documentation/latest/contributing.md?rev=1633259&r1=1633258&r2=1633259&view=diff
==============================================================================
--- incubator/aurora/site/source/documentation/latest/contributing.md (original)
+++ incubator/aurora/site/source/documentation/latest/contributing.md Tue Oct 21 00:49:03 2014
@@ -1,3 +1,9 @@
+Get the Source Code
+-------------------
+First things first, you'll need the source! The Aurora source is available from Apache git:
+
+    git clone https://git-wip-us.apache.org/repos/asf/incubator-aurora
+
 Find Something to Do
 --------------------
 There are issues in [Jira](https://issues.apache.org/jira/browse/AURORA) with the

Modified: incubator/aurora/site/source/documentation/latest/deploying-aurora-scheduler.md
URL: http://svn.apache.org/viewvc/incubator/aurora/site/source/documentation/latest/deploying-aurora-scheduler.md?rev=1633259&r1=1633258&r2=1633259&view=diff
==============================================================================
--- incubator/aurora/site/source/documentation/latest/deploying-aurora-scheduler.md (original)
+++ incubator/aurora/site/source/documentation/latest/deploying-aurora-scheduler.md Tue Oct 21 00:49:03 2014
@@ -1,12 +1,41 @@
-The Aurora scheduler is responsible for scheduling new jobs, rescheduling failed jobs, and killing
-old jobs.
+# Deploying the Aurora Scheduler
 
-# Installing Aurora
-Aurora is a standalone Java server. As part of the build process it creates a bundle of all its
-dependencies, with the notable exceptions of the JVM and libmesos. Each target server should have
-a JVM (Java 7 or higher) and libmesos (0.18.0) installed.
+When setting up your cluster, you will install the scheduler on a small number (usually 3 or 5) of
+machines.  This guide helps you get the scheduler set up and troubleshoot some common hurdles.
 
-## Creating the Distribution .zip File (Optional)
+- [Installing Aurora](#installing-aurora)
+  - [Creating the Distribution .zip File (Optional)](#creating-the-distribution-zip-file-optional)
+  - [Installing Aurora](#installing-aurora-1)
+- [Configuring Aurora](#configuring-aurora)
+  - [A Note on Configuration](#a-note-on-configuration)
+  - [Replicated Log Configuration](#replicated-log-configuration)
+  - [Initializing the Replicated Log](#initializing-the-replicated-log)
+  - [Storage Performance Considerations](#storage-performance-considerations)
+  - [Network considerations](#network-considerations)
+- [Running Aurora](#running-aurora)
+  - [Maintaining an Aurora Installation](#maintaining-an-aurora-installation)
+  - [Monitoring](#monitoring)
+  - [Running stateful services](#running-stateful-services)
+    - [Dedicated attribute](#dedicated-attribute)
+      - [Syntax](#syntax)
+      - [Example](#example)
+- [Common problems](#common-problems)
+  - [Replicated log not initialized](#replicated-log-not-initialized)
+    - [Symptoms](#symptoms)
+    - [Solution](#solution)
+  - [Scheduler not registered](#scheduler-not-registered)
+    - [Symptoms](#symptoms-1)
+    - [Solution](#solution-1)
+  - [Tasks are stuck in PENDING forever](#tasks-are-stuck-in-pending-forever)
+    - [Symptoms](#symptoms-2)
+    - [Solution](#solution-2)
+
+## Installing Aurora
+The Aurora scheduler is a standalone Java server. As part of the build process it creates a bundle
+of all its dependencies, with the notable exceptions of the JVM and libmesos. Each target server
+should have a JVM (Java 7 or higher) and libmesos (0.20.0) installed.
+
+### Creating the Distribution .zip File (Optional)
 To create a distribution for installation you will need build tools installed. On Ubuntu this can be
 done with `sudo apt-get install build-essential default-jdk`.
 
@@ -16,16 +45,16 @@ done with `sudo apt-get install build-es
 
 Copy the generated `dist/distributions/aurora-scheduler-*.zip` to each node that will run a scheduler.
 
-## Installing Aurora
+### Installing Aurora
 Extract the aurora-scheduler zip file. The example configurations assume it is extracted to
 `/usr/local/aurora-scheduler`.
 
     sudo unzip dist/distributions/aurora-scheduler-*.zip -d /usr/local
     sudo ln -nfs "$(ls -dt /usr/local/aurora-scheduler-* | head -1)" /usr/local/aurora-scheduler
 
-# Configuring Aurora
+## Configuring Aurora
 
-## A Note on Configuration
+### A Note on Configuration
 Like Mesos, Aurora uses command-line flags for runtime configuration. As such the Aurora
 "configuration file" is typically a `scheduler.sh` shell script of the form.
 
@@ -59,7 +88,7 @@ documentation run
 
     /usr/local/aurora-scheduler/bin/aurora-scheduler -help
 
-## Replicated Log Configuration
+### Replicated Log Configuration
 All Aurora state is persisted to a replicated log. This includes all jobs Aurora is running
 including where in the cluster they are being run and the configuration for running them, as
 well as other information such as metadata needed to reconnect to the Mesos master, resource
@@ -83,7 +112,7 @@ should be set to `2`, and in a cluster o
 
 *Incorrectly setting this flag will cause data corruption to occur!*
 
-## Initializing the Replicated Log
+### Initializing the Replicated Log
 Before you start Aurora you will also need to initialize the log on the first master.
 
     mesos-log initialize --path="$AURORA_HOME/scheduler/db"
@@ -92,11 +121,11 @@ Failing to do this will result the follo
 
     Replica in EMPTY status received a broadcasted recover request
 
-## Storage Performance Considerations
+### Storage Performance Considerations
 
 See [this document](/documentation/latest/scheduler-storage/) for scheduler storage performance considerations.
 
-## Network considerations
+### Network considerations
 The Aurora scheduler listens on 2 ports - an HTTP port used for client RPCs and a web UI,
 and a libprocess (HTTP+Protobuf) port used to communicate with the Mesos master and for the log
 replication protocol. These can be left unconfigured (the scheduler publishes all selected ports
@@ -112,7 +141,7 @@ to ZooKeeper) or explicitly set in the s
     export LIBPROCESS_PORT=8083
     # ...
 
-# Running Aurora
+## Running Aurora
 Configure a supervisor like [Monit](http://mmonit.com/monit/) or
 [supervisord](http://supervisord.org/) to run the created `scheduler.sh` file and restart it
 whenever it fails. Aurora expects to be restarted by an external process when it fails. Aurora
@@ -126,16 +155,16 @@ For example, monit can be configured wit
 
 assuming you set `-http_port=8081`.
 
-## Maintaining an Aurora Installation
+### Maintaining an Aurora Installation
 
-## Monitoring
+### Monitoring
 Please see our dedicated [monitoring guide](/documentation/latest/monitoring/) for in-depth discussion on monitoring.
 
-## Running stateful services
+### Running stateful services
 Aurora is best suited to run stateless applications, but it also accommodates for stateful services
 like databases, or services that otherwise need to always run on the same machines.
 
-### Dedicated attribute
+#### Dedicated attribute
 The Mesos slave has the `--attributes` command line argument which can be used to mark a slave with
 static attributes (not to be confused with `--resources`, which are dynamic and accounted).
 
@@ -145,14 +174,14 @@ constraints are arbitrary and available 
 `dedicated` attribute.  Aurora treats this specially, and only allows matching jobs to run on these
 machines, and will only schedule matching jobs on these machines.
 
-#### Syntax
+##### Syntax
 The dedicated attribute has semantic meaning. The format is `$role(/.*)?`. When a job is created,
 the scheduler requires that the `$role` component matches the `role` field in the job
 configuration, and will reject the job creation otherwise.  The remainder of the attribute is
 free-form. We've developed the idiom of formatting this attribute as `$role/$job`, but do not
 enforce this.
 
-#### Example
+##### Example
 Consider the following slave command line:
 
     mesos-slave --attributes="host:$HOST;rack:$RACK;dedicated:db_team/redis" ...
@@ -171,3 +200,57 @@ And this job configuration:
 The job configuration is indicating that it should only be scheduled on slaves with the attribute
 `dedicated:dba_team/redis`.  Additionally, Aurora will prevent any tasks that do _not_ have that
 constraint from running on those slaves.
+
+
+## Common problems
+So you've started your first cluster and are running into some issues? We've collected some common
+stumbling blocks and solutions here to help get you moving.
+
+### Replicated log not initialized
+
+#### Symptoms
+- Scheduler RPCs and web interface claim `Storage is not READY`
+- Scheduler log repeatedly prints messages like
+
+  ```
+  I1016 16:12:27.234133 26081 replica.cpp:638] Replica in EMPTY status
+  received a broadcasted recover request
+  I1016 16:12:27.234256 26084 recover.cpp:188] Received a recover response
+  from a replica in EMPTY status
+  ```
+
+#### Solution
+When you create a new cluster, you need to inform a quorum of schedulers that they are safe to
+consider their database to be empty by [initializing](#initializing-the-replicated-log) the
+replicated log. This is done to prevent the scheduler from modifying the cluster state in the event
+of multiple simultaneous disk failures or, more likely, misconfiguration of the replicated log path.
+
+### Scheduler not registered
+
+#### Symptoms
+Scheduler log contains
+
+    Framework has not been registered within the tolerated delay.
+
+#### Solution
+Double-check that the scheduler is configured correctly to reach the master. If you are registering
+the master in ZooKeeper, make sure command line argument to the master:
+
+    --zk=zk://$ZK_HOST:2181/mesos/master
+
+is the same as the one on the scheduler:
+
+    -mesos_master_address=zk://$ZK_HOST:2181/mesos/master
+
+### Tasks are stuck in `PENDING` forever
+
+#### Symptoms
+The scheduler is registered, and (receiving offers](docs/monitoring.md#scheduler_resource_offers),
+but tasks are perpetually shown as `PENDING - Constraint not satisfied: host`.
+
+#### Solution
+Check that your slaves are configured with `host` and `rack` attributes.  Aurora requires that
+slaves are tagged with these two common failure domains to ensure that it can safely place tasks
+such that jobs are resilient to failure.
+
+See our [vagrant example](examples/vagrant/upstart/mesos-slave.conf) for details.

Modified: incubator/aurora/site/source/documentation/latest/developing-aurora-client.md
URL: http://svn.apache.org/viewvc/incubator/aurora/site/source/documentation/latest/developing-aurora-client.md?rev=1633259&r1=1633258&r2=1633259&view=diff
==============================================================================
--- incubator/aurora/site/source/documentation/latest/developing-aurora-client.md (original)
+++ incubator/aurora/site/source/documentation/latest/developing-aurora-client.md Tue Oct 21 00:49:03 2014
@@ -1,6 +1,5 @@
-
 Getting Started
-=================
+===============
 
 Aurora consists of four main pieces: the scheduler (which finds resources in the cluster that can be used to run a job), the executor (which uses the resources assigned by the scheduler to run a job), the command-line client, and the web-ui. For information about working on the scheduler or the webUI, see the file "developing-aurora-scheduler.md" in this directory.
 
@@ -23,8 +22,17 @@ To run all of the client tests:
     $ ./pasts src/test/python/apache/aurora/client/:all
 
 
+Client Configuration
+====================
+
+The client uses a configuration file that specifies available clusters. More information about the
+contents of this file can be found in the
+[Client Cluster Configuration](/documentation/latest/client-cluster-configuration/) documentation. Information about
+how the client locates this file can be found in the
+[Client Commands](client-commands.md#cluster-configuration) documentation.
+
 Client Versions
-==================
+===============
 
 There are currently two versions of the aurora client, imaginatively known as v1 and v2. All new development is done entirely in v2, but we continue to support and fix bugs in v1, until we get to the point where v2 is feature-complete and tested, and aurora users have had some time at adapt and switch their processes to use v2.
 
@@ -38,7 +46,7 @@ found in the `__init__.py` file in that 
 
 
 Building and Testing the Client
-=================================
+===============================
 
 Building and testing the client code are both done using Pants. The relevant targets to know about are:
 
@@ -50,7 +58,7 @@ Building and testing the client code are
 
 
 Overview of the Client Architecture
-=====================================
+===================================
 
 The client is built on a stacked architecture:
 
@@ -80,7 +88,7 @@ The client is built on a stacked archite
        * `client.py` contains the code that binds the client v2 nouns and verbs into an executable.
 
 Running/Debugging the Client
-=============================
+============================
 
 For manually testing client changes against a cluster, we use vagrant. To start a virtual cluster,
 you need to install a working vagrant environment, and then run "vagrant up" for the root of

Modified: incubator/aurora/site/source/documentation/latest/user-guide.md
URL: http://svn.apache.org/viewvc/incubator/aurora/site/source/documentation/latest/user-guide.md?rev=1633259&r1=1633258&r2=1633259&view=diff
==============================================================================
--- incubator/aurora/site/source/documentation/latest/user-guide.md (original)
+++ incubator/aurora/site/source/documentation/latest/user-guide.md Tue Oct 21 00:49:03 2014
@@ -215,6 +215,18 @@ Please see the
 [configuration reference](configuration-reference.md#user-content-healthcheckconfig-objects) for
 configuration options for this feature.
 
+#### Snoozing Health Checks
+
+If you need to pause your health check, you can do so by touching a file inside of your sandbox,
+named `.healthchecksnooze`
+
+As long as that file is present, health checks will be disabled, enabling users to gather core dumps
+or other performance measurements without worrying about Aurora's health check killing their
+process.
+
+WARNING: Remember to remove this when you are done, otherwise your instance will have permanently
+disabled health checks.
+
 #### Tearing a task down
 
 The Executor follows an escalation sequence when killing a running task:



Mime
View raw message