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