luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

website: k/v getting started

This commit is contained in:
Mitchell Hashimoto 2014-04-14 14:05:27 -07:00
parent 0932deafa3
commit 20a0b00cea
1 changed files with 25 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
website/source/intro/getting-started/kv.html.markdown
View File

@ -9,20 +9,18 @@ sidebar_current: "gettingstarted-kv"
In addition to providing service discovery and integrated health checking,
Consul provides an easy to use Key/Value store. This can be used to hold
dynamic configuration, assist in service coordination, build leader election,
and any thing else a developer can think to build. The [HTTP API](/docs/agent/http.html) fully
documents the features of the K/V store.
and anything else a developer can think to build. The
[HTTP API](/docs/agent/http.html) fully documents the features of the K/V store.
This page assumes you have at least one Consul agent already running.
## Simple Usage
To demonstrate how simple it is to get started, we will manipulate a few keys
in the K/V store. We get started by first starting an agent in server mode:
in the K/V store.
```
$ ./bin/consul agent -server -bootstrap -data-dir /tmp/consul
...
```
Now, we can verify that our K/V store contains no keys:
Querying the agent we started in a prior page, we can first verify that
there are no existing keys in the k/v store:
```
$ curl -v http://localhost:8500/v1/kv/?recurse
@ -43,7 +41,8 @@ $ curl -v http://localhost:8500/v1/kv/?recurse
* Closing connection #0
```
Since there are no keys, we get a 404 response back. Now, we can put a few example keys:
Since there are no keys, we get a 404 response back.
Now, we can put a few example keys:
```
$ curl -X PUT -d 'test' http://localhost:8500/v1/kv/web/key1
@ -58,21 +57,24 @@ $ curl http://localhost:8500/v1/kv/?recurse
{"CreateIndex":99,"ModifyIndex":99,"Key":"web/sub/key3","Flags":0,"Value":"dGVzdA=="}]
```
Here we have created 3 keys, each with the value of "test". Note that the `Value` field
returned is base64 encoded to encode non UTF8 characters. For the "web/key2" key, we set
a `flag` value of 42. All keys support setting a 64bit integer flag value. This is opaque
to Consul but can be used by clients.
Here we have created 3 keys, each with the value of "test". Note that the
`Value` field returned is base64 encoded to encode allow for non-UTF8
characters. For the "web/key2" key, we set a `flag` value of 42. All keys
support setting a 64bit integer flag value. This is opaque to Consul but can
be used by clients for any purpose.
Above we retrieved multiple keys using the "?recurse" query parameter, but fetching
a single key is done by providing the path alone:
After setting the values, we then issued a GET request to retrieve multiple
keys using the `?recurse` parameter.
You can also fetch a single key just as easily:
```
$ curl http://localhost:8500/v1/kv/web/key1
[{"CreateIndex":97,"ModifyIndex":97,"Key":"web/key1","Flags":0,"Value":"dGVzdA=="}]
```
Deleting keys is simple as well. We can delete a single key by specifying the full
path, or we can recursively delete all keys under a root using "?recurse":
Deleting keys is simple as well. We can delete a single key by specifying the
full path, or we can recursively delete all keys under a root using "?recurse":
```
$ curl -X DELETE http://localhost:8500/v1/kv/web/sub?recurse
@ -81,9 +83,11 @@ $ curl http://localhost:8500/v1/kv/web?recurse
{"CreateIndex":98,"ModifyIndex":98,"Key":"web/key2","Flags":42,"Value":"dGVzdA=="}]
```
A key can be updated by setting a new value. Additionally, Consul provides a Check-And-Set
operation, that enables an atomic key update. This is done by providing the "?cas=" parameter
with the last `ModifyIndex` value. For example, suppose we wanted to update "web/key1":
A key can be updated by setting a new value by issuing the same PUT request.
Additionally, Consul provides a Check-And-Set operation, enabling atomic
key updates. This is done by providing the `?cas=` paramter with the last
`ModifyIndex` value from the GET request. For example, suppose we wanted
to update "web/key1":
```
$ curl -X PUT -d 'newval' http://localhost:8500/v1/kv/web/key1?cas=97