From 34ec4c955ada62e6fd80ca81c6289f60a6e09c25 Mon Sep 17 00:00:00 2001 From: Alex Dadgar Date: Wed, 24 Feb 2016 20:11:16 -0800 Subject: [PATCH] Add upgrading documentation --- website/source/docs/upgrade/index.html.md | 36 +++++++++++++++ .../docs/upgrade/upgrade-specific.html.md | 44 +++++++++++++++++++ website/source/layouts/docs.erb | 12 +++++ 3 files changed, 92 insertions(+) create mode 100644 website/source/docs/upgrade/index.html.md create mode 100644 website/source/docs/upgrade/upgrade-specific.html.md diff --git a/website/source/docs/upgrade/index.html.md b/website/source/docs/upgrade/index.html.md new file mode 100644 index 000000000..0184cd70d --- /dev/null +++ b/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. diff --git a/website/source/docs/upgrade/upgrade-specific.html.md b/website/source/docs/upgrade/upgrade-specific.html.md new file mode 100644 index 000000000..05edf0cea --- /dev/null +++ b/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 ` 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. diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 62ccf6445..0071549f2 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -31,6 +31,18 @@ Installation + > + Upgrading + + + > Job Specification