go.etcd.io/etcd@v3.3.27+incompatible/Documentation/op-guide/clustering.md (about) 1 --- 2 title: Clustering Guide 3 --- 4 5 ## Overview 6 7 Starting an etcd cluster statically requires that each member knows another in the cluster. In a number of cases, the IPs of the cluster members may be unknown ahead of time. In these cases, the etcd cluster can be bootstrapped with the help of a discovery service. 8 9 Once an etcd cluster is up and running, adding or removing members is done via [runtime reconfiguration][runtime-conf]. To better understand the design behind runtime reconfiguration, we suggest reading [the runtime configuration design document][runtime-reconf-design]. 10 11 This guide will cover the following mechanisms for bootstrapping an etcd cluster: 12 13 * [Static](#static) 14 * [etcd Discovery](#etcd-discovery) 15 * [DNS Discovery](#dns-discovery) 16 17 Each of the bootstrapping mechanisms will be used to create a three machine etcd cluster with the following details: 18 19 |Name|Address|Hostname| 20 |------|---------|------------------| 21 |infra0|10.0.1.10|infra0.example.com| 22 |infra1|10.0.1.11|infra1.example.com| 23 |infra2|10.0.1.12|infra2.example.com| 24 25 ## Static 26 27 As we know the cluster members, their addresses and the size of the cluster before starting, we can use an offline bootstrap configuration by setting the `initial-cluster` flag. Each machine will get either the following environment variables or command line: 28 29 ``` 30 ETCD_INITIAL_CLUSTER="infra0=http://10.0.1.10:2380,infra1=http://10.0.1.11:2380,infra2=http://10.0.1.12:2380" 31 ETCD_INITIAL_CLUSTER_STATE=new 32 ``` 33 34 ``` 35 --initial-cluster infra0=http://10.0.1.10:2380,infra1=http://10.0.1.11:2380,infra2=http://10.0.1.12:2380 \ 36 --initial-cluster-state new 37 ``` 38 39 Note that the URLs specified in `initial-cluster` are the _advertised peer URLs_, i.e. they should match the value of `initial-advertise-peer-urls` on the respective nodes. 40 41 If spinning up multiple clusters (or creating and destroying a single cluster) with same configuration for testing purpose, it is highly recommended that each cluster is given a unique `initial-cluster-token`. By doing this, etcd can generate unique cluster IDs and member IDs for the clusters even if they otherwise have the exact same configuration. This can protect etcd from cross-cluster-interaction, which might corrupt the clusters. 42 43 etcd listens on [`listen-client-urls`][conf-listen-client] to accept client traffic. etcd member advertises the URLs specified in [`advertise-client-urls`][conf-adv-client] to other members, proxies, clients. Please make sure the `advertise-client-urls` are reachable from intended clients. A common mistake is setting `advertise-client-urls` to localhost or leave it as default if the remote clients should reach etcd. 44 45 On each machine, start etcd with these flags: 46 47 ``` 48 $ etcd --name infra0 --initial-advertise-peer-urls http://10.0.1.10:2380 \ 49 --listen-peer-urls http://10.0.1.10:2380 \ 50 --listen-client-urls http://10.0.1.10:2379,http://127.0.0.1:2379 \ 51 --advertise-client-urls http://10.0.1.10:2379 \ 52 --initial-cluster-token etcd-cluster-1 \ 53 --initial-cluster infra0=http://10.0.1.10:2380,infra1=http://10.0.1.11:2380,infra2=http://10.0.1.12:2380 \ 54 --initial-cluster-state new 55 ``` 56 ``` 57 $ etcd --name infra1 --initial-advertise-peer-urls http://10.0.1.11:2380 \ 58 --listen-peer-urls http://10.0.1.11:2380 \ 59 --listen-client-urls http://10.0.1.11:2379,http://127.0.0.1:2379 \ 60 --advertise-client-urls http://10.0.1.11:2379 \ 61 --initial-cluster-token etcd-cluster-1 \ 62 --initial-cluster infra0=http://10.0.1.10:2380,infra1=http://10.0.1.11:2380,infra2=http://10.0.1.12:2380 \ 63 --initial-cluster-state new 64 ``` 65 ``` 66 $ etcd --name infra2 --initial-advertise-peer-urls http://10.0.1.12:2380 \ 67 --listen-peer-urls http://10.0.1.12:2380 \ 68 --listen-client-urls http://10.0.1.12:2379,http://127.0.0.1:2379 \ 69 --advertise-client-urls http://10.0.1.12:2379 \ 70 --initial-cluster-token etcd-cluster-1 \ 71 --initial-cluster infra0=http://10.0.1.10:2380,infra1=http://10.0.1.11:2380,infra2=http://10.0.1.12:2380 \ 72 --initial-cluster-state new 73 ``` 74 75 The command line parameters starting with `--initial-cluster` will be ignored on subsequent runs of etcd. Feel free to remove the environment variables or command line flags after the initial bootstrap process. If the configuration needs changes later (for example, adding or removing members to/from the cluster), see the [runtime configuration][runtime-conf] guide. 76 77 ### TLS 78 79 etcd supports encrypted communication through the TLS protocol. TLS channels can be used for encrypted internal cluster communication between peers as well as encrypted client traffic. This section provides examples for setting up a cluster with peer and client TLS. Additional information detailing etcd's TLS support can be found in the [security guide][security-guide]. 80 81 #### Self-signed certificates 82 83 A cluster using self-signed certificates both encrypts traffic and authenticates its connections. To start a cluster with self-signed certificates, each cluster member should have a unique key pair (`member.crt`, `member.key`) signed by a shared cluster CA certificate (`ca.crt`) for both peer connections and client connections. Certificates may be generated by following the etcd [TLS setup][tls-setup] example. 84 85 On each machine, etcd would be started with these flags: 86 87 ``` 88 $ etcd --name infra0 --initial-advertise-peer-urls https://10.0.1.10:2380 \ 89 --listen-peer-urls https://10.0.1.10:2380 \ 90 --listen-client-urls https://10.0.1.10:2379,https://127.0.0.1:2379 \ 91 --advertise-client-urls https://10.0.1.10:2379 \ 92 --initial-cluster-token etcd-cluster-1 \ 93 --initial-cluster infra0=https://10.0.1.10:2380,infra1=https://10.0.1.11:2380,infra2=https://10.0.1.12:2380 \ 94 --initial-cluster-state new \ 95 --client-cert-auth --trusted-ca-file=/path/to/ca-client.crt \ 96 --cert-file=/path/to/infra0-client.crt --key-file=/path/to/infra0-client.key \ 97 --peer-client-cert-auth --peer-trusted-ca-file=ca-peer.crt \ 98 --peer-cert-file=/path/to/infra0-peer.crt --peer-key-file=/path/to/infra0-peer.key 99 ``` 100 ``` 101 $ etcd --name infra1 --initial-advertise-peer-urls https://10.0.1.11:2380 \ 102 --listen-peer-urls https://10.0.1.11:2380 \ 103 --listen-client-urls https://10.0.1.11:2379,https://127.0.0.1:2379 \ 104 --advertise-client-urls https://10.0.1.11:2379 \ 105 --initial-cluster-token etcd-cluster-1 \ 106 --initial-cluster infra0=https://10.0.1.10:2380,infra1=https://10.0.1.11:2380,infra2=https://10.0.1.12:2380 \ 107 --initial-cluster-state new \ 108 --client-cert-auth --trusted-ca-file=/path/to/ca-client.crt \ 109 --cert-file=/path/to/infra1-client.crt --key-file=/path/to/infra1-client.key \ 110 --peer-client-cert-auth --peer-trusted-ca-file=ca-peer.crt \ 111 --peer-cert-file=/path/to/infra1-peer.crt --peer-key-file=/path/to/infra1-peer.key 112 ``` 113 ``` 114 $ etcd --name infra2 --initial-advertise-peer-urls https://10.0.1.12:2380 \ 115 --listen-peer-urls https://10.0.1.12:2380 \ 116 --listen-client-urls https://10.0.1.12:2379,https://127.0.0.1:2379 \ 117 --advertise-client-urls https://10.0.1.12:2379 \ 118 --initial-cluster-token etcd-cluster-1 \ 119 --initial-cluster infra0=https://10.0.1.10:2380,infra1=https://10.0.1.11:2380,infra2=https://10.0.1.12:2380 \ 120 --initial-cluster-state new \ 121 --client-cert-auth --trusted-ca-file=/path/to/ca-client.crt \ 122 --cert-file=/path/to/infra2-client.crt --key-file=/path/to/infra2-client.key \ 123 --peer-client-cert-auth --peer-trusted-ca-file=ca-peer.crt \ 124 --peer-cert-file=/path/to/infra2-peer.crt --peer-key-file=/path/to/infra2-peer.key 125 ``` 126 127 #### Automatic certificates 128 129 If the cluster needs encrypted communication but does not require authenticated connections, etcd can be configured to automatically generate its keys. On initialization, each member creates its own set of keys based on its advertised IP addresses and hosts. 130 131 On each machine, etcd would be started with these flags: 132 133 ``` 134 $ etcd --name infra0 --initial-advertise-peer-urls https://10.0.1.10:2380 \ 135 --listen-peer-urls https://10.0.1.10:2380 \ 136 --listen-client-urls https://10.0.1.10:2379,https://127.0.0.1:2379 \ 137 --advertise-client-urls https://10.0.1.10:2379 \ 138 --initial-cluster-token etcd-cluster-1 \ 139 --initial-cluster infra0=https://10.0.1.10:2380,infra1=https://10.0.1.11:2380,infra2=https://10.0.1.12:2380 \ 140 --initial-cluster-state new \ 141 --auto-tls \ 142 --peer-auto-tls 143 ``` 144 ``` 145 $ etcd --name infra1 --initial-advertise-peer-urls https://10.0.1.11:2380 \ 146 --listen-peer-urls https://10.0.1.11:2380 \ 147 --listen-client-urls https://10.0.1.11:2379,https://127.0.0.1:2379 \ 148 --advertise-client-urls https://10.0.1.11:2379 \ 149 --initial-cluster-token etcd-cluster-1 \ 150 --initial-cluster infra0=https://10.0.1.10:2380,infra1=https://10.0.1.11:2380,infra2=https://10.0.1.12:2380 \ 151 --initial-cluster-state new \ 152 --auto-tls \ 153 --peer-auto-tls 154 ``` 155 ``` 156 $ etcd --name infra2 --initial-advertise-peer-urls https://10.0.1.12:2380 \ 157 --listen-peer-urls https://10.0.1.12:2380 \ 158 --listen-client-urls https://10.0.1.12:2379,https://127.0.0.1:2379 \ 159 --advertise-client-urls https://10.0.1.12:2379 \ 160 --initial-cluster-token etcd-cluster-1 \ 161 --initial-cluster infra0=https://10.0.1.10:2380,infra1=https://10.0.1.11:2380,infra2=https://10.0.1.12:2380 \ 162 --initial-cluster-state new \ 163 --auto-tls \ 164 --peer-auto-tls 165 ``` 166 167 ### Error cases 168 169 In the following example, we have not included our new host in the list of enumerated nodes. If this is a new cluster, the node _must_ be added to the list of initial cluster members. 170 171 ``` 172 $ etcd --name infra1 --initial-advertise-peer-urls http://10.0.1.11:2380 \ 173 --listen-peer-urls https://10.0.1.11:2380 \ 174 --listen-client-urls http://10.0.1.11:2379,http://127.0.0.1:2379 \ 175 --advertise-client-urls http://10.0.1.11:2379 \ 176 --initial-cluster infra0=http://10.0.1.10:2380 \ 177 --initial-cluster-state new 178 etcd: infra1 not listed in the initial cluster config 179 exit 1 180 ``` 181 182 In this example, we are attempting to map a node (infra0) on a different address (127.0.0.1:2380) than its enumerated address in the cluster list (10.0.1.10:2380). If this node is to listen on multiple addresses, all addresses _must_ be reflected in the "initial-cluster" configuration directive. 183 184 ``` 185 $ etcd --name infra0 --initial-advertise-peer-urls http://127.0.0.1:2380 \ 186 --listen-peer-urls http://10.0.1.10:2380 \ 187 --listen-client-urls http://10.0.1.10:2379,http://127.0.0.1:2379 \ 188 --advertise-client-urls http://10.0.1.10:2379 \ 189 --initial-cluster infra0=http://10.0.1.10:2380,infra1=http://10.0.1.11:2380,infra2=http://10.0.1.12:2380 \ 190 --initial-cluster-state=new 191 etcd: error setting up initial cluster: infra0 has different advertised URLs in the cluster and advertised peer URLs list 192 exit 1 193 ``` 194 195 If a peer is configured with a different set of configuration arguments and attempts to join this cluster, etcd will report a cluster ID mismatch will exit. 196 197 ``` 198 $ etcd --name infra3 --initial-advertise-peer-urls http://10.0.1.13:2380 \ 199 --listen-peer-urls http://10.0.1.13:2380 \ 200 --listen-client-urls http://10.0.1.13:2379,http://127.0.0.1:2379 \ 201 --advertise-client-urls http://10.0.1.13:2379 \ 202 --initial-cluster infra0=http://10.0.1.10:2380,infra1=http://10.0.1.11:2380,infra3=http://10.0.1.13:2380 \ 203 --initial-cluster-state=new 204 etcd: conflicting cluster ID to the target cluster (c6ab534d07e8fcc4 != bc25ea2a74fb18b0). Exiting. 205 exit 1 206 ``` 207 208 ## Discovery 209 210 In a number of cases, the IPs of the cluster peers may not be known ahead of time. This is common when utilizing cloud providers or when the network uses DHCP. In these cases, rather than specifying a static configuration, use an existing etcd cluster to bootstrap a new one. This process is called "discovery". 211 212 There two methods that can be used for discovery: 213 214 * etcd discovery service 215 * DNS SRV records 216 217 ### etcd discovery 218 219 To better understand the design of the discovery service protocol, we suggest reading the discovery service protocol [documentation][discovery-proto]. 220 221 #### Lifetime of a discovery URL 222 223 A discovery URL identifies a unique etcd cluster. Instead of reusing an existing discovery URL, each etcd instance shares a new discovery URL to bootstrap the new cluster. 224 225 Moreover, discovery URLs should ONLY be used for the initial bootstrapping of a cluster. To change cluster membership after the cluster is already running, see the [runtime reconfiguration][runtime-conf] guide. 226 227 #### Custom etcd discovery service 228 229 Discovery uses an existing cluster to bootstrap itself. If using a private etcd cluster, create a URL like so: 230 231 ``` 232 $ curl -X PUT https://myetcd.local/v2/keys/discovery/6c007a14875d53d9bf0ef5a6fc0257c817f0fb83/_config/size -d value=3 233 ``` 234 235 By setting the size key to the URL, a discovery URL is created with an expected cluster size of 3. 236 237 The URL to use in this case will be `https://myetcd.local/v2/keys/discovery/6c007a14875d53d9bf0ef5a6fc0257c817f0fb83` and the etcd members will use the `https://myetcd.local/v2/keys/discovery/6c007a14875d53d9bf0ef5a6fc0257c817f0fb83` directory for registration as they start. 238 239 **Each member must have a different name flag specified. `Hostname` or `machine-id` can be a good choice. Or discovery will fail due to duplicated name.** 240 241 Now we start etcd with those relevant flags for each member: 242 243 ``` 244 $ etcd --name infra0 --initial-advertise-peer-urls http://10.0.1.10:2380 \ 245 --listen-peer-urls http://10.0.1.10:2380 \ 246 --listen-client-urls http://10.0.1.10:2379,http://127.0.0.1:2379 \ 247 --advertise-client-urls http://10.0.1.10:2379 \ 248 --discovery https://myetcd.local/v2/keys/discovery/6c007a14875d53d9bf0ef5a6fc0257c817f0fb83 249 ``` 250 ``` 251 $ etcd --name infra1 --initial-advertise-peer-urls http://10.0.1.11:2380 \ 252 --listen-peer-urls http://10.0.1.11:2380 \ 253 --listen-client-urls http://10.0.1.11:2379,http://127.0.0.1:2379 \ 254 --advertise-client-urls http://10.0.1.11:2379 \ 255 --discovery https://myetcd.local/v2/keys/discovery/6c007a14875d53d9bf0ef5a6fc0257c817f0fb83 256 ``` 257 ``` 258 $ etcd --name infra2 --initial-advertise-peer-urls http://10.0.1.12:2380 \ 259 --listen-peer-urls http://10.0.1.12:2380 \ 260 --listen-client-urls http://10.0.1.12:2379,http://127.0.0.1:2379 \ 261 --advertise-client-urls http://10.0.1.12:2379 \ 262 --discovery https://myetcd.local/v2/keys/discovery/6c007a14875d53d9bf0ef5a6fc0257c817f0fb83 263 ``` 264 265 This will cause each member to register itself with the custom etcd discovery service and begin the cluster once all machines have been registered. 266 267 #### Public etcd discovery service 268 269 If no exiting cluster is available, use the public discovery service hosted at `discovery.etcd.io`. To create a private discovery URL using the "new" endpoint, use the command: 270 271 ``` 272 $ curl https://discovery.etcd.io/new?size=3 273 https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de 274 ``` 275 276 This will create the cluster with an initial size of 3 members. If no size is specified, a default of 3 is used. 277 278 ``` 279 ETCD_DISCOVERY=https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de 280 ``` 281 282 ``` 283 --discovery https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de 284 ``` 285 286 **Each member must have a different name flag specified or else discovery will fail due to duplicated names. `Hostname` or `machine-id` can be a good choice.** 287 288 Now we start etcd with those relevant flags for each member: 289 290 ``` 291 $ etcd --name infra0 --initial-advertise-peer-urls http://10.0.1.10:2380 \ 292 --listen-peer-urls http://10.0.1.10:2380 \ 293 --listen-client-urls http://10.0.1.10:2379,http://127.0.0.1:2379 \ 294 --advertise-client-urls http://10.0.1.10:2379 \ 295 --discovery https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de 296 ``` 297 ``` 298 $ etcd --name infra1 --initial-advertise-peer-urls http://10.0.1.11:2380 \ 299 --listen-peer-urls http://10.0.1.11:2380 \ 300 --listen-client-urls http://10.0.1.11:2379,http://127.0.0.1:2379 \ 301 --advertise-client-urls http://10.0.1.11:2379 \ 302 --discovery https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de 303 ``` 304 ``` 305 $ etcd --name infra2 --initial-advertise-peer-urls http://10.0.1.12:2380 \ 306 --listen-peer-urls http://10.0.1.12:2380 \ 307 --listen-client-urls http://10.0.1.12:2379,http://127.0.0.1:2379 \ 308 --advertise-client-urls http://10.0.1.12:2379 \ 309 --discovery https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de 310 ``` 311 312 This will cause each member to register itself with the discovery service and begin the cluster once all members have been registered. 313 314 Use the environment variable `ETCD_DISCOVERY_PROXY` to cause etcd to use an HTTP proxy to connect to the discovery service. 315 316 #### Error and warning cases 317 318 ##### Discovery server errors 319 320 321 ``` 322 $ etcd --name infra0 --initial-advertise-peer-urls http://10.0.1.10:2380 \ 323 --listen-peer-urls http://10.0.1.10:2380 \ 324 --listen-client-urls http://10.0.1.10:2379,http://127.0.0.1:2379 \ 325 --advertise-client-urls http://10.0.1.10:2379 \ 326 --discovery https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de 327 etcd: error: the cluster doesn’t have a size configuration value in https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de/_config 328 exit 1 329 ``` 330 331 ##### Warnings 332 333 This is a harmless warning indicating the discovery URL will be ignored on this machine. 334 335 ``` 336 $ etcd --name infra0 --initial-advertise-peer-urls http://10.0.1.10:2380 \ 337 --listen-peer-urls http://10.0.1.10:2380 \ 338 --listen-client-urls http://10.0.1.10:2379,http://127.0.0.1:2379 \ 339 --advertise-client-urls http://10.0.1.10:2379 \ 340 --discovery https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de 341 etcdserver: discovery token ignored since a cluster has already been initialized. Valid log found at /var/lib/etcd 342 ``` 343 344 ### DNS discovery 345 346 DNS [SRV records][rfc-srv] can be used as a discovery mechanism. 347 The `--discovery-srv` flag can be used to set the DNS domain name where the discovery SRV records can be found. 348 Setting `--discovery-srv example.com` causes DNS SRV records to be looked up in the listed order: 349 350 * _etcd-server-ssl._tcp.example.com 351 * _etcd-server._tcp.example.com 352 353 If `_etcd-server-ssl._tcp.example.com` is found then etcd will attempt the bootstrapping process over TLS. 354 355 To help clients discover the etcd cluster, the following DNS SRV records are looked up in the listed order: 356 357 * _etcd-client._tcp.example.com 358 * _etcd-client-ssl._tcp.example.com 359 360 If `_etcd-client-ssl._tcp.example.com` is found, clients will attempt to communicate with the etcd cluster over SSL/TLS. 361 362 If etcd is using TLS, the discovery SRV record (e.g. `example.com`) must be included in the SSL certificate DNS SAN along with the hostname, or clustering will fail with log messages like the following: 363 364 ``` 365 [...] rejected connection from "10.0.1.11:53162" (error "remote error: tls: bad certificate", ServerName "example.com") 366 ``` 367 368 If etcd is using TLS without a custom certificate authority, the discovery domain (e.g., example.com) must match the SRV record domain (e.g., infra1.example.com). This is to mitigate attacks that forge SRV records to point to a different domain; the domain would have a valid certificate under PKI but be controlled by an unknown third party. 369 370 The `-discovery-srv-name` flag additionally configures a suffix to the SRV name that is queried during discovery. 371 Use this flag to differentiate between multiple etcd clusters under the same domain. 372 For example, if `discovery-srv=example.com` and `-discovery-srv-name=foo` are set, the following DNS SRV queries are made: 373 374 * _etcd-server-ssl-foo._tcp.example.com 375 * _etcd-server-foo._tcp.example.com 376 377 #### Create DNS SRV records 378 379 ``` 380 $ dig +noall +answer SRV _etcd-server._tcp.example.com 381 _etcd-server._tcp.example.com. 300 IN SRV 0 0 2380 infra0.example.com. 382 _etcd-server._tcp.example.com. 300 IN SRV 0 0 2380 infra1.example.com. 383 _etcd-server._tcp.example.com. 300 IN SRV 0 0 2380 infra2.example.com. 384 ``` 385 386 ``` 387 $ dig +noall +answer SRV _etcd-client._tcp.example.com 388 _etcd-client._tcp.example.com. 300 IN SRV 0 0 2379 infra0.example.com. 389 _etcd-client._tcp.example.com. 300 IN SRV 0 0 2379 infra1.example.com. 390 _etcd-client._tcp.example.com. 300 IN SRV 0 0 2379 infra2.example.com. 391 ``` 392 393 ``` 394 $ dig +noall +answer infra0.example.com infra1.example.com infra2.example.com 395 infra0.example.com. 300 IN A 10.0.1.10 396 infra1.example.com. 300 IN A 10.0.1.11 397 infra2.example.com. 300 IN A 10.0.1.12 398 ``` 399 400 #### Bootstrap the etcd cluster using DNS 401 402 etcd cluster members can advertise domain names or IP address, the bootstrap process will resolve DNS A records. 403 Since 3.2 (3.1 prints warnings) `--listen-peer-urls` and `--listen-client-urls` will reject domain name for the network interface binding. 404 405 The resolved address in `--initial-advertise-peer-urls` *must match* one of the resolved addresses in the SRV targets. The etcd member reads the resolved address to find out if it belongs to the cluster defined in the SRV records. 406 407 ``` 408 $ etcd --name infra0 \ 409 --discovery-srv example.com \ 410 --initial-advertise-peer-urls http://infra0.example.com:2380 \ 411 --initial-cluster-token etcd-cluster-1 \ 412 --initial-cluster-state new \ 413 --advertise-client-urls http://infra0.example.com:2379 \ 414 --listen-client-urls http://0.0.0.0:2379 \ 415 --listen-peer-urls http://0.0.0.0:2380 416 ``` 417 418 ``` 419 $ etcd --name infra1 \ 420 --discovery-srv example.com \ 421 --initial-advertise-peer-urls http://infra1.example.com:2380 \ 422 --initial-cluster-token etcd-cluster-1 \ 423 --initial-cluster-state new \ 424 --advertise-client-urls http://infra1.example.com:2379 \ 425 --listen-client-urls http://0.0.0.0:2379 \ 426 --listen-peer-urls http://0.0.0.0:2380 427 ``` 428 429 ``` 430 $ etcd --name infra2 \ 431 --discovery-srv example.com \ 432 --initial-advertise-peer-urls http://infra2.example.com:2380 \ 433 --initial-cluster-token etcd-cluster-1 \ 434 --initial-cluster-state new \ 435 --advertise-client-urls http://infra2.example.com:2379 \ 436 --listen-client-urls http://0.0.0.0:2379 \ 437 --listen-peer-urls http://0.0.0.0:2380 438 ``` 439 440 The cluster can also bootstrap using IP addresses instead of domain names: 441 442 ``` 443 $ etcd --name infra0 \ 444 --discovery-srv example.com \ 445 --initial-advertise-peer-urls http://10.0.1.10:2380 \ 446 --initial-cluster-token etcd-cluster-1 \ 447 --initial-cluster-state new \ 448 --advertise-client-urls http://10.0.1.10:2379 \ 449 --listen-client-urls http://10.0.1.10:2379 \ 450 --listen-peer-urls http://10.0.1.10:2380 451 ``` 452 453 ``` 454 $ etcd --name infra1 \ 455 --discovery-srv example.com \ 456 --initial-advertise-peer-urls http://10.0.1.11:2380 \ 457 --initial-cluster-token etcd-cluster-1 \ 458 --initial-cluster-state new \ 459 --advertise-client-urls http://10.0.1.11:2379 \ 460 --listen-client-urls http://10.0.1.11:2379 \ 461 --listen-peer-urls http://10.0.1.11:2380 462 ``` 463 464 ``` 465 $ etcd --name infra2 \ 466 --discovery-srv example.com \ 467 --initial-advertise-peer-urls http://10.0.1.12:2380 \ 468 --initial-cluster-token etcd-cluster-1 \ 469 --initial-cluster-state new \ 470 --advertise-client-urls http://10.0.1.12:2379 \ 471 --listen-client-urls http://10.0.1.12:2379 \ 472 --listen-peer-urls http://10.0.1.12:2380 473 ``` 474 475 Since v3.1.0 (except v3.2.9), when `etcd --discovery-srv=example.com` is configured with TLS, server will only authenticate peers/clients when the provided certs have root domain `example.com` as an entry in Subject Alternative Name (SAN) field. See [Notes for DNS SRV][security-guide-dns-srv]. 476 477 ### Gateway 478 479 etcd gateway is a simple TCP proxy that forwards network data to the etcd cluster. Please read [gateway guide][gateway] for more information. 480 481 ### Proxy 482 483 When the `--proxy` flag is set, etcd runs in [proxy mode][proxy]. This proxy mode only supports the etcd v2 API; there are no plans to support the v3 API. Instead, for v3 API support, there will be a new proxy with enhanced features following the etcd 3.0 release. 484 485 To setup an etcd cluster with proxies of v2 API, please read the the [clustering doc in etcd 2.3 release][clustering_etcd2]. 486 487 [conf-adv-client]: configuration.md#--advertise-client-urls 488 [conf-listen-client]: configuration.md#--listen-client-urls 489 [discovery-proto]: ../dev-internal/discovery_protocol.md 490 [rfc-srv]: http://www.ietf.org/rfc/rfc2052.txt 491 [runtime-conf]: runtime-configuration.md 492 [runtime-reconf-design]: runtime-reconf-design.md 493 [proxy]: https://github.com/coreos/etcd/blob/release-2.3/Documentation/proxy.md 494 [clustering_etcd2]: https://github.com/coreos/etcd/blob/release-2.3/Documentation/clustering.md 495 [security-guide]: security.md 496 [security-guide-dns-srv]: security.md#notes-for-dns-srv 497 [tls-setup]: ../../hack/tls-setup 498 [gateway]: gateway.md