github.com/sl1pm4t/consul@v1.4.5-0.20190325224627-74c31c540f9c/website/source/docs/commands/kv/put.html.markdown.erb (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Commands: KV Put"
     4  sidebar_current: "docs-commands-kv-put"
     5  ---
     6  
     7  # Consul KV Put
     8  
     9  Command: `consul kv put`
    10  
    11  The `kv put` command writes the data to the given path in the KV store.
    12  
    13  ## Usage
    14  
    15  Usage: `consul kv put [options] KEY [DATA]`
    16  
    17  #### API Options
    18  
    19  <%= partial "docs/commands/http_api_options_client" %>
    20  <%= partial "docs/commands/http_api_options_server" %>
    21  
    22  #### KV Put Options
    23  
    24  * `-acquire` - Obtain a lock on the key. If the key does not exist, this
    25    operation will create the key and obtain the lock. The session must already
    26    exist and be specified via the -session flag. The default value is false.
    27  
    28  * `-base64` - Treat the data as base 64 encoded. The default value is false.
    29  
    30  * `-cas` - Perform a Check-And-Set operation. Specifying this value also
    31    requires the -modify-index flag to be set. The default value is false.
    32  
    33  * `-flags=<int>` - Unsigned integer value to assign to this KV pair. This
    34    value is not read by Consul, so clients can use this value however makes sense
    35    for their use case. The default value is 0 (no flags).
    36  
    37  * `-modify-index=<int>` - Unsigned integer representing the ModifyIndex of the
    38    key. This is used in combination with the -cas flag.
    39  
    40  * `-release` - Forfeit the lock on the key at the given path. This requires the
    41    -session flag to be set. The key must be held by the session in order to be
    42    unlocked. The default value is false.
    43  
    44  * `-session=<string>` - User-defined identifer for this session as a string.
    45    This is commonly used with the -acquire and -release operations to build
    46    robust locking, but it can be set on any key. The default value is empty (no
    47    session).
    48  
    49  ## Examples
    50  
    51  To insert a value of "5" for the key named "redis/config/connections" in the
    52  KV store:
    53  
    54  ```
    55  $ consul kv put redis/config/connections 5
    56  Success! Data written to: redis/config/connections
    57  ```
    58  
    59  If no data is specified, the key will be created with empty data:
    60  
    61  ```
    62  $ consul kv put redis/config/connections
    63  Success! Data written to: redis/config/connections
    64  ```
    65  
    66  If the `-base64` flag is set, the data will be decoded before writing:
    67  
    68  ```
    69  $ consul kv put -base64 foo/encoded aGVsbG8gd29ybGQK
    70  Success! Data written to: foo/encoded
    71  ```
    72  
    73  !> **Be careful when overwriting data!** The above operation would overwrite
    74  the value at the key to the empty value.
    75  
    76  For longer or sensitive values, it is possible to read from a file by prefixing
    77  with the `@` symbol:
    78  
    79  ```
    80  $ consul kv put redis/config/password @password.txt
    81  Success! Data written to: redis/config/connections
    82  ```
    83  
    84  Or read values from stdin by specifying the `-` symbol:
    85  
    86  ```
    87  $ echo "5" | consul kv put redis/config/password -
    88  Success! Data written to: redis/config/connections
    89  
    90  $ consul kv put redis/config/password -
    91  5
    92  <CTRL+D>
    93  Success! Data written to: redis/config/connections
    94  ```
    95  
    96  ~> For secret and sensitive values, you should consider using a secret
    97  management solution like **[HashiCorp's Vault](https://www.vaultproject.io/)**.
    98  While it is possible to secure values in Consul's KV store, Vault provides a
    99  more robust interface for secret management.
   100  
   101  To only update a key if it has not been modified since a given index, specify
   102  the `-cas` and `-modify-index` flags:
   103  
   104  ```
   105  $ consul kv get -detailed redis/config/connections | grep ModifyIndex
   106  ModifyIndex      456
   107  
   108  $ consul kv put -cas -modify-index=123 redis/config/connections 10
   109  Error! Did not write to redis/config/connections: CAS failed
   110  
   111  $ consul kv put -cas -modify-index=456 redis/config/connections 10
   112  Success! Data written to: redis/config/connections
   113  ```
   114  
   115  To specify flags on the key, use the `-flags` option. These flags are completely
   116  controlled by the user:
   117  
   118  ```
   119  $ consul kv put -flags=42 redis/config/password s3cr3t
   120  Success! Data written to: redis/config/password
   121  ```
   122  
   123  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):
   124  
   125  ```
   126  $ consul kv put -acquire -session=abc123 redis/lock/update
   127  Success! Lock acquired on: redis/lock/update
   128  ```
   129  
   130  When you are finished, release the lock:
   131  
   132  ```
   133  $ consul kv put -release -session=acb123 redis/lock/update
   134  Success! Lock released on: redis/lock/update
   135  ```
   136  
   137  ~> **Warning!** If you are trying to build a locking mechanism with these
   138  low-level primitives, you may want to look at the [<tt>consul
   139  lock</tt>](/docs/commands/lock.html) command. It provides higher-level
   140  functionality without exposing the internal APIs of Consul.