Key/Value Store

Consul Key/Value (KV) Store provides a simple way to store configuration data, feature flags, and other dynamic settings. Keys are organized in a hierarchical folder structure, making it easy to manage configuration across services and environments.

Key Concepts

Hierarchical Structure

Organize keys into folders using path separators. Navigate like a filesystem.

Multiple Formats

Store plain text, JSON, or YAML values with syntax highlighting and validation.

Version Tracking

Every key has create, modify, and lock indexes for tracking changes.

Atomic Operations

Consul ensures atomic read and write operations for consistency.

Required Permissions

Action	Permission
View/Read keys	`iam:project:cicd:consul:read`
Create/Update keys	`iam:project:cicd:consul:write`
Delete keys/folders	`iam:project:cicd:consul:delete`

Keys vs Folders

Item	Description	Example
Key	Stores a value (string, JSON, YAML)	`config/database`
Folder	Organizes keys hierarchically (ends with `/`)	`config/app/`

Folders are virtual—they exist when keys are stored under them. Creating a folder creates an empty key with a trailing slash.

How to Navigate the KV Store

Select Consul Instance

Choose the target Consul cluster from the dropdown.

Browse Folders

Click on folders to navigate deeper. The breadcrumb shows your current path.

Search Keys

Use the search box to filter keys and folders in the current path.

Go Back

Use the back button or click a breadcrumb segment to navigate up.

How to Create a Key

Navigate to Target Folder

Browse to the folder where you want to create the key.

Click New Key

Click the New Key button.

Select Key Type

Choose Key for storing values or Folder for organizing keys.

Enter Key Name

Provide a name for the key. The full path is displayed below.

Select Format (for Keys)

Choose the value format:

Plain Text: Simple string values
JSON: Structured data with validation
YAML: Configuration files

Enter Value

Use the code editor to enter the value. JSON format validates syntax automatically.

Create

Click Create Key to save.

You can create nested paths by including slashes in the key name. For example, entering app/database/host creates the necessary folder structure automatically.

How to View and Edit a Key

Click on the Key

Click any key in the list to open the detail view.

Review Key Information

The detail page displays the key’s indexes (create, modify, lock) and flags for tracking changes.

Edit Value

Modify the value in the code editor. Format is auto-detected or can be set manually.

Save Changes

Click Save Changes to update the key.

How to Copy a Value

Open the key detail page
Click the Copy button in the toolbar
The entire value is copied to your clipboard

How to Hide/Show Values

For sensitive data:

Click the eye icon to hide the value
The editor is replaced with a “Value is hidden” placeholder
Click Show Value to reveal it again

Hide values when sharing your screen or working in public spaces.

How to Delete a Key

Find the Key

Navigate to the key in the folder list or open the detail page.

Click Delete

Click the trash icon on the key row or in the detail toolbar.

Confirm

Confirm the deletion. This action cannot be undone.

How to Delete a Folder

Find the Folder

Navigate to the folder in the KV store.

Click Delete

Click the trash icon on the folder row.

Confirm

Confirm the deletion. All keys within the folder are recursively deleted.

Deleting a folder removes all keys and subfolders inside it. This operation is irreversible.

Path Conventions

Follow these conventions for organizing keys:

# Environment-based
config/production/database
config/staging/database
config/development/database

# Service-based
services/api/settings
services/web/settings
services/worker/settings

# Feature flags
features/dark-mode
features/beta-users

Common Use Cases

Application Configuration

Store database connections, API endpoints, and feature flags:

{
  "database": {
    "host": "db.example.com",
    "port": 5432,
    "maxConnections": 100
  },
  "features": {
    "darkMode": true,
    "betaFeatures": false
  }
}

Service Discovery Configuration

Store service metadata that applications can read:

version: "2.1.0"
endpoints:
  - /api/v1/users
  - /api/v1/orders
healthCheck: /health

Feature Flags

Simple key-value pairs for feature toggles:

Path: features/new-checkout
Value: true

Troubleshooting

Key not appearing after creation

Click the refresh button to reload the key list
Verify you’re in the correct folder path
Check that the key was created successfully (look for error messages)

Cannot edit key

You need write permission for Consul KV
The Consul instance may be in read-only mode
Check network connectivity to Consul

JSON validation error

