diff --git a/website/source/intro/getting-started/kv.html.markdown b/website/source/intro/getting-started/kv.html.markdown index cae74e6d7b..c872210733 100644 --- a/website/source/intro/getting-started/kv.html.markdown +++ b/website/source/intro/getting-started/kv.html.markdown @@ -6,3 +6,109 @@ sidebar_current: "gettingstarted-kv" # 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). + diff --git a/website/source/intro/getting-started/next-steps.html.markdown b/website/source/intro/getting-started/next-steps.html.markdown index 0075c4341b..8d11833ffc 100644 --- a/website/source/intro/getting-started/next-steps.html.markdown +++ b/website/source/intro/getting-started/next-steps.html.markdown @@ -6,21 +6,22 @@ sidebar_current: "gettingstarted-nextsteps" # Next Steps -That concludes the getting started guide for Serf. Hopefully you're able to -see that while Serf is an incredibly simple tool, it is also extremely -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). +That concludes the getting started guide for Consul. Hopefully you're able to +see that while Consul is simple to use, it has a powerful set of features. -And because Serf is completely decentralized, fault tolerant, self-healing, -etc. it is a dream tool for system administrators and built specifically -for modern, elastic infrastructures. +Consul is designed to be friendly to both the DevOps community and +application developers, making it perfect for modern, elastic infrastructures. As a next step, the following resources are available: * [Documentation](/docs/index.html) - The documentation is an in-depth reference - guide to all the features of Serf, including technical details about the - internals of how Serf operates. + guide to all the features of Consul, including technical details about the + 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.