On each etcd node, specify the cluster members:

Run this on each machine:

  2. THIS_NAME=${NAME_1}
  3. THIS_IP=${HOST_1}
  4. etcd --data-dir=data.etcd --name ${THIS_NAME} \
  5.     --initial-advertise-peer-urls http://${THIS_IP}:2380 --listen-peer-urls http://${THIS_IP}:2380 \
  6.     --advertise-client-urls http://${THIS_IP}:2379 --listen-client-urls http://${THIS_IP}:2379 \
  7.     --initial-cluster ${CLUSTER} \
  8.     --initial-cluster-state ${CLUSTER_STATE} --initial-cluster-token ${TOKEN}
  10. # For machine 2
  11. THIS_NAME=${NAME_2}
  12. THIS_IP=${HOST_2}
  13. etcd --data-dir=data.etcd --name ${THIS_NAME} \
  14.     --initial-advertise-peer-urls http://${THIS_IP}:2380 --listen-peer-urls http://${THIS_IP}:2380 \
  15.     --advertise-client-urls http://${THIS_IP}:2379 --listen-client-urls http://${THIS_IP}:2379 \
  16.     --initial-cluster ${CLUSTER} \
  17.     --initial-cluster-state ${CLUSTER_STATE} --initial-cluster-token ${TOKEN}
  19. # For machine 3
  20. THIS_NAME=${NAME_3}
  21. THIS_IP=${HOST_3}
  22. etcd --data-dir=data.etcd --name ${THIS_NAME} \
  23.     --initial-advertise-peer-urls http://${THIS_IP}:2380 --listen-peer-urls http://${THIS_IP}:2380 \
  24.     --advertise-client-urls http://${THIS_IP}:2379 --listen-client-urls http://${THIS_IP}:2379 \
  25.     --initial-cluster ${CLUSTER} \
  26.     --initial-cluster-state ${CLUSTER_STATE} --initial-cluster-token ${TOKEN}

Or use our public discovery service:

  1. curl https://discovery.etcd.io/new?size=3
  2. https://discovery.etcd.io/a81b5818e67a6ea83e9d4daea5ecbc92
  4. # grab this token
  5. TOKEN=token-01
  6. CLUSTER_STATE=new
  7. NAME_1=machine-1
  8. NAME_2=machine-2
  9. NAME_3=machine-3
  10. HOST_1=10.240.0.17
  11. HOST_2=10.240.0.18
  12. HOST_3=10.240.0.19
  13. DISCOVERY=https://discovery.etcd.io/a81b5818e67a6ea83e9d4daea5ecbc92
  15. THIS_NAME=${NAME_1}
  16. THIS_IP=${HOST_1}
  17. etcd --data-dir=data.etcd --name ${THIS_NAME} \
  18.     --initial-advertise-peer-urls http://${THIS_IP}:2380 --listen-peer-urls http://${THIS_IP}:2380 \
  19.     --advertise-client-urls http://${THIS_IP}:2379 --listen-client-urls http://${THIS_IP}:2379 \
  20.     --discovery ${DISCOVERY} \
  21.     --initial-cluster-state ${CLUSTER_STATE} --initial-cluster-token ${TOKEN}
  23. THIS_NAME=${NAME_2}
  24. THIS_IP=${HOST_2}
  25. etcd --data-dir=data.etcd --name ${THIS_NAME} \
  26.     --initial-advertise-peer-urls http://${THIS_IP}:2380 --listen-peer-urls http://${THIS_IP}:2380 \
  27.     --advertise-client-urls http://${THIS_IP}:2379 --listen-client-urls http://${THIS_IP}:2379 \
  28.     --discovery ${DISCOVERY} \
  29.     --initial-cluster-state ${CLUSTER_STATE} --initial-cluster-token ${TOKEN}
  31. THIS_NAME=${NAME_3}
  32. THIS_IP=${HOST_3}
  33. etcd --data-dir=data.etcd --name ${THIS_NAME} \
  34.     --initial-advertise-peer-urls http://${THIS_IP}:2380 --listen-peer-urls http://${THIS_IP}:2380 \
  35.     --advertise-client-urls http://${THIS_IP}:2379 --listen-client-urls http://${THIS_IP}:2379 \
  36.     --discovery ${DISCOVERY} \
  37.     --initial-cluster-state ${CLUSTER_STATE} --initial-cluster-token ${TOKEN}

Now etcd is ready! To connect to etcd with etcdctl:

  1. export ETCDCTL_API=3
  2. HOST_1=10.240.0.17
  3. HOST_2=10.240.0.18
  4. HOST_3=10.240.0.19
  5. ENDPOINTS=$HOST_1:2379,$HOST_2:2379,$HOST_3:2379
  7. etcdctl --endpoints=$ENDPOINTS member list

Access etcd

02_etcdctl_access_etcd_2016051001

put command to write:

  1. etcdctl --endpoints=$ENDPOINTS put foo "Hello World!"

