diff --git a/website/source/intro/getting-started/kv.html.markdown b/website/source/intro/getting-started/kv.html.markdown index c87221073..191b8443e 100644 --- a/website/source/intro/getting-started/kv.html.markdown +++ b/website/source/intro/getting-started/kv.html.markdown @@ -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