aurora-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dles...@apache.org
Subject svn commit: r1659836 - in /incubator/aurora/site: publish/documentation/latest/client-commands/ publish/documentation/latest/configuration-reference/ publish/documentation/latest/configuration-tutorial/ publish/documentation/latest/developing-aurora-cl...
Date Sat, 14 Feb 2015 18:29:22 GMT
Author: dlester
Date: Sat Feb 14 18:29:21 2015
New Revision: 1659836

URL: http://svn.apache.org/r1659836
Log:
Updates Aurora documentation to reflect the latest available.

Added:
    incubator/aurora/site/publish/documentation/latest/thrift-deprecation/
    incubator/aurora/site/publish/documentation/latest/thrift-deprecation/index.html
    incubator/aurora/site/source/documentation/latest/thrift-deprecation.md
Modified:
    incubator/aurora/site/publish/documentation/latest/client-commands/index.html
    incubator/aurora/site/publish/documentation/latest/configuration-reference/index.html
    incubator/aurora/site/publish/documentation/latest/configuration-tutorial/index.html
    incubator/aurora/site/publish/documentation/latest/developing-aurora-client/index.html
    incubator/aurora/site/publish/documentation/latest/developing-aurora-scheduler/index.html
    incubator/aurora/site/publish/documentation/latest/hooks/index.html
    incubator/aurora/site/publish/documentation/latest/tutorial/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-reference.md
    incubator/aurora/site/source/documentation/latest/configuration-tutorial.md
    incubator/aurora/site/source/documentation/latest/developing-aurora-client.md
    incubator/aurora/site/source/documentation/latest/developing-aurora-scheduler.md
    incubator/aurora/site/source/documentation/latest/hooks.md
    incubator/aurora/site/source/documentation/latest/tutorial.md
    incubator/aurora/site/source/documentation/latest/user-guide.md

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=1659836&r1=1659835&r2=1659836&view=diff
==============================================================================
--- incubator/aurora/site/publish/documentation/latest/client-commands/index.html (original)
+++ incubator/aurora/site/publish/documentation/latest/client-commands/index.html Sat Feb
14 18:29:21 2015
@@ -346,7 +346,7 @@ cluster.</p>
 
 <p>When you create a job, part of the output response contains a URL that goes
 to the job&rsquo;s scheduler UI page. For example:</p>
-<pre class="highlight text">vagrant@precise64:~$ aurora create devcluster/www-data/prod/hello
/vagrant/examples/jobs/hello_world.aurora
+<pre class="highlight text">vagrant@precise64:~$ aurora job 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

Modified: incubator/aurora/site/publish/documentation/latest/configuration-reference/index.html
URL: http://svn.apache.org/viewvc/incubator/aurora/site/publish/documentation/latest/configuration-reference/index.html?rev=1659836&r1=1659835&r2=1659836&view=diff
==============================================================================
--- incubator/aurora/site/publish/documentation/latest/configuration-reference/index.html
(original)
+++ incubator/aurora/site/publish/documentation/latest/configuration-reference/index.html
Sat Feb 14 18:29:21 2015
@@ -857,9 +857,9 @@ hello_world_job = Job(
 jobs = [hello_world_job]
 </pre>
 <p>Then issue the following commands to create and kill the job, using your own values
for the job key.</p>
-<pre class="highlight text">aurora create cluster1/$USER/test/hello_world hello_world.aurora
+<pre class="highlight text">aurora job create cluster1/$USER/test/hello_world hello_world.aurora
 
-aurora kill cluster1/$USER/test/hello_world
+aurora job kill cluster1/$USER/test/hello_world
 </pre>
 <h3 id="environment-tailoring">Environment Tailoring</h3>
 
@@ -888,9 +888,9 @@ jobs = [
 ]
 </pre>
 <p>Then issue the following commands to create and kill the job, using your own values
for the job key</p>
-<pre class="highlight text">aurora create cluster1/$USER/test/hello_world-cluster1
hello_world_productionized.aurora
+<pre class="highlight text">aurora job create cluster1/$USER/test/hello_world-cluster1
hello_world_productionized.aurora
 
-aurora kill cluster1/$USER/test/hello_world-cluster1
+aurora job kill cluster1/$USER/test/hello_world-cluster1
 </pre></div>
 
   		</div>

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=1659836&r1=1659835&r2=1659836&view=diff
==============================================================================
--- incubator/aurora/site/publish/documentation/latest/configuration-tutorial/index.html (original)
+++ incubator/aurora/site/publish/documentation/latest/configuration-tutorial/index.html Sat
Feb 14 18:29:21 2015
@@ -43,8 +43,8 @@
 
 <p>How to write Aurora configuration files, including feature descriptions
 and best practices. When writing a configuration file, make use of
-<code>aurora inspect</code>. It takes the same job key and configuration file
-arguments as <code>aurora create</code> or <code>aurora update</code>.
It first ensures the
+<code>aurora job inspect</code>. It takes the same job key and configuration
file
+arguments as <code>aurora job create</code> or <code>aurora job update</code>.
It first ensures the
 configuration parses, then outputs it in human-readable form.</p>
 
 <p>You should read this after going through the general <a href="/documentation/latest/tutorial/">Aurora
Tutorial</a>.</p>
@@ -511,7 +511,7 @@ hello_world_job = Job(
   cluster=&quot;cluster1&quot;)
 </pre>
 <p>When written to <code>hello_world.aurora</code>, you invoke it with
a simple
-<code>aurora create cluster1/$USER/test/hello_world hello_world.aurora</code>.</p>
+<code>aurora job create cluster1/$USER/test/hello_world hello_world.aurora</code>.</p>
 
 <h3 id="combining-tasks">Combining tasks</h3>
 

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=1659836&r1=1659835&r2=1659836&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
Sat Feb 14 18:29:21 2015
@@ -122,6 +122,10 @@ running in the vagrant image, it would b
 is the directory where our example clusters.json is found).</li>
 <li>You should now be able to run and debug this configuration!</li>
 </ul>
