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

146 lines
4.5 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'
sidebar_title: 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
## 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'
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
2020-05-19 18:32:38 +00:00
```shell-session
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:
2020-05-19 18:32:38 +00:00
```shell-session
2016-09-26 15:12:29 +00:00
$ consul kv put redis/config/connections
Success! Data written to: redis/config/connections
```
If the `-base64` flag is set, the data will be decoded before writing:
2020-05-19 18:32:38 +00:00
```shell-session
$ consul kv put -base64 foo/encoded aGVsbG8gd29ybGQK
Success! Data written to: foo/encoded
```
2016-09-26 15:12:29 +00:00
!> **Be careful when overwriting data!** The above operation would overwrite
the value at the key to the empty value.
For longer or sensitive values, it is possible to read from a file by prefixing
with the `@` symbol:
2020-05-19 18:32:38 +00:00
```shell-session
2016-09-26 15:12:29 +00:00
$ consul kv put redis/config/password @password.txt
Success! Data written to: redis/config/connections
```
Or read values from stdin by specifying the `-` symbol:
2020-05-19 18:32:38 +00:00
```shell-session
2016-09-26 15:12:29 +00:00
$ echo "5" | consul kv put redis/config/password -
Success! Data written to: redis/config/connections
$ consul kv put redis/config/password -
5
<CTRL+D>
Success! Data written to: redis/config/connections
```
~> For secret and sensitive values, you should consider using a secret
management solution like **[HashiCorp's Vault](https://www.vaultproject.io/)**.
While it is possible to secure values in Consul's KV store, Vault provides a
more robust interface for secret management.
To only update 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: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
```
To specify flags on the key, use the `-flags` option. These flags are completely
controlled by the user:
2020-05-19 18:32:38 +00:00
```shell-session
2016-09-26 15:12:29 +00:00
$ consul kv put -flags=42 redis/config/password s3cr3t
Success! Data written to: redis/config/password
```
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
2020-05-19 18:32:38 +00:00
```shell-session
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:
2020-05-19 18:32:38 +00:00
```shell-session
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.