124 lines
4.9 KiB
Markdown
124 lines
4.9 KiB
Markdown
---
|
|
layout: "intro"
|
|
page_title: "Key/Value Data"
|
|
sidebar_current: "gettingstarted-kv"
|
|
description: |-
|
|
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 enable anything else a developer can think to build.
|
|
---
|
|
|
|
# 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 enable anything else a developer can think to build.
|
|
|
|
This step 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.
|
|
|
|
Querying the local agent we started in the [Run the Agent step](agent.html),
|
|
we can first verify that there are no existing keys in the k/v store:
|
|
|
|
```text
|
|
$ 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 allow non-UTF8 characters. For the
|
|
key "web/key2", we set a `flag` value of 42. All keys support setting a 64-bit
|
|
integer flag value. This is not used internally by Consul, but it can be used by
|
|
clients to add meaningful metadata to any KV.
|
|
|
|
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:
|
|
|
|
```text
|
|
$ 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, accomplished by using the `DELETE` verb. We can
|
|
delete a single key by specifying the full path, or we can recursively delete all
|
|
keys under a root using "?recurse":
|
|
|
|
```text
|
|
$ 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 modified by issuing a `PUT` request to the same URI and
|
|
providing a different message body. Additionally, Consul provides a
|
|
Check-And-Set operation, enabling atomic key updates. This is done by
|
|
providing the `?cas=` parameter with the last `ModifyIndex` value from
|
|
the GET request. For example, suppose we wanted to update "web/key1":
|
|
|
|
```text
|
|
$ 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 `ModifyIndex` 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:
|
|
|
|
```text
|
|
$ 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.
|
|
|
|
## Next Steps
|
|
|
|
These are only a few examples of what the API supports. For full documentation, please
|
|
see [the /kv/ route of the HTTP API](/docs/agent/http/kv.html).
|
|
|
|
Next, we will look at the [web UI](ui.html) options supported by Consul.
|