status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #2580 from hashicorp/sethvargo/kv_main 

Switch to KV CLI in getting started
This commit is contained in:
Seth Vargo 2016-12-07 14:42:13 -08:00 committed by GitHub
parent 406a868277 bdb318a3ef
commit e026bf2551
2 changed files with 99 additions and 87 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
website/source/assets/stylesheets/_docs.scss
View File

@ -200,8 +200,15 @@ body.layout-intro{
text-decoration: none; text-decoration: none;
} }
pre{ pre {
margin: 0 0 18px; 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{ a{

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

@ -17,113 +17,118 @@ 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
in the K/V store. 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), First let us explore the KV store. We can ask Consul for the value of the key at
we can first verify that there are no existing keys in the k/v store: the path named `redis/config/minconns`:
Also check https://www.hashicorp.com/blog/consul-kv-cli.html for using the 'consul kv' from ```sh
the commandline. $ consul kv get redis/config/minconns
Error! No key exists at: redis/config/minconns
```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 As you can see, we get no result, which makes sense because there is no data in
few example keys: the KV store. Next we can insert or "put" values into the KV store.
``` ```sh
$ curl -X PUT -d 'test' http://localhost:8500/v1/kv/web/key1 $ consul kv put redis/config/minconns 1
true Success! Data written to: redis/config/minconns
$ curl -X PUT -d 'test' http://localhost:8500/v1/kv/web/key2?flags=42
true $ consul kv put redis/config/maxconns 25
$ curl -X PUT -d 'test' http://localhost:8500/v1/kv/web/sub/key3 Success! Data written to: redis/config/maxconns
true
$ curl http://localhost:8500/v1/kv/?recurse $ consul kv put -flags=42 redis/config/users/admin abcd1234
[{"CreateIndex":97,"ModifyIndex":97,"Key":"web/key1","Flags":0,"Value":"dGVzdA=="}, Success! Data written to: redis/config/users/admin
{"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 Now that we have keys in the store, we can query for the value of individual
`Value` field returned is base64 encoded to allow non-UTF8 characters. For the keys:
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 ```sh
keys using the `?recurse` parameter. $ consul kv get redis/config/minconns
1
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 Consul retains additional metadata about the field, which is retrieved using the
delete a single key by specifying the full path, or we can recursively delete all `-detailed` flag:
keys under a root using "?recurse":
```text ```sh
$ curl -X DELETE http://localhost:8500/v1/kv/web/sub?recurse $ consul kv get -detailed redis/config/minconns
$ curl http://localhost:8500/v1/kv/web?recurse CreateIndex 207
[{"CreateIndex":97,"ModifyIndex":97,"Key":"web/key1","Flags":0,"Value":"dGVzdA=="}, Flags 0
{"CreateIndex":98,"ModifyIndex":98,"Key":"web/key2","Flags":42,"Value":"dGVzdA=="}] 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 For the key "redis/config/users/admin", we set a `flag` value of 42. All keys
providing a different message body. Additionally, Consul provides a support setting a 64-bit integer flag value. This is not used internally by
Check-And-Set operation, enabling atomic key updates. This is done by Consul, but it can be used by clients to add meaningful metadata to any KV.
providing the `?cas=` parameter with the last `ModifyIndex` value from
the GET request. For example, suppose we wanted to update "web/key1":
```text It is possible to list all the keys in the store using the `recurse` options.
$ curl -X PUT -d 'newval' http://localhost:8500/v1/kv/web/key1?cas=97 Results will be returned in lexicographical order:
true
$ curl -X PUT -d 'newval' http://localhost:8500/v1/kv/web/key1?cas=97 ```sh
false $ 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. To delete a key from the Consul KV store, issue a "delete" call:
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. ```sh
For example, suppose we wanted to wait for key2 to be modified: $ consul kv delete redis/config/minconns
Success! Deleted key: redis/config/minconns
```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 It is also possible to delete an entire prefix using the `recurse` option:
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 ```sh
key modifications. Additionally, this same technique can be used to wait for a list $ consul kv delete -recurse redis
of keys, waiting only until any of the keys has a newer modification time. 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 ## Next Steps
These are only a few examples of what the API supports. For full documentation, please These are only a few examples of what the API supports. For the complete
see [the /kv/ route of the HTTP API](/docs/agent/http/kv.html). 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 [kv-api]: /docs/agent/http/kv.html
the commandline. [kv-cli]: /docs/commands/kv.html