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