+
+<h1 id="making-thrift-schema-changes">Making thrift schema changes</h1>
+
+<p>See <a href="/documentation/latest/thrift-deprecation/">this document</a>
for any thrift related changes.</p>
 </div>
 
   		</div>

Modified: incubator/aurora/site/publish/documentation/latest/developing-aurora-scheduler/index.html
URL: http://svn.apache.org/viewvc/incubator/aurora/site/publish/documentation/latest/developing-aurora-scheduler/index.html?rev=1659836&r1=1659835&r2=1659836&view=diff
==============================================================================
--- incubator/aurora/site/publish/documentation/latest/developing-aurora-scheduler/index.html
(original)
+++ incubator/aurora/site/publish/documentation/latest/developing-aurora-scheduler/index.html
Sat Feb 14 18:29:21 2015
@@ -132,6 +132,10 @@ should not be modified directly:</p>
 </pre>
 <p>To upgrade Gradle unpack the new version somewhere, run <code>/path/to/new/gradle
wrapper</code> in the
 repository root and commit the changed files.</p>
+
+<h1 id="making-thrift-schema-changes">Making thrift schema changes</h1>
+
+<p>See <a href="/documentation/latest/thrift-deprecation/">this document</a>
for any thrift related changes.</p>
 </div>
 
   		</div>

Modified: incubator/aurora/site/publish/documentation/latest/hooks/index.html
URL: http://svn.apache.org/viewvc/incubator/aurora/site/publish/documentation/latest/hooks/index.html?rev=1659836&r1=1659835&r2=1659836&view=diff
==============================================================================
--- incubator/aurora/site/publish/documentation/latest/hooks/index.html (original)
+++ incubator/aurora/site/publish/documentation/latest/hooks/index.html Sat Feb 14 18:29:21
2015
@@ -209,10 +209,10 @@ returning <code>True</code>. For example
 <h2 id="command-line">Command Line</h2>
 
 <p>All Aurora Command Line commands now accept an <code>.aurora</code>
config file as an optional parameter (some, of course, accept it as a required parameter).
Whenever a command has a <code>.aurora</code> file parameter, any hooks specified
and activated in the <code>.aurora</code> file can be used. For example:</p>
-<pre class="highlight text">aurora restart cluster1/role/env/app myapp.aurora
+<pre class="highlight text">aurora job restart cluster1/role/env/app myapp.aurora
 </pre>
 <p>The command activates any hooks specified and activated in <code>myapp.aurora</code>.
For the <code>restart</code> command, that is the only thing the <code>myapp.aurora</code>
parameter does. So, if the command was the following, since there is no <code>.aurora</code>
config file to specify any hooks, no hooks on the <code>restart</code> command
can run.</p>
-<pre class="highlight text">aurora restart cluster1/role/env/app
+<pre class="highlight text">aurora job restart cluster1/role/env/app
 </pre>
 <h2 id="hooks-protocol">Hooks Protocol</h2>
 

