github.com/quite/nomad@v0.8.6/website/source/api/operator.html.md (about) 1 --- 2 layout: api 3 page_title: Operator - HTTP API 4 sidebar_current: api-operator 5 description: |- 6 The /operator endpoints provides cluster-level tools for Nomad operators, such 7 as interacting with the Raft subsystem. 8 --- 9 # /v1/operator 10 11 The `/operator` endpoint provides cluster-level tools for Nomad operators, such 12 as interacting with the Raft subsystem. 13 14 ~> Use this interface with extreme caution, as improper use could lead to a 15 Nomad outage and even loss of data. 16 17 See the [Outage Recovery](/guides/outage.html) guide for some examples of how 18 these capabilities are used. For a CLI to perform these operations manually, 19 please see the documentation for the 20 [`nomad operator`](/docs/commands/operator.html) command. 21 22 23 ## Read Raft Configuration 24 25 This endpoint queries the status of a client node registered with Nomad. 26 27 | Method | Path | Produces | 28 | ------ | --------------------------------- | -------------------------- | 29 | `GET` | `/v1/operator/raft/configuration` | `application/json` | 30 31 The table below shows this endpoint's support for 32 [blocking queries](/api/index.html#blocking-queries) and 33 [required ACLs](/api/index.html#acls). 34 35 | Blocking Queries | ACL Required | 36 | ---------------- | ------------ | 37 | `NO` | `management` | 38 39 ### Parameters 40 41 - `stale` - Specifies if the cluster should respond without an active leader. 42 This is specified as a querystring parameter. 43 44 ### Sample Request 45 46 ```text 47 $ curl \ 48 https://localhost:4646/v1/operator/raft/configuration 49 ``` 50 51 ### Sample Response 52 53 ```json 54 { 55 "Index": 1, 56 "Servers": [ 57 { 58 "Address": "127.0.0.1:4647", 59 "ID": "127.0.0.1:4647", 60 "Leader": true, 61 "Node": "bacon-mac.global", 62 "RaftProtocol": 2, 63 "Voter": true 64 } 65 ] 66 } 67 ``` 68 69 #### Field Reference 70 71 - `Index` `(int)` - The `Index` value is the Raft corresponding to this 72 configuration. The latest configuration may not yet be committed if changes 73 are in flight. 74 75 - `Servers` `(array: Server)` - The returned `Servers` array has information 76 about the servers in the Raft peer configuration. 77 78 - `ID` `(string)` - The ID of the server. This is the same as the `Address` 79 but may be upgraded to a GUID in a future version of Nomad. 80 81 - `Node` `(string)` - The node name of the server, as known to Nomad, or 82 `"(unknown)"` if the node is stale and not known. 83 84 - `Address` `(string)` - The `ip:port` for the server. 85 86 - `Leader` `(bool)` - is either "true" or "false" depending on the server's 87 role in the Raft configuration. 88 89 - `Voter` `(bool)` - is "true" or "false", indicating if the server has a vote 90 in the Raft configuration. Future versions of Nomad may add support for 91 non-voting servers. 92 93 ## Remove Raft Peer 94 95 This endpoint removes a Nomad server with given address from the Raft 96 configuration. The return code signifies success or failure. 97 98 | Method | Path | Produces | 99 | -------- | ---------------------------| -------------------------- | 100 | `DELETE` | `/v1/operator/raft/peer` | `application/json` | 101 102 The table below shows this endpoint's support for 103 [blocking queries](/api/index.html#blocking-queries) and 104 [required ACLs](/api/index.html#acls). 105 106 | Blocking Queries | ACL Required | 107 | ---------------- | ------------ | 108 | `NO` | `management` | 109 110 ### Parameters 111 112 - `address` `(string: <optional>)` - Specifies the server to remove as 113 `ip:port`. This cannot be provided along with the `id` parameter. 114 115 - `id` `(string: <optional>)` - Specifies the server to remove as 116 `id`. This cannot be provided along with the `address` parameter. 117 118 - `stale` - Specifies if the cluster should respond without an active leader. 119 This is specified as a querystring parameter. 120 121 ### Sample Request 122 123 ```text 124 $ curl \ 125 --request DELETE \ 126 https://localhost:4646/v1/operator/raft/peer?address=1.2.3.4 127 ``` 128 129 ## Read Autopilot Configuration 130 131 This endpoint retrieves its latest Autopilot configuration. 132 133 | Method | Path | Produces | 134 | ------ | ---------------------------- | -------------------------- | 135 | `GET` | `/operator/autopilot/configuration` | `application/json` | 136 137 The table below shows this endpoint's support for 138 [blocking queries](/api/index.html#blocking-queries), 139 [consistency modes](/api/index.html#consistency-modes), and 140 [required ACLs](/api/index.html#acls). 141 142 | Blocking Queries | Consistency Modes | ACL Required | 143 | ---------------- | ----------------- | --------------- | 144 | `NO` | `none` | `operator:read` | 145 146 ### Sample Request 147 148 ```text 149 $ curl \ 150 https://localhost:4646/operator/autopilot/configuration 151 ``` 152 153 ### Sample Response 154 155 ```json 156 { 157 "CleanupDeadServers": true, 158 "LastContactThreshold": "200ms", 159 "MaxTrailingLogs": 250, 160 "ServerStabilizationTime": "10s", 161 "EnableRedundancyZones": false, 162 "DisableUpgradeMigration": false, 163 "EnableCustomUpgrades": false, 164 "CreateIndex": 4, 165 "ModifyIndex": 4 166 } 167 ``` 168 169 For more information about the Autopilot configuration options, see the 170 [agent configuration section](/docs/agent/configuration/autopilot.html). 171 172 ## Update Autopilot Configuration 173 174 This endpoint updates the Autopilot configuration of the cluster. 175 176 | Method | Path | Produces | 177 | ------ | ---------------------------- | -------------------------- | 178 | `PUT` | `/operator/autopilot/configuration` | `application/json` | 179 180 The table below shows this endpoint's support for 181 [blocking queries](/api/index.html#blocking-queries), 182 [consistency modes](/api/index.html#consistency-modes), and 183 [required ACLs](/api/index.html#acls). 184 185 | Blocking Queries | Consistency Modes | ACL Required | 186 | ---------------- | ----------------- | ---------------- | 187 | `NO` | `none` | `operator:write` | 188 189 ### Parameters 190 191 - `cas` `(int: 0)` - Specifies to use a Check-And-Set operation. The update will 192 only happen if the given index matches the `ModifyIndex` of the configuration 193 at the time of writing. 194 195 ### Sample Payload 196 197 ```json 198 { 199 "CleanupDeadServers": true, 200 "LastContactThreshold": "200ms", 201 "MaxTrailingLogs": 250, 202 "ServerStabilizationTime": "10s", 203 "EnableRedundancyZones": false, 204 "DisableUpgradeMigration": false, 205 "EnableCustomUpgrades": false, 206 "CreateIndex": 4, 207 "ModifyIndex": 4 208 } 209 ``` 210 211 - `CleanupDeadServers` `(bool: true)` - Specifies automatic removal of dead 212 server nodes periodically and whenever a new server is added to the cluster. 213 214 - `LastContactThreshold` `(string: "200ms")` - Specifies the maximum amount of 215 time a server can go without contact from the leader before being considered 216 unhealthy. Must be a duration value such as `10s`. 217 218 - `MaxTrailingLogs` `(int: 250)` specifies the maximum number of log entries 219 that a server can trail the leader by before being considered unhealthy. 220 221 - `ServerStabilizationTime` `(string: "10s")` - Specifies the minimum amount of 222 time a server must be stable in the 'healthy' state before being added to the 223 cluster. Only takes effect if all servers are running Raft protocol version 3 224 or higher. Must be a duration value such as `30s`. 225 226 - `EnableRedundancyZones` `(bool: false)` - (Enterprise-only) Specifies whether 227 to enable redundancy zones. 228 229 - `DisableUpgradeMigration` `(bool: false)` - (Enterprise-only) Disables Autopilot's 230 upgrade migration strategy in Nomad Enterprise of waiting until enough 231 newer-versioned servers have been added to the cluster before promoting any of 232 them to voters. 233 234 - `EnableCustomUpgrades` `(bool: false)` - (Enterprise-only) Specifies whether to 235 enable using custom upgrade versions when performing migrations. 236 237 ## Read Health 238 239 This endpoint queries the health of the autopilot status. 240 241 | Method | Path | Produces | 242 | ------ | ---------------------------- | -------------------------- | 243 | `GET` | `/operator/autopilot/health` | `application/json` | 244 245 The table below shows this endpoint's support for 246 [blocking queries](/api/index.html#blocking-queries), 247 [consistency modes](/api/index.html#consistency-modes), and 248 [required ACLs](/api/index.html#acls). 249 250 | Blocking Queries | Consistency Modes | ACL Required | 251 | ---------------- | ----------------- | --------------- | 252 | `NO` | `none` | `operator:read` | 253 254 ### Sample Request 255 256 ```text 257 $ curl \ 258 https://localhost:4646/v1/operator/autopilot/health 259 ``` 260 261 ### Sample response 262 263 ```json 264 { 265 "Healthy": true, 266 "FailureTolerance": 0, 267 "Servers": [ 268 { 269 "ID": "e349749b-3303-3ddf-959c-b5885a0e1f6e", 270 "Name": "node1", 271 "Address": "127.0.0.1:8300", 272 "SerfStatus": "alive", 273 "Version": "0.8.0", 274 "Leader": true, 275 "LastContact": "0s", 276 "LastTerm": 2, 277 "LastIndex": 46, 278 "Healthy": true, 279 "Voter": true, 280 "StableSince": "2017-03-06T22:07:51Z" 281 }, 282 { 283 "ID": "e36ee410-cc3c-0a0c-c724-63817ab30303", 284 "Name": "node2", 285 "Address": "127.0.0.1:8205", 286 "SerfStatus": "alive", 287 "Version": "0.8.0", 288 "Leader": false, 289 "LastContact": "27.291304ms", 290 "LastTerm": 2, 291 "LastIndex": 46, 292 "Healthy": true, 293 "Voter": false, 294 "StableSince": "2017-03-06T22:18:26Z" 295 } 296 ] 297 } 298 ``` 299 300 - `Healthy` is whether all the servers are currently healthy. 301 302 - `FailureTolerance` is the number of redundant healthy servers that could be 303 fail without causing an outage (this would be 2 in a healthy cluster of 5 304 servers). 305 306 - `Servers` holds detailed health information on each server: 307 308 - `ID` is the Raft ID of the server. 309 310 - `Name` is the node name of the server. 311 312 - `Address` is the address of the server. 313 314 - `SerfStatus` is the SerfHealth check status for the server. 315 316 - `Version` is the Nomad version of the server. 317 318 - `Leader` is whether this server is currently the leader. 319 320 - `LastContact` is the time elapsed since this server's last contact with the leader. 321 322 - `LastTerm` is the server's last known Raft leader term. 323 324 - `LastIndex` is the index of the server's last committed Raft log entry. 325 326 - `Healthy` is whether the server is healthy according to the current Autopilot configuration. 327 328 - `Voter` is whether the server is a voting member of the Raft cluster. 329 330 - `StableSince` is the time this server has been in its current `Healthy` state. 331 332 The HTTP status code will indicate the health of the cluster. If `Healthy` is true, then a 333 status of 200 will be returned. If `Healthy` is false, then a status of 429 will be returned.