> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shiftlabs.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Key/Value Store

> Store and manage configuration data with Consul KV

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

<CardGroup cols={2}>
  <Card title="Hierarchical Structure" icon="folder-tree">
    Organize keys into folders using path separators. Navigate like a filesystem.
  </Card>

  <Card title="Multiple Formats" icon="code">
    Store plain text, JSON, or YAML values with syntax highlighting and validation.
  </Card>

  <Card title="Version Tracking" icon="clock-rotate-left">
    Every key has create, modify, and lock indexes for tracking changes.
  </Card>

  <Card title="Atomic Operations" icon="atom">
    Consul ensures atomic read and write operations for consistency.
  </Card>
</CardGroup>

## 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

<Steps>
  <Step title="Select Consul Instance">
    Choose the target Consul cluster from the dropdown.
  </Step>

  <Step title="Browse Folders">
    Click on folders to navigate deeper. The breadcrumb shows your current path.
  </Step>

  <Step title="Search Keys">
    Use the search box to filter keys and folders in the current path.
  </Step>

  <Step title="Go Back">
    Use the back button or click a breadcrumb segment to navigate up.
  </Step>
</Steps>

## How to Create a Key

<Steps>
  <Step title="Navigate to Target Folder">
    Browse to the folder where you want to create the key.
  </Step>

  <Step title="Click New Key">
    Click the **New Key** button.
  </Step>

  <Step title="Select Key Type">
    Choose **Key** for storing values or **Folder** for organizing keys.
  </Step>

  <Step title="Enter Key Name">
    Provide a name for the key. The full path is displayed below.
  </Step>

  <Step title="Select Format (for Keys)">
    Choose the value format:

    * **Plain Text**: Simple string values
    * **JSON**: Structured data with validation
    * **YAML**: Configuration files
  </Step>

  <Step title="Enter Value">
    Use the code editor to enter the value. JSON format validates syntax automatically.
  </Step>

  <Step title="Create">
    Click **Create Key** to save.
  </Step>
</Steps>

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

## How to View and Edit a Key

<Steps>
  <Step title="Click on the Key">
    Click any key in the list to open the detail view.
  </Step>

  <Step title="Review Key Information">
    The detail page displays the key's indexes (create, modify, lock) and flags for tracking changes.
  </Step>

  <Step title="Edit Value">
    Modify the value in the code editor. Format is auto-detected or can be set manually.
  </Step>

  <Step title="Save Changes">
    Click **Save Changes** to update the key.
  </Step>
</Steps>

## 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

<Tip>
  Hide values when sharing your screen or working in public spaces.
</Tip>

## How to Delete a Key

<Steps>
  <Step title="Find the Key">
    Navigate to the key in the folder list or open the detail page.
  </Step>

  <Step title="Click Delete">
    Click the trash icon on the key row or in the detail toolbar.
  </Step>

  <Step title="Confirm">
    Confirm the deletion. This action cannot be undone.
  </Step>
</Steps>

## How to Delete a Folder

<Steps>
  <Step title="Find the Folder">
    Navigate to the folder in the KV store.
  </Step>

  <Step title="Click Delete">
    Click the trash icon on the folder row.
  </Step>

  <Step title="Confirm">
    Confirm the deletion. All keys within the folder are recursively deleted.
  </Step>
</Steps>

<Warning>
  Deleting a folder removes all keys and subfolders inside it. This operation is irreversible.
</Warning>

## 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:

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

### Service Discovery Configuration

Store service metadata that applications can read:

```yaml theme={null}
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

<AccordionGroup>
  <Accordion title="Key not appearing after creation" icon="circle-question">
    * 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)
  </Accordion>

  <Accordion title="Cannot edit key" icon="circle-question">
    * You need write permission for Consul KV
    * The Consul instance may be in read-only mode
    * Check network connectivity to Consul
  </Accordion>

  <Accordion title="JSON validation error" icon="circle-question">
    * 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
  </Accordion>

  <Accordion title="Cannot delete folder" icon="circle-question">
    * You need delete permission for Consul KV
    * Ensure the folder path is correct
    * Try deleting individual keys first if bulk delete fails
  </Accordion>

  <Accordion title="Changes not persisting" icon="circle-question">
    * 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
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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:

```json theme={null}
{
  "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