luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity
open-consul/website/content/api-docs/kv.mdx

315 lines
11 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
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.
In order to perform atomic operations on multiple KV pairs (up to a limit of 64)
please consider using [transactions](/api-docs/txn) instead.
## 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.
For multi-key reads (up to a limit of 64 KV operations) please consider using
[transactions](/api-docs/txn) instead.
If the [`recurse`](#recurse) or [`keys`](#keys) query parameters are `true`,
this endpoint will return an array of keys. In this case,
the HTTP response includes the `X-Consul-Results-Filtered-By-ACLs: true` header
if the response array excludes results due to ACL policy configuration.
Refer to the [HTTP API documentation](/api-docs#results-filtered-by-acls) for more information.
| Method | Path | Produces |
| ------ | ---------- | ------------------ |
| `GET` | `/kv/:key` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `YES` | `all` | `none` | `key:read` |
The corresponding CLI command is [`consul kv get`](/commands/kv/get).
### Path Parameters
- `key` `(string: "")` - Specifies the path of the key to read.
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried.
- `recurse` `(bool: false)` - Specifies if the lookup should be recursive and
treat `key` as a prefix instead of a literal match.
- `raw` `(bool: false)` - Specifies the response is just the raw value of the
key, without any encoding or metadata.
- `keys` `(bool: false)` - Specifies to return only keys (no values or
metadata). Specifying this parameter implies `recurse`.
- `separator` `(string: "")` - Specifies the string to use as a separator
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.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
For recursive lookups, the namespace may be specified as '\*'
to return results for all namespaces.
### Sample Request
```shell-session
$ curl \
http://127.0.0.1:8500/v1/kv/my-key
```
### 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.
API consumers can use this field any way they choose 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
["/web/bar", "/web/foo", "/web/subdir/"]
```
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
is instead `text/plain`.
```
)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)
!> **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.
## Create/Update Key
This endpoint updates the value of the specified key. If no key exists at the given
path, the key will be created.
| Method | Path | Produces |
| ------ | ---------- | ------------------ |
| `PUT` | `/kv/:key` | `application/json` |
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
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `key:write` |
The corresponding CLI command is [`consul kv put`](/commands/kv/put).
### Path Parameters
- `key` `(string: "")` - Specifies the path of the key.
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried.
- `flags` `(int: 0)` - Specifies an unsigned value between `0` and `(2^64)-1`
to store with the key.
API consumers can use this field any way they choose for their application.
- `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.
- `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
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
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.**
For an example of how to use the lock feature, check the
[Leader Election tutorial](https://learn.hashicorp.com/tutorials/consul/application-leader-elections).
- `release` `(string: "")` - Supply a session ID to use in a release operation. This is
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.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Payload
The payload is arbitrary, and is loaded directly into Consul as supplied.
### Sample Requests
```shell-session
$ curl \
--request PUT \
--data @contents \
http://127.0.0.1:8500/v1/kv/my-key
# or
$ curl \
--request PUT \
--data-binary @contents \
http://127.0.0.1:8500/v1/kv/my-key
```
### Sample Response
```json
true
```
## Delete Key
This endpoint deletes a single key or all keys sharing a prefix.
| Method | Path | Produces |
| -------- | ---------- | ------------------ |
| `DELETE` | `/kv/:key` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `key:write` |
The corresponding CLI command is [`consul kv delete`](/commands/kv/delete).
### Path Parameters
- `key` `(string: "")` - Specifies the path of the key to delete.
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. If the DC is invalid,
the error "No path to datacenter" is returned.
- `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.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Request
```shell-session
$ curl \
--request DELETE \
http://127.0.0.1:8500/v1/kv/my-key
```
### Sample Response
```json
true
```
## Methods to Specify Namespace <EnterpriseAlert inline />
The key-value store endpoints
support several methods for specifying the namespace of resources
with the following order of precedence:
1. `ns` query parameter
1. `X-Consul-Namespace` request header
1. Namespace is inherited from the namespace of the request's ACL token (if any)
1. The `default` namespace
Reference in New Issue View Git Blame Copy Permalink