Implementation:LMCache LMCache Controller Config

Knowledge Sources	LMCache
Domains	Configuration, Cache Controller
Last Updated	2026-02-09 00:00 GMT

Overview

Provides the configuration system for the LMCache Controller, supporting YAML files, environment variables, and command-line overrides with a thread-safe singleton pattern.

Description

The Controller Config module defines the configuration schema and loading mechanisms for the LMCache cache controller. It declares configuration parameters such as monitor ports, host address, API server port, health check interval, and worker timeout using a declarative dictionary of definitions. The module leverages generic base utilities (create_config_class, create_singleton_config, load_config_with_overrides) to dynamically construct the ControllerConfig dataclass and a singleton getter function. Configuration values can be loaded from a YAML file (referenced by the LMCACHE_CONTROLLER_CONFIG_FILE environment variable), from individual environment variables prefixed with LMCACHE_CONTROLLER_, or overridden programmatically via a dictionary.

Usage

Use this module when initializing the LMCache cache controller to obtain a validated configuration instance. Call controller_get_or_create_config for singleton access, load_controller_config_with_overrides for explicit file-based loading with optional overrides, or override_controller_config_from_dict to dynamically patch an existing config at runtime.

Code Reference

Source Location

• Repository: LMCache
• File: lmcache/v1/cache_controller/config.py
• Lines: 1-176

Signature

ControllerConfig = create_config_class(
    config_name="ControllerConfig",
    config_definitions=_CONTROLLER_CONFIG_DEFINITIONS,
    namespace_extras={...},
    env_prefix="LMCACHE_CONTROLLER_",
)

controller_get_or_create_config = create_singleton_config(
    getter_func_name="controller_get_or_create_config",
    config_class=ControllerConfig,
    config_env_var="LMCACHE_CONTROLLER_CONFIG_FILE",
)

def override_controller_config_from_dict(
    config: "ControllerConfig",
    overrides: dict[str, Any],
) -> None: ...

def load_controller_config_with_overrides(
    config_file_path: Optional[str] = None,
    overrides: Optional[Dict[str, Any]] = None,
) -> "ControllerConfig": ...

Import

from lmcache.v1.cache_controller.config import (
    ControllerConfig,
    controller_get_or_create_config,
    override_controller_config_from_dict,
    load_controller_config_with_overrides,
)

I/O Contract

Inputs

Name	Type	Required	Description
controller_monitor_ports	Optional[dict]	No	JSON string or dict of monitor ports (default: {"pull": 8300, "reply": 8400})
controller_host	str	No	Controller host address (default: "0.0.0.0")
controller_port	int	No	Controller API server port (default: 9000)
health_check_interval	int	No	Health check interval in seconds; -1 disables (default: -1)
lmcache_worker_timeout	int	No	Worker timeout in seconds (default: 300)
extra_config	Optional[dict]	No	Extra configuration parameters (default: None)
config_file_path	Optional[str]	No	Path to YAML config file for load_controller_config_with_overrides
overrides	Optional[Dict[str, Any]]	No	Dictionary of overrides for load_controller_config_with_overrides

Outputs

Name	Type	Description
ControllerConfig	dataclass instance	Validated controller configuration object with all defined fields

Usage Examples

# Singleton access (reads from env var LMCACHE_CONTROLLER_CONFIG_FILE)
from lmcache.v1.cache_controller.config import controller_get_or_create_config
config = controller_get_or_create_config()

# Load with explicit file and overrides
from lmcache.v1.cache_controller.config import load_controller_config_with_overrides
config = load_controller_config_with_overrides(
    config_file_path="/path/to/controller_config.yaml",
    overrides={"controller_port": 9001, "health_check_interval": 30},
)

# Runtime override of an existing config
from lmcache.v1.cache_controller.config import override_controller_config_from_dict
override_controller_config_from_dict(config, {"lmcache_worker_timeout": 600})