github.com/blixtra/nomad@v0.7.2-0.20171221000451-da9a1d7bb050/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.6.0
    19  
    20  ### Default `advertise` address changes
    21  
    22  When no `advertise` address was specified and Nomad's `bind_addr` was loopback
    23  or `0.0.0.0`, Nomad attempted to resolve the local hostname to use as an
    24  advertise address.
    25  
    26  Many hosts cannot properly resolve their hostname, so Nomad 0.6 defaults
    27  `advertise` to the first private IP on the host (e.g. `10.1.2.3`).
    28  
    29  If you manually configure `advertise` addresses no changes are necessary.
    30  
    31  ## Nomad Clients
    32  
    33  The change to the default, advertised IP also effect clients that do not specify
    34  which network_interface to use. If you have several routable IPs, it is advised
    35  to configure the client's [network
    36  interface](https://www.nomadproject.io/docs/agent/configuration/client.html#network_interface)
    37  such that tasks bind to the correct address.
    38  
    39  ## Nomad 0.5.5
    40  
    41  ### Docker `load` changes
    42  
    43  Nomad 0.5.5 has a backward incompatible change in the `docker` driver's
    44  configuration. Prior to 0.5.5 the `load` configuration option accepted a list
    45  images to load, in 0.5.5 it has been changed to a single string. No
    46  functionality was changed. Even if more than one item was specified prior to
    47  0.5.5 only the first item was used.
    48  
    49  To do a zero-downtime deploy with jobs that use the `load` option:
    50  
    51  * Upgrade servers to version 0.5.5 or later.
    52  
    53  * Deploy new client nodes on the same version as the servers.
    54  
    55  * Resubmit jobs with the `load` option fixed and a constraint to only run on
    56    version 0.5.5 or later:
    57  
    58  ```hcl
    59      constraint {
    60        attribute = "${attr.nomad.version}"
    61        operator  = "version"
    62        value     = ">= 0.5.5"
    63      }
    64  ```
    65  
    66  * Drain and shutdown old client nodes.
    67  
    68  ### Validation changes
    69  
    70  Due to internal job serialization and validation changes you may run into
    71  issues using 0.5.5 command line tools such as `nomad run` and `nomad validate`
    72  with 0.5.4 or earlier agents.
    73  
    74  It is recommended you upgrade agents before or alongside your command line
    75  tools.
    76  
    77  ## Nomad 0.4.0
    78  
    79  Nomad 0.4.0 has backward incompatible changes in the logic for Consul
    80  deregistration.  When a Task which was started by Nomad v0.3.x is uncleanly shut
    81  down, the Nomad 0.4 Client will no longer clean up any stale services.  If an
    82  in-place upgrade of the Nomad client to 0.4 prevents the Task from gracefully
    83  shutting down and deregistering its Consul-registered services, the Nomad Client
    84  will not clean up the remaining Consul services registered with the 0.3
    85  Executor.
    86  
    87  We recommend draining a node before upgrading to 0.4.0 and then re-enabling the
    88  node once the upgrade is complete.
    89  
    90  
    91  ## Nomad 0.3.1
    92  
    93  Nomad 0.3.1 removes artifact downloading from driver configurations and places them as
    94  a first class element of the task. As such, jobs will have to be rewritten in
    95  the proper format and resubmitted to Nomad. Nomad clients will properly
    96  re-attach to existing tasks but job definitions must be updated before they can
    97  be dispatched to clients running 0.3.1.
    98  
    99  ## Nomad 0.3.0
   100  
   101  Nomad 0.3.0 has made several substantial changes to job files included a new
   102  `log` block and variable interpretation syntax (`${var}`), a modified `restart`
   103  policy syntax, and minimum resources for tasks as well as validation. These
   104  changes require a slight change to the default upgrade flow.
   105  
   106  After upgrading the version of the servers, all previously submitted jobs must
   107  be resubmitted with the updated job syntax using a Nomad 0.3.0 binary.
   108  
   109  * All instances of `$var` must be converted to the new syntax of `${var}`
   110  
   111  * All tasks must provide their required resources for CPU, memory and disk as
   112    well as required network usage if ports are required by the task.
   113  
   114  * Restart policies must be updated to indicate whether it is desired for the
   115    task to restart on failure or to fail using `mode = "delay"` or `mode =
   116    "fail"` respectively.
   117  
   118  * Service names that include periods will fail validation. To fix, remove any
   119    periods from the service name before running the job.
   120  
   121  After updating the Servers and job files, Nomad Clients can be upgraded by first
   122  draining the node so no tasks are running on it. This can be verified by running
   123  `nomad node-status <node-id>` and verify there are no tasks in the `running`
   124  state. Once that is done the client can be killed, the `data_dir` should be
   125  deleted and then Nomad 0.3.0 can be launched.