github.com/djenriquez/nomad-1@v0.8.1/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  ### Periods in Environment Variable Names No Longer Escaped
    55  
    56  *Applications which expect periods in environment variable names to be replaced
    57  with underscores must be updated.*
    58  
    59  In Nomad 0.7 periods (`.`) in environment variables names were replaced with an
    60  underscore in both the [`env`](/docs/job-specification/env.html) and
    61  [`template`](/docs/job-specification/template.html) stanzas.
    62  
    63  In Nomad 0.8 periods are *not* replaced and will be included in environment
    64  variables verbatim.
    65  
    66  For example the following stanza:
    67  
    68  ```text
    69  env {
    70    registry.consul.addr = "${NOMAD_IP_http}:8500"
    71  }
    72  ```
    73  
    74  In Nomad 0.7 would be exposed to the task as
    75  `registry_consul_addr=127.0.0.1:8500`. In Nomad 0.8 it will now appear exactly
    76  as specified: `registry.consul.addr=127.0.0.1:8500`.
    77  
    78  ### Client APIs Unavailable on Older Nodes
    79  
    80  Because Nomad 0.8 uses a new RPC mechanism to route node-specific APIs like
    81  [`nomad alloc fs`](/docs/commands/alloc/fs.html) through servers to the node,
    82  0.8 CLIs are incompatible using these commands on clients older than 0.8.
    83  
    84  To access these commands on older clients either continue to use a pre-0.8
    85  version of the CLI, or upgrade all clients to 0.8.
    86  
    87  ### CLI Command Changes
    88  
    89  Nomad 0.8 has changed the organization of CLI commands to be based on
    90  subcommands. An example of this change is the change from `nomad alloc-status`
    91  to `nomad alloc status`. All commands have been made to be backwards compatible,
    92  but operators should update any usage of the old style commands to the new style
    93  as the old style will be deprecated in future versions of Nomad.
    94  
    95  ### RPC Advertise Address
    96  
    97  The behavior of the [advertised RPC
    98  address](/docs/agent/configuration/index.html#rpc-1) has changed to be only used
    99  to advertise the RPC address of servers to client nodes. Server to server
   100  communication is done using the advertised Serf address. Existing cluster's
   101  should not be effected but the advertised RPC address may need to be updated to
   102  allow connecting client's over a NAT.
   103  
   104  
   105  ## Nomad 0.6.0
   106  
   107  ### Default `advertise` address changes
   108  
   109  When no `advertise` address was specified and Nomad's `bind_addr` was loopback
   110  or `0.0.0.0`, Nomad attempted to resolve the local hostname to use as an
   111  advertise address.
   112  
   113  Many hosts cannot properly resolve their hostname, so Nomad 0.6 defaults
   114  `advertise` to the first private IP on the host (e.g. `10.1.2.3`).
   115  
   116  If you manually configure `advertise` addresses no changes are necessary.
   117  
   118  ## Nomad Clients
   119  
   120  The change to the default, advertised IP also effect clients that do not specify
   121  which network_interface to use. If you have several routable IPs, it is advised
   122  to configure the client's [network
   123  interface](https://www.nomadproject.io/docs/agent/configuration/client.html#network_interface)
   124  such that tasks bind to the correct address.
   125  
   126  ## Nomad 0.5.5
   127  
   128  ### Docker `load` changes
   129  
   130  Nomad 0.5.5 has a backward incompatible change in the `docker` driver's
   131  configuration. Prior to 0.5.5 the `load` configuration option accepted a list
   132  images to load, in 0.5.5 it has been changed to a single string. No
   133  functionality was changed. Even if more than one item was specified prior to
   134  0.5.5 only the first item was used.
   135  
   136  To do a zero-downtime deploy with jobs that use the `load` option:
   137  
   138  * Upgrade servers to version 0.5.5 or later.
   139  
   140  * Deploy new client nodes on the same version as the servers.
   141  
   142  * Resubmit jobs with the `load` option fixed and a constraint to only run on
   143    version 0.5.5 or later:
   144  
   145  ```hcl
   146      constraint {
   147        attribute = "${attr.nomad.version}"
   148        operator  = "version"
   149        value     = ">= 0.5.5"
   150      }
   151  ```
   152  
   153  * Drain and shutdown old client nodes.
   154  
   155  ### Validation changes
   156  
   157  Due to internal job serialization and validation changes you may run into
   158  issues using 0.5.5 command line tools such as `nomad run` and `nomad validate`
   159  with 0.5.4 or earlier agents.
   160  
   161  It is recommended you upgrade agents before or alongside your command line
   162  tools.
   163  
   164  ## Nomad 0.4.0
   165  
   166  Nomad 0.4.0 has backward incompatible changes in the logic for Consul
   167  deregistration.  When a Task which was started by Nomad v0.3.x is uncleanly shut
   168  down, the Nomad 0.4 Client will no longer clean up any stale services.  If an
   169  in-place upgrade of the Nomad client to 0.4 prevents the Task from gracefully
   170  shutting down and deregistering its Consul-registered services, the Nomad Client
   171  will not clean up the remaining Consul services registered with the 0.3
   172  Executor.
   173  
   174  We recommend draining a node before upgrading to 0.4.0 and then re-enabling the
   175  node once the upgrade is complete.
   176  
   177  
   178  ## Nomad 0.3.1
   179  
   180  Nomad 0.3.1 removes artifact downloading from driver configurations and places them as
   181  a first class element of the task. As such, jobs will have to be rewritten in
   182  the proper format and resubmitted to Nomad. Nomad clients will properly
   183  re-attach to existing tasks but job definitions must be updated before they can
   184  be dispatched to clients running 0.3.1.
   185  
   186  ## Nomad 0.3.0
   187  
   188  Nomad 0.3.0 has made several substantial changes to job files included a new
   189  `log` block and variable interpretation syntax (`${var}`), a modified `restart`
   190  policy syntax, and minimum resources for tasks as well as validation. These
   191  changes require a slight change to the default upgrade flow.
   192  
   193  After upgrading the version of the servers, all previously submitted jobs must
   194  be resubmitted with the updated job syntax using a Nomad 0.3.0 binary.
   195  
   196  * All instances of `$var` must be converted to the new syntax of `${var}`
   197  
   198  * All tasks must provide their required resources for CPU, memory and disk as
   199    well as required network usage if ports are required by the task.
   200  
   201  * Restart policies must be updated to indicate whether it is desired for the
   202    task to restart on failure or to fail using `mode = "delay"` or `mode =
   203    "fail"` respectively.
   204  
   205  * Service names that include periods will fail validation. To fix, remove any
   206    periods from the service name before running the job.
   207  
   208  After updating the Servers and job files, Nomad Clients can be upgraded by first
   209  draining the node so no tasks are running on it. This can be verified by running
   210  `nomad node status <node-id>` and verify there are no tasks in the `running`
   211  state. Once that is done the client can be killed, the `data_dir` should be
   212  deleted and then Nomad 0.3.0 can be launched.