Added: incubator/aurora/site/publish/documentation/latest/thrift-deprecation/index.html
URL: http://svn.apache.org/viewvc/incubator/aurora/site/publish/documentation/latest/thrift-deprecation/index.html?rev=1659836&view=auto
==============================================================================
--- incubator/aurora/site/publish/documentation/latest/thrift-deprecation/index.html (added)
+++ incubator/aurora/site/publish/documentation/latest/thrift-deprecation/index.html Sat Feb
14 18:29:21 2015
@@ -0,0 +1,128 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+	<title>Apache Aurora</title>
+    <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.1/css/bootstrap.min.css">
+    <link href="/assets/css/main.css" rel="stylesheet">
+	<!-- 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="container-fluid section-header">
+  <div class="container">
+    <div class="nav nav-bar">
+    <a href="/"><img src="/assets/img/aurora_logo_white_bkg.svg" width="300" alt="Transparent
Apache Aurora logo with dark background"/></a>
+	<ul class="nav navbar-nav navbar-right">
+      <li><a href="/documentation/latest/">Documentation</a></li>
+      <li><a href="/community/">Community</a></li>
+      <li><a href="/downloads/">Downloads</a></li>
+      <li><a href="/blog/">Blog</a></li>
+    </ul>
+    </div>
+  </div>
+</div>	
+  	  <div class="container-fluid">
+  	  	<div class="container content">
+          <div class="col-md-12 documentation">
+<h5 class="page-header text-uppercase">Documentation</h5>
+<h1 id="thrift-api-changes">Thrift API Changes</h1>
+
+<h2 id="overview">Overview</h2>
+
+<p>Aurora uses <a href="https://thrift.apache.org/">Apache Thrift</a> for
representing structured data in
+client/server RPC protocol as well as for internal data storage. While Thrift is capable
of
+correctly handling additions and renames of the existing members, field removals must be
done
+carefully to ensure backwards compatibility and provide predictable deprecation cycle. This
+document describes general guidelines for making Thrift schema changes to the existing fields
in
+<a href="../api/src/main/thrift/org/apache/aurora/gen/api.thrift">api.thrift</a>.</p>
+
+<p>It is highly recommended to go through the
+<a href="http://diwakergupta.github.io/thrift-missing-guide/">Thrift: The Missing Guide</a>
first to refresh on
+basic Thrift schema concepts.</p>
+
+<h2 id="checklist">Checklist</h2>
+
+<p>Every existing Thrift schema modification is unique in its requirements and must
be analyzed
+carefully to identify its scope and expected consequences. The following checklist may help
in that
+analysis:
+* Is this a new field/struct? If yes, go ahead
+* Is this a pure field/struct rename without any type/structure change? If yes, go ahead
and rename
+* Anything else, read further to make sure your change is properly planned</p>
+
+<h2 id="deprecation-cycle">Deprecation cycle</h2>
+
+<p>Any time a breaking change (e.g.: field replacement or removal) is required, the
following cycle
+must be followed:</p>
+
+<h3 id="vcurrent">vCurrent</h3>
+
+<p>Change is applied in a way that does not break scheduler/client with this version
to
+communicate with scheduler/client from vCurrent-1.
+* Do not remove or rename the old field
+* Add a new field as an eventual replacement of the old one and implement a dual read/write
+anywhere the old field is used
+* Check <a href="../api/src/main/thrift/org/apache/aurora/gen/storage.thrift">storage.thrift</a>
to see if the
+affected struct is stored in Aurora scheduler storage. If so, you most likely need to backfill
+existing data to ensure both fields are populated eagerly on startup
+See <a href="../src/main/java/org/apache/aurora/scheduler/storage/StorageBackfill.java">StorageBackfill.java</a>
+* Add a deprecation jira ticket into the vCurrent+1 release candidate
+* Add a TODO for the deprecated field mentioning the jira ticket</p>
+
+<h3 id="vcurrent+1">vCurrent+1</h3>
+
+<p>Finalize the change by removing the deprecated fields from the Thrift schema.
+* Drop any dual read/write routines added in the previous version
+* Remove the deprecated Thrift field</p>
+
+<h2 id="testing">Testing</h2>
+
+<p>It&rsquo;s always advisable to test your changes in the local vagrant environment
to build more
+confidence that you change is backwards compatible. It&rsquo;s easy to simulate different
+client/scheduler versions by playing with <code>aurorabuild</code> command. See
<a href="/documentation/latest/vagrant/">this document</a>
+for more.</p>
+</div>
+
+  		</div>
+  	  </div>
+	  
+      	<div class="container-fluid section-footer buffer">
+      <div class="container">
+        <div class="row">
+		  <div class="col-md-2 col-md-offset-1"><h3>Quick Links</h3>
+		  <ul>
+		    <li><a href="/downloads/">Downloads</a></li>
+            <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="/documentation/latest/contributing/">How To Contribute</a></li>
    
