Spotlight: Consul KV CLI

Spotlight: Consul KV CLI

Dec 01 2016    Seth Vargo

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.

close modal

Request a Demo

Fill out the form below and we'll reach out to discuss a product demo.

check mark
check mark
check mark
check mark
Select an option
  • Select one
  • Terraform
  • Nomad
  • Vault
  • Consul
Trusted by
  • Adobe Logo
  • Barclays Logo
  • Cisco Logo
  • Citadel Logo
  • DigitalOcean Logo
  • Hewlett Packard Enterprise Logo
  • SAP Arabia Logo
  • New Relic Logo
  • Pinterest Logo
  • Segment Logo
  • Spaceflight Logo
  • Stripe Logo