2017-04-04 16:33:22 +00:00
|
|
|
|
---
|
|
|
|
|
layout: api
|
|
|
|
|
page_title: KV Store - HTTP API
|
|
|
|
|
description: |-
|
|
|
|
|
The /kv endpoints access Consul's simple key/value store, useful for storing
|
|
|
|
|
service configuration or other metadata.
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
# KV Store Endpoints
|
|
|
|
|
|
|
|
|
|
The `/kv` endpoints access Consul's simple key/value store, useful for storing
|
|
|
|
|
service configuration or other metadata.
|
|
|
|
|
|
|
|
|
|
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, please view the
|
|
|
|
|
[Consul Replicate](https://github.com/hashicorp/consul-replicate) project.
|
|
|
|
|
|
|
|
|
|
~> Values in the KV store cannot be larger than 512kb.
|
|
|
|
|
|
2020-04-09 23:46:54 +00:00
|
|
|
|
For multi-key updates, please consider using [transaction](/api/txn).
|
2017-04-04 16:33:22 +00:00
|
|
|
|
|
|
|
|
|
## Read Key
|
|
|
|
|
|
|
|
|
|
This endpoint returns the specified key. If no key exists at the given path, a
|
|
|
|
|
404 is returned instead of a 200 response.
|
|
|
|
|
|
2020-04-09 23:46:54 +00:00
|
|
|
|
For multi-key reads, please consider using [transaction](/api/txn).
|
2017-10-18 00:07:13 +00:00
|
|
|
|
|
2020-04-06 20:27:35 +00:00
|
|
|
|
| Method | Path | Produces |
|
|
|
|
|
| ------ | ---------- | ------------------ |
|
|
|
|
|
| `GET` | `/kv/:key` | `application/json` |
|
2017-04-04 16:33:22 +00:00
|
|
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2020-04-09 23:46:54 +00:00
|
|
|
|
[blocking queries](/api/features/blocking),
|
|
|
|
|
[consistency modes](/api/features/consistency),
|
|
|
|
|
[agent caching](/api/features/caching), and
|
2020-04-09 23:20:00 +00:00
|
|
|
|
[required ACLs](/api#authentication).
|
2017-04-04 16:33:22 +00:00
|
|
|
|
|
2018-09-06 10:34:28 +00:00
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
|
|
|
| ---------------- | ----------------- | ------------- | ------------ |
|
|
|
|
|
| `YES` | `all` | `none` | `key:read` |
|
2017-04-04 16:33:22 +00:00
|
|
|
|
|
2022-01-15 17:29:35 +00:00
|
|
|
|
The corresponding CLI command is [`consul kv get`](/commands/kv/get).
|
2022-01-10 19:21:32 +00:00
|
|
|
|
|
2017-04-04 16:33:22 +00:00
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
|
|
- `key` `(string: "")` - Specifies the path of the key to read.
|
|
|
|
|
|
|
|
|
|
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
|
|
|
|
|
the datacenter of the agent being queried. This is specified as part of the
|
|
|
|
|
URL as a query parameter.
|
|
|
|
|
|
|
|
|
|
- `recurse` `(bool: false)` - Specifies if the lookup should be recursive and
|
|
|
|
|
`key` treated as a prefix instead of a literal match. This is specified as
|
|
|
|
|
part of the URL as a query parameter.
|
|
|
|
|
|
|
|
|
|
- `raw` `(bool: false)` - Specifies the response is just the raw value of the
|
|
|
|
|
key, without any encoding or metadata. This is specified as part of the URL as
|
|
|
|
|
a query parameter.
|
|
|
|
|
|
|
|
|
|
- `keys` `(bool: false)` - Specifies to return only keys (no values or
|
|
|
|
|
metadata). Specifying this implies `recurse`. This is specified as part of the
|
|
|
|
|
URL as a query parameter.
|
|
|
|
|
|
2019-11-25 17:57:35 +00:00
|
|
|
|
- `separator` `(string: "")` - Specifies the string to use as a separator
|
2020-04-06 20:27:35 +00:00
|
|
|
|
for recursive key lookups. This option is only used when paired with the `keys`
|
|
|
|
|
parameter to limit the prefix of keys returned, only up to the given separator.
|
2018-12-06 15:59:43 +00:00
|
|
|
|
This is specified as part of the URL as a query parameter.
|
2017-04-04 16:33:22 +00:00
|
|
|
|
|
2020-04-23 22:13:18 +00:00
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
|
2019-12-20 16:52:50 +00:00
|
|
|
|
If not provided, the namespace will be inferred from the request's ACL token,
|
|
|
|
|
or will default to the `default` namespace. This is specified as part of the
|
2021-12-16 09:27:57 +00:00
|
|
|
|
URL as a query parameter.
|
2020-04-06 20:27:35 +00:00
|
|
|
|
For recursive lookups, the namespace may be specified as '\*' and then results
|
2019-12-10 21:04:24 +00:00
|
|
|
|
will be returned for all namespaces. Added in Consul 1.7.0.
|
2019-11-25 17:57:35 +00:00
|
|
|
|
|
2017-04-04 16:33:22 +00:00
|
|
|
|
### Sample Request
|
|
|
|
|
|
2020-05-19 18:32:38 +00:00
|
|
|
|
```shell-session
|
2017-04-04 16:33:22 +00:00
|
|
|
|
$ curl \
|
2018-08-28 16:07:15 +00:00
|
|
|
|
http://127.0.0.1:8500/v1/kv/my-key
|
2017-04-04 16:33:22 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
|
|
#### Metadata Response
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
[
|
|
|
|
|
{
|
|
|
|
|
"CreateIndex": 100,
|
|
|
|
|
"ModifyIndex": 200,
|
|
|
|
|
"LockIndex": 200,
|
|
|
|
|
"Key": "zip",
|
|
|
|
|
"Flags": 0,
|
|
|
|
|
"Value": "dGVzdA==",
|
|
|
|
|
"Session": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
|
|
|
|
|
}
|
|
|
|
|
]
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
- `CreateIndex` is the internal index value that represents when the entry was
|
|
|
|
|
created.
|
|
|
|
|
|
|
|
|
|
- `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.
|
|
|
|
|
|
|
|
|
|
- `LockIndex` is the number of times this key has successfully been acquired in
|
|
|
|
|
a lock. 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` 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.
|
|
|
|
|
|
|
|
|
|
#### Keys Response
|
|
|
|
|
|
|
|
|
|
When using the `?keys` query parameter, the response structure changes to an
|
|
|
|
|
array of strings instead of an array of JSON objects. Listing `/web/` with a `/`
|
|
|
|
|
separator may return:
|
|
|
|
|
|
|
|
|
|
```json
|
2020-04-06 20:27:35 +00:00
|
|
|
|
["/web/bar", "/web/foo", "/web/subdir/"]
|
2017-04-04 16:33:22 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
#### Raw Response
|
|
|
|
|
|
|
|
|
|
When using the `?raw` endpoint, the response is not `application/json`, but
|
2021-04-14 20:21:03 +00:00
|
|
|
|
is instead `text/plain`.
|
2017-04-04 16:33:22 +00:00
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
)k<><6B><EFBFBD><EFBFBD><EFBFBD><EFBFBD>z^<5E>-<2D>ɑj<C991>q<EFBFBD><71><EFBFBD><EFBFBD>#u<>-R<>r<EFBFBD><72>T<EFBFBD>D<EFBFBD><44>٬<EFBFBD>Y<EFBFBD><59>l,<2C>ιK<CEB9><4B>Fm<46><6D>}<7D>#e<><65>
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
(Yes, that is intentionally a bunch of gibberish characters to showcase the
|
|
|
|
|
response)
|
|
|
|
|
|
2021-04-14 20:36:40 +00:00
|
|
|
|
!> **Warning:** Consul versions before 1.9.5, 1.8.10 and 1.7.14 detected the content-type
|
|
|
|
|
of the raw KV data which could be used for cross-site scripting (XSS) attacks. This is
|
|
|
|
|
identified publicly as CVE-2020-25864.
|
|
|
|
|
|
2017-04-04 16:33:22 +00:00
|
|
|
|
## Create/Update Key
|
|
|
|
|
|
2019-12-13 17:12:01 +00:00
|
|
|
|
This endpoint updates the value of the specified key. If no key exists at the given
|
|
|
|
|
path, the key will be created.
|
2017-04-04 16:33:22 +00:00
|
|
|
|
|
2020-04-06 20:27:35 +00:00
|
|
|
|
| Method | Path | Produces |
|
|
|
|
|
| ------ | ---------- | ------------------ |
|
|
|
|
|
| `PUT` | `/kv/:key` | `application/json` |
|
2017-04-04 16:33:22 +00:00
|
|
|
|
|
|
|
|
|
Even though the return type is `application/json`, the value is either `true` or
|
|
|
|
|
`false`, indicating whether the create/update succeeded.
|
|
|
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2020-04-09 23:46:54 +00:00
|
|
|
|
[blocking queries](/api/features/blocking),
|
|
|
|
|
[consistency modes](/api/features/consistency),
|
|
|
|
|
[agent caching](/api/features/caching), and
|
2020-04-09 23:20:00 +00:00
|
|
|
|
[required ACLs](/api#authentication).
|
2017-04-04 16:33:22 +00:00
|
|
|
|
|
2018-09-06 10:34:28 +00:00
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
|
|
|
| ---------------- | ----------------- | ------------- | ------------ |
|
|
|
|
|
| `NO` | `none` | `none` | `key:write` |
|
2017-04-04 16:33:22 +00:00
|
|
|
|
|
2022-01-15 17:29:35 +00:00
|
|
|
|
The corresponding CLI command is [`consul kv put`](/commands/kv/put).
|
2022-01-10 19:21:32 +00:00
|
|
|
|
|
2017-04-04 16:33:22 +00:00
|
|
|
|
### Parameters
|
|
|
|
|
|
2019-12-13 17:12:01 +00:00
|
|
|
|
- `key` `(string: "")` - Specifies the path of the key.
|
2017-04-04 16:33:22 +00:00
|
|
|
|
|
|
|
|
|
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
|
|
|
|
|
the datacenter of the agent being queried. This is specified as part of the
|
|
|
|
|
URL as a query parameter.
|
|
|
|
|
|
|
|
|
|
- `flags` `(int: 0)` - Specifies an unsigned value between `0` and `(2^64)-1`.
|
|
|
|
|
Clients can choose to use this however makes sense for their application. This
|
|
|
|
|
is specified as part of the URL as a query parameter.
|
|
|
|
|
|
|
|
|
|
- `cas` `(int: 0)` - Specifies to use a Check-And-Set 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.
|
|
|
|
|
|
2019-04-03 15:54:21 +00:00
|
|
|
|
- `acquire` `(string: "")` - Supply a session ID to use in a lock acquisition operation.
|
|
|
|
|
This is useful as it allows leader election to be built on top of Consul. If the
|
2017-04-04 16:33:22 +00:00
|
|
|
|
lock is not held and the session is valid, this increments the `LockIndex` and
|
|
|
|
|
sets the `Session` value of the key in addition to updating the key contents.
|
|
|
|
|
A key does not need to exist to be acquired. If the lock is already held by
|
|
|
|
|
the given session, then the `LockIndex` is not incremented but the key
|
|
|
|
|
contents are updated. This lets the current lock holder update the key
|
2018-02-01 20:08:06 +00:00
|
|
|
|
contents without having to give up the lock and reacquire it. **Note that an update
|
|
|
|
|
that does not include the acquire parameter will proceed normally even if another
|
|
|
|
|
session has locked the key.**
|
2017-04-04 16:33:22 +00:00
|
|
|
|
|
2020-12-08 23:24:36 +00:00
|
|
|
|
For an example of how to use the lock feature, check the
|
2020-08-17 16:20:02 +00:00
|
|
|
|
[Leader Election tutorial](https://learn.hashicorp.com/tutorials/consul/application-leader-elections).
|
2018-02-22 23:57:46 +00:00
|
|
|
|
|
2019-04-03 15:54:21 +00:00
|
|
|
|
- `release` `(string: "")` - Supply a session ID to use in a release operation. This is
|
2017-04-04 16:33:22 +00:00
|
|
|
|
useful when paired with `?acquire=` as it allows clients to 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.
|
|
|
|
|
|
2020-04-23 22:13:18 +00:00
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
|
2019-12-20 16:52:50 +00:00
|
|
|
|
If not provided, the namespace will be inferred from the request's ACL token,
|
|
|
|
|
or will default to the `default` namespace. This is specified as part of the
|
|
|
|
|
URL as a query parameter. Added in Consul 1.7.0.
|
2019-11-25 17:57:35 +00:00
|
|
|
|
|
2017-04-04 16:33:22 +00:00
|
|
|
|
### Sample Payload
|
|
|
|
|
|
|
|
|
|
The payload is arbitrary, and is loaded directly into Consul as supplied.
|
|
|
|
|
|
2018-01-24 10:55:17 +00:00
|
|
|
|
### Sample Requests
|
2017-04-04 16:33:22 +00:00
|
|
|
|
|
2020-05-19 18:32:38 +00:00
|
|
|
|
```shell-session
|
2017-04-04 16:33:22 +00:00
|
|
|
|
$ curl \
|
|
|
|
|
--request PUT \
|
|
|
|
|
--data @contents \
|
2018-08-28 16:07:15 +00:00
|
|
|
|
http://127.0.0.1:8500/v1/kv/my-key
|
2018-01-24 10:55:17 +00:00
|
|
|
|
|
|
|
|
|
# or
|
|
|
|
|
|
|
|
|
|
$ curl \
|
|
|
|
|
--request PUT \
|
|
|
|
|
--data-binary @contents \
|
2018-08-28 16:07:15 +00:00
|
|
|
|
http://127.0.0.1:8500/v1/kv/my-key
|
2017-04-04 16:33:22 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
true
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Delete Key
|
|
|
|
|
|
|
|
|
|
This endpoint deletes a single key or all keys sharing a prefix.
|
|
|
|
|
|
2020-04-06 20:27:35 +00:00
|
|
|
|
| Method | Path | Produces |
|
|
|
|
|
| -------- | ---------- | ------------------ |
|
|
|
|
|
| `DELETE` | `/kv/:key` | `application/json` |
|
2017-04-04 16:33:22 +00:00
|
|
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2020-04-09 23:46:54 +00:00
|
|
|
|
[blocking queries](/api/features/blocking),
|
|
|
|
|
[consistency modes](/api/features/consistency),
|
|
|
|
|
[agent caching](/api/features/caching), and
|
2020-04-09 23:20:00 +00:00
|
|
|
|
[required ACLs](/api#authentication).
|
2017-04-04 16:33:22 +00:00
|
|
|
|
|
2018-09-06 10:34:28 +00:00
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
|
|
|
| ---------------- | ----------------- | ------------- | ------------ |
|
|
|
|
|
| `NO` | `none` | `none` | `key:write` |
|
2017-04-04 16:33:22 +00:00
|
|
|
|
|
2022-01-15 17:29:35 +00:00
|
|
|
|
The corresponding CLI command is [`consul kv delete`](/commands/kv/delete).
|
2022-01-10 19:21:32 +00:00
|
|
|
|
|
2017-04-04 16:33:22 +00:00
|
|
|
|
### Parameters
|
|
|
|
|
|
2020-06-18 18:10:45 +00:00
|
|
|
|
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
|
|
|
|
|
the datacenter of the agent being queried. This is specified as part of the
|
|
|
|
|
URL as a query parameter, and gives "No path to datacenter" error when dc is
|
|
|
|
|
invalid.
|
|
|
|
|
|
2017-04-04 16:33:22 +00:00
|
|
|
|
- `recurse` `(bool: false)` - Specifies to delete all keys which have the
|
|
|
|
|
specified prefix. Without this, only a key with an exact match will be
|
|
|
|
|
deleted.
|
|
|
|
|
|
|
|
|
|
- `cas` `(int: 0)` - Specifies to use a Check-And-Set 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.
|
|
|
|
|
|
2020-04-23 22:13:18 +00:00
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
|
2019-12-20 16:52:50 +00:00
|
|
|
|
If not provided, the namespace will be inferred from the request's ACL token,
|
|
|
|
|
or will default to the `default` namespace. This is specified as part of the
|
|
|
|
|
URL as a query parameter. Added in Consul 1.7.0.
|
2019-11-25 17:57:35 +00:00
|
|
|
|
|
2017-04-04 16:33:22 +00:00
|
|
|
|
### Sample Request
|
|
|
|
|
|
2020-05-19 18:32:38 +00:00
|
|
|
|
```shell-session
|
2017-04-04 16:33:22 +00:00
|
|
|
|
$ curl \
|
|
|
|
|
--request DELETE \
|
2018-08-28 16:07:15 +00:00
|
|
|
|
http://127.0.0.1:8500/v1/kv/my-key
|
2017-04-04 16:33:22 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
true
|
|
|
|
|
```
|