+		  </ul>
+	      </div>
+		  <div class="col-md-2"><h3>The ASF</h3>
+          <ul>
+            <li><a href="http://www.apache.org/licenses/">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>
+		  <div class="col-md-6">
+		    <p class="disclaimer">Apache Aurora is an effort undergoing incubation at The
Apache Software Foundation (ASF), sponsored by the Apache Incubator. Incubation is required
of all newly accepted projects until a further review indicates that the infrastructure, communications,
and decision making process have stabilized in a manner consistent with other successful ASF
projects. While incubation status is not necessarily a reflection of the completeness or stability
of the code, it does indicate that the project has yet to be fully endorsed by the ASF.</p>
+			<p class="disclaimer">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>. The <a href="https://www.flickr.com/photos/trondk/12706051375/">Aurora
Borealis IX photo</a> displayed on the homepage is available under a <a href="https://creativecommons.org/licenses/by-nc-nd/2.0/">Creative
Commons BY-NC-ND 2.0 license</a>. Apache, Apache Aurora, and the Apache feather logo
are trademarks of The Apache Software Foundation.</p>
+        </div>
+      </div>
+    </div>
+	</body>
+</html>
\ No newline at end of file

Modified: incubator/aurora/site/publish/documentation/latest/tutorial/index.html
URL: http://svn.apache.org/viewvc/incubator/aurora/site/publish/documentation/latest/tutorial/index.html?rev=1659836&r1=1659835&r2=1659836&view=diff
==============================================================================
--- incubator/aurora/site/publish/documentation/latest/tutorial/index.html (original)
+++ incubator/aurora/site/publish/documentation/latest/tutorial/index.html Sat Feb 14 18:29:21
2015
@@ -202,12 +202,12 @@ are available, contact your sysadmin.</p
 
 <p>Environment names are namespaces; you can count on <code>prod</code>,
<code>devel</code> and <code>test</code> existing.</p>
 
-<p>The Aurora Client command that actually runs our Job is <code>aurora create</code>.
It creates a Job as
+<p>The Aurora Client command that actually runs our Job is <code>aurora job create</code>.
It creates a Job as
 specified by its job key and configuration file arguments and runs it.</p>
-<pre class="highlight text">aurora create &lt;cluster&gt;/&lt;role&gt;/&lt;environment&gt;/&lt;jobname&gt;
&lt;config_file&gt;
+<pre class="highlight text">aurora job create &lt;cluster&gt;/&lt;role&gt;/&lt;environment&gt;/&lt;jobname&gt;
&lt;config_file&gt;
 </pre>
 <p>Or for our example:</p>
-<pre class="highlight text">aurora create devcluster/www-data/devel/hello_world /vagrant/hello_world.aurora
+<pre class="highlight text">aurora job create devcluster/www-data/devel/hello_world
/vagrant/hello_world.aurora
 </pre>
 <p>This returns:</p>
 <pre class="highlight text">$ vagrant ssh
