Merge pull request #3372 from xiang90/doc

improve clustering.md doc

Documentation/clustering.md

@@ -4,7 +4,7 @@
 
 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.
 
-Once an etcd cluster is up and running, adding or removing members is done via [runtime reconfiguration](runtime-configuration.md).
+Once an etcd cluster is up and running, adding or removing members is done via [runtime reconfiguration](runtime-configuration.md). To better understand the design behind runtime reconfiguration, we suggest you read [this](runtime-reconf-design.md).
 
 This guide will cover the following mechanisms for bootstrapping an etcd cluster:
 
@@ -38,6 +38,8 @@ Note that the URLs specified in `initial-cluster` are the _advertised peer URLs_
 
 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`](configuration.md#-listen-client-urls) to accept client traffic. etcd member advertises the URLs specified in [`advertise-client-urls`](configuration.md#-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.
+
 On each machine you would start etcd with these flags:
 
 ```

Documentation/configuration.md

@@ -32,12 +32,16 @@ To start etcd automatically using custom settings at startup in Linux, using a [
 + default: "1000"
 
 ##### -listen-peer-urls
-+ List of URLs to listen on for peer traffic.
++ List of URLs to listen on for peer traffic. This flag tells the etcd to accept incoming requests from its peers on the specified scheme://IP:port combinations. Scheme can be either http or https.If 0.0.0.0 is specified as the IP, etcd listens to the given port on all interfaces. If an IP address is given as well as a port, etcd will listen on the given port and interface. Multiple URLs may be used to specify a number of addresses and ports to listen on. The etcd will respond to requests from any of the listed addresses and ports.
 + default: "http://localhost:2380,http://localhost:7001"
++ example: "http://10.0.0.1:2380"
++ invalid example: "http://example.com:2380" (domain name is invalid for binding)
 
 ##### -listen-client-urls
-+ List of URLs to listen on for client traffic.
++ List of URLs to listen on for client traffic. This flag tells the etcd to accept incoming requests from the clients on the specified scheme://IP:port combinations. Scheme can be either http or https. If 0.0.0.0 is specified as the IP, etcd listens to the given port on all interfaces. If an IP address is given as well as a port, etcd will listen on the given port and interface. Multiple URLs may be used to specify a number of addresses and ports to listen on. The etcd will respond to requests from any of the listed addresses and ports.
 + default: "http://localhost:2379,http://localhost:4001"
++ example: "http://10.0.0.1:2379"
++ invalid example: "http://example.com:2379" (domain name is invalid for binding)
 
 ##### -max-snapshots
 + Maximum number of snapshot files to retain (0 is unlimited)
@@ -61,8 +65,9 @@ To start etcd automatically using custom settings at startup in Linux, using a [
 
 ##### -initial-advertise-peer-urls
 
-+ List of this member's peer URLs to advertise to the rest of the cluster. These addresses are used for communicating etcd data around the cluster. At least one must be routable to all cluster members.
++ List of this member's peer URLs to advertise to the rest of the cluster. These addresses are used for communicating etcd data around the cluster. At least one must be routable to all cluster members. These URLs can contain domain names.
 + default: "http://localhost:2380,http://localhost:7001"
++ example: "http://example.com:2380, http://10.0.0.1:2380"
 
 ##### -initial-cluster
 + Initial cluster configuration for bootstrapping.
@@ -80,8 +85,9 @@ To start etcd automatically using custom settings at startup in Linux, using a [
 + default: "etcd-cluster"
 
 ##### -advertise-client-urls
-+ List of this member's client URLs to advertise to the rest of the cluster.
++ List of this member's client URLs to advertise to the rest of the cluster. These URLs can contain domain names.
 + default: "http://localhost:2379,http://localhost:4001"
++ example: "http://example.com:2379, http://10.0.0.1:2379"
 + Be careful if you are advertising URLs such as http://localhost:2379 from a cluster member and are using the proxy feature of etcd. This will cause loops, because the proxy will be forwarding requests to itself until its resources (memory, file descriptors) are eventually depleted.
 
 ##### -discovery