Consul KV Put

Command: consul kv put

Corresponding HTTP API Endpoint: [PUT] /v1/kv/: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 instead. Alternatively, the transaction API provides support for performing up to 64 KV operations atomically.

The table below shows this command's required ACLs. Configuration of blocking queries and agent 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]

Command 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).

Enterprise Options

-partition=<string> - Enterprise Specifies the admin partition to query. If not provided, the partition is inferred from the request's ACL token, or defaults to the default partition.

-namespace=<string> - Specifies the namespace to query. If not provided, the namespace will be inferred from the request's ACL token, or will default to the default namespace. Namespaces are a Consul Enterprise feature added in v1.7.0.

API Options

-ca-file=<value> - Path to a CA file to use for TLS when communicating with Consul. This can also be specified via the CONSUL_CACERT environment variable.
-ca-path=<value> - Path to a directory of CA certificates to use for TLS when communicating with Consul. This can also be specified via the CONSUL_CAPATH environment variable.
-client-cert=<value> - Path to a client cert file to use for TLS when verify_incoming is enabled. This can also be specified via the CONSUL_CLIENT_CERT environment variable.
-client-key=<value> - Path to a client key file to use for TLS when verify_incoming is enabled. This can also be specified via the CONSUL_CLIENT_KEY environment variable.
-http-addr=<addr> - Address of the Consul agent with the port. This can be an IP address or DNS address, but it must include the port. This can also be specified via the CONSUL_HTTP_ADDR environment variable. In Consul 0.8 and later, the default value is http://127.0.0.1:8500, and https can optionally be used instead. The scheme can also be set to HTTPS by setting the environment variable CONSUL_HTTP_SSL=true. This may be a unix domain socket using unix:///path/to/socket if the agent is configured to listen that way.
-tls-server-name=<value> - The server name to use as the SNI host when connecting via TLS. This can also be specified via the CONSUL_TLS_SERVER_NAME environment variable.
-token=<value> - ACL token to use in the request. This can also be specified via the CONSUL_HTTP_TOKEN environment variable. If unspecified, the query will default to the token of the Consul agent at the HTTP address.
-token-file=<value> - File containing the ACL token to use in the request instead of one specified via the -token argument or CONSUL_HTTP_TOKEN environment variable. This can also be specified via the CONSUL_HTTP_TOKEN_FILE environment variable.

-datacenter=<name> - Name of the datacenter to query. If unspecified, the query will default to the datacenter of the Consul agent at the HTTP address.
-stale - Permit any Consul server (non-leader) to respond to this request. This allows for lower latency and higher throughput, but can result in stale data. This option has no effect on non-read operations. The default value is false.

Examples

To insert a value of "5" for the key named "redis/config/connections" in the KV store:

$ 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:

$ 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:

$ 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:

$ consul kv put redis/config/password @password.txt
Success! Data written to: redis/config/password

Or read values from stdin by specifying the - symbol:

$ echo "5" | consul kv put redis/config/connections -
Success! Data written to: redis/config/connections

$ consul kv put redis/config/connections -
5
<CTRL+D>
Success! Data written to: redis/config/connections

$ 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. 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:

$ 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):

$ consul kv put -acquire -session=abc123 redis/lock/update
Success! Lock acquired on: redis/lock/update

When you are finished, release the lock:

$ 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 consul 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:

$ consul kv put -flags=42 redis/config/password s3cr3t
Success! Data written to: redis/config/password