@@ -216,7 +216,7 @@ Welcome to Ubuntu 12.04 LTS (GNU/Linux 3
  * Documentation:  https://help.ubuntu.com/
 Welcome to your Vagrant-built virtual machine.
 Last login: Fri Jan  3 02:18:55 2014 from 10.0.2.2
-vagrant@precise64:~$ aurora create devcluster/www-data/devel/hello_world \
+vagrant@precise64:~$ aurora job create devcluster/www-data/devel/hello_world \
     /vagrant/hello_world.aurora
  INFO] Creating job hello_world
  INFO] Response from scheduler: OK (message: 1 new tasks pending for job
@@ -258,7 +258,7 @@ to <code>stderr</code> on the failed <co
 <p>It looks like we made a typo in our Python script. We wanted <code>xrange</code>,
 not <code>xrang</code>. Edit the <code>hello_world.py</code> script
to use the correct function and
 we will try again.</p>
-<pre class="highlight text">aurora update devcluster/www-data/devel/hello_world /vagrant/hello_world.aurora
+<pre class="highlight text">aurora job update devcluster/www-data/devel/hello_world
/vagrant/hello_world.aurora
 </pre>
 <p>This time, the task comes up, we inspect the page, and see that the
 <code>hello_world</code> process is running.</p>
@@ -273,7 +273,7 @@ output:</p>
 <h2 id="cleanup">Cleanup</h2>
 
 <p>Now that we&rsquo;re done, we kill the job using the Aurora client:</p>
-<pre class="highlight text">vagrant@precise64:~$ aurora killall devcluster/www-data/devel/hello_world
+<pre class="highlight text">vagrant@precise64:~$ aurora job killall devcluster/www-data/devel/hello_world
  INFO] Killing tasks for job: devcluster/www-data/devel/hello_world
  INFO] Response from scheduler: OK (message: Tasks killed.)
  INFO] Job url: http://precise64:8081/scheduler/www-data/devel/hello_world

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=1659836&r1=1659835&r2=1659836&view=diff
==============================================================================
--- incubator/aurora/site/publish/documentation/latest/user-guide/index.html (original)
+++ incubator/aurora/site/publish/documentation/latest/user-guide/index.html Sat Feb 14 18:29:21
2015
@@ -92,7 +92,7 @@ request 1 core of cpu, 1 GB of RAM, and
 in the configuration file <code>hello_world.aurora</code>. I want to
 update it so it requests 2 GB of RAM instead of 1. I create a new
 configuration file to do that called <code>new_hello_world.aurora</code> and
-issue a <code>aurora update --shards=0-1 &lt;job_key_value&gt; new_hello_world.aurora</code>
+issue a <code>aurora job update &lt;job_key_value&gt;/0-1 new_hello_world.aurora</code>
 command.</p>
 
 <p>This results in instances 0 and 1 having 1 cpu, 2 GB of RAM, and 1 GB of disk space,
@@ -344,7 +344,7 @@ after reaching a set of failure limits,
 
 <h3 id="forceful-termination:-killing,-restarting">Forceful Termination: KILLING, RESTARTING</h3>
 
-<p>You can terminate a <code>Task</code> by issuing an <code>aurora
kill</code> command, which
+<p>You can terminate a <code>Task</code> by issuing an <code>aurora
job kill</code> command, which
 moves it into <code>KILLING</code> state. The scheduler then sends the slave
 a
 request to terminate the <code>Task</code>. If the scheduler receives a successful
 response, it moves the Task into <code>KILLED</code> state and never restarts
it.</p>
@@ -398,7 +398,7 @@ about the Aurora Client.</p>
 <p>Part of the output from creating a new Job is a URL for the Job&rsquo;s scheduler
UI page.</p>
 
 <p>For example:</p>
-<pre class="highlight text">  vagrant@precise64:~$ aurora create devcluster/www-data/prod/hello
\
+<pre class="highlight text">  vagrant@precise64:~$ aurora job 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)
@@ -407,8 +407,8 @@ about the Aurora Client.</p>
 <p>The &ldquo;Job url&rdquo; goes to the Job&rsquo;s scheduler UI page.
To go to the overall scheduler UI page,
   stop at the &ldquo;scheduler&rdquo; part of the URL, in this case, <code>http://precise64:8081/scheduler</code></p>
 
-<p>You can also reach the scheduler UI page via the Client command <code>aurora
open</code>:</p>
-<pre class="highlight text">  aurora open [&lt;cluster&gt;[/&lt;role&gt;[/&lt;env&gt;/&lt;job_name&gt;]]]
+<p>You can also reach the scheduler UI page via the Client command <code>aurora
job open</code>:</p>
+<pre class="highlight text">  aurora job open [&lt;cluster&gt;[/&lt;role&gt;[/&lt;env&gt;/&lt;job_name&gt;]]]
 </pre>
 <p>If only the cluster is specified, it goes directly to that cluster&rsquo;s scheduler
main page.
   If the role is specified, it goes to the top-level role page. If the full job key is specified,

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=1659836&r1=1659835&r2=1659836&view=diff
==============================================================================
--- incubator/aurora/site/source/documentation/latest/client-commands.md (original)
+++ incubator/aurora/site/source/documentation/latest/client-commands.md Sat Feb 14 18:29:21
2015
@@ -319,7 +319,7 @@ cluster.
 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
+    vagrant@precise64:~$ aurora job 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

