From 1b6b1e09bd631d04b3f36f59f8774ef1954152e0 Mon Sep 17 00:00:00 2001 From: Ryan Breen Date: Wed, 11 Feb 2015 21:54:03 -0500 Subject: [PATCH] Website: cleanup of docs/agent/http/kv --- .../source/docs/agent/http/kv.html.markdown | 105 +++++++++--------- 1 file changed, 55 insertions(+), 50 deletions(-) diff --git a/website/source/docs/agent/http/kv.html.markdown b/website/source/docs/agent/http/kv.html.markdown index ef5b581980..3d2bff2d3d 100644 --- a/website/source/docs/agent/http/kv.html.markdown +++ b/website/source/docs/agent/http/kv.html.markdown @@ -3,36 +3,37 @@ layout: "docs" page_title: "Key/Value store (HTTP)" sidebar_current: "docs-agent-http-kv" description: > - The KV endpoint is used to expose a simple key/value store. This can be used - to store service configurations or other meta data in a simple way. + The KV endpoint is used to access Consul's simple key/value store, useful for storing + service configurations or other metadata. --- # Key/Value HTTP Endpoint -The KV endpoint is used to expose a simple key/value store. This can be used -to store service configurations or other meta data in a simple way. It has only -a single endpoint: +The KV endpoint is used to access Consul's simple key/value store, useful for storing +service configurations or other metadata. + +It has only a single endpoint: /v1/kv/ -This is the only endpoint that is used with the Key/Value store. -Its use depends on the HTTP method. The `GET`, `PUT` and `DELETE` methods -are all supported. It is important to note that each datacenter has its -own K/V store, and that there is no replication between datacenters. -By default the datacenter of the agent is queried, however the dc can -be provided using the "?dc=" query parameter. If a client wants to write -to all Datacenters, one request per datacenter must be made. The KV endpoint -supports the use of ACL tokens. +The `GET`, `PUT` and `DELETE` methods are all supported. -If you are interested in Key/Value replication between datacenters, -look at the [consul-replicate project](https://github.com/hashicorp/consul-replicate). +By default the datacenter of the agent is queried; however, the dc can be provided +using the "?dc=" query parameter. It is important to note that each datacenter has +its own KV store, and there is no built-in replication between datacenters. If you +are interested replication between datacenters, look at the +[consul-replicate project](https://github.com/hashicorp/consul-replicate). + +The KV endpoint supports the use of ACL tokens. ### GET Method -When using the `GET` method, Consul will return the specified key, -or if the "?recurse" query parameter is provided, it will return +When using the `GET` method, Consul will return the specified key. +If the "?recurse" query parameter is provided, it will return all keys with the given prefix. +This endpoint supports blocking queries and all consistency modes. + Each object will look like: ```javascript @@ -49,24 +50,31 @@ Each object will look like: ] ``` -The `CreateIndex` is the internal index value that represents -when the entry was created. The `ModifyIndex` is the last index -that modified this key. This index corresponds to the `X-Consul-Index` -header value that is returned. A blocking query can be used to wait for -a value to change. If "?recurse" is used, the `X-Consul-Index` corresponds -to the latest `ModifyIndex` and so a blocking query waits until any of the -listed keys are updated. The `LockIndex` is the last index of a successful -lock acquisition. If the lock is held, the `Session` key provides the -session that owns the lock. +`CreateIndex` is the internal index value that represents +when the entry was created. -The `Key` is simply the full path of the entry. `Flags` are an opaque -unsigned integer that can be attached to each entry. The use of this is -left totally to the user. The `Value` is a base64 key value. +`ModifyIndex` is the last index that modified this key. This index corresponds +to the `X-Consul-Index` header value that is returned in responses, and it can +be used to establish blocking queries by setting the "?index" query parameter. +You can even perform blocking queries against entire subtrees of the KV store: +if "?recurse" is provided, the returned `X-Consul-Index` corresponds +to the latest `ModifyIndex` within the prefix, and a blocking query using that +"?index" will wait until any key within that prefix is updated. -It is possible to also only list keys without their values by using the -"?keys" query parameter along with a `GET` request. This will return -a list of the keys under the given prefix. The optional "?separator=" -can be used to list only up to a given separator. +`LockIndex` is the last index of a successful lock acquisition. If the lock is +held, the `Session` key provides the session that owns the lock. + +`Key` is simply the full path of the entry. + +`Flags` are an opaque unsigned integer that can be attached to each entry. Clients +can choose to use this however makes sense for their application. + +`Value` is a Base64-encoded blob of data. Note that values cannot be larger than +512kB. + +It is possible to list just keys without their values by using the "?keys" query +parameter. This will return a list of the keys under the given prefix. The optional +"?separator=" can be used to list only up to a given separator. For example, listing "/web/" with a "/" separator may return: @@ -79,30 +87,27 @@ For example, listing "/web/" with a "/" separator may return: ``` Using the key listing method may be suitable when you do not need -the values or flags, or want to implement a key-space explorer. +the values or flags or want to implement a key-space explorer. If the "?raw" query parameter is used with a non-recursive GET, -then the response is just the raw value of the key, without any +the response is just the raw value of the key, without any encoding. If no entries are found, a 404 code is returned. -This endpoint supports blocking queries and all consistency modes. - ### PUT method When using the `PUT` method, Consul expects the request body to be the -value corresponding to the key. There are a number of parameters that can +value corresponding to the key. There are a number of query parameters that can be used with a PUT request: * ?flags=\ : This can be used to specify an unsigned value between - 0 and 2^64-1. It is opaque to the user, but a client application may - use it. + 0 and 2^64-1. Clients can choose to use this however makes sense for their application. * ?cas=\ : This flag is used to turn the `PUT` into a Check-And-Set - operation. This is very useful as it allows clients to build more complex - synchronization primitives on top. If the index is 0, then Consul will only - put the key if it does not already exist. If the index is non-zero, then + operation. This is very useful as a building block for more complex + synchronization primitives. If the index is 0, Consul will only + put the key if it does not already exist. If the index is non-zero, the key is only set if the index matches the `ModifyIndex` of that key. * ?acquire=\ : This flag is used to turn the `PUT` into a lock acquisition @@ -116,20 +121,20 @@ be used with a PUT request: yield a lock. This will leave the `LockIndex` unmodified but will clear the associated `Session` of the key. The key must be held by this session to be unlocked. -The return value is simply either `true` or `false`. If `false` is returned, -then the update has not taken place. +The return value is either `true` or `false`. If `false` is returned, +the update has not taken place. ### DELETE method The `DELETE` method can be used to delete a single key or all keys sharing -a prefix. There are a number of query parameters that can be used with a +a prefix. There are a few query parameters that can be used with a DELETE request: * ?recurse : This is used to delete all keys which have the specified prefix. Without this, only a key with an exact match will be deleted. * ?cas=\ : This flag is used to turn the `DELETE` into a Check-And-Set - operation. This is very useful as it allows clients to build more complex - synchronization primitives on top. If the index is 0, then Consul will only - delete the key if it does not already exist (noop). If the index is non-zero, then - the key is only deleted if the index matches the `ModifyIndex` of that key. + operation. This is very useful as a building block for more complex + synchronization primitives. Unlike `PUT`, the index must be greater than 0 + for Consul to take any action: a 0 index will not delete the key. If the index + is non-zero, the key is only deleted if the index matches the `ModifyIndex` of that key.