diff --git a/website/source/docs/agent/http.html.markdown b/website/source/docs/agent/http.html.markdown index 38936a14ba..20dfc5a54b 100644 --- a/website/source/docs/agent/http.html.markdown +++ b/website/source/docs/agent/http.html.markdown @@ -16,14 +16,14 @@ Each endpoint manages a different aspect of Consul: * [acl](http/acl.html) - Access Control Lists * [agent](http/agent.html) - Consul Agent -* [catalog](http/catalog.html) - Nodes and services -* [coordinate](http/coordinate.html) - Network coordinates +* [catalog](http/catalog.html) - Nodes and Services +* [coordinate](http/coordinate.html) - Network Coordinates * [event](http/event.html) - User Events -* [health](http/health.html) - Health checks -* [kv](http/kv.html) - Key/Value store +* [health](http/health.html) - Health Checks +* [kv](http/kv.html) - Key/Value Store * [query](http/query.html) - Prepared Queries * [session](http/session.html) - Sessions -* [status](http/status.html) - Consul system status +* [status](http/status.html) - Consul System Status Each of these is documented in detail at the links above. Consul also has a number of internal APIs which are purposely undocumented and subject to change. diff --git a/website/source/docs/agent/http/kv.html.markdown b/website/source/docs/agent/http/kv.html.markdown index d3cde07e3c..9d2f2def54 100644 --- a/website/source/docs/agent/http/kv.html.markdown +++ b/website/source/docs/agent/http/kv.html.markdown @@ -1,22 +1,29 @@ --- layout: "docs" -page_title: "Key/Value store (HTTP)" +page_title: "Key/Value Store (HTTP)" sidebar_current: "docs-agent-http-kv" description: > - The KV endpoint is used to access Consul's simple key/value store, useful for storing + The KV endpoints are used to access Consul's simple key/value store, useful for storing service configuration or other metadata. --- -# Key/Value HTTP Endpoint +# Key/Value Store Endpoints -The KV endpoint is used to access Consul's simple key/value store, useful for storing +The KV endpoints are used to access Consul's simple key/value store, useful for storing service configuration or other metadata. -It has only a single endpoint: +The following endpoints are supported: - /v1/kv/ +* [`/v1/kv/`](#single): Manages updates of individual keys, deletes of individual + keys or key prefixes, and fetches of individual keys or key prefixes +* [`/v1/txn`](#txn): Manages updates or fetches of multiple keys inside a single, + atomic transaction -The `GET`, `PUT` and `DELETE` methods are all supported. +### /v1/kv/<key> + +This endpoint manages updates of individual keys, deletes of individual keys or key +prefixes, and fetches of individual keys or key prefixes. The `GET`, `PUT` and +`DELETE` methods are all supported. 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 @@ -24,9 +31,9 @@ its own KV store, and there is no built-in replication between datacenters. If y 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. +The KV endpoint supports the use of ACL tokens using the "?token=" query parameter. -### GET Method +#### GET Method When using the `GET` method, Consul will return the specified key. If the "?recurse" query parameter is provided, it will return @@ -67,7 +74,7 @@ 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 +`Flags` is 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 @@ -96,7 +103,7 @@ encoding. If no entries are found, a 404 code is returned. -### PUT method +#### 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 query parameters that can @@ -128,7 +135,7 @@ be used with a PUT request: The return value is either `true` or `false`. If `false` is returned, 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 a prefix. There are a few query parameters that can be used with a @@ -142,3 +149,207 @@ DELETE request: 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. + +### /v1/txn + +Available in Consul 0.7 and later, this endpoint manages updates or fetches of +multiple keys inside a single, atomic transaction. Only the `PUT` method is supported. + +By default, the datacenter of the agent receives the transaction; 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 in replication between datacenters, look at the +[Consul Replicate project](https://github.com/hashicorp/consul-replicate). + +The transaction endpoint supports the use of ACL tokens using the "?token=" query +parameter. + +#### PUT Method + +The `PUT` method lets you submit a list of operations to apply to the key/value store +inside a transaction. If any operation fails, the transaction will be rolled back and +none of the changes will be applied. + +The body of the request should be a list of operations to perform inside the atomic +transaction, which looks like this: + +```javascript +[ + { + "KV": { + "Verb": "", + "Key": "", + "Value": "", + "Flags": , + "Index": , + "Session": "" + } + }, + ... +] +``` + +`KV` is the only available operation type, though other types of operations may be added +in future versions of Consul to be mixed with key/value operations. The following fields +are available: + +* `Verb` is the type of operation to perform. Please see the table below for +available verbs. + +* `Key` is simply the full path of the entry. + +* `Value` is a Base64-encoded blob of data. Note that values cannot be larger than +512kB. + +* `Flags` is an opaque unsigned integer that can be attached to each entry. Clients +can choose to use this however makes sense for their application. + +* `Index` and `Session` are used for locking, unlocking, and check-and-set operations. +Please see the table below for details on how they are used. + +The following table summarizes the available verbs and the fields that apply to that +operation ("X" means a field is required and "O" means it is optional): + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
VerbOperationKeyValueFlagsIndexSession
setSets the `Key` to the given `Value`.XXO
casSets the `Key` to the given `Value` with check-and-set semantics. The `Key` will only be set if its current modify index matches the supplied `Index`.XXOX
lockLocks the `Key` with the given `Session`. The `Key` will only obtain the lock if the `Session` is valid, and no other session has it locked.XXOX
unlockUnlocks the `Key` with the given `Session`. The `Key` will only release the lock if the `Session` is valid and currently has it locked..XXOX
getGets the `Key` during the transaction. This fails the transaction if the `Key` doesn't exist.X
check-indexFails the transaction if `Key` does not have a modify index equal to `Index`.XX
check-sessionFails the transaction if `Key` is not currently locked by `Session`.XX
deleteDeletes the `Key`.X
delete-treeDeletes all keys with a prefix of`Key`.X
delete-casDeletes the `Key` with check-and-set semantics. The `Key` will only be deleted if its current modify index matches the supplied `Index`.XX
+ +If the transaction can be processed, a status code of 200 will be returned if it +was successfully applied, or a status code of 409 will be returned if it was rolled +back. If either of these status codes are returned, the response will look like this: + +```javascript +{ + "Results": [ + { + "KV": { + "LockIndex": , + "Key": "", + "Flags": , + "Value": "", + "CreateIndex": , + "ModifyIndex": + } + }, + ... + ], + "Errors": [ + { + "OpIndex": , + "What": "" + }, + ... + ] +} +``` + +`Results` has an entry for each operation if the transaction was successful. To save +space, the `Value` will be `null` for any `Verb` other than "get". Like the `/v1/kv/` +endpoint, `Value` will be Base64-encoded if it is present. For verbs that delete +keys, a `null` result entry will be present, keeping the list of `Results` 1:1 with the +list of operations given in the transaction. + +`Errors` has entries describing which operations failed if the transaction was rolled +back. The `OpIndex` gives the index of the failed operation in the transaction, and +`What` is a string with an error message about why that operation failed. + +If any other status code is returned, such as 400 or 500, then the body of the response +will simply be an unstructured error message about what happened. diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 92dd3e4b98..113e0647a3 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -171,7 +171,7 @@ > - Key/Value store + Key/Value Store >