Modified: incubator/aurora/site/source/documentation/latest/configuration-reference.md
URL: http://svn.apache.org/viewvc/incubator/aurora/site/source/documentation/latest/configuration-reference.md?rev=1659836&r1=1659835&r2=1659836&view=diff
==============================================================================
--- incubator/aurora/site/source/documentation/latest/configuration-reference.md (original)
+++ incubator/aurora/site/source/documentation/latest/configuration-reference.md Sat Feb 14
18:29:21 2015
@@ -521,9 +521,9 @@ for values such as `cluster`s.
 
 Then issue the following commands to create and kill the job, using your own values for the
job key.
 
-    aurora create cluster1/$USER/test/hello_world hello_world.aurora
+    aurora job create cluster1/$USER/test/hello_world hello_world.aurora
 
-    aurora kill cluster1/$USER/test/hello_world
+    aurora job kill cluster1/$USER/test/hello_world
 
 ### Environment Tailoring
 
@@ -554,6 +554,6 @@ for values such as `cluster`s.
 
 Then issue the following commands to create and kill the job, using your own values for the
job key
 
-    aurora create cluster1/$USER/test/hello_world-cluster1 hello_world_productionized.aurora
+    aurora job create cluster1/$USER/test/hello_world-cluster1 hello_world_productionized.aurora
 
-    aurora kill cluster1/$USER/test/hello_world-cluster1
+    aurora job kill cluster1/$USER/test/hello_world-cluster1

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=1659836&r1=1659835&r2=1659836&view=diff
==============================================================================
--- incubator/aurora/site/source/documentation/latest/configuration-tutorial.md (original)
+++ incubator/aurora/site/source/documentation/latest/configuration-tutorial.md Sat Feb 14
18:29:21 2015
@@ -3,8 +3,8 @@ Aurora Configuration Tutorial
 
 How to write Aurora configuration files, including feature descriptions
 and best practices. When writing a configuration file, make use of
-`aurora inspect`. It takes the same job key and configuration file
-arguments as `aurora create` or `aurora update`. It first ensures the
+`aurora job inspect`. It takes the same job key and configuration file
+arguments as `aurora job create` or `aurora job update`. It first ensures the
 configuration parses, then outputs it in human-readable form.
 
 You should read this after going through the general [Aurora Tutorial](/documentation/latest/tutorial/).
@@ -443,7 +443,7 @@ The simplest idiomatic Job configuration
       cluster="cluster1")
 
 When written to `hello_world.aurora`, you invoke it with a simple
-`aurora create cluster1/$USER/test/hello_world hello_world.aurora`.
+`aurora job create cluster1/$USER/test/hello_world hello_world.aurora`.
 
 ### Combining tasks
 

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=1659836&r1=1659835&r2=1659836&view=diff
==============================================================================
--- incubator/aurora/site/source/documentation/latest/developing-aurora-client.md (original)
+++ incubator/aurora/site/source/documentation/latest/developing-aurora-client.md Sat Feb
14 18:29:21 2015
@@ -86,4 +86,6 @@ a Run configuration:
   is the directory where our example clusters.json is found).
 * You should now be able to run and debug this configuration!
 
-
+Making thrift schema changes
+============================
+See [this document](/documentation/latest/thrift-deprecation/) for any thrift related changes.

Modified: incubator/aurora/site/source/documentation/latest/developing-aurora-scheduler.md
URL: http://svn.apache.org/viewvc/incubator/aurora/site/source/documentation/latest/developing-aurora-scheduler.md?rev=1659836&r1=1659835&r2=1659836&view=diff
==============================================================================
--- incubator/aurora/site/source/documentation/latest/developing-aurora-scheduler.md (original)
+++ incubator/aurora/site/source/documentation/latest/developing-aurora-scheduler.md Sat Feb
14 18:29:21 2015
@@ -106,3 +106,7 @@ should not be modified directly:
 
 To upgrade Gradle unpack the new version somewhere, run `/path/to/new/gradle wrapper` in
the
 repository root and commit the changed files.
+
+Making thrift schema changes
+============================
+See [this document](/documentation/latest/thrift-deprecation/) for any thrift related changes.

