Introduction to Consul (Part-2): KV-Store

Reading Time: 4 minutes

Hello All !!

In our previous blog we discussed in brief about what Consul is, and what could it provide us to work upon. And now we will be discussing one of the features mentioned earlier.

Feature: Configuring the services.

Consul provides a hierarchical key/value store for fulfilling our purposes like, including dynamic configuration, feature flagging, coordination, leader election and more. And in this blog, we will be looking into providing key-value pairs that could be used our code while implementing some functionality.

To demonstrate how simple it is to use KV-Store, we will manipulate a few keys in the K/V store.

We will be discussing two ways to interact with the Consul KV store: via the Consul library provided for java i.e. via code implementation and via the Consul KV CLI.

Let’s first look into the basic commands/functions provided by Consul:

  1. GET: It takes the key and provides the value corresponding to that key in Consul. If the key is not there, it provides an error message.
  2. PUT: It takes the key-value pair and stores it in the Consul KV-Store.
  3. DELETE: It takes the Key and deletes the corresponding key-value pair from KV-store.

Now let’s see the CLI interaction, here we will be covering a few of the commands with their purposes.

  1. Start a Consul cluster in dev mode:
    $ ./consul agent -dev
  2. Put a key-value pair in store:
    $ ./consul kv put my-app/address
  3. Get a value corresponding to a particular key:
    $ ./consul kv get my-app/address
  4. Members of Consul cluster:
    $ ./consul members
  5. To get the list of all keys:
    $ ./consul kv get -recurse
  6. Delete a key-value pair:
    ./consul kv delete my-app/address
  7. For metadata of nodes:
    curl localhost:8500/v1/catalog/nodes
  8. Metadata for a key: Consul retains additional metadata about the field, which is retrieved using the -detailed flag:
    $ ./consul kv get -detailed my-app/address

The last command will show you some of the important details for the Key-Value pair. There are three fields that should grab our eyeballs:

  1. CreateIndex: This is the index given by Consul for each key added and it stays the same for the whole span till the key is not deleted or the Consul server goes down.
  2. ModifyIndex: The index is same as CreatedIndex initially when a pair is added, but once the value for the key is modified, the modified index also changes. This could be used to keep the track for the modifications done and also could be used while putting conditions when CAS is used. It’s an advanced command that could be looked for in the Consul documentation.
  3. LockIndex: This index is 0 initially, but it gets modified every time, some node/service takes a lock on the key for a time period.

Export and Import:

The “./consul kv export” command is used to retrieve KV pairs for the given prefix from Consul’s KV store, and write a JSON representation to stdout. This can be used with the command “./consul kv import” to move entire trees between Consul clusters.

This was all about the basics while working with Consul CLI, now let’s have a peek through the code implementation. The code snippets will be for Java with Maven, but consul provides libraries for multiple languages like Scala, Rust etc.

Be-it any language the steps remain the same:

Step 1: Add Consul’s dependency.

Step 2: Create a cluster object and connect to the Server. While connecting provide the ACLToken “key” to let it know that we will be interacting with KV-Store. The ACLToken is an important field to be provided. If no token is provided, the rules associated with a special, configurable anonymous token are automatically applied. Tokens are bound to a set of rules that control which Consul resources the token has access to. Please go through the following link for details about all the policies provided, P.S. “key” is one of those policies.

Step 3: Once connected, create a key-value client and use the methods get, put delete and so on, to interact with KV-store.

Here’s the example:

Step 1:


Step 2:

Step 3:

So this was our attempt to provide a brief use of Consul’s KV-Store. Hope it would be useful for you. Thanks for giving us your time. Keep going through our blogs, because we at Knoldus believe in gaining knowledge by sharing it across.

Here are some references, for further detailed understandings:


Written by 

Anmol Mehta is a Software Consultant having experience of more than 1.5 years. A keen programmer who has experience in Scala and Java. He is recognized as a dedicated and determined team player who enjoys working on new technologies. He is a professional and a technology enthusiast. He believes in the approach that “teamwork makes the dream work”. He is a quick and always-on learner who ensures better quality in every increment of his work. He believes in abiding standard coding practices. He always looks after that the team is working in sync with each other both at the technical and managerial level.