github.com/outbrain/consul@v1.4.5/website/source/api/kv.html.md (about)

     1  ---
     2  layout: api
     3  page_title: KV Store - HTTP API
     4  sidebar_current: api-kv-store
     5  description: |-
     6    The /kv endpoints access Consul's simple key/value store, useful for storing
     7    service configuration or other metadata.
     8  ---
     9  
    10  # KV Store Endpoints
    11  
    12  The `/kv` endpoints access Consul's simple key/value store, useful for storing
    13  service configuration or other metadata.
    14  
    15  It is important to note that each datacenter has its own KV store, and there is
    16  no built-in replication between datacenters. If you are interested in
    17  replication between datacenters, please view the
    18  [Consul Replicate](https://github.com/hashicorp/consul-replicate) project.
    19  
    20  ~> Values in the KV store cannot be larger than 512kb.
    21  
    22  For multi-key updates, please consider using [transaction](/api/txn.html).
    23  
    24  ## Read Key
    25  
    26  This endpoint returns the specified key. If no key exists at the given path, a
    27  404 is returned instead of a 200 response.
    28  
    29  For multi-key reads, please consider using [transaction](/api/txn.html).
    30  
    31  | Method | Path                         | Produces                   |
    32  | ------ | ---------------------------- | -------------------------- |
    33  | `GET`  | `/kv/:key`                   | `application/json`         |
    34  
    35  The table below shows this endpoint's support for
    36  [blocking queries](/api/index.html#blocking-queries),
    37  [consistency modes](/api/index.html#consistency-modes),
    38  [agent caching](/api/index.html#agent-caching), and
    39  [required ACLs](/api/index.html#acls).
    40  
    41  | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
    42  | ---------------- | ----------------- | ------------- | ------------ |
    43  | `YES`            | `all`             | `none`        | `key:read`   |
    44  
    45  ### Parameters
    46  
    47  - `key` `(string: "")` - Specifies the path of the key to read.
    48  
    49  - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
    50    the datacenter of the agent being queried. This is specified as part of the
    51    URL as a query parameter.
    52  
    53  - `recurse` `(bool: false)` - Specifies if the lookup should be recursive and
    54    `key` treated as a prefix instead of a literal match. This is specified as
    55    part of the URL as a query parameter.
    56  
    57  - `raw` `(bool: false)` - Specifies the response is just the raw value of the
    58    key, without any encoding or metadata. This is specified as part of the URL as
    59    a query parameter.
    60  
    61  - `keys` `(bool: false)` - Specifies to return only keys (no values or
    62    metadata). Specifying this implies `recurse`. This is specified as part of the
    63    URL as a query parameter.
    64  
    65  - `separator` `(string: '/')` - Specifies the string to use as a separator
    66    for recursive key lookups. This option is only used when paired with the `keys` 
    67    parameter to limit the prefix of keys returned,  only up to the given separator. 
    68    This is specified as part of the URL as a query parameter.
    69  
    70  ### Sample Request
    71  
    72  ```text
    73  $ curl \
    74      http://127.0.0.1:8500/v1/kv/my-key
    75  ```
    76  
    77  ### Sample Response
    78  
    79  #### Metadata Response
    80  
    81  ```json
    82  [
    83    {
    84      "CreateIndex": 100,
    85      "ModifyIndex": 200,
    86      "LockIndex": 200,
    87      "Key": "zip",
    88      "Flags": 0,
    89      "Value": "dGVzdA==",
    90      "Session": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
    91    }
    92  ]
    93  ```
    94  
    95  - `CreateIndex` is the internal index value that represents when the entry was
    96    created.
    97  
    98  - `ModifyIndex` is the last index that modified this key. This index corresponds
    99    to the `X-Consul-Index` header value that is returned in responses, and it can
   100    be used to establish blocking queries by setting the `?index` query parameter.
   101    You can even perform blocking queries against entire subtrees of the KV store:
   102    if `?recurse` is provided, the returned `X-Consul-Index` corresponds to the
   103    latest `ModifyIndex` within the prefix, and a blocking query using that
   104    `?index` will wait until any key within that prefix is updated.
   105  
   106  - `LockIndex` is the number of times this key has successfully been acquired in
   107    a lock. If the lock is held, the `Session` key provides the session that owns
   108    the lock.
   109  
   110  - `Key` is simply the full path of the entry.
   111  
   112  - `Flags` is an opaque unsigned integer that can be attached to each entry.
   113    Clients can choose to use this however makes sense for their application.
   114  
   115  - `Value` is a base64-encoded blob of data.
   116  
   117  #### Keys Response
   118  
   119  When using the `?keys` query parameter, the response structure changes to an
   120  array of strings instead of an array of JSON objects. Listing `/web/` with a `/`
   121  separator may return:
   122  
   123  ```json
   124  [
   125    "/web/bar",
   126    "/web/foo",
   127    "/web/subdir/"
   128  ]
   129  ```
   130  
   131  Using the key listing method may be suitable when you do not need the values or
   132  flags or want to implement a key-space explorer.
   133  
   134  #### Raw Response
   135  
   136  When using the `?raw` endpoint, the response is not `application/json`, but
   137  rather the content type of the uploaded content.
   138  
   139  ```
   140  )k������z^�-�ɑj�q����#u�-R�r��T�D��٬�Y��l,�ιK��Fm��}�#e��
   141  ```
   142  
   143  (Yes, that is intentionally a bunch of gibberish characters to showcase the
   144  response)
   145  
   146  ## Create/Update Key
   147  
   148  This endpoint
   149  
   150  | Method | Path                         | Produces                   |
   151  | ------ | ---------------------------- | -------------------------- |
   152  | `PUT`  | `/kv/:key`                   | `application/json`         |
   153  
   154  Even though the return type is `application/json`, the value is either `true` or
   155  `false`, indicating whether the create/update succeeded.
   156  
   157  The table below shows this endpoint's support for
   158  [blocking queries](/api/index.html#blocking-queries),
   159  [consistency modes](/api/index.html#consistency-modes),
   160  [agent caching](/api/index.html#agent-caching), and
   161  [required ACLs](/api/index.html#acls).
   162  
   163  | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
   164  | ---------------- | ----------------- | ------------- | ------------ |
   165  | `NO`             | `none`            | `none`        | `key:write`  |
   166  
   167  ### Parameters
   168  
   169  - `key` `(string: "")` - Specifies the path of the key to read.
   170  
   171  - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
   172    the datacenter of the agent being queried. This is specified as part of the
   173    URL as a query parameter.
   174  
   175  - `flags` `(int: 0)` - Specifies an unsigned value between `0` and `(2^64)-1`.
   176    Clients can choose to use this however makes sense for their application. This
   177    is specified as part of the URL as a query parameter.
   178  
   179  - `cas` `(int: 0)` - Specifies to use a Check-And-Set operation. This is very
   180    useful as a building block for more complex synchronization primitives. If the
   181    index is 0, Consul will only put the key if it does not already exist. If the
   182    index is non-zero, the key is only set if the index matches the `ModifyIndex`
   183    of that key.
   184  
   185  - `acquire` `(string: "")` - Specifies to use a lock acquisition operation. This
   186    is useful as it allows leader election to be built on top of Consul. If the
   187    lock is not held and the session is valid, this increments the `LockIndex` and
   188    sets the `Session` value of the key in addition to updating the key contents.
   189    A key does not need to exist to be acquired. If the lock is already held by
   190    the given session, then the `LockIndex` is not incremented but the key
   191    contents are updated. This lets the current lock holder update the key
   192    contents without having to give up the lock and reacquire it. **Note that an update
   193    that does not include the acquire parameter will proceed normally even if another
   194    session has locked the key.**
   195  
   196      For an example of how to use the lock feature, see the [Leader Election Guide]
   197      (/docs/guides/leader-election.html).
   198  
   199  - `release` `(string: "")` - Specifies to use a lock release operation. This is
   200    useful when paired with `?acquire=` as it allows clients to yield a lock. This
   201    will leave the `LockIndex` unmodified but will clear the associated `Session`
   202    of the key. The key must be held by this session to be unlocked.
   203  
   204  ### Sample Payload
   205  
   206  The payload is arbitrary, and is loaded directly into Consul as supplied.
   207  
   208  ### Sample Requests
   209  
   210  ```bash
   211  $ curl \
   212      --request PUT \
   213      --data @contents \
   214      http://127.0.0.1:8500/v1/kv/my-key
   215  
   216  # or
   217  
   218  $ curl \
   219      --request PUT \
   220      --data-binary @contents \
   221      http://127.0.0.1:8500/v1/kv/my-key
   222  ```
   223  
   224  ### Sample Response
   225  
   226  ```json
   227  true
   228  ```
   229  
   230  ## Delete Key
   231  
   232  This endpoint deletes a single key or all keys sharing a prefix.
   233  
   234  | Method   | Path                         | Produces                   |
   235  | -------- | ---------------------------- | -------------------------- |
   236  | `DELETE` | `/kv/:key`                   | `application/json`         |
   237  
   238  The table below shows this endpoint's support for
   239  [blocking queries](/api/index.html#blocking-queries),
   240  [consistency modes](/api/index.html#consistency-modes),
   241  [agent caching](/api/index.html#agent-caching), and
   242  [required ACLs](/api/index.html#acls).
   243  
   244  | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
   245  | ---------------- | ----------------- | ------------- | ------------ |
   246  | `NO`             | `none`            | `none`        | `key:write`  |
   247  
   248  ### Parameters
   249  
   250  - `recurse` `(bool: false)` - Specifies to delete all keys which have the
   251    specified prefix. Without this, only a key with an exact match will be
   252    deleted.
   253  
   254  - `cas` `(int: 0)` - Specifies to use a Check-And-Set operation. This is very
   255    useful as a building block for more complex synchronization primitives. Unlike
   256    `PUT`, the index must be greater than 0 for Consul to take any action: a 0
   257    index will not delete the key. If the index is non-zero, the key is only
   258    deleted if the index matches the `ModifyIndex` of that key.
   259  
   260  ### Sample Request
   261  
   262  ```text
   263  $ curl \
   264      --request DELETE \
   265      http://127.0.0.1:8500/v1/kv/my-key
   266  ```
   267  
   268  ### Sample Response
   269  
   270  ```json
   271  true
   272  ```