[CONFIG] Add drop-in configuration support with conf.d directory

[manusa]

Description

Background

Many Linux system services follow a convention of supporting drop-in configuration directories (commonly named conf.d/ or *.d/) that allow users to extend or override base configuration without modifying the main configuration file. This pattern is widely used in:

• systemd - Uses *.conf.d/ directories for unit file overrides
• CRI-O - Supports /etc/crio/crio.conf.d/ for container runtime configuration
• kubelet - Supports drop-in configurations for flexible node customization

This approach provides several benefits:

• Clean separation between default and custom configurations
• Easy configuration management in containerized/orchestrated environments
• Predictable override behavior through alphabetical ordering
• Simplified package management (packages can drop configs without conflicts)

Feature Request

Add support for drop-in configuration directories to kubernetes-mcp-server, allowing users to:

1. Automatically load drop-in configurations from a conf.d/ directory relative to the main config file
2. Optionally specify a custom configuration directory via --config-dir flag
3. Load partial configuration files from the directory in alphabetical order
4. Merge drop-in configurations with the main config file (--config)
5. Dynamically reload configuration via SIGHUP signal when using config flags

Use Cases

1. Container deployments: Mount ConfigMaps as individual files in a conf.d directory
2. Package distribution: Ship default configs that users can override without editing
3. Environment-specific overrides: Layer environment-specific settings on top of base config
4. Feature flags: Enable/disable specific toolsets via separate drop-in files

Proposed Implementation

CLI Flags

# Load main config + automatically load drop-ins from conf.d/ relative to config file
# (e.g., /etc/kmcp/conf.d/ when config is /etc/kmcp/config.toml)
kubernetes-mcp-server --config /etc/kmcp/config.toml

# Load main config + drop-ins from custom directory (overrides default conf.d)
kubernetes-mcp-server --config /etc/kmcp/config.toml --config-dir /custom/conf.d/

# Load only from drop-in directory (no main config)
kubernetes-mcp-server --config-dir /etc/kmcp/conf.d/

Default Behavior

When --config is specified:

• The --config-dir defaults to conf.d/ within the same directory as the config file
• Example: --config /etc/kmcp/config.toml → config-dir defaults to /etc/kmcp/conf.d/
• This can be overridden by explicitly setting --config-dir

Processing Order

1. Load main config file (if --config specified)
2. Determine config-dir (explicit --config-dir or default conf.d/ relative to config file)
3. Scan config-dir for *.toml files (if directory exists)
4. Sort files alphabetically
5. Merge each drop-in file in order (later files override earlier ones)

Extended Configuration Merging

Extended configurations (config.Extended) must be properly merged when scattered across multiple drop-in files. For example:

# conf.d/10-base-extended.toml
[extended.myextension]
setting1 = "value1"

# conf.d/20-override-extended.toml
[extended.myextension]
setting2 = "value2"

# conf.d/30-another-extension.toml
[extended.otherextension]
enabled = true

The merged result should contain both extensions with their respective settings properly combined.

Example Directory Structure

/etc/kmcp/
├── config.toml              # Main configuration
└── conf.d/                  # Default drop-in directory (auto-discovered)
    ├── 00-base.toml         # Base settings
    ├── 10-toolsets.toml     # Toolset configuration
    ├── 20-security.toml     # Security settings
    ├── 30-extended.toml     # Extended configuration
    └── 99-overrides.toml    # Final overrides

Dynamic Reload

When --config or --config-dir is specified:

• The server should handle SIGHUP signal
• On SIGHUP, reload and re-merge all configuration files
• Apply new configuration without server restart

Acceptance Criteria

• When --config is specified, --config-dir defaults to conf.d/ in the same directory as the config file
• New --config-dir flag accepts a path to override the default configuration directory
• Drop-in files (*.toml) are processed in alphabetical order
• Drop-in configurations can contain partial settings (only override specific values)
• Extended configurations (config.Extended) are properly merged when scattered across multiple drop-in files
• Main config (--config) and drop-in directory (--config-dir) can be used together or independently
• If the default conf.d/ directory doesn't exist, the server continues without error
• SIGHUP signal triggers configuration reload when config flags are used
• Configuration changes are applied dynamically without restart
• Documentation is updated with examples and best practices

Tests

• Unit tests for drop-in file discovery and ordering
• Unit tests for configuration merging logic
• Unit tests for default conf.d directory resolution
• Unit tests for extended configuration merging across multiple drop-in files
• Integration tests for SIGHUP reload behavior
• Edge case tests: empty directory, missing conf.d directory, invalid TOML files, conflicting settings

Additional Information

• Related PR: feat(config): add drop-in configuration support with dynamic reload #524
• References:
  • systemd drop-in documentation
  • CRI-O configuration