get to read from etcd:

  1. etcdctl --endpoints=$ENDPOINTS --write-out="json" get foo

Get by prefix

  1. etcdctl --endpoints=$ENDPOINTS put web1 value1
  2. etcdctl --endpoints=$ENDPOINTS put web2 value2
  3. etcdctl --endpoints=$ENDPOINTS put web3 value3
  5. etcdctl --endpoints=$ENDPOINTS get web --prefix

Delete

04_etcdctl_delete_2016050601

  1. etcdctl --endpoints=$ENDPOINTS put user1 bad
  2. etcdctl --endpoints=$ENDPOINTS txn --interactive
  4. compares:
  5. value("user1") = "bad"      
  7. success requests (get, put, delete):
  8. del user1  
  10. failure requests (get, put, delete):
  11. put user1 good

Watch

watch to get notified of future changes:

06_etcdctl_watch_2016050501

  1. etcdctl --endpoints=$ENDPOINTS watch stock1
  2. etcdctl --endpoints=$ENDPOINTS put stock1 1000
  4. etcdctl --endpoints=$ENDPOINTS watch stock --prefix
  5. etcdctl --endpoints=$ENDPOINTS put stock1 10
  6. etcdctl --endpoints=$ENDPOINTS put stock2 20

Lease

lease to write with TTL:

  1. etcdctl --endpoints=$ENDPOINTS lease grant 300
  2. # lease 2be7547fbc6a5afa granted with TTL(300s)
  4. etcdctl --endpoints=$ENDPOINTS put sample value --lease=2be7547fbc6a5afa
  5. etcdctl --endpoints=$ENDPOINTS get sample
  7. etcdctl --endpoints=$ENDPOINTS lease keep-alive 2be7547fbc6a5afa
  8. etcdctl --endpoints=$ENDPOINTS lease revoke 2be7547fbc6a5afa
  9. # or after 300 seconds
  10. etcdctl --endpoints=$ENDPOINTS get sample

Distributed locks

lock for distributed lock:

08_etcdctl_lock_2016050501

  1. etcdctl --endpoints=$ENDPOINTS lock mutex1
  3. # another client with the same name blocks
  4. etcdctl --endpoints=$ENDPOINTS lock mutex1

elect for leader election:

  1. etcdctl --endpoints=$ENDPOINTS elect one p1
  3. # another client with the same name blocks
  4. etcdctl --endpoints=$ENDPOINTS elect one p2

Cluster status

Specify the initial cluster configuration for each machine:

  1. etcdctl --write-out=table --endpoints=$ENDPOINTS endpoint status
  3. +------------------+------------------+---------+---------+-----------+-----------+------------+
  4. |     ENDPOINT     |        ID        | VERSION | DB SIZE | IS LEADER | RAFT TERM | RAFT INDEX |
  5. +------------------+------------------+---------+---------+-----------+-----------+------------+
  6. | 10.240.0.17:2379 | 4917a7ab173fabe7 | 3.0.0   | 45 kB   | true      |         4 |      16726 |
  7. | 10.240.0.18:2379 | 59796ba9cd1bcd72 | 3.0.0   | 45 kB   | false     |         4 |      16726 |
  8. | 10.240.0.19:2379 | 94df724b66343e6c | 3.0.0   | 45 kB   | false     |         4 |      16726 |
  9. +------------------+------------------+---------+---------+-----------+-----------+------------+

Snapshot

snapshot to save point-in-time snapshot of etcd database:

11_etcdctl_snapshot_2016051001

  1. etcdctl --endpoints=$ENDPOINTS snapshot save my.db
  3. Snapshot saved at my.db
  1. etcdctl --write-out=table --endpoints=$ENDPOINTS snapshot status my.db
  3. +---------+----------+------------+------------+
  4. |  HASH   | REVISION | TOTAL KEYS | TOTAL SIZE |
  5. +---------+----------+------------+------------+
  6. | c55e8b8 |        9 |         13 | 25 kB      |
  7. +---------+----------+------------+------------+

Migrate

migrate to transform etcd v2 to v3 data:

  1. # write key in etcd version 2 store
  2. export ETCDCTL_API=2
  3. etcdctl --endpoints=http://$ENDPOINT set foo bar
  5. # read key in etcd v2
  6. etcdctl --endpoints=$ENDPOINTS --output="json" get foo
  8. # stop etcd node to migrate, one by one
  10. # migrate v2 data
  11. export ETCDCTL_API=3
  12. etcdctl --endpoints=$ENDPOINT migrate --data-dir="default.etcd" --wal-dir="default.etcd/member/wal"
  14. # restart etcd node after migrate, one by one
  16. # confirm that the key got migrated
  17. etcdctl --endpoints=$ENDPOINTS get /foo

member to add,remove,update membership:

