fix(README): cleanup the prose in the README
This cleans up the prose in the README file a bit and introduces some formatting changes.release-0.4
parent
f03b872c72
commit
6e669dab8e
103
README.md
103
README.md
|
@ -2,10 +2,24 @@
|
|||
|
||||
## Getting Started
|
||||
|
||||
### Setting up a node
|
||||
### Building
|
||||
|
||||
etcd is installed like any other Go binary. The steps below will put everything into a directory called etcd.
|
||||
|
||||
```
|
||||
mkdir etcd
|
||||
cd etcd
|
||||
export GOPATH=`pwd`
|
||||
go get github.com/coreos/etcd
|
||||
go install github.com/coreos/etcd
|
||||
```
|
||||
|
||||
### Running a single node
|
||||
|
||||
These examples will use a single node cluster to show you the basics of the etcd REST API. Lets start etcd:
|
||||
|
||||
```sh
|
||||
./etcd
|
||||
./bin/etcd
|
||||
```
|
||||
|
||||
This will bring up a node, which will be listening on internal port 7001 (for server communication) and external port 4001 (for client communication)
|
||||
|
@ -37,18 +51,18 @@ Notice we use a file system like structure to represent the key-value pairs. So
|
|||
|
||||
#### Getting the value of a key
|
||||
|
||||
Get the value that we just set in `/message` by issuing a GET:
|
||||
|
||||
```sh
|
||||
curl http://127.0.0.1:4001/v1/keys/message
|
||||
```
|
||||
|
||||
You should receive the response as
|
||||
|
||||
```json
|
||||
{"action":"GET","key":"/message","value":"Hello world","index":3}
|
||||
```
|
||||
#### Changing the value of a key
|
||||
|
||||
We change the value of `/message` from `Hello world` to `Hello etcd`
|
||||
Change the value of `/message` from `Hello world` to `Hello etcd` with another POST to the key:
|
||||
|
||||
```sh
|
||||
curl http://127.0.0.1:4001/v1/keys/message -d value="Hello etcd"
|
||||
|
@ -58,54 +72,54 @@ curl http://127.0.0.1:4001/v1/keys/message -d value="Hello etcd"
|
|||
{"action":"SET","key":"/message","prevValue":"Hello world","value":"Hello etcd","index":4}
|
||||
```
|
||||
|
||||
There is a new field in the response: prevValue. It is the value of the key before the change happened.
|
||||
Notice that the `prevValue` is set to `Hello world`.
|
||||
|
||||
#### Deleting a key
|
||||
|
||||
Remove the `/message` key with a DELETE:
|
||||
|
||||
```sh
|
||||
curl http://127.0.0.1:4001/v1/keys/message -X DELETE
|
||||
```
|
||||
|
||||
You should see the response as
|
||||
|
||||
```json
|
||||
{"action":"DELETE","key":"/message","prevValue":"Hello etcd","index":5}
|
||||
```
|
||||
|
||||
#### Using time to live key
|
||||
|
||||
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:
|
||||
|
||||
```sh
|
||||
curl http://127.0.0.1:4001/v1/keys/foo -d value=bar -d ttl=5
|
||||
```
|
||||
|
||||
You should see the similar response as (not exact same, they should have different expiration time)
|
||||
|
||||
```json
|
||||
{"action":"SET","key":"/foo","value":"bar","newKey":true,"expiration":"2013-07-11T20:31:12.156146039-07:00","ttl":4,"index":6}
|
||||
```
|
||||
|
||||
There are the last two new fields in response.
|
||||
Note the last two new fields in response:
|
||||
|
||||
Expiration field is the time that this key will expire and be deleted.
|
||||
1. The expiration is the time that this key will expire and be deleted.
|
||||
|
||||
Ttl field is the time to live of the key, it can be derived from current time and expiration time.
|
||||
2. The ttl is the time to live of the key.
|
||||
|
||||
Now you can try to get the key by sending
|
||||
Now you can try to get the key by sending:
|
||||
|
||||
```sh
|
||||
curl http://127.0.0.1:4001/v1/keys/foo
|
||||
```
|
||||
You can expect the ttl is counting down and after 5 seconds you should see this,
|
||||
|
||||
If the TTL has passed then you will
|
||||
|
||||
```html
|
||||
404 page not found
|
||||
```
|
||||
|
||||
which indicates the key has expired and was deleted.
|
||||
|
||||
#### Watching a prefix
|
||||
|
||||
Watch command can watch as a prefix path and get notification if any key changes after the prefix.
|
||||
We can watch a path prefix and get notifications if any key change under that prefix.
|
||||
|
||||
In one terminal, we send a watch request:
|
||||
|
||||
|
@ -127,32 +141,31 @@ The first terminal should get the notification and return with the same response
|
|||
{"action":"SET","key":"/foo/foo","value":"barbar","newKey":true,"index":7}
|
||||
```
|
||||
|
||||
OK. Watch command can do more than this. We have index and in etcd we store the most recent 1000 responses by default, which allow us to watch for previous commands.
|
||||
However, the watch command can do more than this. Using the the index we can watch for commands that has happened in the past. This is useful for ensuring you don't miss events between watch commands.
|
||||
|
||||
Let us try to watch for the set command of index 6 again.
|
||||
Let's try to watch for the set command of index 6 again:
|
||||
|
||||
```sh
|
||||
curl http://127.0.0.1:4001/v1/watch/foo -d index=7
|
||||
```
|
||||
|
||||
You should see the watch command return immediately with the same response as previous.
|
||||
The watch command returns immediately with the same response as previous.
|
||||
|
||||
#### Trying TestAndSet
|
||||
#### Atomic Test and Set
|
||||
|
||||
Etcd servers will process all the command in sequence atomically, thus it can be used as a centralized decision making cluster.
|
||||
Etcd servers will process all the command in sequence atomically. Thus it can be used as a centralized coordination service in a cluster.
|
||||
|
||||
TestAndSet is the most basic operation to build distributed lock service and more interesting stuff.
|
||||
`TestAndSet` is the most basic operation to build distributed lock service.
|
||||
|
||||
What it does is to test whether the given previous value is equal to the value of the key, if equal etcd will change the value of the key to the given value.
|
||||
The basic logic is to test whether the given previous value is equal to the value of the key, if equal etcd will change the value of the key to the given value.
|
||||
|
||||
Here is a simple example.
|
||||
Let us create a key-value pair first: `testAndSet=one`.
|
||||
Here is a simple example. Let's create a key-value pair first: `testAndSet=one`.
|
||||
|
||||
```sh
|
||||
curl http://127.0.0.1:4001/v1/keys/testAndSet -d value=one
|
||||
```
|
||||
|
||||
Let us try a invaild `TestAndSet` command.
|
||||
Let's try an invaild `TestAndSet` command.
|
||||
|
||||
```sh
|
||||
curl http://127.0.0.1:4001/v1/testAndSet/testAndSet -d prevValue=two -d value=three
|
||||
|
@ -160,8 +173,6 @@ curl http://127.0.0.1:4001/v1/testAndSet/testAndSet -d prevValue=two -d value=th
|
|||
|
||||
This will try to test if the previous of the key is two, it is change it to three.
|
||||
|
||||
The response should be
|
||||
|
||||
```html
|
||||
Test one==two fails
|
||||
```
|
||||
|
@ -180,7 +191,7 @@ The response should be
|
|||
{"action":"SET","key":"/testAndSet","prevValue":"one","value":"two","index":10}
|
||||
```
|
||||
|
||||
We successfully change the value from “one” to “two”, since we give the correct previous value.
|
||||
We successfully changed the value from “one” to “two”, since we give the correct previous value.
|
||||
|
||||
|
||||
#### Listing directory
|
||||
|
@ -213,11 +224,9 @@ which meas `foo=barbar` is a key-value pair under `/foo` and `foo_dir` is a dire
|
|||
|
||||
### Setting up a cluster of three machines
|
||||
|
||||
Next we can explore the power of etcd cluster. We use go-raft as the underlay distributed protocol which provide consistency and persistence of all the machines in the cluster. The will allow if the minor machine dies, the cluster will still be able to performance correctly. Also if most of the machines dead and restart, we will recover from the previous state of the cluster.
|
||||
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.
|
||||
|
||||
Let us create 3 new machines.
|
||||
|
||||
The first one will be
|
||||
Let start by creating 3 new etcd instances.
|
||||
|
||||
We use -s to specify server port and -c to specify client port and -d to specify the directory to store the log and info of the node in the cluster
|
||||
|
||||
|
@ -225,21 +234,14 @@ We use -s to specify server port and -c to specify client port and -d to specify
|
|||
./etcd -s 7001 -c 4001 -d nodes/node1
|
||||
```
|
||||
|
||||
We use -C to specify the Cluster
|
||||
|
||||
Let the second one join it.
|
||||
Let the join two more nodes to this cluster using the -C argument:
|
||||
|
||||
```sh
|
||||
./etcd -c 4002 -s 7002 -C 127.0.0.1:7001 -d nod/node2
|
||||
```
|
||||
|
||||
And the third one:
|
||||
|
||||
```sh
|
||||
./etcd -c 4003 -s 7003 -C 127.0.0.1:7001 -d nod/node3
|
||||
```
|
||||
|
||||
Let us add a key to the cluster of 3 nodes.
|
||||
Now we can do normal SET and GET operations on keys as we explored earlier.
|
||||
|
||||
```sh
|
||||
curl http://127.0.0.1:4001/v1/keys/foo -d value=bar
|
||||
|
@ -249,17 +251,15 @@ curl http://127.0.0.1:4001/v1/keys/foo -d value=bar
|
|||
{"action":"SET","key":"/foo","value":"bar","newKey":true,"index":5}
|
||||
```
|
||||
|
||||
Let us kill the leader of the cluster to see what will happen.
|
||||
#### Killing Nodes in the Cluster
|
||||
|
||||
Kill the first node which is the current leader
|
||||
|
||||
Try to get the value from the other machine
|
||||
Let's kill the leader of the cluster and get the value from the other machine:
|
||||
|
||||
```sh
|
||||
curl http://127.0.0.1:4002/v1/keys/foo
|
||||
```
|
||||
|
||||
You should be able to see this
|
||||
You should be able to see this:
|
||||
|
||||
```json
|
||||
{"action":"GET","key":"/foo","value":"bar","index":5}
|
||||
|
@ -267,14 +267,15 @@ You should be able to see this
|
|||
|
||||
It succeed!
|
||||
|
||||
OK. Next let us kill all the nodes to test persistence. And restart all the nodes use the same command before.
|
||||
#### Testing Persistence
|
||||
|
||||
Try
|
||||
OK. Next let us kill all the nodes to test persistence. And restart all the nodes use the same command as before.
|
||||
|
||||
Your request for the `foo` key will return the correct value:
|
||||
|
||||
```sh
|
||||
curl http://127.0.0.1:4002/v1/keys/foo
|
||||
```
|
||||
You should able to see
|
||||
|
||||
```json
|
||||
{"action":"GET","key":"/foo","value":"bar","index":5}
|
||||
|
|
Loading…
Reference in New Issue