From fe35839a77f998f0e1b27557b8967ae67c0bb28f Mon Sep 17 00:00:00 2001 From: Rob Szumski Date: Thu, 30 Jan 2014 11:03:05 -0800 Subject: [PATCH] feat(docs): add cluster discovery documentation --- Documentation/cluster-discovery.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 Documentation/cluster-discovery.md diff --git a/Documentation/cluster-discovery.md b/Documentation/cluster-discovery.md new file mode 100644 index 000000000..24b995073 --- /dev/null +++ b/Documentation/cluster-discovery.md @@ -0,0 +1,21 @@ +# Cluster Discovery + +## Overview + +Starting an etcd cluster can be painful since each node needs to know of another node in the cluster to get started. If you are trying to bring up a cluster all at once, say using a cloud formation, you also need to coordinate who will be the initial cluster leader. The discovery protocol helps you by providing an automated way to discover other existing peers in a cluster. + +## Using the Discovery API + +To use the discovery API, you must first create a token for your etcd cluster. Visit https://discovery.etcd.io/new to create a new token. + +When each etcd instance is started, specify the token in the `-discovery` flag. This will allow each instance to download the list of existing peers in the cluster. If the instance is the first peer, it will start as the leader of the cluster. + +You can inspect the list of peers by viewing `https://discovery.etcd.io/`. + +## Stale Peers + +etcd will automatically clean up the address of a stale peer that is no longer part of the cluster. The TTL for this process is a week, which should be long enough to handle any extremely long outage you may encounter. There is no harm in having stale peers in the list until they are cleaned up, since an etcd instance only needs to connect to one valid peer in the cluster to join. + +## Supported Platforms + +etcd discovery works on any platform that can read traffic from https://discovery.etcd.io. For example, you can use the same token across cloud servers and bare metal. Be sure to configure `-peer-addr` with an address that all peers can communicate with (no private IPs!). \ No newline at end of file