open-consul/website/content/commands/kv/delete.mdx

103 lines
2.9 KiB
Plaintext
Raw Normal View History

2016-09-26 15:12:40 +00:00
---
layout: commands
2020-04-07 18:55:19 +00:00
page_title: 'Commands: KV Delete'
2016-09-26 15:12:40 +00:00
---
# Consul KV Delete
Command: `consul kv delete`
2022-01-11 13:26:58 +00:00
Corresponding HTTP API Endpoint: [\[DELETE\] /v1/kv/:key](/api-docs/kv#delete-key)
2017-04-04 16:33:22 +00:00
The `kv delete` command removes the value from Consul's KV store at the
2016-09-26 15:12:40 +00:00
given path. If no key exists at the path, no action is taken.
The table below shows this command's [required ACLs](/api#authentication). Configuration of
[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching)
are not supported from commands, but may be from the corresponding HTTP endpoint.
| ACL Required |
| ------------ |
| `key:write` |
2016-09-26 15:12:40 +00:00
## Usage
Usage: `consul kv delete [options] KEY_OR_PREFIX`
#### API Options
2020-04-07 18:55:19 +00:00
@include 'http_api_options_client.mdx'
2020-04-07 23:56:08 +00:00
2020-04-07 18:55:19 +00:00
@include 'http_api_options_server.mdx'
2016-09-26 15:12:40 +00:00
#### Enterprise Options
2020-04-07 18:55:19 +00:00
@include 'http_api_namespace_options.mdx'
@include 'http_api_partition_options.mdx'
2016-09-26 15:12:40 +00:00
#### KV Delete Options
2020-04-07 18:55:19 +00:00
- `-cas` - Perform a Check-And-Set operation. Specifying this value also
2016-09-26 23:15:27 +00:00
requires the -modify-index flag to be set. The default value is false.
2016-09-26 15:12:40 +00:00
2020-04-07 18:55:19 +00:00
- `-modify-index=<int>` - Unsigned integer representing the ModifyIndex of the
key. This is used in combination with the -cas flag.
2016-09-26 15:12:40 +00:00
2020-04-07 18:55:19 +00:00
- `-recurse` - Recursively delete all keys with the path. The default value is
2016-09-26 15:12:40 +00:00
false.
## Examples
To remove the value for the key named "redis/config/connections" in the
2017-04-04 16:33:22 +00:00
KV store:
2016-09-26 15:12:40 +00:00
2020-05-19 18:32:38 +00:00
```shell-session
2016-09-26 15:12:40 +00:00
$ consul kv delete redis/config/connections
Success! Deleted key: redis/config/connections
```
If the key does not exist, the command will not error, and a success message
will be returned:
2020-05-19 18:32:38 +00:00
```shell-session
2016-09-26 15:12:40 +00:00
$ consul kv delete not-a-real-key
Success! Deleted key: not-a-real-key
```
To only delete a key if it has not been modified since a given index, specify
the `-cas` and `-modify-index` flags:
2020-05-19 18:32:38 +00:00
```shell-session
2016-09-26 15:12:40 +00:00
$ consul kv get -detailed redis/config/connections | grep ModifyIndex
ModifyIndex 456
$ consul kv delete -cas -modify-index=123 redis/config/connections
Error! Did not delete key redis/config/connections: CAS failed
$ consul kv delete -cas -modify-index=456 redis/config/connections
Success! Deleted key: redis/config/connections
```
To recursively delete all keys that start with a given prefix, specify the
`-recurse` flag:
2020-05-19 18:32:38 +00:00
```shell-session
2016-09-26 15:12:40 +00:00
$ consul kv delete -recurse redis/
Success! Deleted keys with prefix: redis/
```
!> **Trailing slashes are important** in the recursive delete operation, since
Consul performs a greedy match on the provided prefix. If you were to use "foo"
as the key, this would recursively delete any key starting with those letters
such as "foo", "food", and "football" not just "foo". To ensure you are deleting
a folder, always use a trailing slash.
It is not valid to combine the `-cas` option with `-recurse`, since you are
deleting multiple keys under a prefix in a single operation:
2020-05-19 18:32:38 +00:00
```shell-session
2016-09-26 15:12:40 +00:00
$ consul kv delete -cas -recurse redis/
Cannot specify both -cas and -recurse!
```