115 lines
4.3 KiB
Markdown
115 lines
4.3 KiB
Markdown
---
|
|
layout: "intro"
|
|
page_title: "Key/Value Data"
|
|
sidebar_current: "gettingstarted-kv"
|
|
---
|
|
|
|
# Key/Value Data
|
|
|
|
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.
|
|
|
|
## 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:
|
|
|
|
```
|
|
$ ./bin/consul agent -server -bootstrap -data-dir /tmp/consul
|
|
...
|
|
```
|
|
|
|
Now, we can verify that our K/V store contains no keys:
|
|
|
|
```
|
|
$ curl -v http://localhost:8500/v1/kv/?recurse
|
|
* About to connect() to localhost port 8500 (#0)
|
|
* Trying 127.0.0.1... connected
|
|
> GET /v1/kv/?recurse HTTP/1.1
|
|
> User-Agent: curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3
|
|
> Host: localhost:8500
|
|
> Accept: */*
|
|
>
|
|
< HTTP/1.1 404 Not Found
|
|
< X-Consul-Index: 1
|
|
< Date: Fri, 11 Apr 2014 02:10:28 GMT
|
|
< Content-Length: 0
|
|
< Content-Type: text/plain; charset=utf-8
|
|
<
|
|
* Connection #0 to host localhost left intact
|
|
* Closing connection #0
|
|
```
|
|
|
|
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
|
|
true
|
|
$ curl -X PUT -d 'test' http://localhost:8500/v1/kv/web/key2?flags=42
|
|
true
|
|
$ curl -X PUT -d 'test' http://localhost:8500/v1/kv/web/sub/key3
|
|
true
|
|
$ curl http://localhost:8500/v1/kv/?recurse
|
|
[{"CreateIndex":97,"ModifyIndex":97,"Key":"web/key1","Flags":0,"Value":"dGVzdA=="},
|
|
{"CreateIndex":98,"ModifyIndex":98,"Key":"web/key2","Flags":42,"Value":"dGVzdA=="},
|
|
{"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.
|
|
|
|
Above we retrieved multiple keys using the "?recurse" query parameter, but fetching
|
|
a single key is done by providing the path alone:
|
|
|
|
```
|
|
$ 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":
|
|
|
|
```
|
|
$ curl -X DELETE http://localhost:8500/v1/kv/web/sub?recurse
|
|
$ curl http://localhost:8500/v1/kv/web?recurse
|
|
[{"CreateIndex":97,"ModifyIndex":97,"Key":"web/key1","Flags":0,"Value":"dGVzdA=="},
|
|
{"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":
|
|
|
|
```
|
|
$ curl -X PUT -d 'newval' http://localhost:8500/v1/kv/web/key1?cas=97
|
|
true
|
|
$ curl -X PUT -d 'newval' http://localhost:8500/v1/kv/web/key1?cas=97
|
|
false
|
|
```
|
|
|
|
In this case, the first CAS update succeeds because the last modify time is 97.
|
|
However the second operation fails because the `ModifyIndex` is no longer 97.
|
|
|
|
We can also make use of the `ModifyIndex` to wait for a key's value to change.
|
|
For example, suppose we wanted to wait for key2 to be modified:
|
|
|
|
```
|
|
$ curl "http://localhost:8500/v1/kv/web/key2?index=101&wait=5s"
|
|
[{"CreateIndex":98,"ModifyIndex":101,"Key":"web/key2","Flags":42,"Value":"dGVzdA=="}]
|
|
```
|
|
|
|
By providing "?index=" we are asking to wait until the key has a `ModifyIndex` greater
|
|
than 101. However the "?wait=5s" parameter restricts the query to at most 5 seconds,
|
|
returning the current, unchanged value. This can be used to efficiently wait for
|
|
key modifications. Additionally, this same technique can be used to wait for a list
|
|
of keys, waiting only until any of the keys has a newer modification time.
|
|
|
|
This is only a few example of what the API supports. For full documentation, please
|
|
reference the [HTTP API](/docs/agent/http.html).
|
|
|