Modified: incubator/aurora/site/source/documentation/latest/hooks.md
URL: http://svn.apache.org/viewvc/incubator/aurora/site/source/documentation/latest/hooks.md?rev=1659836&r1=1659835&r2=1659836&view=diff
==============================================================================
--- incubator/aurora/site/source/documentation/latest/hooks.md (original)
+++ incubator/aurora/site/source/documentation/latest/hooks.md Sat Feb 14 18:29:21 2015
@@ -133,11 +133,11 @@ jobs.extend(
 
 All Aurora Command Line commands now accept an `.aurora` config file as an optional parameter
(some, of course, accept it as a required parameter). Whenever a command has a `.aurora` file
parameter, any hooks specified and activated in the `.aurora` file can be used. For example:
 
-    aurora restart cluster1/role/env/app myapp.aurora
+    aurora job restart cluster1/role/env/app myapp.aurora
 
 The command activates any hooks specified and activated in `myapp.aurora`. For the `restart`
command, that is the only thing the `myapp.aurora` parameter does. So, if the command was
the following, since there is no `.aurora` config file to specify any hooks, no hooks on the
`restart` command can run.
 
-    aurora restart cluster1/role/env/app
+    aurora job restart cluster1/role/env/app
 
 ## Hooks Protocol
 

Added: incubator/aurora/site/source/documentation/latest/thrift-deprecation.md
URL: http://svn.apache.org/viewvc/incubator/aurora/site/source/documentation/latest/thrift-deprecation.md?rev=1659836&view=auto
==============================================================================
--- incubator/aurora/site/source/documentation/latest/thrift-deprecation.md (added)
+++ incubator/aurora/site/source/documentation/latest/thrift-deprecation.md Sat Feb 14 18:29:21
2015
@@ -0,0 +1,50 @@
+# Thrift API Changes
+
+## Overview
+Aurora uses [Apache Thrift](https://thrift.apache.org/) for representing structured data
in
+client/server RPC protocol as well as for internal data storage. While Thrift is capable
of
+correctly handling additions and renames of the existing members, field removals must be
done
+carefully to ensure backwards compatibility and provide predictable deprecation cycle. This
+document describes general guidelines for making Thrift schema changes to the existing fields
in
+[api.thrift](../api/src/main/thrift/org/apache/aurora/gen/api.thrift).
+
+It is highly recommended to go through the
+[Thrift: The Missing Guide](http://diwakergupta.github.io/thrift-missing-guide/) first to
refresh on
+basic Thrift schema concepts.
+
+## Checklist
+Every existing Thrift schema modification is unique in its requirements and must be analyzed
+carefully to identify its scope and expected consequences. The following checklist may help
in that
+analysis:
+* Is this a new field/struct? If yes, go ahead
+* Is this a pure field/struct rename without any type/structure change? If yes, go ahead
and rename
+* Anything else, read further to make sure your change is properly planned
+
+## Deprecation cycle
+Any time a breaking change (e.g.: field replacement or removal) is required, the following
cycle
+must be followed:
+
+### vCurrent
+Change is applied in a way that does not break scheduler/client with this version to
+communicate with scheduler/client from vCurrent-1.
+* Do not remove or rename the old field
+* Add a new field as an eventual replacement of the old one and implement a dual read/write
+anywhere the old field is used
+* Check [storage.thrift](../api/src/main/thrift/org/apache/aurora/gen/storage.thrift) to
see if the
+affected struct is stored in Aurora scheduler storage. If so, you most likely need to backfill
+existing data to ensure both fields are populated eagerly on startup
+See [StorageBackfill.java](../src/main/java/org/apache/aurora/scheduler/storage/StorageBackfill.java)
+* Add a deprecation jira ticket into the vCurrent+1 release candidate
+* Add a TODO for the deprecated field mentioning the jira ticket
+
+### vCurrent+1
+Finalize the change by removing the deprecated fields from the Thrift schema.
+* Drop any dual read/write routines added in the previous version
+* Remove the deprecated Thrift field
+
+## Testing
+It's always advisable to test your changes in the local vagrant environment to build more
+confidence that you change is backwards compatible. It's easy to simulate different
+client/scheduler versions by playing with `aurorabuild` command. See [this document](/documentation/latest/vagrant/)
+for more.
+

Modified: incubator/aurora/site/source/documentation/latest/tutorial.md
URL: http://svn.apache.org/viewvc/incubator/aurora/site/source/documentation/latest/tutorial.md?rev=1659836&r1=1659835&r2=1659836&view=diff
==============================================================================
--- incubator/aurora/site/source/documentation/latest/tutorial.md (original)
+++ incubator/aurora/site/source/documentation/latest/tutorial.md Sat Feb 14 18:29:21 2015
@@ -166,14 +166,14 @@ are available, contact your sysadmin.
 
 Environment names are namespaces; you can count on `prod`, `devel` and `test` existing.
 
-The Aurora Client command that actually runs our Job is `aurora create`. It creates a Job
as
+The Aurora Client command that actually runs our Job is `aurora job create`. It creates a
Job as
 specified by its job key and configuration file arguments and runs it.
 
-    aurora create <cluster>/<role>/<environment>/<jobname> <config_file>
+    aurora job create <cluster>/<role>/<environment>/<jobname> <config_file>
 
 Or for our example:
 
-    aurora create devcluster/www-data/devel/hello_world /vagrant/hello_world.aurora
+    aurora job create devcluster/www-data/devel/hello_world /vagrant/hello_world.aurora
 
 This returns:
 
@@ -183,7 +183,7 @@ This returns:
      * Documentation:  https://help.ubuntu.com/
     Welcome to your Vagrant-built virtual machine.
     Last login: Fri Jan  3 02:18:55 2014 from 10.0.2.2
-    vagrant@precise64:~$ aurora create devcluster/www-data/devel/hello_world \
+    vagrant@precise64:~$ aurora job create devcluster/www-data/devel/hello_world \
         /vagrant/hello_world.aurora
      INFO] Creating job hello_world
      INFO] Response from scheduler: OK (message: 1 new tasks pending for job
@@ -226,7 +226,7 @@ It looks like we made a typo in our Pyth
 not `xrang`. Edit the `hello_world.py` script to use the correct function and
 we will try again.
 
-    aurora update devcluster/www-data/devel/hello_world /vagrant/hello_world.aurora
+    aurora job update devcluster/www-data/devel/hello_world /vagrant/hello_world.aurora
 
 This time, the task comes up, we inspect the page, and see that the
 `hello_world` process is running.
@@ -242,7 +242,7 @@ output:
 
 Now that we're done, we kill the job using the Aurora client:
 
-    vagrant@precise64:~$ aurora killall devcluster/www-data/devel/hello_world
+    vagrant@precise64:~$ aurora job killall devcluster/www-data/devel/hello_world
      INFO] Killing tasks for job: devcluster/www-data/devel/hello_world
      INFO] Response from scheduler: OK (message: Tasks killed.)
      INFO] Job url: http://precise64:8081/scheduler/www-data/devel/hello_world

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=1659836&r1=1659835&r2=1659836&view=diff
==============================================================================
--- incubator/aurora/site/source/documentation/latest/user-guide.md (original)
+++ incubator/aurora/site/source/documentation/latest/user-guide.md Sat Feb 14 18:29:21 2015
@@ -45,7 +45,7 @@ request 1 core of cpu, 1 GB of RAM, and
 in the configuration file `hello_world.aurora`. I want to
 update it so it requests 2 GB of RAM instead of 1. I create a new
 configuration file to do that called `new_hello_world.aurora` and
