diff --git a/README.md b/README.md index 018764f5e..c4034acbe 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,9 @@ These examples will use a single node cluster to show you the basics of the etcd This will bring up an etcd node listening on port 4001 for client communication and on port 7001 for server-to-server communication. The `-d node0` argument tells etcd to write node configuration, logs and snapshots to the `./node0/` directory. -#### Setting the value to a key +## Usage + +### Setting the value to a key Let’s set the first key-value pair to the node. In this case the key is `/message` and the value is `Hello world`. @@ -61,7 +63,7 @@ Notice we use a file system like structure to represent the key-value pairs. So 5. Index is the unique internal log index of the set request. Requests that change the log index include `SET`, `DELETE` and `TESTANDSET`. The `GET`, `LIST` and `WATCH` commands do not change state in the store and so they do not change the index. You may notice that in this example the index is 3, although it is the first request you sent to the server. This is because there are internal commands that also change the state like adding and syncing servers. -#### Getting the value of a key +### Get the value of a key Get the value that we just set in `/message` by issuing a GET: @@ -72,7 +74,7 @@ curl -L http://127.0.0.1:4001/v1/keys/message ```json {"action":"GET","key":"/message","value":"Hello world","index":3} ``` -#### Changing the value of a key +### Change the value of a key Change the value of `/message` from `Hello world` to `Hello etcd` with another POST to the key: @@ -86,7 +88,7 @@ curl -L http://127.0.0.1:4001/v1/keys/message -d value="Hello etcd" Notice that the `prevValue` is set to `Hello world`. -#### Deleting a key +### Delete a key Remove the `/message` key with a DELETE: @@ -98,7 +100,7 @@ curl -L http://127.0.0.1:4001/v1/keys/message -X DELETE {"action":"DELETE","key":"/message","prevValue":"Hello etcd","index":5} ``` -#### Using a TTL on a key +### Using key TTL Keys in etcd can be set to expire after a specified number of seconds. That is done by setting a TTL (time to live) on the key when you POST: @@ -128,8 +130,7 @@ If the TTL has expired, the key will be deleted, and you will be returned a 404. 404 page not found ``` - -#### Watching a prefix +### Watching a prefix We can watch a path prefix and get notifications if any key change under that prefix. @@ -163,9 +164,7 @@ curl -L http://127.0.0.1:4001/v1/watch/foo -d index=7 The watch command returns immediately with the same response as previous. -#### Atomic Test and Set - -Etcd servers will process all the command in sequence atomically. Thus it can be used as a centralized coordination service in a cluster. +### Atomic Test and Set `TestAndSet` is the most basic operation to build distributed lock service. @@ -206,8 +205,7 @@ The response should be We successfully changed the value from “one” to “two”, since we give the correct previous value. - -#### Listing directory +### Listing a directory Last we provide a simple List command to list all the keys under a prefix path. @@ -235,7 +233,10 @@ We should see the response as an array of items which meas `foo=barbar` is a key-value pair under `/foo` and `foo_dir` is a directory. -#### Using HTTPS between server and client +## Advanced Usage + +### Transport security with HTTPS + Etcd supports SSL/TLS and client cert authentication for clients to server, as well as server to server communication Before that we need to have a CA cert`clientCA.crt` and signed key pair `client.crt`, `client.key` . @@ -273,7 +274,9 @@ And also the response from the etcd server. {"action":"SET","key":"/foo","value":"bar","newKey":true,"index":3} ``` -We also can do authentication using CA cert. The clients will also need to provide their cert to the server. The server will check whether the cert is signed by the CA and decide whether to serve the request. +### Authentication with HTTPS client certificates + +We can also do authentication using CA certs. The clients will provide their cert to the server and the server will check whether the cert is signed by the CA and decide whether to serve the request. ```sh ./etcd -clientCert client.crt -clientKey client.key -clientCAFile clientCA.crt -f @@ -322,9 +325,11 @@ And also the response from the server {"action":"SET","key":"/foo","value":"bar","newKey":true,"index":3} ``` -### Setting up a cluster of three machines +## Clustering -Next let's explore the use of etcd clustering. We use go-raft as the underlying distributed protocol which provides consistency and persistence of the data across all of the etcd instances. +### Example cluster of three machines + +Let's explore the use of etcd clustering. We use go-raft as the underlying distributed protocol which provides consistency and persistence of the data across all of the etcd instances. Let start by creating 3 new etcd instances. @@ -382,16 +387,11 @@ Now we can do normal SET and GET operations on keys as we explored earlier. curl -L http://127.0.0.1:4001/v1/keys/foo -d value=bar ``` -When the client sends a sensitive command (`set`, `delete`, `testAndset` ) to the server, the command needs to be redirect to the leader of the cluster. - -So we add the ` -L ` flag to make curl follow location hints in http location header when there is a redirection http response. - -The response should be ```json {"action":"SET","key":"/foo","value":"bar","newKey":true,"index":5} ``` -#### Killing Nodes in the Cluster +### Killing Nodes in the Cluster Let's kill the leader of the cluster and get the value from the other machine: @@ -417,7 +417,7 @@ You should be able to see this: It succeed! -#### Testing Persistence +### Testing Persistence OK. Next let us kill all the nodes to test persistence. And restart all the nodes use the same command as before. @@ -431,7 +431,8 @@ curl -L http://127.0.0.1:4002/v1/keys/foo {"action":"GET","key":"/foo","value":"bar","index":5} ``` -#### Using HTTPS between servers +### Using HTTPS between servers + In the previous example we showed how to use SSL client certs for client to server communication. Etcd can also do internal server to server communication using SSL client certs. To do this just change the ```-client*``` flags to ```-server*```. If you are using SSL for server to server communication, you must use it on all instances of etcd.