github.com/hspak/nomad@v0.7.2-0.20180309000617-bc4ae22a39a5/website/source/docs/upgrade/upgrade-specific.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Upgrade Guides"
     4  sidebar_current: "docs-upgrade-specific"
     5  description: |-
     6    Specific versions of Nomad may have additional information about the upgrade
     7    process beyond the standard flow.
     8  ---
     9  
    10  # Upgrading Specific Versions
    11  
    12  The [upgrading page](/docs/upgrade/index.html) covers the details of doing
    13  a standard upgrade. However, specific versions of Nomad may have more
    14  details provided for their upgrades as a result of new features or changed
    15  behavior. This page is used to document those details separately from the
    16  standard upgrade flow.
    17  
    18  ## Nomad 0.8.0
    19  
    20  #### Raft Protocol Version Compatibility
    21  
    22  When upgrading to Nomad 0.8.0 from a version lower than 0.7.0, users will need to
    23  set the [`-raft-protocol`](/docs/agent/options.html#_raft_protocol) option to 1 in
    24  order to maintain backwards compatibility with the old servers during the upgrade.
    25  After the servers have been migrated to version 0.8.0, `-raft-protocol` can be moved
    26  up to 2 and the servers restarted to match the default.
    27  
    28  The Raft protocol must be stepped up in this way; only adjacent version numbers are
    29  compatible (for example, version 1 cannot talk to version 3). Here is a table of the
    30  Raft Protocol versions supported by each Consul version:
    31  
    32  <table class="table table-bordered table-striped">
    33    <tr>
    34      <th>Version</th>
    35      <th>Supported Raft Protocols</th>
    36    </tr>
    37    <tr>
    38      <td>0.6 and earlier</td>
    39      <td>0</td>
    40    </tr>
    41    <tr>
    42      <td>0.7</td>
    43      <td>1</td>
    44    </tr>
    45    <tr>
    46      <td>0.8</td>
    47      <td>1, 2, 3</td>
    48    </tr>
    49  </table>
    50  
    51  In order to enable all [Autopilot](/guides/cluster/autopilot.html) features, all servers
    52  in a Nomad cluster must be running with Raft protocol version 3 or later.
    53  
    54  ## Nomad 0.6.0
    55  
    56  ### Default `advertise` address changes
    57  
    58  When no `advertise` address was specified and Nomad's `bind_addr` was loopback
    59  or `0.0.0.0`, Nomad attempted to resolve the local hostname to use as an
    60  advertise address.
    61  
    62  Many hosts cannot properly resolve their hostname, so Nomad 0.6 defaults
    63  `advertise` to the first private IP on the host (e.g. `10.1.2.3`).
    64  
    65  If you manually configure `advertise` addresses no changes are necessary.
    66  
    67  ## Nomad Clients
    68  
    69  The change to the default, advertised IP also effect clients that do not specify
    70  which network_interface to use. If you have several routable IPs, it is advised
    71  to configure the client's [network
    72  interface](https://www.nomadproject.io/docs/agent/configuration/client.html#network_interface)
    73  such that tasks bind to the correct address.
    74  
    75  ## Nomad 0.5.5
    76  
    77  ### Docker `load` changes
    78  
    79  Nomad 0.5.5 has a backward incompatible change in the `docker` driver's
    80  configuration. Prior to 0.5.5 the `load` configuration option accepted a list
    81  images to load, in 0.5.5 it has been changed to a single string. No
    82  functionality was changed. Even if more than one item was specified prior to
    83  0.5.5 only the first item was used.
    84  
    85  To do a zero-downtime deploy with jobs that use the `load` option:
    86  
    87  * Upgrade servers to version 0.5.5 or later.
    88  
    89  * Deploy new client nodes on the same version as the servers.
    90  
    91  * Resubmit jobs with the `load` option fixed and a constraint to only run on
    92    version 0.5.5 or later:
    93  
    94  ```hcl
    95      constraint {
    96        attribute = "${attr.nomad.version}"
    97        operator  = "version"
    98        value     = ">= 0.5.5"
    99      }
   100  ```
   101  
   102  * Drain and shutdown old client nodes.
   103  
   104  ### Validation changes
   105  
   106  Due to internal job serialization and validation changes you may run into
   107  issues using 0.5.5 command line tools such as `nomad run` and `nomad validate`
   108  with 0.5.4 or earlier agents.
   109  
   110  It is recommended you upgrade agents before or alongside your command line
   111  tools.
   112  
   113  ## Nomad 0.4.0
   114  
   115  Nomad 0.4.0 has backward incompatible changes in the logic for Consul
   116  deregistration.  When a Task which was started by Nomad v0.3.x is uncleanly shut
   117  down, the Nomad 0.4 Client will no longer clean up any stale services.  If an
   118  in-place upgrade of the Nomad client to 0.4 prevents the Task from gracefully
   119  shutting down and deregistering its Consul-registered services, the Nomad Client
   120  will not clean up the remaining Consul services registered with the 0.3
   121  Executor.
   122  
   123  We recommend draining a node before upgrading to 0.4.0 and then re-enabling the
   124  node once the upgrade is complete.
   125  
   126  
   127  ## Nomad 0.3.1
   128  
   129  Nomad 0.3.1 removes artifact downloading from driver configurations and places them as
   130  a first class element of the task. As such, jobs will have to be rewritten in
   131  the proper format and resubmitted to Nomad. Nomad clients will properly
   132  re-attach to existing tasks but job definitions must be updated before they can
   133  be dispatched to clients running 0.3.1.
   134  
   135  ## Nomad 0.3.0
   136  
   137  Nomad 0.3.0 has made several substantial changes to job files included a new
   138  `log` block and variable interpretation syntax (`${var}`), a modified `restart`
   139  policy syntax, and minimum resources for tasks as well as validation. These
   140  changes require a slight change to the default upgrade flow.
   141  
   142  After upgrading the version of the servers, all previously submitted jobs must
   143  be resubmitted with the updated job syntax using a Nomad 0.3.0 binary.
   144  
   145  * All instances of `$var` must be converted to the new syntax of `${var}`
   146  
   147  * All tasks must provide their required resources for CPU, memory and disk as
   148    well as required network usage if ports are required by the task.
   149  
   150  * Restart policies must be updated to indicate whether it is desired for the
   151    task to restart on failure or to fail using `mode = "delay"` or `mode =
   152    "fail"` respectively.
   153  
   154  * Service names that include periods will fail validation. To fix, remove any
   155    periods from the service name before running the job.
   156  
   157  After updating the Servers and job files, Nomad Clients can be upgraded by first
   158  draining the node so no tasks are running on it. This can be verified by running
   159  `nomad node-status <node-id>` and verify there are no tasks in the `running`
   160  state. Once that is done the client can be killed, the `data_dir` should be
   161  deleted and then Nomad 0.3.0 can be launched.