185 lines
5.7 KiB
Plaintext
185 lines
5.7 KiB
Plaintext
---
|
|
layout: commands
|
|
page_title: 'Commands: KV Put'
|
|
---
|
|
|
|
# Consul KV Put
|
|
|
|
Command: `consul kv put`
|
|
|
|
Corresponding HTTP API Endpoint: [\[PUT\] /v1/kv/:key](/api-docs/kv#create-update-key)
|
|
|
|
The `kv put` command writes the data to the given path in the KV store.
|
|
|
|
-> **Note**: When writing multiple entries at once, consider using
|
|
[`kv import`](/commands/kv/import) instead. Alternatively, the
|
|
[transaction API](/api-docs/txn) provides support for performing up to
|
|
64 KV operations atomically.
|
|
|
|
The table below shows this command's [required ACLs](/api#authentication). Configuration of
|
|
[blocking queries](/api/features/blocking) and [agent caching](/api/features/caching)
|
|
are not supported from commands, but may be from the corresponding HTTP endpoint.
|
|
|
|
| ACL Required |
|
|
| ------------ |
|
|
| `key:write` |
|
|
|
|
## Usage
|
|
|
|
Usage: `consul kv put [options] KEY [DATA]`
|
|
|
|
#### API Options
|
|
|
|
@include 'http_api_options_client.mdx'
|
|
|
|
@include 'http_api_options_server.mdx'
|
|
|
|
#### Enterprise Options
|
|
|
|
@include 'http_api_namespace_options.mdx'
|
|
|
|
@include 'http_api_partition_options.mdx'
|
|
|
|
#### KV Put Options
|
|
|
|
- `-acquire` - Obtain a lock on the key. If the key does not exist, this
|
|
operation will create the key and obtain the lock. The session must already
|
|
exist and be specified via the -session flag. The default value is false.
|
|
|
|
- `-base64` - Treat the data as base 64 encoded. The default value is false.
|
|
|
|
- `-cas` - Perform a Check-And-Set operation. Specifying this value also
|
|
requires the -modify-index flag to be set. The default value is false.
|
|
|
|
- `-flags=<int>` - Unsigned integer value to assign to this KV pair. This
|
|
value is not read by Consul, so clients can use this value however makes sense
|
|
for their use case. The default value is 0 (no flags).
|
|
|
|
- `-modify-index=<int>` - Unsigned integer representing the ModifyIndex of the
|
|
key. This is used in combination with the -cas flag.
|
|
|
|
- `-release` - Forfeit the lock on the key at the given path. This requires the
|
|
-session flag to be set. The key must be held by the session in order to be
|
|
unlocked. The default value is false.
|
|
|
|
- `-session=<string>` - User-defined identifier for this session as a string.
|
|
This is commonly used with the -acquire and -release operations to build
|
|
robust locking, but it can be set on any key. The default value is empty (no
|
|
session).
|
|
|
|
## Examples
|
|
|
|
To insert a value of "5" for the key named "redis/config/connections" in the
|
|
KV store:
|
|
|
|
```shell-session hideClipboard
|
|
$ consul kv put redis/config/connections 5
|
|
Success! Data written to: redis/config/connections
|
|
```
|
|
|
|
If no data is specified, the key will be created with empty data:
|
|
|
|
```shell-session hideClipboard
|
|
$ consul kv put redis/config/connections
|
|
Success! Data written to: redis/config/connections
|
|
```
|
|
|
|
!> **Be careful of overwriting data!** The above operation would overwrite
|
|
any existing value at the key to the empty value.
|
|
|
|
### Base64 Encoded Values
|
|
|
|
If the `-base64` flag is set, the given data will be Base64-decoded before writing:
|
|
|
|
```shell-session hideClipboard
|
|
$ consul kv put -base64 foo/encoded aGVsbG8gd29ybGQK
|
|
Success! Data written to: foo/encoded
|
|
```
|
|
|
|
### Longer or Sensitive Values
|
|
|
|
For longer or sensitive values, it is possible to read from a file by
|
|
supplying its path prefixed with the `@` symbol:
|
|
|
|
```shell-session hideClipboard
|
|
$ consul kv put redis/config/password @password.txt
|
|
Success! Data written to: redis/config/password
|
|
```
|
|
|
|
Or read values from stdin by specifying the `-` symbol:
|
|
|
|
```shell-session hideClipboard
|
|
$ echo "5" | consul kv put redis/config/connections -
|
|
Success! Data written to: redis/config/connections
|
|
```
|
|
|
|
```shell-session hideClipboard
|
|
$ consul kv put redis/config/connections -
|
|
5
|
|
<CTRL+D>
|
|
Success! Data written to: redis/config/connections
|
|
```
|
|
|
|
```shell-session hideClipboard
|
|
$ consul kv put leaderboard/scores - <<EOF
|
|
{
|
|
"user-a": 100,
|
|
"user-b": 250,
|
|
"user-c": 75
|
|
}
|
|
EOF
|
|
Success! Data written to: leaderboard/scores
|
|
```
|
|
|
|
~> **Warning**: For secret and sensitive values, you should consider using a
|
|
secret management solution like **[HashiCorp's Vault](https://learn.hashicorp.com/tutorials/vault/static-secrets?in=vault/secrets-management)**.
|
|
While it is possible to encrypt data before writing it to Consul's KV store,
|
|
Consul provides no built-in support for encryption at-rest.
|
|
|
|
### Atomic Check-And-Set (CAS)
|
|
|
|
To only update a key if it has not been modified since a given index, specify
|
|
the `-cas` and `-modify-index` flags:
|
|
|
|
```shell-session hideClipboard
|
|
$ consul kv get -detailed redis/config/connections | grep ModifyIndex
|
|
ModifyIndex 456
|
|
|
|
$ consul kv put -cas -modify-index=123 redis/config/connections 10
|
|
Error! Did not write to redis/config/connections: CAS failed
|
|
|
|
$ consul kv put -cas -modify-index=456 redis/config/connections 10
|
|
Success! Data written to: redis/config/connections
|
|
```
|
|
|
|
### Locking Primitives
|
|
|
|
To create or tune a lock, use the `-acquire` and `-session` flags. The session must already exist (this command will not create it or manage it):
|
|
|
|
```shell-session hideClipboard
|
|
$ consul kv put -acquire -session=abc123 redis/lock/update
|
|
Success! Lock acquired on: redis/lock/update
|
|
```
|
|
|
|
When you are finished, release the lock:
|
|
|
|
```shell-session hideClipboard
|
|
$ consul kv put -release -session=acb123 redis/lock/update
|
|
Success! Lock released on: redis/lock/update
|
|
```
|
|
|
|
~> **Warning!** If you are trying to build a locking mechanism with these
|
|
low-level primitives, you may want to look at the [<tt>consul
|
|
lock</tt>](/commands/lock) command. It provides higher-level
|
|
functionality without exposing the internal APIs of Consul.
|
|
|
|
### Flags
|
|
|
|
To set user-defined flags on the entry, use the `-flags` option. These flags
|
|
are completely controlled by the user and have no special meaning to Consul:
|
|
|
|
```shell-session hideClipboard
|
|
$ consul kv put -flags=42 redis/config/password s3cr3t
|
|
Success! Data written to: redis/config/password
|
|
```
|