github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Website: cleanup for intro/getting-started/kv.html.

Browse Source
pull/799/head
Ryan Breen 10 years ago
parent 8920da59ee
commit 823b707011
1 changed files with 28 additions and 24 deletions
Show Stats Download Patch File Download Diff File

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

@ -3,7 +3,7 @@ layout: "intro"
page_title: "Key/Value Data" page_title: "Key/Value Data"
sidebar_current: "gettingstarted-kv" sidebar_current: "gettingstarted-kv"
description: |- 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 anything else a developer can think to build. 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 # Key/Value Data
@ -11,18 +11,17 @@ description: |-
In addition to providing service discovery and integrated health checking, 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 Consul provides an easy to use Key/Value store. This can be used to hold
dynamic configuration, assist in service coordination, build leader election, dynamic configuration, assist in service coordination, build leader election,
and anything else a developer can think to build. The and enable anything else a developer can think to build.
[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. This step assumes you have at least one Consul agent already running.
## Simple Usage ## Simple Usage
To demonstrate how simple it is to get started, we will manipulate a few keys To demonstrate how simple it is to get started, we will manipulate a few keys
in the K/V store. in the K/V store.
Querying the agent we started in a prior page, we can first verify that Querying the local agent we started in the [Run the Agent step](agent.html),
there are no existing keys in the k/v store: we can first verify that there are no existing keys in the k/v store:
```text ```text
$ curl -v http://localhost:8500/v1/kv/?recurse $ curl -v http://localhost:8500/v1/kv/?recurse
@ -43,8 +42,8 @@ $ curl -v http://localhost:8500/v1/kv/?recurse
* Closing connection #0 * Closing connection #0
``` ```
Since there are no keys, we get a 404 response back. Since there are no keys, we get a 404 response back. Now, we can `PUT` a
Now, we can put a few example keys: few example keys:
``` ```
$ curl -X PUT -d 'test' http://localhost:8500/v1/kv/web/key1 $ curl -X PUT -d 'test' http://localhost:8500/v1/kv/web/key1
@ -60,12 +59,12 @@ $ curl http://localhost:8500/v1/kv/?recurse
``` ```
Here we have created 3 keys, each with the value of "test". Note that the 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 `Value` field returned is base64 encoded to allow non-UTF8 characters. For the
characters. For the "web/key2" key, we set a `flag` value of 42. All keys key "web/key2", we set a `flag` value of 42. All keys support setting a 64-bit
support setting a 64-bit integer flag value. This is opaque to Consul but can integer flag value. This is not used internally by Consul, but it can be used by
be used by clients for any purpose. clients to add meaningful metadata to any KV.
After setting the values, we then issued a GET request to retrieve multiple After setting the values, we then issued a `GET` request to retrieve multiple
keys using the `?recurse` parameter. keys using the `?recurse` parameter.
You can also fetch a single key just as easily: You can also fetch a single key just as easily:
@ -75,8 +74,9 @@ $ curl http://localhost:8500/v1/kv/web/key1
[{"CreateIndex":97,"ModifyIndex":97,"Key":"web/key1","Flags":0,"Value":"dGVzdA=="}] [{"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 Deleting keys is simple as well, accomplished by using the `DELETE` verb. We can
full path, or we can recursively delete all keys under a root using "?recurse": delete a single key by specifying the full path, or we can recursively delete all
keys under a root using "?recurse":
```text ```text
$ curl -X DELETE http://localhost:8500/v1/kv/web/sub?recurse $ curl -X DELETE http://localhost:8500/v1/kv/web/sub?recurse
@ -85,11 +85,11 @@ $ curl http://localhost:8500/v1/kv/web?recurse
{"CreateIndex":98,"ModifyIndex":98,"Key":"web/key2","Flags":42,"Value":"dGVzdA=="}] {"CreateIndex":98,"ModifyIndex":98,"Key":"web/key2","Flags":42,"Value":"dGVzdA=="}]
``` ```
A key can be updated by setting a new value by issuing the same PUT request. A key can be modified by issuing a `PUT` request to the same URI and
Additionally, Consul provides a Check-And-Set operation, enabling atomic providing a different message body. Additionally, Consul provides a
key updates. This is done by providing the `?cas=` parameter with the last Check-And-Set operation, enabling atomic key updates. This is done by
`ModifyIndex` value from the GET request. For example, suppose we wanted providing the `?cas=` parameter with the last `ModifyIndex` value from
to update "web/key1": the GET request. For example, suppose we wanted to update "web/key1":
```text ```text
$ curl -X PUT -d 'newval' http://localhost:8500/v1/kv/web/key1?cas=97 $ curl -X PUT -d 'newval' http://localhost:8500/v1/kv/web/key1?cas=97
@ -98,7 +98,7 @@ $ curl -X PUT -d 'newval' http://localhost:8500/v1/kv/web/key1?cas=97
false false
``` ```
In this case, the first CAS update succeeds because the last modify time is 97. 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. 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. We can also make use of the `ModifyIndex` to wait for a key's value to change.
@ -109,11 +109,15 @@ $ curl "http://localhost:8500/v1/kv/web/key2?index=101&wait=5s"
[{"CreateIndex":98,"ModifyIndex":101,"Key":"web/key2","Flags":42,"Value":"dGVzdA=="}] [{"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 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, 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 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 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. of keys, waiting only until any of the keys has a newer modification time.
These are only a few examples of what the API supports. For full ## Next Steps
documentation, please see the [HTTP API](/docs/agent/http.html).
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.

Write Preview
Loading…
Cancel
Save