github.com/smintz/nomad@v0.8.3/website/source/docs/agent/configuration/server.html.md (about) 1 --- 2 layout: "docs" 3 page_title: "server Stanza - Agent Configuration" 4 sidebar_current: "docs-agent-configuration-server" 5 description: |- 6 The "server" stanza configures the Nomad agent to operate in server mode to 7 participate in scheduling decisions, register with service discovery, handle 8 join failures, and more. 9 --- 10 11 # `server` Stanza 12 13 <table class="table table-bordered table-striped"> 14 <tr> 15 <th width="120">Placement</th> 16 <td> 17 <code>**server**</code> 18 </td> 19 </tr> 20 </table> 21 22 23 The `server` stanza configures the Nomad agent to operate in server mode to 24 participate in scheduling decisions, register with service discovery, handle 25 join failures, and more. 26 27 ```hcl 28 server { 29 enabled = true 30 bootstrap_expect = 3 31 retry_join = ["1.2.3.4", "5.6.7.8"] 32 } 33 ``` 34 35 ## `server` Parameters 36 37 - `authoritative_region` `(string: "")` - Specifies the authoritative region, which 38 provides a single source of truth for global configurations such as ACL Policies and 39 global ACL tokens. Non-authoritative regions will replicate from the authoritative 40 to act as a mirror. By default, the local region is assumed to be authoritative. 41 42 - `bootstrap_expect` `(int: required)` - Specifies the number of server nodes to 43 wait for before bootstrapping. It is most common to use the odd-numbered 44 integers `3` or `5` for this value, depending on the cluster size. A value of 45 `1` does not provide any fault tolerance and is not recommended for production 46 use cases. 47 48 - `data_dir` `(string: "[data_dir]/server")` - Specifies the directory to use - 49 for server-specific data, including the replicated log. By default, this is - 50 the top-level [data_dir](/docs/agent/configuration/index.html#data_dir) 51 suffixed with "server", like `"/opt/nomad/server"`. This must be an absolute 52 path. 53 54 - `enabled` `(bool: false)` - Specifies if this agent should run in server mode. 55 All other server options depend on this value being set. 56 57 - `enabled_schedulers` `(array<string>: [all])` - Specifies which sub-schedulers 58 this server will handle. This can be used to restrict the evaluations that 59 worker threads will dequeue for processing. 60 61 - `encrypt` `(string: "")` - Specifies the secret key to use for encryption of 62 Nomad server's gossip network traffic. This key must be 16 bytes that are 63 base64-encoded. The provided key is automatically persisted to the data 64 directory and loaded automatically whenever the agent is restarted. This means 65 that to encrypt Nomad server's gossip protocol, this option only needs to be 66 provided once on each agent's initial startup sequence. If it is provided 67 after Nomad has been initialized with an encryption key, then the provided key 68 is ignored and a warning will be displayed. See the 69 [Nomad encryption documentation][encryption] for more details on this option 70 and its impact on the cluster. 71 72 - `node_gc_threshold` `(string: "24h")` - Specifies how long a node must be in a 73 terminal state before it is garbage collected and purged from the system. This 74 is specified using a label suffix like "30s" or "1h". 75 76 - `job_gc_threshold` `(string: "4h")` - Specifies the minimum time a job must be 77 in the terminal state before it is eligible for garbage collection. This is 78 specified using a label suffix like "30s" or "1h". 79 80 - `eval_gc_threshold` `(string: "1h")` - Specifies the minimum time an 81 evaluation must be in the terminal state before it is eligible for garbage 82 collection. This is specified using a label suffix like "30s" or "1h". 83 84 - `deployment_gc_threshold` `(string: "1h")` - Specifies the minimum time a 85 deployment must be in the terminal state before it is eligible for garbage 86 collection. This is specified using a label suffix like "30s" or "1h". 87 88 - `heartbeat_grace` `(string: "10s")` - Specifies the additional time given as a 89 grace period beyond the heartbeat TTL of nodes to account for network and 90 processing delays as well as clock skew. This is specified using a label 91 suffix like "30s" or "1h". 92 93 - `min_heartbeat_ttl` `(string: "10s")` - Specifies the minimum time between 94 node heartbeats. This is used as a floor to prevent excessive updates. This is 95 specified using a label suffix like "30s" or "1h". Lowering the minimum TTL is 96 a tradeoff as it lowers failure detection time of nodes at the tradeoff of 97 false positives and increased load on the leader. 98 99 - `max_heartbeats_per_second` `(float: 50.0)` - Specifies the maximum target 100 rate of heartbeats being processed per second. This allows the TTL to be 101 increased to meet the target rate. Increasing the maximum heartbeats per 102 second is a tradeoff as it lowers failure detection time of nodes at the 103 tradeoff of false positives and increased load on the leader. 104 105 - `non_voting_server` `(bool: false)` - (Enterprise-only) Specifies whether 106 this server will act as a non-voting member of the cluster to help provide 107 read scalability. 108 109 - `num_schedulers` `(int: [num-cores])` - Specifies the number of parallel 110 scheduler threads to run. This can be as many as one per core, or `0` to 111 disallow this server from making any scheduling decisions. This defaults to 112 the number of CPU cores. 113 114 - `protocol_version` `(int: 1)` - Specifies the Nomad protocol version to use 115 when communicating with other Nomad servers. This value is typically not 116 required as the agent internally knows the latest version, but may be useful 117 in some upgrade scenarios. 118 119 - `raft_protocol` `(int: 2)` - Specifies the Raft protocol version to use when 120 communicating with other Nomad servers. This affects available Autopilot 121 features and is typically not required as the agent internally knows the 122 latest version, but may be useful in some upgrade scenarios. 123 124 - `redundancy_zone` `(string: "")` - (Enterprise-only) Specifies the redundancy 125 zone that this server will be a part of for Autopilot management. For more 126 information, see the [Autopilot Guide](/guides/cluster/autopilot.html). 127 128 - `rejoin_after_leave` `(bool: false)` - Specifies if Nomad will ignore a 129 previous leave and attempt to rejoin the cluster when starting. By default, 130 Nomad treats leave as a permanent intent and does not attempt to join the 131 cluster again when starting. This flag allows the previous state to be used to 132 rejoin the cluster. 133 134 - `retry_join` `(array<string>: [])` - Specifies a list of server addresses to 135 retry joining if the first attempt fails. This is similar to 136 [`start_join`](#start_join), but only invokes if the initial join attempt 137 fails. The list of addresses will be tried in the order specified, until one 138 succeeds. After one succeeds, no further addresses will be contacted. This is 139 useful for cases where we know the address will become available eventually. 140 Use `retry_join` with an array as a replacement for `start_join`, **do not use 141 both options**. See the [server address format](#server-address-format) 142 section for more information on the format of the string. 143 144 - `retry_interval` `(string: "30s")` - Specifies the time to wait between retry 145 join attempts. 146 147 - `retry_max` `(int: 0)` - Specifies the maximum number of join attempts to be 148 made before exiting with a return code of 1. By default, this is set to 0 149 which is interpreted as infinite retries. 150 151 - `start_join` `(array<string>: [])` - Specifies a list of server addresses to 152 join on startup. If Nomad is unable to join with any of the specified 153 addresses, agent startup will fail. See the 154 [server address format](#server-address-format) section for more information 155 on the format of the string. 156 157 - `upgrade_version` `(string: "")` - A custom version of the format X.Y.Z to use 158 in place of the Nomad version when custom upgrades are enabled in Autopilot. 159 For more information, see the [Autopilot Guide](/guides/cluster/autopilot.html). 160 161 ### Server Address Format 162 163 This section describes the acceptable syntax and format for describing the 164 location of a Nomad server. There are many ways to reference a Nomad server, 165 including directly by IP address and resolving through DNS. 166 167 #### Directly via IP Address 168 169 It is possible to address another Nomad server using its IP address. This is 170 done in the `ip:port` format, such as: 171 172 ``` 173 1.2.3.4:5678 174 ``` 175 176 If the port option is omitted, it defaults to the Serf port, which is 4648 177 unless configured otherwise: 178 179 ``` 180 1.2.3.4 => 1.2.3.4:4648 181 ``` 182 183 #### Via Domains or DNS 184 185 It is possible to address another Nomad server using its DNS address. This is 186 done in the `address:port` format, such as: 187 188 ``` 189 nomad-01.company.local:5678 190 ``` 191 192 If the port option is omitted, it defaults to the Serf port, which is 4648 193 unless configured otherwise: 194 195 ``` 196 nomad-01.company.local => nomad-01.company.local:4648 197 ``` 198 199 ## `server` Examples 200 201 ### Common Setup 202 203 This example shows a common Nomad agent `server` configuration stanza. The two 204 IP addresses could also be DNS, and should point to the other Nomad servers in 205 the cluster 206 207 ```hcl 208 server { 209 enabled = true 210 bootstrap_expect = 3 211 retry_join = ["1.2.3.4", "5.6.7.8"] 212 } 213 ``` 214 215 ### Configuring Data Directory 216 217 This example shows configuring a custom data directory for the server data. 218 219 ```hcl 220 server { 221 data_dir = "/opt/nomad/server" 222 } 223 ``` 224 225 ### Automatic Bootstrapping 226 227 The Nomad servers can automatically bootstrap if Consul is configured. For a 228 more detailed explanation, please see the 229 [automatic Nomad bootstrapping documentation](/guides/cluster/automatic.html). 230 231 ### Restricting Schedulers 232 233 This example shows restricting the schedulers that are enabled as well as the 234 maximum number of cores to utilize when participating in scheduling decisions: 235 236 ```hcl 237 server { 238 enabled = true 239 enabled_schedulers = ["batch", "service"] 240 num_schedulers = 7 241 } 242 ``` 243 244 [encryption]: /docs/agent/encryption.html "Nomad Agent Encryption"