Live Reconfiguration

Debugging etcd

Migration

This is the documentation for etcd2 releases. Read etcd3 doc for etcd3 releases.

Clustering Guide

Overview

Starting an etcd cluster statically requires that each member knows another in the cluster. In a number of cases, you might not know the IPs of your cluster members ahead of time. In these cases, you can bootstrap an etcd cluster with the help of a discovery service.

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 command line or environment variables:

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 you are spinning up multiple clusters (or creating and destroying a single cluster) with same configuration for testing purpose, it is highly recommended that you specify a unique initial-cluster-token for the different clusters. 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 you from cross-cluster-interaction, which might corrupt your clusters.

etcd listens on listen-client-urls to accept client traffic. etcd member advertises the URLs specified in advertise-client-urls 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 when you want the remote clients to reach etcd.

The command line parameters starting with --initial-cluster will be ignored on subsequent runs of etcd. You are free to remove the environment variables or command line flags after the initial bootstrap process. If you need to make changes to the configuration later (for example, adding or removing members to/from the cluster), see the runtime configuration guide.

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.

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.

Discovery

In a number of cases, you might not know the IPs of your cluster peers ahead of time. This is common when utilizing cloud providers or when your network uses DHCP. In these cases, rather than specifying a static configuration, you can use an existing etcd cluster to bootstrap a new one. We call this process "discovery".

There two methods that can be used for discovery:

etcd discovery service

DNS SRV records

etcd Discovery

To better understand the design about discovery service protocol, we suggest you read this.

Lifetime of a Discovery URL

A discovery URL identifies a unique etcd cluster. Instead of reusing a discovery URL, you should always create discovery URLs for new clusters.

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 guide.

Custom etcd Discovery Service

Discovery uses an existing cluster to bootstrap itself. If you are using your own etcd cluster you can create a URL like so:

By setting the size key to the URL, you create a discovery URL with an expected cluster size of 3.

If you bootstrap an etcd cluster using discovery service with more than the expected number of etcd members, the extra etcd processes will fall back to being proxies by default.

The URL you will 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.

DNS Discovery

DNS SRV records 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.
The following DNS SRV records are 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 SSL.

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.

Bootstrap the etcd cluster using DNS

etcd cluster members can listen on domain names or IP address, the bootstrap process will resolve DNS A records.

The resolved address in --initial-advertise-peer-urlsmust 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 client configuration

etcdctl also supports DNS Discovery by specifying the --discovery-srv option.

$ etcdctl --discovery-srv example.com set foo bar

Error Cases

You might see an error like cannot find local etcd $name from SRV records.. That means the etcd member fails to find itself from the cluster defined in SRV records. The resolved address in --initial-advertise-peer-urlsmust match one of the resolved addresses in the SRV targets.

0.4 to 2.0+ Migration Guide

In etcd 2.0 we introduced the ability to listen on more than one address and to advertise multiple addresses. This makes using etcd easier when you have complex networking, such as private and public networks on various cloud providers.

To make understanding this feature easier, we changed the naming of some flags, but we support the old flags to make the migration from the old to new version easier.

Old Flag

New Flag

Migration Behavior

-peer-addr

–initial-advertise-peer-urls

If specified, peer-addr will be used as the only peer URL. Error if both flags specified.

-addr

–advertise-client-urls

If specified, addr will be used as the only client URL. Error if both flags specified.

-peer-bind-addr

–listen-peer-urls

If specified, peer-bind-addr will be used as the only peer bind URL. Error if both flags specified.

-bind-addr

–listen-client-urls

If specified, bind-addr will be used as the only client bind URL. Error if both flags specified.

-peers

none

Deprecated. The –initial-cluster flag provides a similar concept with different semantics. Please read this guide on cluster startup.

-peers-file

none

Deprecated. The –initial-cluster flag provides a similar concept with different semantics. Please read this guide on cluster startup.