13_etcdctl_member_2016062301

  1. # For each machine
  2. TOKEN=my-etcd-token-1
  3. CLUSTER_STATE=new
  4. NAME_1=etcd-node-1
  5. NAME_2=etcd-node-2
  6. NAME_3=etcd-node-3
  7. HOST_1=10.240.0.13
  8. HOST_3=10.240.0.15
  9. CLUSTER=${NAME_1}=http://${HOST_1}:2380,${NAME_2}=http://${HOST_2}:2380,${NAME_3}=http://${HOST_3}:2380
  11. # For node 1
  12. THIS_NAME=${NAME_1}
  14. etcd --data-dir=data.etcd --name ${THIS_NAME} \
  15.     --initial-advertise-peer-urls http://${THIS_IP}:2380 \
  16.     --listen-peer-urls http://${THIS_IP}:2380 \
  17.     --advertise-client-urls http://${THIS_IP}:2379 \
  18.     --listen-client-urls http://${THIS_IP}:2379 \
  19.     --initial-cluster ${CLUSTER} \
  20.     --initial-cluster-state ${CLUSTER_STATE} \
  21.     --initial-cluster-token ${TOKEN}
  23. # For node 2
  24. THIS_NAME=${NAME_2}
  25. THIS_IP=${HOST_2}
  26. etcd --data-dir=data.etcd --name ${THIS_NAME} \
  27.     --initial-advertise-peer-urls http://${THIS_IP}:2380 \
  28.     --listen-peer-urls http://${THIS_IP}:2380 \
  29.     --advertise-client-urls http://${THIS_IP}:2379 \
  30.     --listen-client-urls http://${THIS_IP}:2379 \
  31.     --initial-cluster ${CLUSTER} \
  32.     --initial-cluster-state ${CLUSTER_STATE} \
  33.     --initial-cluster-token ${TOKEN}
  35. # For node 3
  36. THIS_NAME=${NAME_3}
  37. THIS_IP=${HOST_3}
  38. etcd --data-dir=data.etcd --name ${THIS_NAME} \
  39.     --initial-advertise-peer-urls http://${THIS_IP}:2380 \
  40.     --listen-peer-urls http://${THIS_IP}:2380 \
  41.     --advertise-client-urls http://${THIS_IP}:2379 \
  42.     --listen-client-urls http://${THIS_IP}:2379 \
  43.     --initial-cluster ${CLUSTER} \
  44.     --initial-cluster-state ${CLUSTER_STATE} \
  45.     --initial-cluster-token ${TOKEN}

Then replace a member with member remove and member add commands:

  1. # get member ID
  2. export ETCDCTL_API=3
  3. HOST_1=10.240.0.13
  4. HOST_2=10.240.0.14
  5. HOST_3=10.240.0.15
  6. etcdctl --endpoints=${HOST_1}:2379,${HOST_2}:2379,${HOST_3}:2379 member list
  8. # remove the member
  9. MEMBER_ID=278c654c9a6dfd3b
  10. etcdctl --endpoints=${HOST_1}:2379,${HOST_2}:2379,${HOST_3}:2379 \
  11.     member remove ${MEMBER_ID}
  13. # add a new member (node 4)
  14. export ETCDCTL_API=3
  15. NAME_1=etcd-node-1
  16. NAME_2=etcd-node-2
  17. NAME_4=etcd-node-4
  18. HOST_1=10.240.0.13
  19. HOST_2=10.240.0.14
  20. HOST_4=10.240.0.16 # new member
  21. etcdctl --endpoints=${HOST_1}:2379,${HOST_2}:2379 \
  22.     member add ${NAME_4} \
  23.     --peer-urls=http://${HOST_4}:2380

Next, start the new member with --initial-cluster-state existing flag:

  1. # [WARNING] If the new member starts from the same disk space,
  2. # make sure to remove the data directory of the old member
  3. #
  4. # restart with 'existing' flag
  5. TOKEN=my-etcd-token-1
  6. CLUSTER_STATE=existing
  7. NAME_1=etcd-node-1
  8. NAME_2=etcd-node-2
  9. NAME_4=etcd-node-4
  10. HOST_1=10.240.0.13
  11. HOST_2=10.240.0.14
  12. HOST_4=10.240.0.16 # new member
  13. CLUSTER=${NAME_1}=http://${HOST_1}:2380,${NAME_2}=http://${HOST_2}:2380,${NAME_4}=http://${HOST_4}:2380
  15. THIS_NAME=${NAME_4}
  16. THIS_IP=${HOST_4}
  17. etcd --data-dir=data.etcd --name ${THIS_NAME} \
  18.     --initial-advertise-peer-urls http://${THIS_IP}:2380 \
  19.     --listen-peer-urls http://${THIS_IP}:2380 \
  20.     --advertise-client-urls http://${THIS_IP}:2379 \
  21.     --listen-client-urls http://${THIS_IP}:2379 \
  22.     --initial-cluster ${CLUSTER} \
  23.     --initial-cluster-state ${CLUSTER_STATE} \

Auth

auth,user,role for authentication: