From 52637b1125953586391a837ea172811ce92e026b Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Wed, 7 Dec 2016 14:01:48 -0800 Subject: [PATCH] Switch to KV CLI in getting started --- website/source/assets/stylesheets/_docs.scss | 9 +- .../intro/getting-started/kv.html.markdown | 177 +++++++++--------- 2 files changed, 99 insertions(+), 87 deletions(-) diff --git a/website/source/assets/stylesheets/_docs.scss b/website/source/assets/stylesheets/_docs.scss index 0a9d3a2d8..98a67644d 100755 --- a/website/source/assets/stylesheets/_docs.scss +++ b/website/source/assets/stylesheets/_docs.scss @@ -200,8 +200,15 @@ body.layout-intro{ text-decoration: none; } - pre{ + pre { margin: 0 0 18px; + + // This will force the code to scroll horizontally on small screens + // instead of wrapping. + code { + overflow-wrap: normal; + white-space: pre; + } } a{ diff --git a/website/source/intro/getting-started/kv.html.markdown b/website/source/intro/getting-started/kv.html.markdown index acd9c6fbb..28b8784f8 100644 --- a/website/source/intro/getting-started/kv.html.markdown +++ b/website/source/intro/getting-started/kv.html.markdown @@ -17,113 +17,118 @@ 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. +To demonstrate how simple it is to get started, we will manipulate a few keys in +the K/V store. There are two ways to interact with the Consul KV store: via the +HTTP API and via the Consul KV CLI. The examples below show using the Consul KV +CLI because it is the easiest to get started. For more advanced integrations, +you may want to use the [Consul KV HTTP API][kv-api] -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: +First let us explore the KV store. We can ask Consul for the value of the key at +the path named `redis/config/minconns`: -Also check https://www.hashicorp.com/blog/consul-kv-cli.html for using the 'consul kv' from -the commandline. - -```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 +```sh +$ consul kv get redis/config/minconns +Error! No key exists at: redis/config/minconns ``` -Since there are no keys, we get a 404 response back. Now, we can `PUT` a -few example keys: +As you can see, we get no result, which makes sense because there is no data in +the KV store. Next we can insert or "put" values into the KV store. -``` -$ 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=="}] +```sh +$ consul kv put redis/config/minconns 1 +Success! Data written to: redis/config/minconns + +$ consul kv put redis/config/maxconns 25 +Success! Data written to: redis/config/maxconns + +$ consul kv put -flags=42 redis/config/users/admin abcd1234 +Success! Data written to: redis/config/users/admin ``` -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. +Now that we have keys in the store, we can query for the value of individual +keys: -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=="}] +```sh +$ consul kv get redis/config/minconns +1 ``` -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": +Consul retains additional metadata about the field, which is retrieved using the +`-detailed` flag: -```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=="}] +```sh +$ consul kv get -detailed redis/config/minconns +CreateIndex 207 +Flags 0 +Key redis/config/minconns +LockIndex 0 +ModifyIndex 207 +Session - +Value 1 ``` -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": +For the key "redis/config/users/admin", 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. -```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 +It is possible to list all the keys in the store using the `recurse` options. +Results will be returned in lexicographical order: + +```sh +$ consul kv get -recurse +redis/config/maxconns:25 +redis/config/minconns:1 +redis/config/users/admin:abcd1234 ``` -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. +To delete a key from the Consul KV store, issue a "delete" call: -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=="}] +```sh +$ consul kv delete redis/config/minconns +Success! Deleted key: redis/config/minconns ``` -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. +It is also possible to delete an entire prefix using the `recurse` option: + +```sh +$ consul kv delete -recurse redis +Success! Deleted keys with prefix: redis +``` + +To update the value of an existing key, "put" a value at the same path: + +```sh +$ consul kv put foo bar + +$ consul kv get foo +bar + +$ consul kv put foo zip + +$ consul kv get foo +zip +``` + +Consul can provide atomic key updates using a Check-And_set operation. To perform a CAS operation, specify the `-cas` flag: + +```sh +$ consul kv put -cas -modify-index=123 foo bar +Success! Data written to: foo + +$ consul kv put -cas -modify-index=123 foo bar +Error! Did not write to foo: CAS failed +``` + +In this case, the first CAS update succeeds because the index is 123. The second +operation fails because the index is no longer 123. ## 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). +These are only a few examples of what the API supports. For the complete +documentation, please see [Consul KV HTTP API][kv-api] or +[Consul KV CLI][kv-cli] documentation. -Next, we will look at the [web UI](ui.html) options supported by Consul. +Next, we will look at the [web UI](ui.html) options supported by Consul. -Also check https://www.hashicorp.com/blog/consul-kv-cli.html for using the 'consul kv' from -the commandline. +[kv-api]: /docs/agent/http/kv.html +[kv-cli]: /docs/commands/kv.html