diff --git a/Documentation/demo.md b/Documentation/demo.md new file mode 100644 index 000000000..2b2553a22 --- /dev/null +++ b/Documentation/demo.md @@ -0,0 +1,286 @@ +# Demo + +This series of examples shows the basic procedures for working with an etcd cluster. + +## Set up a cluster + +01_etcd_clustering_2016050601 + +On each etcd node, specify the cluster members: + +``` +TOKEN=token-01 +CLUSTER_STATE=new +NAME_1=machine-1 +NAME_2=machine-2 +NAME_3=machine-3 +HOST_1=10.240.0.17 +HOST_2=10.240.0.18 +HOST_3=10.240.0.19 +CLUSTER=${NAME_1}=http://${HOST_1}:2380,${NAME_2}=http://${HOST_2}:2380,${NAME_3}=http://${HOST_3}:2380 +``` + +Run this on each machine: + +``` +# For machine 1 +THIS_NAME=${NAME_1} +THIS_IP=${HOST_1} +etcd --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 machine 2 +THIS_NAME=${NAME_2} +THIS_IP=${HOST_2} +etcd --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 machine 3 +THIS_NAME=${NAME_3} +THIS_IP=${HOST_3} +etcd --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} +``` + +Or use our public discovery service: + +``` +curl https://discovery.etcd.io/new?size=3 +https://discovery.etcd.io/a81b5818e67a6ea83e9d4daea5ecbc92 + +# grab this token +TOKEN=token-01 +CLUSTER_STATE=new +NAME_1=machine-1 +NAME_2=machine-2 +NAME_3=machine-3 +HOST_1=10.240.0.17 +HOST_2=10.240.0.18 +HOST_3=10.240.0.19 +DISCOVERY=https://discovery.etcd.io/a81b5818e67a6ea83e9d4daea5ecbc92 + +THIS_NAME=${NAME_1} +THIS_IP=${HOST_1} +etcd --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 \ + --discovery ${DISCOVERY} \ + --initial-cluster-state ${CLUSTER_STATE} --initial-cluster-token ${TOKEN} + +THIS_NAME=${NAME_2} +THIS_IP=${HOST_2} +etcd --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 \ + --discovery ${DISCOVERY} \ + --initial-cluster-state ${CLUSTER_STATE} --initial-cluster-token ${TOKEN} + +THIS_NAME=${NAME_3} +THIS_IP=${HOST_3} +etcd --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 \ + --discovery ${DISCOVERY} \ + --initial-cluster-state ${CLUSTER_STATE} --initial-cluster-token ${TOKEN} +``` + +Now etcd is ready! To connect to etcd with etcdctl: + +``` +export ETCDCTL_API=3 +HOST_1=10.240.0.17 +HOST_2=10.240.0.18 +HOST_3=10.240.0.19 +ENDPOINTS=$HOST_1:2379,$HOST_2:2379,$HOST_3:2379 + +etcdctl --endpoints=$ENDPOINTS member list +``` + + +## Access etcd + +02_etcdctl_access_etcd_2016051001 + +`put` command to write: + +``` +etcdctl --endpoints=$ENDPOINTS put foo "Hello World!" +``` + +`get` to read from etcd: + +``` +etcdctl --endpoints=$ENDPOINTS get foo +etcdctl --endpoints=$ENDPOINTS --write-out="json" get foo +``` + + +## Get by prefix + +03_etcdctl_get_by_prefix_2016050501 + +``` +etcdctl --endpoints=$ENDPOINTS put web1 value1 +etcdctl --endpoints=$ENDPOINTS put web2 value2 +etcdctl --endpoints=$ENDPOINTS put web3 value3 + +etcdctl --endpoints=$ENDPOINTS get web --prefix +``` + + +## Delete + +04_etcdctl_delete_2016050601 + +``` +etcdctl --endpoints=$ENDPOINTS put key myvalue +etcdctl --endpoints=$ENDPOINTS del key + +etcdctl --endpoints=$ENDPOINTS put k1 value1 +etcdctl --endpoints=$ENDPOINTS put k2 value2 +etcdctl --endpoints=$ENDPOINTS del k --prefix +``` + + +## Transactional write + +`txn` to wrap multiple requests into one transaction: + +05_etcdctl_transaction_2016050501 + +``` +etcdctl --endpoints=$ENDPOINTS put user1 bad +etcdctl --endpoints=$ENDPOINTS txn --interactive + +compares: +value("user1") = "bad" + +success requests (get, put, delete): +del user1 + +failure requests (get, put, delete): +put user1 good +``` + + +## Watch + +`watch` to get notified of future changes: + +06_etcdctl_watch_2016050501 + +``` +etcdctl --endpoints=$ENDPOINTS watch stock1 +etcdctl --endpoints=$ENDPOINTS put stock1 1000 + +etcdctl --endpoints=$ENDPOINTS watch stock --prefix +etcdctl --endpoints=$ENDPOINTS put stock1 10 +etcdctl --endpoints=$ENDPOINTS put stock2 20 +``` + + +## Lease + +`lease` to write with TTL: + +07_etcdctl_lease_2016050501 + +``` +etcdctl --endpoints=$ENDPOINTS lease grant 300 +# lease 2be7547fbc6a5afa granted with TTL(300s) + +etcdctl --endpoints=$ENDPOINTS put sample value --lease=2be7547fbc6a5afa +etcdctl --endpoints=$ENDPOINTS get sample + +etcdctl --endpoints=$ENDPOINTS lease keep-alive 2be7547fbc6a5afa +etcdctl --endpoints=$ENDPOINTS lease revoke 2be7547fbc6a5afa +# or after 300 seconds +etcdctl --endpoints=$ENDPOINTS get sample +``` + + +## Distributed locks + +`lock` for distributed lock: + +08_etcdctl_lock_2016050501 + +``` +etcdctl --endpoints=$ENDPOINTS lock mutex1 + +# another client with the same name blocks +etcdctl --endpoints=$ENDPOINTS lock mutex1 +``` + + +## Elections + +`elect` for leader election: + +09_etcdctl_elect_2016050501 + +``` +etcdctl --endpoints=$ENDPOINTS elect one p1 + +# another client with the same name blocks +etcdctl --endpoints=$ENDPOINTS elect one p2 +``` + + +## Cluster status + +Specify the initial cluster configuration for each machine: + +10_etcdctl_endpoint_2016050501 + +``` +etcdctl --write-out=table --endpoints=$ENDPOINTS endpoint status + ++------------------+------------------+---------+---------+-----------+-----------+------------+ +| ENDPOINT | ID | VERSION | DB SIZE | IS LEADER | RAFT TERM | RAFT INDEX | ++------------------+------------------+---------+---------+-----------+-----------+------------+ +| 10.240.0.17:2379 | 4917a7ab173fabe7 | 3.0.0 | 45 kB | true | 4 | 16726 | +| 10.240.0.18:2379 | 59796ba9cd1bcd72 | 3.0.0 | 45 kB | false | 4 | 16726 | +| 10.240.0.19:2379 | 94df724b66343e6c | 3.0.0 | 45 kB | false | 4 | 16726 | ++------------------+------------------+---------+---------+-----------+-----------+------------+ +``` + +``` +etcdctl --endpoints=$ENDPOINTS endpoint health + +10.240.0.17:2379 is healthy: successfully committed proposal: took = 3.345431ms +10.240.0.19:2379 is healthy: successfully committed proposal: took = 3.767967ms +10.240.0.18:2379 is healthy: successfully committed proposal: took = 4.025451ms +``` + + +## Snapshot + +`snapshot` to save point-in-time snapshot of etcd database: + +11_etcdctl_snapshot_2016051001 + +``` +etcdctl --endpoints=$ENDPOINTS snapshot save my.db + +Snapshot saved at my.db +``` + +``` +etcdctl --write-out=table --endpoints=$ENDPOINTS snapshot status my.db + ++---------+----------+------------+------------+ +| HASH | REVISION | TOTAL KEYS | TOTAL SIZE | ++---------+----------+------------+------------+ +| c55e8b8 | 9 | 13 | 25 kB | ++---------+----------+------------+------------+ +``` diff --git a/Documentation/docs.md b/Documentation/docs.md index dbf65c6e3..976f82940 100644 --- a/Documentation/docs.md +++ b/Documentation/docs.md @@ -4,7 +4,7 @@ etcd is a distributed key-value store designed to reliably and quickly preserve ## Getting started -New etcd users and developers should get started by [downloading and building][download_build] etcd. +New etcd users and developers should get started by [downloading and building][download_build] etcd. Once you have etcd, follow this [quick demo][demo] to see the basics of creating and working with an etcd cluster. ## Developing with etcd @@ -42,6 +42,7 @@ To learn more about the concepts and internals behind etcd, read the following p [api_ref]: dev-guide/api_reference_v3.md [clustering]: op-guide/clustering.md [conf]: op-guide/configuration.md +[demo]: demo.md [download_build]: dl_build.md [glossary]: learning/glossary.md [interacting]: dev-guide/interacting_v3.md