Merge pull request #852 from hashicorp/d-upgrading

Add upgrading documentation

website/source/docs/upgrade/index.html.md

@@ -0,0 +1,36 @@
+---
+layout: "docs"
+page_title: "Upgrade Nomad"
+sidebar_current: "docs-upgrade-upgrading"
+description: |-
+  Learn how to upgrade Nomad.
+---
+
+# Upgrading Nomad
+
+Both Nomad Clients and Servers are meant to be long-running processes that
+maintain communication with each other. Nomad Servers maintain quorum with other
+Servers and Clients are in constant communication with Servers. As such, care
+should be taken to properly upgrade Nomad to ensure minimal service disruption.
+
+This page documents how to upgrade Nomad when a new version is released.
+
+## Standard Upgrades
+
+For upgrades we strive to ensure backwards compatibility. For most upgrades, the
+process is simple. Assuming the current version of Nomad is A, and version B is
+released.
+
+1. On each server, install version B of Nomad.
+
+2. Shut down version A, restart with version B on one server at a time.
+
+    3. You can run `nomad server-members` to ensure that all servers are
+       clustered and running the version B.
+
+4. Once all the servers are upgraded, begin a rollout of clients following
+   the same process.
+
+   5. Done! You are now running the latest Nomad version. You can verify all
+      Clients joined by running `nomad node-status` and checking all the clients
+      are in a `ready` state.

website/source/docs/upgrade/upgrade-specific.html.md

@@ -0,0 +1,44 @@
+---
+layout: "docs"
+page_title: "Upgrading Specific Versions"
+sidebar_current: "docs-upgrade-specific"
+description: |-
+  Specific versions of Nomad may have additional information about the upgrade
+  process beyond the standard flow.
+---
+
+# Upgrading Specific Versions
+
+The [upgrading page](/docs/upgrade/index.html) covers the details of doing
+a standard upgrade. However, specific versions of Nomad may have more
+details provided for their upgrades as a result of new features or changed
+behavior. This page is used to document those details separately from the
+standard upgrade flow.
+
+## Nomad 0.3.0
+
+Nomad 0.3.0 has made several substantial changes to job files included a new
+`log` block and variable interpretation syntax (`${var}`), a modified `restart`
+policy syntax, and minimum resources for tasks as well as validation. These
+changes require a slight change to the default upgrade flow.
+
+After upgrading the version of the servers, all previously submitted jobs must
+be resubmitted with the updated job syntax using a Nomad 0.3.0 binary.
+
+* All instances of `$var` must be converted to the new syntax of `${var}`
+
+* All tasks must provide their required resources for CPU, memory and disk as
+  well as required network usage if ports are required by the task.
+
+* Restart policies must be updated to indicate whether it is desired for the
+  task to restart on failure or to fail using `mode = "delay"` or `mode =
+  "fail"` respectively.
+
+* Service names that include periods will fail validation. To fix, remove any
+  periods from the service name before running the job.
+
+After updating the Servers and job files, Nomad Clients can be upgraded by first
+draining the node so no tasks are running on it. This can be verified by running
+`nomad node-status <node-id>` and verify there are no tasks in the `running`
+state. Once that is done the client can be killed, the `data_dir` should be
+deleted and then Nomad 0.3.0 can be launched.

website/source/layouts/docs.erb

@@ -31,6 +31,18 @@
 					<a href="/docs/install/index.html">Installation</a>
                 </li>
 
+				<li<%= sidebar_current("docs-upgrade") %>>
+					<a href="/docs/upgrade/index.html">Upgrading</a>
+					<ul class="nav">
+						<li<%= sidebar_current("docs-upgrade-upgrading") %>>
+							<a href="/docs/upgrade/index.html">Upgrading Nomad</a>
+                        </li>
+						<li<%= sidebar_current("docs-upgrade-specific") %>>
+							<a href="/docs/upgrade/upgrade-specific.html">Specific Version Details</a>
+                        </li>
+					</ul>
+                </li>
+
 
 				<li<%= sidebar_current("docs-jobspec") %>>
 					<a href="/docs/jobspec/index.html">Job Specification</a>