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.