LinuxCommandLibrary

consul-kv

Manage Consul key-value store data

TLDR

Read a value from the key-value store

$ consul kv get [key]
copy

Store a new key-value pair
$ consul kv put [key] [value]
copy

Delete a key-value pair
$ consul kv delete [key]
copy

SYNOPSIS

consul kv [subcommand] [options]

PARAMETERS

get
    Retrieves the value associated with the specified key. Defaults to the value on stdout.

get -detailed
    Retrieves the value associated with the specified key with verbose output.

get -decode
    Attempt to decode the value with base64.

get -recurse
    Lists all keys and values under the specified prefix recursively. Useful for retrieving entire configuration trees.

put
    Sets the value for the specified key. Overwrites existing values.

delete
    Deletes the specified key. Note that this command is destructive.

delete -recurse
    Deletes all keys under the specified prefix recursively. Use with extreme caution!

export
    Exports the key-value store as a serialized stream. Useful for backups or migrations.

import
    Imports a serialized stream into the key-value store. Useful for restoring backups.

-datacenter
    Specifies the datacenter to query. If not provided, the default datacenter configured in Consul is used.

-http-addr


    Address of the Consul agent to query

DESCRIPTION

The `consul kv` command provides a command-line interface for interacting with Consul's key-value store. It allows users to read, write, delete, and list keys and their corresponding values within the Consul cluster's data store. This is a fundamental tool for managing configuration data, service discovery information, and other application-related data within a Consul-based infrastructure. The command facilitates the dynamic configuration of applications and services, allowing for changes to be pushed to the cluster without requiring restarts or redeployments. It supports various data types (strings, integers, booleans) and allows for complex data structures to be serialized as strings (e.g., JSON). The command is an integral part of Consul's ecosystem, enabling programmatic access to the key-value store for automation and integration with other tools and systems. Its use extends from simple configuration management to more advanced scenarios like feature flagging, dynamic routing, and distributed locking.

CAVEATS

Changes to the Consul KV store are immediately reflected, meaning applications must be designed to handle configuration updates gracefully. Using `-recurse` with `delete` can have severe consequences if the wrong prefix is specified. Always double-check your prefixes before running destructive operations.

ERROR HANDLING

The `consul kv` command will return a non-zero exit code if an error occurs, such as a connection problem with the Consul agent or an invalid key. Always check the exit code in scripts and automation workflows.

ACLS (ACCESS CONTROL LISTS)

Access to the key-value store is governed by Consul's ACL system. Ensure the Consul agent has the necessary permissions to read, write, or delete keys based on the ACL policies in place. Insufficient permissions will result in errors when attempting to perform operations.

SEE ALSO

consul(1)

Copied to clipboard