Skip to main content
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

ActionPermission
View/Read keysiam:project:cicd:consul:read
Create/Update keysiam:project:cicd:consul:write
Delete keys/foldersiam:project:cicd:consul:delete

​
Keys vs Folders

ItemDescriptionExample
KeyStores a value (string, JSON, YAML)config/database
FolderOrganizes 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

1

Select Consul Instance

Choose the target Consul cluster from the dropdown.
2

Browse Folders

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

Search Keys

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

Go Back

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

​
How to Create a Key

1

Navigate to Target Folder

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

Click New Key

Click the New Key button.
3

Select Key Type

Choose Key for storing values or Folder for organizing keys.
4

Enter Key Name

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

Select Format (for Keys)

Choose the value format:
  • Plain Text: Simple string values
  • JSON: Structured data with validation
  • YAML: Configuration files
6

Enter Value

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

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

1

Click on the Key

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

Review Key Information

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

Edit Value

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

Save Changes

Click Save Changes to update the key.

​
How to Copy a Value

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

​
How to Hide/Show Values

For sensitive data:
  1. Click the eye icon to hide the value
  2. The editor is replaced with a “Value is hidden” placeholder
  3. Click Show Value to reveal it again
Hide values when sharing your screen or working in public spaces.

​
How to Delete a Key

1

Find the Key

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

Click Delete

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

Confirm

Confirm the deletion. This action cannot be undone.

​
How to Delete a Folder

1

Find the Folder

Navigate to the folder in the KV store.
2

Click Delete

Click the trash icon on the folder row.
3

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

  • 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)
  • You need write permission for Consul KV
  • The Consul instance may be in read-only mode
  • Check network connectivity to Consul
  • 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
  • You need delete permission for Consul KV
  • Ensure the folder path is correct
  • Try deleting individual keys first if bulk delete fails
  • 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

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.
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.
Yes. Consul KV changes are immediately available to all clients. Applications using Consul watches or blocking queries will be notified of changes.
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.
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.
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.
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