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

website: finishing up getting started

This commit is contained in:
Armon Dadgar 2014-04-10 19:27:48 -07:00
parent 79c07e8113
commit 859c489c61
2 changed files with 119 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -6,3 +6,109 @@ sidebar_current: "gettingstarted-kv"
# Key/Value Data # Key/Value Data
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.
## 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:
```
$ ./bin/consul agent -server -bootstrap -data-dir /tmp/consul
...
```
Now, we can verify that our K/V store contains no keys:
```
$ 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 few example keys:
```
$ 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=="}]
```
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.
Above we retrieved multiple keys using the "?recurse" query parameter, but fetching
a single key is done by providing the path alone:
```
$ 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":
```
$ 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=="}]
```
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":
```
$ 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
```
In this case, the first CAS update succeeds because the last modify time is 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.
For example, suppose we wanted to wait for key2 to be modified:
```
$ 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
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.
This is only a few example of what the API supports. For full documentation, please
reference the [HTTP API](/docs/agent/http.html).

25
website/source/intro/getting-started/next-steps.html.markdown
View File

@ -6,21 +6,22 @@ sidebar_current: "gettingstarted-nextsteps"
# Next Steps # Next Steps
That concludes the getting started guide for Serf. Hopefully you're able to That concludes the getting started guide for Consul. Hopefully you're able to
see that while Serf is an incredibly simple tool, it is also extremely see that while Consul is simple to use, it has a powerful set of features.
powerful. The dead simple membership information and events system that
Serf provides make up the building blocks of [incredible use cases](/intro/use-cases.html).
And because Serf is completely decentralized, fault tolerant, self-healing, Consul is designed to be friendly to both the DevOps community and
etc. it is a dream tool for system administrators and built specifically application developers, making it perfect for modern, elastic infrastructures.
for modern, elastic infrastructures.
As a next step, the following resources are available: As a next step, the following resources are available:
* [Documentation](/docs/index.html) - The documentation is an in-depth reference * [Documentation](/docs/index.html) - The documentation is an in-depth reference
guide to all the features of Serf, including technical details about the guide to all the features of Consul, including technical details about the
internals of how Serf operates. internals of how Consul operates.
* [Guides](/docs/guides/index.html) - This section provides various getting
started guides with Consul, including how to bootstrap a new datacenter.
* [Examples](https://github.com/hashicorp/consul/tree/master/demo) - The work-in-progress examples folder within the GitHub
repository for Consul contains functional examples of various use cases
of Consul to help you get started with exactly what you need.
* [Examples](https://github.com/hashicorp/serf/tree/master/demo) - The work-in-progress examples folder within the GitHub
repository for Serf contains functional examples of various use cases
of Serf to help you get started with exactly what you need.