-issue a `aurora update --shards=0-1 <job_key_value> new_hello_world.aurora`
+issue a `aurora job update <job_key_value>/0-1 new_hello_world.aurora`
 command.
 
 This results in instances 0 and 1 having 1 cpu, 2 GB of RAM, and 1 GB of disk space,
@@ -274,7 +274,7 @@ after reaching a set of failure limits,
 
 ### Forceful Termination: KILLING, RESTARTING
 
-You can terminate a `Task` by issuing an `aurora kill` command, which
+You can terminate a `Task` by issuing an `aurora job kill` command, which
 moves it into `KILLING` state. The scheduler then sends the slave  a
 request to terminate the `Task`. If the scheduler receives a successful
 response, it moves the Task into `KILLED` state and never restarts it.
@@ -329,7 +329,7 @@ You interact with Aurora jobs either via
 
   For example:
 
-      vagrant@precise64:~$ aurora create devcluster/www-data/prod/hello \
+      vagrant@precise64:~$ aurora job 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)
@@ -338,9 +338,9 @@ You interact with Aurora jobs either via
   The "Job url" goes to the Job's scheduler UI page. To go to the overall scheduler UI page,
   stop at the "scheduler" part of the URL, in this case, `http://precise64:8081/scheduler`
 
-  You can also reach the scheduler UI page via the Client command `aurora open`:
+  You can also reach the scheduler UI page via the Client command `aurora job open`:
 
-      aurora open [<cluster>[/<role>[/<env>/<job_name>]]]
+      aurora job 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,



Mime
View raw message