499 lines
24 KiB
Markdown
499 lines
24 KiB
Markdown
---
|
||
title: Clustering Guide
|
||
---
|
||
|
||
## Overview
|
||
|
||
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.
|
||
|
||
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].
|
||
|
||
This guide will cover the following mechanisms for bootstrapping an etcd cluster:
|
||
|
||
* [Static](#static)
|
||
* [etcd Discovery](#etcd-discovery)
|
||
* [DNS Discovery](#dns-discovery)
|
||
|
||
Each of the bootstrapping mechanisms will be used to create a three machine etcd cluster with the following details:
|
||
|
||
|Name|Address|Hostname|
|
||
|------|---------|------------------|
|
||
|infra0|10.0.1.10|infra0.example.com|
|
||
|infra1|10.0.1.11|infra1.example.com|
|
||
|infra2|10.0.1.12|infra2.example.com|
|
||
|
||
## Static
|
||
|
||
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:
|
||
|
||
```
|
||
ETCD_INITIAL_CLUSTER="infra0=http://10.0.1.10:2380,infra1=http://10.0.1.11:2380,infra2=http://10.0.1.12:2380"
|
||
ETCD_INITIAL_CLUSTER_STATE=new
|
||
```
|
||
|
||
```
|
||
--initial-cluster infra0=http://10.0.1.10:2380,infra1=http://10.0.1.11:2380,infra2=http://10.0.1.12:2380 \
|
||
--initial-cluster-state new
|
||
```
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
On each machine, start etcd with these flags:
|
||
|
||
```
|
||
$ etcd --name infra0 --initial-advertise-peer-urls http://10.0.1.10:2380 \
|
||
--listen-peer-urls http://10.0.1.10:2380 \
|
||
--listen-client-urls http://10.0.1.10:2379,http://127.0.0.1:2379 \
|
||
--advertise-client-urls http://10.0.1.10:2379 \
|
||
--initial-cluster-token etcd-cluster-1 \
|
||
--initial-cluster infra0=http://10.0.1.10:2380,infra1=http://10.0.1.11:2380,infra2=http://10.0.1.12:2380 \
|
||
--initial-cluster-state new
|
||
```
|
||
```
|
||
$ etcd --name infra1 --initial-advertise-peer-urls http://10.0.1.11:2380 \
|
||
--listen-peer-urls http://10.0.1.11:2380 \
|
||
--listen-client-urls http://10.0.1.11:2379,http://127.0.0.1:2379 \
|
||
--advertise-client-urls http://10.0.1.11:2379 \
|
||
--initial-cluster-token etcd-cluster-1 \
|
||
--initial-cluster infra0=http://10.0.1.10:2380,infra1=http://10.0.1.11:2380,infra2=http://10.0.1.12:2380 \
|
||
--initial-cluster-state new
|
||
```
|
||
```
|
||
$ etcd --name infra2 --initial-advertise-peer-urls http://10.0.1.12:2380 \
|
||
--listen-peer-urls http://10.0.1.12:2380 \
|
||
--listen-client-urls http://10.0.1.12:2379,http://127.0.0.1:2379 \
|
||
--advertise-client-urls http://10.0.1.12:2379 \
|
||
--initial-cluster-token etcd-cluster-1 \
|
||
--initial-cluster infra0=http://10.0.1.10:2380,infra1=http://10.0.1.11:2380,infra2=http://10.0.1.12:2380 \
|
||
--initial-cluster-state new
|
||
```
|
||
|
||
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.
|
||
|
||
### TLS
|
||
|
||
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].
|
||
|
||
#### Self-signed certificates
|
||
|
||
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.
|
||
|
||
On each machine, etcd would be started with these flags:
|
||
|
||
```
|
||
$ etcd --name infra0 --initial-advertise-peer-urls https://10.0.1.10:2380 \
|
||
--listen-peer-urls https://10.0.1.10:2380 \
|
||
--listen-client-urls https://10.0.1.10:2379,https://127.0.0.1:2379 \
|
||
--advertise-client-urls https://10.0.1.10:2379 \
|
||
--initial-cluster-token etcd-cluster-1 \
|
||
--initial-cluster infra0=https://10.0.1.10:2380,infra1=https://10.0.1.11:2380,infra2=https://10.0.1.12:2380 \
|
||
--initial-cluster-state new \
|
||
--client-cert-auth --trusted-ca-file=/path/to/ca-client.crt \
|
||
--cert-file=/path/to/infra0-client.crt --key-file=/path/to/infra0-client.key \
|
||
--peer-client-cert-auth --peer-trusted-ca-file=ca-peer.crt \
|
||
--peer-cert-file=/path/to/infra0-peer.crt --peer-key-file=/path/to/infra0-peer.key
|
||
```
|
||
```
|
||
$ etcd --name infra1 --initial-advertise-peer-urls https://10.0.1.11:2380 \
|
||
--listen-peer-urls https://10.0.1.11:2380 \
|
||
--listen-client-urls https://10.0.1.11:2379,https://127.0.0.1:2379 \
|
||
--advertise-client-urls https://10.0.1.11:2379 \
|
||
--initial-cluster-token etcd-cluster-1 \
|
||
--initial-cluster infra0=https://10.0.1.10:2380,infra1=https://10.0.1.11:2380,infra2=https://10.0.1.12:2380 \
|
||
--initial-cluster-state new \
|
||
--client-cert-auth --trusted-ca-file=/path/to/ca-client.crt \
|
||
--cert-file=/path/to/infra1-client.crt --key-file=/path/to/infra1-client.key \
|
||
--peer-client-cert-auth --peer-trusted-ca-file=ca-peer.crt \
|
||
--peer-cert-file=/path/to/infra1-peer.crt --peer-key-file=/path/to/infra1-peer.key
|
||
```
|
||
```
|
||
$ etcd --name infra2 --initial-advertise-peer-urls https://10.0.1.12:2380 \
|
||
--listen-peer-urls https://10.0.1.12:2380 \
|
||
--listen-client-urls https://10.0.1.12:2379,https://127.0.0.1:2379 \
|
||
--advertise-client-urls https://10.0.1.12:2379 \
|
||
--initial-cluster-token etcd-cluster-1 \
|
||
--initial-cluster infra0=https://10.0.1.10:2380,infra1=https://10.0.1.11:2380,infra2=https://10.0.1.12:2380 \
|
||
--initial-cluster-state new \
|
||
--client-cert-auth --trusted-ca-file=/path/to/ca-client.crt \
|
||
--cert-file=/path/to/infra2-client.crt --key-file=/path/to/infra2-client.key \
|
||
--peer-client-cert-auth --peer-trusted-ca-file=ca-peer.crt \
|
||
--peer-cert-file=/path/to/infra2-peer.crt --peer-key-file=/path/to/infra2-peer.key
|
||
```
|
||
|
||
#### Automatic certificates
|
||
|
||
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.
|
||
|
||
On each machine, etcd would be started with these flags:
|
||
|
||
```
|
||
$ etcd --name infra0 --initial-advertise-peer-urls https://10.0.1.10:2380 \
|
||
--listen-peer-urls https://10.0.1.10:2380 \
|
||
--listen-client-urls https://10.0.1.10:2379,https://127.0.0.1:2379 \
|
||
--advertise-client-urls https://10.0.1.10:2379 \
|
||
--initial-cluster-token etcd-cluster-1 \
|
||
--initial-cluster infra0=https://10.0.1.10:2380,infra1=https://10.0.1.11:2380,infra2=https://10.0.1.12:2380 \
|
||
--initial-cluster-state new \
|
||
--auto-tls \
|
||
--peer-auto-tls
|
||
```
|
||
```
|
||
$ etcd --name infra1 --initial-advertise-peer-urls https://10.0.1.11:2380 \
|
||
--listen-peer-urls https://10.0.1.11:2380 \
|
||
--listen-client-urls https://10.0.1.11:2379,https://127.0.0.1:2379 \
|
||
--advertise-client-urls https://10.0.1.11:2379 \
|
||
--initial-cluster-token etcd-cluster-1 \
|
||
--initial-cluster infra0=https://10.0.1.10:2380,infra1=https://10.0.1.11:2380,infra2=https://10.0.1.12:2380 \
|
||
--initial-cluster-state new \
|
||
--auto-tls \
|
||
--peer-auto-tls
|
||
```
|
||
```
|
||
$ etcd --name infra2 --initial-advertise-peer-urls https://10.0.1.12:2380 \
|
||
--listen-peer-urls https://10.0.1.12:2380 \
|
||
--listen-client-urls https://10.0.1.12:2379,https://127.0.0.1:2379 \
|
||
--advertise-client-urls https://10.0.1.12:2379 \
|
||
--initial-cluster-token etcd-cluster-1 \
|
||
--initial-cluster infra0=https://10.0.1.10:2380,infra1=https://10.0.1.11:2380,infra2=https://10.0.1.12:2380 \
|
||
--initial-cluster-state new \
|
||
--auto-tls \
|
||
--peer-auto-tls
|
||
```
|
||
|
||
### Error cases
|
||
|
||
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.
|
||
|
||
```
|
||
$ etcd --name infra1 --initial-advertise-peer-urls http://10.0.1.11:2380 \
|
||
--listen-peer-urls https://10.0.1.11:2380 \
|
||
--listen-client-urls http://10.0.1.11:2379,http://127.0.0.1:2379 \
|
||
--advertise-client-urls http://10.0.1.11:2379 \
|
||
--initial-cluster infra0=http://10.0.1.10:2380 \
|
||
--initial-cluster-state new
|
||
etcd: infra1 not listed in the initial cluster config
|
||
exit 1
|
||
```
|
||
|
||
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.
|
||
|
||
```
|
||
$ etcd --name infra0 --initial-advertise-peer-urls http://127.0.0.1:2380 \
|
||
--listen-peer-urls http://10.0.1.10:2380 \
|
||
--listen-client-urls http://10.0.1.10:2379,http://127.0.0.1:2379 \
|
||
--advertise-client-urls http://10.0.1.10:2379 \
|
||
--initial-cluster infra0=http://10.0.1.10:2380,infra1=http://10.0.1.11:2380,infra2=http://10.0.1.12:2380 \
|
||
--initial-cluster-state=new
|
||
etcd: error setting up initial cluster: infra0 has different advertised URLs in the cluster and advertised peer URLs list
|
||
exit 1
|
||
```
|
||
|
||
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.
|
||
|
||
```
|
||
$ etcd --name infra3 --initial-advertise-peer-urls http://10.0.1.13:2380 \
|
||
--listen-peer-urls http://10.0.1.13:2380 \
|
||
--listen-client-urls http://10.0.1.13:2379,http://127.0.0.1:2379 \
|
||
--advertise-client-urls http://10.0.1.13:2379 \
|
||
--initial-cluster infra0=http://10.0.1.10:2380,infra1=http://10.0.1.11:2380,infra3=http://10.0.1.13:2380 \
|
||
--initial-cluster-state=new
|
||
etcd: conflicting cluster ID to the target cluster (c6ab534d07e8fcc4 != bc25ea2a74fb18b0). Exiting.
|
||
exit 1
|
||
```
|
||
|
||
## Discovery
|
||
|
||
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".
|
||
|
||
There two methods that can be used for discovery:
|
||
|
||
* etcd discovery service
|
||
* DNS SRV records
|
||
|
||
### etcd discovery
|
||
|
||
To better understand the design of the discovery service protocol, we suggest reading the discovery service protocol [documentation][discovery-proto].
|
||
|
||
#### Lifetime of a discovery URL
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
#### Custom etcd discovery service
|
||
|
||
Discovery uses an existing cluster to bootstrap itself. If using a private etcd cluster, create a URL like so:
|
||
|
||
```
|
||
$ curl -X PUT https://myetcd.local/v2/keys/discovery/6c007a14875d53d9bf0ef5a6fc0257c817f0fb83/_config/size -d value=3
|
||
```
|
||
|
||
By setting the size key to the URL, a discovery URL is created with an expected cluster size of 3.
|
||
|
||
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.
|
||
|
||
**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.**
|
||
|
||
Now we start etcd with those relevant flags for each member:
|
||
|
||
```
|
||
$ etcd --name infra0 --initial-advertise-peer-urls http://10.0.1.10:2380 \
|
||
--listen-peer-urls http://10.0.1.10:2380 \
|
||
--listen-client-urls http://10.0.1.10:2379,http://127.0.0.1:2379 \
|
||
--advertise-client-urls http://10.0.1.10:2379 \
|
||
--discovery https://myetcd.local/v2/keys/discovery/6c007a14875d53d9bf0ef5a6fc0257c817f0fb83
|
||
```
|
||
```
|
||
$ etcd --name infra1 --initial-advertise-peer-urls http://10.0.1.11:2380 \
|
||
--listen-peer-urls http://10.0.1.11:2380 \
|
||
--listen-client-urls http://10.0.1.11:2379,http://127.0.0.1:2379 \
|
||
--advertise-client-urls http://10.0.1.11:2379 \
|
||
--discovery https://myetcd.local/v2/keys/discovery/6c007a14875d53d9bf0ef5a6fc0257c817f0fb83
|
||
```
|
||
```
|
||
$ etcd --name infra2 --initial-advertise-peer-urls http://10.0.1.12:2380 \
|
||
--listen-peer-urls http://10.0.1.12:2380 \
|
||
--listen-client-urls http://10.0.1.12:2379,http://127.0.0.1:2379 \
|
||
--advertise-client-urls http://10.0.1.12:2379 \
|
||
--discovery https://myetcd.local/v2/keys/discovery/6c007a14875d53d9bf0ef5a6fc0257c817f0fb83
|
||
```
|
||
|
||
This will cause each member to register itself with the custom etcd discovery service and begin the cluster once all machines have been registered.
|
||
|
||
#### Public etcd discovery service
|
||
|
||
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:
|
||
|
||
```
|
||
$ curl https://discovery.etcd.io/new?size=3
|
||
https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de
|
||
```
|
||
|
||
This will create the cluster with an initial size of 3 members. If no size is specified, a default of 3 is used.
|
||
|
||
```
|
||
ETCD_DISCOVERY=https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de
|
||
```
|
||
|
||
```
|
||
--discovery https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de
|
||
```
|
||
|
||
**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.**
|
||
|
||
Now we start etcd with those relevant flags for each member:
|
||
|
||
```
|
||
$ etcd --name infra0 --initial-advertise-peer-urls http://10.0.1.10:2380 \
|
||
--listen-peer-urls http://10.0.1.10:2380 \
|
||
--listen-client-urls http://10.0.1.10:2379,http://127.0.0.1:2379 \
|
||
--advertise-client-urls http://10.0.1.10:2379 \
|
||
--discovery https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de
|
||
```
|
||
```
|
||
$ etcd --name infra1 --initial-advertise-peer-urls http://10.0.1.11:2380 \
|
||
--listen-peer-urls http://10.0.1.11:2380 \
|
||
--listen-client-urls http://10.0.1.11:2379,http://127.0.0.1:2379 \
|
||
--advertise-client-urls http://10.0.1.11:2379 \
|
||
--discovery https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de
|
||
```
|
||
```
|
||
$ etcd --name infra2 --initial-advertise-peer-urls http://10.0.1.12:2380 \
|
||
--listen-peer-urls http://10.0.1.12:2380 \
|
||
--listen-client-urls http://10.0.1.12:2379,http://127.0.0.1:2379 \
|
||
--advertise-client-urls http://10.0.1.12:2379 \
|
||
--discovery https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de
|
||
```
|
||
|
||
This will cause each member to register itself with the discovery service and begin the cluster once all members have been registered.
|
||
|
||
Use the environment variable `ETCD_DISCOVERY_PROXY` to cause etcd to use an HTTP proxy to connect to the discovery service.
|
||
|
||
#### Error and warning cases
|
||
|
||
##### Discovery server errors
|
||
|
||
|
||
```
|
||
$ etcd --name infra0 --initial-advertise-peer-urls http://10.0.1.10:2380 \
|
||
--listen-peer-urls http://10.0.1.10:2380 \
|
||
--listen-client-urls http://10.0.1.10:2379,http://127.0.0.1:2379 \
|
||
--advertise-client-urls http://10.0.1.10:2379 \
|
||
--discovery https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de
|
||
etcd: error: the cluster doesn’t have a size configuration value in https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de/_config
|
||
exit 1
|
||
```
|
||
|
||
##### Warnings
|
||
|
||
This is a harmless warning indicating the discovery URL will be ignored on this machine.
|
||
|
||
```
|
||
$ etcd --name infra0 --initial-advertise-peer-urls http://10.0.1.10:2380 \
|
||
--listen-peer-urls http://10.0.1.10:2380 \
|
||
--listen-client-urls http://10.0.1.10:2379,http://127.0.0.1:2379 \
|
||
--advertise-client-urls http://10.0.1.10:2379 \
|
||
--discovery https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de
|
||
etcdserver: discovery token ignored since a cluster has already been initialized. Valid log found at /var/lib/etcd
|
||
```
|
||
|
||
### DNS discovery
|
||
|
||
DNS [SRV records][rfc-srv] can be used as a discovery mechanism.
|
||
The `--discovery-srv` flag can be used to set the DNS domain name where the discovery SRV records can be found.
|
||
Setting `--discovery-srv example.com` causes DNS SRV records to be looked up in the listed order:
|
||
|
||
* _etcd-server-ssl._tcp.example.com
|
||
* _etcd-server._tcp.example.com
|
||
|
||
If `_etcd-server-ssl._tcp.example.com` is found then etcd will attempt the bootstrapping process over TLS.
|
||
|
||
To help clients discover the etcd cluster, the following DNS SRV records are looked up in the listed order:
|
||
|
||
* _etcd-client._tcp.example.com
|
||
* _etcd-client-ssl._tcp.example.com
|
||
|
||
If `_etcd-client-ssl._tcp.example.com` is found, clients will attempt to communicate with the etcd cluster over SSL/TLS.
|
||
|
||
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:
|
||
|
||
```
|
||
[...] rejected connection from "10.0.1.11:53162" (error "remote error: tls: bad certificate", ServerName "example.com")
|
||
```
|
||
|
||
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.
|
||
|
||
The `-discovery-srv-name` flag additionally configures a suffix to the SRV name that is queried during discovery.
|
||
Use this flag to differentiate between multiple etcd clusters under the same domain.
|
||
For example, if `discovery-srv=example.com` and `-discovery-srv-name=foo` are set, the following DNS SRV queries are made:
|
||
|
||
* _etcd-server-ssl-foo._tcp.example.com
|
||
* _etcd-server-foo._tcp.example.com
|
||
|
||
#### Create DNS SRV records
|
||
|
||
```
|
||
$ dig +noall +answer SRV _etcd-server._tcp.example.com
|
||
_etcd-server._tcp.example.com. 300 IN SRV 0 0 2380 infra0.example.com.
|
||
_etcd-server._tcp.example.com. 300 IN SRV 0 0 2380 infra1.example.com.
|
||
_etcd-server._tcp.example.com. 300 IN SRV 0 0 2380 infra2.example.com.
|
||
```
|
||
|
||
```
|
||
$ dig +noall +answer SRV _etcd-client._tcp.example.com
|
||
_etcd-client._tcp.example.com. 300 IN SRV 0 0 2379 infra0.example.com.
|
||
_etcd-client._tcp.example.com. 300 IN SRV 0 0 2379 infra1.example.com.
|
||
_etcd-client._tcp.example.com. 300 IN SRV 0 0 2379 infra2.example.com.
|
||
```
|
||
|
||
```
|
||
$ dig +noall +answer infra0.example.com infra1.example.com infra2.example.com
|
||
infra0.example.com. 300 IN A 10.0.1.10
|
||
infra1.example.com. 300 IN A 10.0.1.11
|
||
infra2.example.com. 300 IN A 10.0.1.12
|
||
```
|
||
|
||
#### Bootstrap the etcd cluster using DNS
|
||
|
||
etcd cluster members can advertise domain names or IP address, the bootstrap process will resolve DNS A records.
|
||
Since 3.2 (3.1 prints warnings) `--listen-peer-urls` and `--listen-client-urls` will reject domain name for the network interface binding.
|
||
|
||
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.
|
||
|
||
```
|
||
$ etcd --name infra0 \
|
||
--discovery-srv example.com \
|
||
--initial-advertise-peer-urls http://infra0.example.com:2380 \
|
||
--initial-cluster-token etcd-cluster-1 \
|
||
--initial-cluster-state new \
|
||
--advertise-client-urls http://infra0.example.com:2379 \
|
||
--listen-client-urls http://0.0.0.0:2379 \
|
||
--listen-peer-urls http://0.0.0.0:2380
|
||
```
|
||
|
||
```
|
||
$ etcd --name infra1 \
|
||
--discovery-srv example.com \
|
||
--initial-advertise-peer-urls http://infra1.example.com:2380 \
|
||
--initial-cluster-token etcd-cluster-1 \
|
||
--initial-cluster-state new \
|
||
--advertise-client-urls http://infra1.example.com:2379 \
|
||
--listen-client-urls http://0.0.0.0:2379 \
|
||
--listen-peer-urls http://0.0.0.0:2380
|
||
```
|
||
|
||
```
|
||
$ etcd --name infra2 \
|
||
--discovery-srv example.com \
|
||
--initial-advertise-peer-urls http://infra2.example.com:2380 \
|
||
--initial-cluster-token etcd-cluster-1 \
|
||
--initial-cluster-state new \
|
||
--advertise-client-urls http://infra2.example.com:2379 \
|
||
--listen-client-urls http://0.0.0.0:2379 \
|
||
--listen-peer-urls http://0.0.0.0:2380
|
||
```
|
||
|
||
The cluster can also bootstrap using IP addresses instead of domain names:
|
||
|
||
```
|
||
$ etcd --name infra0 \
|
||
--discovery-srv example.com \
|
||
--initial-advertise-peer-urls http://10.0.1.10:2380 \
|
||
--initial-cluster-token etcd-cluster-1 \
|
||
--initial-cluster-state new \
|
||
--advertise-client-urls http://10.0.1.10:2379 \
|
||
--listen-client-urls http://10.0.1.10:2379 \
|
||
--listen-peer-urls http://10.0.1.10:2380
|
||
```
|
||
|
||
```
|
||
$ etcd --name infra1 \
|
||
--discovery-srv example.com \
|
||
--initial-advertise-peer-urls http://10.0.1.11:2380 \
|
||
--initial-cluster-token etcd-cluster-1 \
|
||
--initial-cluster-state new \
|
||
--advertise-client-urls http://10.0.1.11:2379 \
|
||
--listen-client-urls http://10.0.1.11:2379 \
|
||
--listen-peer-urls http://10.0.1.11:2380
|
||
```
|
||
|
||
```
|
||
$ etcd --name infra2 \
|
||
--discovery-srv example.com \
|
||
--initial-advertise-peer-urls http://10.0.1.12:2380 \
|
||
--initial-cluster-token etcd-cluster-1 \
|
||
--initial-cluster-state new \
|
||
--advertise-client-urls http://10.0.1.12:2379 \
|
||
--listen-client-urls http://10.0.1.12:2379 \
|
||
--listen-peer-urls http://10.0.1.12:2380
|
||
```
|
||
|
||
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].
|
||
|
||
### Gateway
|
||
|
||
etcd gateway is a simple TCP proxy that forwards network data to the etcd cluster. Please read [gateway guide][gateway] for more information.
|
||
|
||
### Proxy
|
||
|
||
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.
|
||
|
||
To setup an etcd cluster with proxies of v2 API, please read the the [clustering doc in etcd 2.3 release][clustering_etcd2].
|
||
|
||
[conf-adv-client]: configuration.md#--advertise-client-urls
|
||
[conf-listen-client]: configuration.md#--listen-client-urls
|
||
[discovery-proto]: ../dev-internal/discovery_protocol.md
|
||
[rfc-srv]: http://www.ietf.org/rfc/rfc2052.txt
|
||
[runtime-conf]: runtime-configuration.md
|
||
[runtime-reconf-design]: runtime-reconf-design.md
|
||
[proxy]: https://github.com/coreos/etcd/blob/release-2.3/Documentation/proxy.md
|
||
[clustering_etcd2]: https://github.com/coreos/etcd/blob/release-2.3/Documentation/clustering.md
|
||
[security-guide]: security.md
|
||
[security-guide-dns-srv]: security.md#notes-for-dns-srv
|
||
[tls-setup]: ../../hack/tls-setup
|
||
[gateway]: gateway.md
|