Spotlight: Consul KV CLI

The recent release of Consul 0.7.1 included a number of exciting new features. One powerful new capability is the addition of a full-featured CLI for interacting with Consul's key-value store. This blog post explores the new Consul KV CLI with some great examples and techniques.

Since its launch, Consul has boasted a highly-available, globally distributed key-value store for reading, writing, and listing data. However, until Consul 0.7.1, the only way to interact with the key-value store was via the HTTP API. Using a tool like curl or a Consul client library, you could read and write data from the key-value store.

»API

Consul has and will continue to have a full HTTP API. It is important to note that the HTTP API is not going away; the CLI just provides a different abstraction. In order to understand that abstraction, it is important to understand typical interactions with the API.

The following example would store the value of "bar" inside a key named "foo":

$ curl -X PUT $CONSUL_ADDR/v1/kv/foo -d'bar'

And then to retrieve the data:

$ curl $CONSUL_ADDR/v1/kv/foo
{
  "CreateIndex": 100,
  "ModifyIndex": 200,
  "LockIndex": 200,
  "Key": "zip",
  "Flags": 0,
  "Value": "YmFyCg==",
  "Session": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
}

But the API poses a number of implementation challenges. First, because of the transport mechanism, the resulting data is base64 encoded. Additionally, the API often includes more data than the average user requires. To get just the value of a key in Consul's KV store, you would need at least three separate tools:

$ curl $CONSUL_ADDR/v1/kv/foo | jq -r '.Value' | base64 -d

This created an unnecessary learning curve for interacting with the KV store, forcing users to understand the underlying implementations for even the most basic interactions.

Consul 0.7.1 features a new KV CLI which aims to provide a more seamless integration with the Consul's key-value store through the consul binary.

»CLI

All of the key-value commands reside under the the kv subcommand. For example:

Usage: consul kv <subcommand> [options] [args]

  # ...

Subcommands:

    delete    Removes data from the KV store
    get       Retrieves or lists data from the KV store
    put       Sets or updates data in the KV store

Immediately you can see the CLI supports reading, writing, and deleting from the key-value store. Let us take a look at some additional examples:

To create or update the key named "redis/config/connections" to the value "5" in Consul's key-value store:

$ consul kv put redis/config/connections 5
Success! Data written to: redis/config/connections

To read that value back from Consul:

$ consul kv get redis/config/connections
5

This new CLI removes the need for additional tools to parse JSON and perform base64 decoding. The Consul KV CLI is also capable or rendering all of the information returned from the HTTP API in a human-friendly format using the -detailed flag:

$ consul kv get -detailed redis/config/connections
CreateIndex      336
Flags            0
Key              redis/config/connections
LockIndex        0
ModifyIndex      336
Session          -
Value            5

Deleting a key is just as easy:

$ consul kv delete redis/config/connections
Success! Data deleted at key: redis/config/connections

In addition to the basic CRUD operations, the CLI also supports writing data from stdin or a file. For example:

$ consul kv put foo @file.txt

or

$ echo -n "foo" | consul kv put -

All commands support the advanced HTTP API options, such as CAS and recurse operations.

We really hope you enjoy the new Consul KV CLI. For more information, examples, and the complete API, please see the Consul KV CLI documentation.