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 #692 from ryanbreen/kv 

Website: cleanup of docs/agent/http/kv
This commit is contained in:
Armon Dadgar 2015-02-12 16:53:49 -08:00
parent a82bbb6561 22162efccf
commit 20e936ead7
1 changed files with 55 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

105
website/source/docs/agent/http/kv.html.markdown
View File

@ -3,36 +3,37 @@ layout: "docs"
page_title: "Key/Value store (HTTP)" page_title: "Key/Value store (HTTP)"
sidebar_current: "docs-agent-http-kv" sidebar_current: "docs-agent-http-kv"
description: > description: >
The KV endpoint is used to expose a simple key/value store. This can be used The KV endpoint is used to access Consul's simple key/value store, useful for storing
to store service configurations or other meta data in a simple way. service configuration or other metadata.
--- ---
# Key/Value HTTP Endpoint # Key/Value HTTP Endpoint
The KV endpoint is used to expose a simple key/value store. This can be used The KV endpoint is used to access Consul's simple key/value store, useful for storing
to store service configurations or other meta data in a simple way. It has only service configuration or other metadata.
a single endpoint:
It has only a single endpoint:
/v1/kv/<key> /v1/kv/<key>
This is the only endpoint that is used with the Key/Value store. The `GET`, `PUT` and `DELETE` methods are all supported.
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.
If you are interested in Key/Value replication between datacenters, By default, the datacenter of the agent is queried; however, the dc can be provided
look at the [consul-replicate project](https://github.com/hashicorp/consul-replicate). 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 in 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 ### GET Method
When using the `GET` method, Consul will return the specified key, When using the `GET` method, Consul will return the specified key.
or if the "?recurse" query parameter is provided, it will return If the "?recurse" query parameter is provided, it will return
all keys with the given prefix. all keys with the given prefix.
This endpoint supports blocking queries and all consistency modes.
Each object will look like: Each object will look like:
```javascript ```javascript
@ -49,24 +50,31 @@ Each object will look like:
] ]
``` ```
The `CreateIndex` is the internal index value that represents `CreateIndex` is the internal index value that represents
when the entry was created. The `ModifyIndex` is the last index when the entry was created.
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.
The `Key` is simply the full path of the entry. `Flags` are an opaque `ModifyIndex` is the last index that modified this key. This index corresponds
unsigned integer that can be attached to each entry. The use of this is to the `X-Consul-Index` header value that is returned in responses, and it can
left totally to the user. The `Value` is a base64 key value. 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 `LockIndex` is the last index of a successful lock acquisition. If the lock is
"?keys" query parameter along with a `GET` request. This will return held, the `Session` key provides the session that owns the lock.
a list of the keys under the given prefix. The optional "?separator="
can be used to list only up to a given separator. `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: 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 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, 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. encoding.
If no entries are found, a 404 code is returned. If no entries are found, a 404 code is returned.
This endpoint supports blocking queries and all consistency modes.
### PUT method ### PUT method
When using the `PUT` method, Consul expects the request body to be the 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: be used with a PUT request:
* ?flags=\<num\> : This can be used to specify an unsigned value between * ?flags=\<num\> : 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 0 and 2^64-1. Clients can choose to use this however makes sense for their application.
use it.
* ?cas=\<index\> : This flag is used to turn the `PUT` into a Check-And-Set * ?cas=\<index\> : 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 operation. This is very useful as a building block for more complex
synchronization primitives on top. If the index is 0, then Consul will only 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, then 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. the key is only set if the index matches the `ModifyIndex` of that key.
* ?acquire=\<session\> : This flag is used to turn the `PUT` into a lock acquisition * ?acquire=\<session\> : 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 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. `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, The return value is either `true` or `false`. If `false` is returned,
then the update has not taken place. the update has not taken place.
### DELETE method ### DELETE method
The `DELETE` method can be used to delete a single key or all keys sharing 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: DELETE request:
* ?recurse : This is used to delete all keys which have the specified prefix. * ?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. Without this, only a key with an exact match will be deleted.
* ?cas=\<index\> : This flag is used to turn the `DELETE` into a Check-And-Set * ?cas=\<index\> : 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 operation. This is very useful as a building block for more complex
synchronization primitives on top. If the index is 0, then Consul will only synchronization primitives. Unlike `PUT`, the index must be greater than 0
delete the key if it does not already exist (noop). If the index is non-zero, then for Consul to take any action: a 0 index will not delete the key. If the index
the key is only deleted if the index matches the `ModifyIndex` of that key. is non-zero, the key is only deleted if the index matches the `ModifyIndex` of that key.