Check for missing commas between key-value pairs
Ensure all strings are wrapped in double quotes
Verify brackets and braces are properly matched
Use an external JSON validator if needed

Cannot delete folder

You need delete permission for Consul KV
Ensure the folder path is correct
Try deleting individual keys first if bulk delete fails

Changes not persisting

Click Save Changes after editing
Check for validation errors (invalid JSON badge)
Verify you have write permissions
Refresh and check if another process is overwriting

FAQ

What's the maximum value size?

Consul has a default limit of 512KB per key-value entry. This can be configured on the Consul server. For larger data, consider using external storage and storing only references in Consul.

Can I store binary data?

Consul KV stores values as base64-encoded strings. While you can store binary data, the UI works best with text-based formats (plain text, JSON, YAML). For binary files, consider dedicated storage solutions.

Are changes immediately visible to applications?

Yes. Consul KV changes are immediately available to all clients. Applications using Consul watches or blocking queries will be notified of changes.

What are flags used for?

Flags are a 64-bit unsigned integer associated with each key. Applications can use them for versioning, tagging, or any custom purpose. The UI preserves flags when updating values.

How do I back up KV data?

Use the Consul CLI: consul kv export > backup.json. You can also use the HTTP API for programmatic backups. Consider regular snapshots for disaster recovery.

Can multiple users edit the same key?

Yes, but the last write wins. Consul supports Check-and-Set (CAS) operations for optimistic locking. The modify index can be used to detect conflicts.

What's the difference between create and modify index?

Create Index is set when the key is first created and never changes. Modify Index updates on every write. Use these for change detection and caching strategies.

Best Practices

Organize by Environment

Keep environment-specific configurations separate:

config/production/
config/staging/
config/development/

Use Meaningful Names

Name keys descriptively:

# Good
services/payment-api/database-url
features/checkout-v2-enabled

# Avoid
key1
temp

Prefer JSON for Structured Data

JSON provides validation and is widely supported:

{
  "timeout": 30,
  "retries": 3,
  "endpoints": ["api1.example.com", "api2.example.com"]
}

Document Key Purpose

Use consistent naming that indicates purpose:

config/     → Configuration values
features/   → Feature flags
services/   → Service metadata
secrets/    → (Consider using Vault instead)

Avoid Sensitive Data

Consul KV is not designed for secrets. Use HashiCorp Vault for:

Passwords
API keys
Certificates
Any sensitive credentials

Getting Started

Infrastructure

Platform Services

CI/CD & Deployments

Pipeline & Helm

Performance Testing

Security

Mesh Networking

Access Management

Audit & Compliance

Settings

Key Concepts

Hierarchical Structure

Multiple Formats

Version Tracking

Atomic Operations

Required Permissions

Keys vs Folders

How to Navigate the KV Store

How to Create a Key

How to View and Edit a Key

How to Copy a Value

How to Hide/Show Values

How to Delete a Key

How to Delete a Folder

Path Conventions

Common Use Cases

Application Configuration

Service Discovery Configuration

Feature Flags

Troubleshooting

FAQ

Best Practices

Organize by Environment

Use Meaningful Names

Prefer JSON for Structured Data

Document Key Purpose

Avoid Sensitive Data

​Key Concepts

Hierarchical Structure

Multiple Formats

Version Tracking

Atomic Operations

​Required Permissions

​Keys vs Folders

​How to Navigate the KV Store

​How to Create a Key

​How to View and Edit a Key

​How to Copy a Value

​How to Hide/Show Values

​How to Delete a Key

​How to Delete a Folder

​Path Conventions

​Common Use Cases

​Application Configuration

​Service Discovery Configuration

​Feature Flags

​Troubleshooting

​FAQ

​Best Practices

​Organize by Environment

​Use Meaningful Names

​Prefer JSON for Structured Data

​Document Key Purpose

​Avoid Sensitive Data

Key Concepts

Required Permissions

Keys vs Folders

How to Navigate the KV Store

How to Create a Key

How to View and Edit a Key

How to Copy a Value

How to Hide/Show Values

How to Delete a Key

How to Delete a Folder

Path Conventions

Common Use Cases

Application Configuration

Service Discovery Configuration

Feature Flags

Troubleshooting

FAQ

Best Practices

Organize by Environment

Use Meaningful Names

Prefer JSON for Structured Data

Document Key Purpose

Avoid Sensitive Data