Merge pull request #11977 from hashicorp/boxofrad/kv-docs-examples

docs: kv doc improvements

website/content/api-docs/kv.mdx

@@ -18,14 +18,16 @@ replication between datacenters, please view the
 
 ~> Values in the KV store cannot be larger than 512kb.
 
-For multi-key updates, please consider using [transaction](/api/txn).
+In order to perform atomic operations on multiple KV pairs (up to a limit of 64)
+please consider using [transactions](/api/txn) instead.
 
 ## Read Key
 
 This endpoint returns the specified key. If no key exists at the given path, a
 404 is returned instead of a 200 response.
 
-For multi-key reads, please consider using [transaction](/api/txn).
+For multi-key reads (up to a limit of 64 KV operations) please consider using
+[transactions](/api/txn) instead.
 
 | Method | Path       | Produces           |
 | ------ | ---------- | ------------------ |

website/content/commands/kv/get.mdx

@@ -12,6 +12,12 @@ store at the given key name. If no key exists with that name, an error is
 returned. If a key exists with that name but has no data, nothing is returned.
 A key name or prefix is required.
 
+-> **Note**: When reading many entries under a given prefix, it may be worth
+considering [`kv export`](/commands/kv/export) instead. The kv export output
+can be used with [`kv import`](/commands/kv/import) to move entire trees between
+Consul clusters. Alternatively, the [transaction API](/api-docs/txn) provides
+support for performing up to 64 KV operations atomically.
+
 ## Usage
 
 Usage: `consul kv get [options] [KEY_OR_PREFIX]`
@@ -53,17 +59,27 @@ Usage: `consul kv get [options] [KEY_OR_PREFIX]`
 To retrieve the value for the key named "redis/config/connections" in the
 KV store:
 
-```shell-session
+```shell-session hideClipboard
 $ consul kv get redis/config/connections
 5
 ```
 
-This will return the original, raw value stored in Consul. To view detailed
+This will return the original raw value stored in Consul.
-information about the key, specify the "-detailed" flag. This will output all
-known metadata about the key including ModifyIndex and any user-supplied
-flags:
 
-```shell-session
+If the key with the given name does not exist, an error is returned.
+
+```shell-session hideClipboard
+$ consul kv get not-a-real-key
+Error! No key exists at: not-a-real-key
+```
+
+### Detailed Output
+
+To view detailed information about the key, specify the `-detailed` flag.
+This will output all known metadata about the key including `ModifyIndex`
+and any user-supplied flags:
+
+```shell-session hideClipboard
 $ consul kv get -detailed redis/config/connections
 CreateIndex      336
 Flags            0
@@ -74,26 +90,22 @@ Session          -
 Value            5
 ```
 
-If the key with the given name does not exist, an error is returned:
+### Recursively Reading By Prefix
 
-```shell-session
+To treat the path as a prefix and list all entries which start with the given
-$ consul kv get not-a-real-key
+prefix, specify the `-recurse` flag:
-Error! No key exists at: not-a-real-key
-```
 
-To treat the path as a prefix and list all keys which start with the given
+```shell-session hideClipboard
-prefix, specify the "-recurse" flag:
-
-```shell-session
 $ consul kv get -recurse redis/
 redis/config/connections:5
 redis/config/cpu:128
 redis/config/memory:512
 ```
 
-Or list detailed information about all pairs under a prefix:
+Alternatively, combine with the `-detailed` flag to list detailed information
+about all entries under a prefix:
 
-```shell-session
+```shell-session hideClipboard
 $ consul kv get -recurse -detailed redis
 CreateIndex      336
 Flags            0
@@ -120,10 +132,12 @@ Session          -
 Value            512
 ```
 
-To just list the keys which start with the specified prefix, use the "-keys"
+### Listing Keys
+
+To just list the keys which start with the specified prefix, use the `-keys`
 option instead. This is more performant and results in a smaller payload:
 
-```shell-session
+```shell-session hideClipboard
 $ consul kv get -keys redis/config/
 redis/config/connections
 redis/config/cpu
@@ -134,7 +148,7 @@ By default, the `-keys` operation uses a separator of "/", meaning it will not
 recurse beyond that separator. You can choose a different separator by setting
 `-separator="<string>"`.
 
-```shell-session
+```shell-session hideClipboard
 $ consul kv get -keys -separator="c" redis
 redis/c
 ```
@@ -142,7 +156,7 @@ redis/c
 Alternatively, you can disable the separator altogether by setting it to the
 empty string:
 
-```shell-session
+```shell-session hideClipboard
 $ consul kv get -keys -separator="" redis
 redis/config/connections
 redis/config/cpu
@@ -151,7 +165,7 @@ redis/config/memory
 
 To list all keys at the root, simply omit the prefix parameter:
 
-```shell-session
+```shell-session hideClipboard
 $ consul kv get -keys
 memcached/
 redis/

website/content/commands/kv/put.mdx

@@ -9,6 +9,11 @@ Command: `consul kv put`
 
 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.
+
 ## Usage
 
 Usage: `consul kv put [options] KEY [DATA]`
@@ -57,57 +62,76 @@ Usage: `consul kv put [options] KEY [DATA]`
 To insert a value of "5" for the key named "redis/config/connections" in the
 KV store:
 
-```shell-session
+```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
+```shell-session hideClipboard
 $ 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:
+!> **Be careful of overwriting data!** The above operation would overwrite
+any existing value at the key to the empty value.
 
-```shell-session
+### 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
 ```
 
-!> **Be careful when overwriting data!** The above operation would overwrite
+### Longer or Sensitive Values
-the value at the key to the empty value.
 
-For longer or sensitive values, it is possible to read from a file by prefixing
+For longer or sensitive values, it is possible to read from a file by
-with the `@` symbol:
+supplying its path prefixed with the `@` symbol:
 
-```shell-session
+```shell-session hideClipboard
 $ consul kv put redis/config/password @password.txt
-Success! Data written to: redis/config/connections
+Success! Data written to: redis/config/password
 ```
 
 Or read values from stdin by specifying the `-` symbol:
 
-```shell-session
+```shell-session hideClipboard
-$ echo "5" | consul kv put redis/config/password -
+$ echo "5" | consul kv put redis/config/connections -
 Success! Data written to: redis/config/connections
+```
 
-$ consul kv put redis/config/password -
+```shell-session hideClipboard
+$ consul kv put redis/config/connections -
 5
 <CTRL+D>
 Success! Data written to: redis/config/connections
 ```
 
-~> For secret and sensitive values, you should consider using a secret
+```shell-session hideClipboard
-management solution like **[HashiCorp's Vault](https://www.vaultproject.io/)**.
+$ consul kv put leaderboard/scores - <<EOF
-While it is possible to secure values in Consul's KV store, Vault provides a
+{
-more robust interface for secret management.
+  "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)
 
 To only update a key if it has not been modified since a given index, specify
 the `-cas` and `-modify-index` flags:
 
-```shell-session
+```shell-session hideClipboard
 $ consul kv get -detailed redis/config/connections | grep ModifyIndex
 ModifyIndex      456
 
@@ -118,24 +142,18 @@ $ 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
+### Locking Primitives
-controlled by the user:
-
-```shell-session
-$ 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):
 
-```shell-session
+```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
+```shell-session hideClipboard
 $ consul kv put -release -session=acb123 redis/lock/update
 Success! Lock released on: redis/lock/update
 ```
@@ -144,3 +162,13 @@ Success! Lock released on: redis/lock/update
 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
+```