Merge pull request #5559 from gyuho/docker_guide

Documentation: add docker guide for v3

Documentation/docs.md

@@ -19,6 +19,7 @@ The easiest way to get started using etcd as a distributed key-value store for y
 Administrators who need to create reliable and scalable key-value stores for the developers they support should begin with a [cluster on multiple machines][clustering].
 
  - [Setting up clusters][clustering]
+ - [Run etcd clusters inside containers][container]
  - [Configuration][conf]
  - [Security][security]
  - Monitoring
@@ -56,3 +57,4 @@ To learn more about the concepts and internals behind etcd, read the following p
 [maintenance]: op-guide/maintenance.md
 [security]: op-guide/security.md
 [v2_migration]: op-guide/v2-migration.md
+[container]: op-guide/container.md

Documentation/op-guide/container.md

@@ -0,0 +1,54 @@
+# Run etcd clusters inside containers
+
+The following guide shows how to run etcd with rkt and Docker using the [static bootstrap process](clustering.md#static).
+
+## Docker
+
+In order to expose the etcd API to clients outside of Docker host, use the host IP address of the container. Please see [`docker inspect`](https://docs.docker.com/engine/reference/commandline/inspect) for more detail on how to get the IP address. Alternatively, specify `--net=host` flag to `docker run` command to skip placing the container inside of a separate network stack.
+
+```
+# For each machine
+ETCD_VERSION=v3.0.0-beta.0
+TOKEN=my-etcd-token
+CLUSTER_STATE=new
+NAME_1=etcd-node-0
+NAME_2=etcd-node-1
+NAME_3=etcd-node-2
+HOST_1=10.20.30.1
+HOST_2=10.20.30.2
+HOST_3=10.20.30.3
+CLUSTER=${NAME_1}=http://${HOST_1}:2380,${NAME_2}=http://${HOST_2}:2380,${NAME_3}=http://${HOST_3}:2380
+
+# For node 1
+THIS_NAME=${NAME_1}
+THIS_IP=${HOST_1}
+sudo docker run --net=host --name etcd quay.io/coreos/etcd:${ETCD_VERSION} \
+    --data-dir=data.etcd --name ${THIS_NAME} \
+	--initial-advertise-peer-urls http://${THIS_IP}:2380 --listen-peer-urls http://${THIS_IP}:2380 \
+	--advertise-client-urls http://${THIS_IP}:2379 --listen-client-urls http://${THIS_IP}:2379 \
+	--initial-cluster ${CLUSTER} \
+	--initial-cluster-state ${CLUSTER_STATE} --initial-cluster-token ${TOKEN}
+
+# For node 2
+THIS_NAME=${NAME_2}
+THIS_IP=${HOST_2}
+sudo docker run --net=host --name etcd quay.io/coreos/etcd:${ETCD_VERSION} \
+    --data-dir=data.etcd --name ${THIS_NAME} \
+	--initial-advertise-peer-urls http://${THIS_IP}:2380 --listen-peer-urls http://${THIS_IP}:2380 \
+	--advertise-client-urls http://${THIS_IP}:2379 --listen-client-urls http://${THIS_IP}:2379 \
+	--initial-cluster ${CLUSTER} \
+	--initial-cluster-state ${CLUSTER_STATE} --initial-cluster-token ${TOKEN}
+
+# For node 3
+THIS_NAME=${NAME_3}
+THIS_IP=${HOST_3}
+sudo docker run --net=host --name etcd quay.io/coreos/etcd:${ETCD_VERSION} \
+    --data-dir=data.etcd --name ${THIS_NAME} \
+	--initial-advertise-peer-urls http://${THIS_IP}:2380 --listen-peer-urls http://${THIS_IP}:2380 \
+	--advertise-client-urls http://${THIS_IP}:2379 --listen-client-urls http://${THIS_IP}:2379 \
+	--initial-cluster ${CLUSTER} \
+	--initial-cluster-state ${CLUSTER_STATE} --initial-cluster-token ${TOKEN}
+```
+
+TODO: current etcd docker container is shipped with etcdctl, but the `ETCDCTL_API` environment value is not set inside the container. So currently there's no way to use etcdctl for v3 directly from the container (e.g. `docker exec etcd /etcdctl put foo bar` won't work).
+