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

175 lines
5.3 KiB
Plaintext
Raw Normal View History

2016-09-26 15:12:29 +00:00
---
layout: commands
2020-04-07 18:55:19 +00:00
page_title: 'Commands: KV Put'
2016-09-26 15:12:29 +00:00
---
# Consul KV Put
Command: `consul kv put`
2017-04-04 16:33:22 +00:00
The `kv put` command writes the data to the given path in the KV store.
2016-09-26 15:12:29 +00:00
-> **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.
2016-09-26 15:12:29 +00:00
## Usage
Usage: `consul kv put [options] KEY [DATA]`
#### 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:29 +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:29 +00:00
#### KV Put Options
2020-04-07 18:55:19 +00:00
- `-acquire` - Obtain a lock on the key. If the key does not exist, this
2016-09-26 15:12:29 +00:00
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.
2020-04-07 18:55:19 +00:00
- `-base64` - Treat the data as base 64 encoded. The default value is false.
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:29 +00:00
2020-04-07 18:55:19 +00:00
- `-flags=<int>` - Unsigned integer value to assign to this KV pair. This
2016-09-26 15:12:29 +00:00
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).
2020-04-07 18:55:19 +00:00
- `-modify-index=<int>` - Unsigned integer representing the ModifyIndex of the
2016-09-26 23:06:32 +00:00
key. This is used in combination with the -cas flag.
2016-09-26 15:12:29 +00:00
2020-04-07 18:55:19 +00:00
- `-release` - Forfeit the lock on the key at the given path. This requires the
2016-09-26 15:12:29 +00:00
-session flag to be set. The key must be held by the session in order to be
unlocked. The default value is false.
2020-04-07 18:55:19 +00:00
- `-session=<string>` - User-defined identifier for this session as a string.
2016-09-26 15:12:29 +00:00
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
2017-04-04 16:33:22 +00:00
KV store:
2016-09-26 15:12:29 +00:00
```shell-session hideClipboard
2016-09-26 15:12:29 +00:00
$ 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
2016-09-26 15:12:29 +00:00
$ 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:
2016-09-26 15:12:29 +00:00
```shell-session hideClipboard
2016-09-26 15:12:29 +00:00
$ consul kv put redis/config/password @password.txt
Success! Data written to: redis/config/password
2016-09-26 15:12:29 +00:00
```
Or read values from stdin by specifying the `-` symbol:
```shell-session hideClipboard
$ echo "5" | consul kv put redis/config/connections -
2016-09-26 15:12:29 +00:00
Success! Data written to: redis/config/connections
```
2016-09-26 15:12:29 +00:00
```shell-session hideClipboard
$ consul kv put redis/config/connections -
2016-09-26 15:12:29 +00:00
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 encrpyt data before writing it to Consul's KV store,
Consul provides no built-in support for encryption at-rest.
### Atomic Check-And-Set (CAS)
2016-09-26 15:12:29 +00:00
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
2016-09-26 15:12:29 +00:00
$ 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
2016-09-26 15:12:29 +00:00
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):
2016-09-26 15:12:29 +00:00
```shell-session hideClipboard
2016-09-26 15:12:29 +00:00
$ 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
2016-09-26 15:12:29 +00:00
$ 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
2016-09-26 15:12:29 +00:00
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
```