github.com/ncodes/nomad@v0.5.7-0.20170403112158-97adf4a74fb3/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.5.5
    19  
    20  ### Docker `load` changes
    21  
    22  Nomad 0.5.5 has a backward incompatible change in the `docker` driver's
    23  configuration. Prior to 0.5.5 the `load` configuration option accepted a list
    24  images to load, in 0.5.5 it has been changed to a single string. No
    25  functionality was changed. Even if more than one item was specificed prior to
    26  0.5.5 only the first item was used.
    27  
    28  If you have jobs that use the `load` option first upgrade all nodes to 0.5.5,
    29  then resubmit those jobs with `load` as a single string.
    30  
    31  ### Validation changes
    32  
    33  Due to internal job serialization and validation changes you may run into
    34  issues using 0.5.5 command line tools such as `nomad run` and `nomad validate`
    35  with 0.5.4 or earlier agents.
    36  
    37  It is recommended you upgrade agents before or alongside your command line
    38  tools.
    39  
    40  ## Nomad 0.4.0
    41  
    42  Nomad 0.4.0 has backward incompatible changes in the logic for Consul
    43  deregistration.  When a Task which was started by Nomad 0.3.X is uncleanly shut
    44  down, the Nomad 0.4 Client will no longer clean up any stale services.  If an
    45  in-place upgrade of the Nomad client to 0.4 prevents the Task from gracefully
    46  shutting down and deregistering its Consul-registered services, the Nomad Client
    47  will not clean up the remaining Consul services registered with the 0.3
    48  Executor.
    49  
    50  We recommend draining a node before upgrading to 0.4.0 and then re-enabling the
    51  node once the upgrade is complete.
    52  
    53  
    54  ## Nomad 0.3.1
    55  
    56  Nomad 0.3.1 removes artifact downloading from driver configs and places them as
    57  a first class element of the task. As such, jobs will have to be rewritten in
    58  the proper format and resubmitted to Nomad. Nomad clients will properly
    59  re-attach to existing tasks but job definitions must be updated before they can
    60  be dispatched to clients running 0.3.1.
    61  
    62  ## Nomad 0.3.0
    63  
    64  Nomad 0.3.0 has made several substantial changes to job files included a new
    65  `log` block and variable interpretation syntax (`${var}`), a modified `restart`
    66  policy syntax, and minimum resources for tasks as well as validation. These
    67  changes require a slight change to the default upgrade flow.
    68  
    69  After upgrading the version of the servers, all previously submitted jobs must
    70  be resubmitted with the updated job syntax using a Nomad 0.3.0 binary.
    71  
    72  * All instances of `$var` must be converted to the new syntax of `${var}`
    73  
    74  * All tasks must provide their required resources for CPU, memory and disk as
    75    well as required network usage if ports are required by the task.
    76  
    77  * Restart policies must be updated to indicate whether it is desired for the
    78    task to restart on failure or to fail using `mode = "delay"` or `mode =
    79    "fail"` respectively.
    80  
    81  * Service names that include periods will fail validation. To fix, remove any
    82    periods from the service name before running the job.
    83  
    84  After updating the Servers and job files, Nomad Clients can be upgraded by first
    85  draining the node so no tasks are running on it. This can be verified by running
    86  `nomad node-status <node-id>` and verify there are no tasks in the `running`
    87  state. Once that is done the client can be killed, the `data_dir` should be
    88  deleted and then Nomad 0.3.0 can be launched.