go.etcd.io/etcd@v3.3.27+incompatible/Documentation/dev-guide/local_cluster.md (about) 1 --- 2 title: Set up a local cluster 3 --- 4 5 For testing and development deployments, the quickest and easiest way is to configure a local cluster. For a production deployment, refer to the [clustering][clustering] section. 6 7 ## Local standalone cluster 8 9 ### Starting a cluster 10 11 Run the following to deploy an etcd cluster as a standalone cluster: 12 13 ``` 14 $ ./etcd 15 ... 16 ``` 17 18 If the `etcd` binary is not present in the current working directory, it might be located either at `$GOPATH/bin/etcd` or at `/usr/local/bin/etcd`. Run the command appropriately. 19 20 The running etcd member listens on `localhost:2379` for client requests. 21 22 ### Interacting with the cluster 23 24 Use `etcdctl` to interact with the running cluster: 25 26 1. Store an example key-value pair in the cluster: 27 28 ``` 29 $ ./etcdctl put foo bar 30 OK 31 ``` 32 33 If OK is printed, storing key-value pair is successful. 34 35 2. Retrieve the value of `foo`: 36 37 ``` 38 $ ./etcdctl get foo 39 bar 40 ``` 41 42 If `bar` is returned, interaction with the etcd cluster is working as expected. 43 44 ## Local multi-member cluster 45 46 ### Starting a cluster 47 48 A `Procfile` at the base of the etcd git repository is provided to easily configure a local multi-member cluster. To start a multi-member cluster, navigate to the root of the etcd source tree and perform the following: 49 50 1. Install `goreman` to control Procfile-based applications: 51 52 ``` 53 $ go get github.com/mattn/goreman 54 ``` 55 56 2. Start a cluster with `goreman` using etcd's stock Procfile: 57 58 ``` 59 $ goreman -f Procfile start 60 ``` 61 62 The members start running. They listen on `localhost:2379`, `localhost:22379`, and `localhost:32379` respectively for client requests. 63 64 ### Interacting with the cluster 65 66 Use `etcdctl` to interact with the running cluster: 67 68 1. Print the list of members: 69 70 ``` 71 $ etcdctl --write-out=table --endpoints=localhost:2379 member list 72 ``` 73 The list of etcd members are displayed as follows: 74 75 ``` 76 +------------------+---------+--------+------------------------+------------------------+ 77 | ID | STATUS | NAME | PEER ADDRS | CLIENT ADDRS | 78 +------------------+---------+--------+------------------------+------------------------+ 79 | 8211f1d0f64f3269 | started | infra1 | http://127.0.0.1:2380 | http://127.0.0.1:2379 | 80 | 91bc3c398fb3c146 | started | infra2 | http://127.0.0.1:22380 | http://127.0.0.1:22379 | 81 | fd422379fda50e48 | started | infra3 | http://127.0.0.1:32380 | http://127.0.0.1:32379 | 82 +------------------+---------+--------+------------------------+------------------------+ 83 ``` 84 85 2. Store an example key-value pair in the cluster: 86 87 ``` 88 $ etcdctl put foo bar 89 OK 90 ``` 91 92 If OK is printed, storing key-value pair is successful. 93 94 ### Testing fault tolerance 95 96 To exercise etcd's fault tolerance, kill a member and attempt to retrieve the key. 97 98 1. Identify the process name of the member to be stopped. 99 100 The `Procfile` lists the properties of the multi-member cluster. For example, consider the member with the process name, `etcd2`. 101 102 2. Stop the member: 103 104 ``` 105 # kill etcd2 106 $ goreman run stop etcd2 107 ``` 108 109 3. Store a key: 110 111 ``` 112 $ etcdctl put key hello 113 OK 114 ``` 115 116 4. Retrieve the key that is stored in the previous step: 117 118 ``` 119 $ etcdctl get key 120 hello 121 ``` 122 123 5. Retrieve a key from the stopped member: 124 125 ``` 126 $ etcdctl --endpoints=localhost:22379 get key 127 ``` 128 129 The command should display an error caused by connection failure: 130 131 ``` 132 2017/06/18 23:07:35 grpc: Conn.resetTransport failed to create client transport: connection error: desc = "transport: dial tcp 127.0.0.1:22379: getsockopt: connection refused"; Reconnecting to "localhost:22379" 133 Error: grpc: timed out trying to connect 134 ``` 135 6. Restart the stopped member: 136 137 ``` 138 $ goreman run restart etcd2 139 ``` 140 141 7. Get the key from the restarted member: 142 143 ``` 144 $ etcdctl --endpoints=localhost:22379 get key 145 hello 146 ``` 147 148 Restarting the member re-establish the connection. `etcdctl` will now be able to retrieve the key successfully. To learn more about interacting with etcd, read [interacting with etcd section][interacting]. 149 150 [interacting]: ./interacting_v3.md 151 [clustering]: ../op-guide/clustering.md