Switch to KV CLI in getting started
This commit is contained in:
Seth Vargo
parent
dc64fb64af
commit
52637b1125
|
|
@ -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{
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue