github.com/outbrain/consul@v1.4.5/website/source/intro/getting-started/kv.html.md (about)

     1  ---
     2  layout: "intro"
     3  page_title: "KV Data"
     4  sidebar_current: "gettingstarted-kv"
     5  description: |-
     6    In addition to providing service discovery and integrated health checking, Consul provides an easy to use KV store. This can be used to hold dynamic configuration, assist in service coordination, build leader election, and enable anything else a developer can think to build.
     7  ---
     8  
     9  # KV Data
    10  
    11  In addition to providing service discovery and integrated health checking,
    12  Consul provides an easy to use KV store. This can be used to hold
    13  dynamic configuration, assist in service coordination, build leader election,
    14  and enable anything else a developer can think to build.
    15  
    16  This step assumes you have at least one Consul agent already running.
    17  
    18  ## Simple Usage
    19  
    20  To demonstrate how simple it is to get started, we will manipulate a few keys in
    21  the KV store. There are two ways to interact with the Consul KV store: via the
    22  HTTP API and via the Consul KV CLI. The examples below show using the Consul KV
    23  CLI because it is the easiest to get started. For more advanced integrations,
    24  you may want to use the [Consul KV HTTP API][kv-api]
    25  
    26  First let us explore the KV store. We can ask Consul for the value of the key at
    27  the path named `redis/config/minconns`:
    28  
    29  ```sh
    30  $ consul kv get redis/config/minconns
    31  Error! No key exists at: redis/config/minconns
    32  ```
    33  
    34  As you can see, we get no result, which makes sense because there is no data in
    35  the KV store. Next we can insert or "put" values into the KV store.
    36  
    37  ```sh
    38  $ consul kv put redis/config/minconns 1
    39  Success! Data written to: redis/config/minconns
    40  
    41  $ consul kv put redis/config/maxconns 25
    42  Success! Data written to: redis/config/maxconns
    43  
    44  $ consul kv put -flags=42 redis/config/users/admin abcd1234
    45  Success! Data written to: redis/config/users/admin
    46  ```
    47  
    48  Now that we have keys in the store, we can query for the value of individual
    49  keys:
    50  
    51  ```sh
    52  $ consul kv get redis/config/minconns
    53  1
    54  ```
    55  
    56  Consul retains additional metadata about the field, which is retrieved using the
    57  `-detailed` flag:
    58  
    59  ```sh
    60  $ consul kv get -detailed redis/config/minconns
    61  CreateIndex      207
    62  Flags            0
    63  Key              redis/config/minconns
    64  LockIndex        0
    65  ModifyIndex      207
    66  Session          -
    67  Value            1
    68  ```
    69  
    70  For the key "redis/config/users/admin", we set a `flag` value of 42. All keys
    71  support setting a 64-bit integer flag value. This is not used internally by
    72  Consul, but it can be used by clients to add meaningful metadata to any KV.
    73  
    74  It is possible to list all the keys in the store using the `recurse` options.
    75  Results will be returned in lexicographical order:
    76  
    77  ```sh
    78  $ consul kv get -recurse
    79  redis/config/maxconns:25
    80  redis/config/minconns:1
    81  redis/config/users/admin:abcd1234
    82  ```
    83  
    84  To delete a key from the Consul KV store, issue a "delete" call:
    85  
    86  ```sh
    87  $ consul kv delete redis/config/minconns
    88  Success! Deleted key: redis/config/minconns
    89  ```
    90  
    91  It is also possible to delete an entire prefix using the `recurse` option:
    92  
    93  ```sh
    94  $ consul kv delete -recurse redis
    95  Success! Deleted keys with prefix: redis
    96  ```
    97  
    98  To update the value of an existing key, "put" a value at the same path:
    99  
   100  ```sh
   101  $ consul kv put foo bar
   102  
   103  $ consul kv get foo
   104  bar
   105  
   106  $ consul kv put foo zip
   107  
   108  $ consul kv get foo
   109  zip
   110  ```
   111  
   112  Consul can provide atomic key updates using a Check-And-Set operation. To perform a CAS operation, specify the `-cas` flag:
   113  
   114  ```sh
   115  $ consul kv put -cas -modify-index=123 foo bar
   116  Success! Data written to: foo
   117  
   118  $ consul kv put -cas -modify-index=123 foo bar
   119  Error! Did not write to foo: CAS failed
   120  ```
   121  
   122  In this case, the first CAS update succeeds because the index is 123. The second
   123  operation fails because the index is no longer 123.
   124  
   125  ## Next Steps
   126  
   127  These are only a few examples of what the API supports. For the complete
   128  documentation, please see [Consul KV HTTP API][kv-api] or
   129  [Consul KV CLI][kv-cli] documentation.
   130  
   131  Next, we will look at the [web UI](ui.html) options supported by Consul.
   132  
   133  [kv-api]: /api/kv.html
   134  [kv-cli]: /docs/commands/kv.html