Dynamic Client Configuration

PREVIEW

This feature is ready for testing but we recommend keeping it in non-production environments. Note that it is subject to change and may not be feature-complete. Aerospike provides no SLAs or technical support commitments for this preview. Feel free to ask questions or surface concerns directly to our product team.

Overview

Dynamic Client Configuration allows Site Reliability Engineers (SREs) and operators to update most client configuration parameters in real time without redeploying, restarting, or requiring code changes. This enables organizations to accelerate production deployments, resolve incidents faster, eliminate bottlenecks between app development and operations, and enable detailed observability through integrated metrics.

Client library compatibility matrix

Supported clients:

• Java: v9.1.0+
• Python: v17.1.0+
• C: v7.1.0+
• C#: v8.1.0+
• Node.js: v6.3.0+
• Go: not yet available
• Rust: not yet available
• PHP: not yet available

Key benefits

• Real-time operational agility: change most client-side connection and policy parameters instantly, without having to restart your application or roll out new software.
• Separation of concerns: developers focus on business logic, while operators adjust runtime behavior for uptime and SLAs.
• Faster incident recovery: SREs can react quickly to production traffic, correcting misconfigurations and restoring stability in minutes instead of days.
• Integrated metrics control: SREs can turn metrics on and off dynamically, add custom labels, and drive root cause analysis without code changes.

How it works

Dynamic Client Configuration is managed with a local YAML configuration file. The client library monitors this file for changes and applies updates at a configurable interval.

Enable dynamic configuration

To enable dynamic client configuration, set the AEROSPIKE_CLIENT_CONFIG_URL environment variable. This environment variable tells the client which configuration file to monitor for changes. For example:

AEROSPIKE_CLIENT_CONFIG_URL=file://$HOME/.aerospike/config/aerospikeconfig.yaml

Refresh interval

The client polls the file at intervals. The default interval is 5 seconds, configurable with the config_interval parameter.

Change detection

When the file is modified and saved, new settings are loaded and applied in real time.

Fallback

If the file is deleted or invalid, the client continues operating with the last valid configuration in memory and logs an error.

See the Dynamic Client Configuration Quickstart for a full walkthrough of how to get started.

Configuration schema example

Dynamic Client Configuration uses a YAML file with a schema divided into static and dynamic sections.

• static: Options are read at startup and cannot be changed without restarting the app.

• dynamic: The file is polled at defined intervals and options are applied at runtime, enabling live modifications.

Example

version: 1.0.0
static:
  client:
    max_connections_per_node: 100
    min_connections_per_node: 10
dynamic:
  client:
    max_error_rate: 20
  read:
    connect_timeout: 1500
    max_retries: 2
  metrics:
    enable: true
    labels:
      app_id: "fraud-service"
      team: fraud

See the full configuration schema for a complete list of options.

Common Dynamic Client Configuration scenarios

Note

Log output may vary slightly depending on the SDK version and log settings.

Enabling Dynamic Client Configuration

Scenario: You create a valid aerospikeconfig.yaml file and set the AEROSPIKE_CLIENT_CONFIG_URL environment variable.

Sample log output:

DEBUG YAML config successfully loaded.

Error with parsing config file

Scenario: the configuration file has invalid YAML (for example, a missing colon or misaligned indentation).

Sample log output:

WARN Failed to parse <configuration file> <parse error/exception>

If there is no previous valid file, the client uses code settings or built-in defaults.

Adding a new parameter

Scenario: you add a new configuration key not present before (for example, enabling a new metrics label).

YAML before (no metrics section):

dynamic:
  client:
    max_error_rate: 10

YAML After (with new metrics section):

dynamic:
  client:
    max_error_rate: 10
  read:
    max_retries: 2
      team: fraud
      region: us-west

Sample log output:

INFO Set Policy.maxRetries = 2

Important

• When you add the metrics parameter, the client detects the updated YAML file on the next polling interval (1 second by default, or as set by config_interval).
• Behavior and log output may vary slightly depending on the SDK version and log settings, but the above examples are representative for normal log levels.

Updating a parameter

Scenario: Changing the max_retries parameter for read operations.

YAML before:

dynamic:
  client:
    max_error_rate: 10
  read:
    max_retries: 2

YAML after:

dynamic:
  client:
    max_error_rate: 10
  read:
    max_retries: 5

Sample log output:

INFO Set Policy.maxRetries = 5

Usage patterns and best practices

• Organizations with many nodes/apps should use automation (Ansible, Puppet, or other) to manage distribution of configuration files and avoid “file sprawl”. Each client instance must use its own appropriately maintained YAML file.

• No built-in guardrails: The system does not prevent operators from applying extreme, risky, or out-of-bounds configuration values. Server operators who maintain overall SLA compliance and resource availability have the final authority to override developer-set configurations. However, we recommend a close partnership between app developers and server operators to ensure that any changes align with the application’s intended performance and functionality.

Frequently asked questions

1. How does this feature differ from the existing dynamic configuration functionality?

   Dynamic Client Configurations allows operators to update client configurations that previously only lived in the application code. The existing dynamic configuration feature updates server configurations.

2. How long does it take for a dynamic configuration to actuate?

   The client polls the configuration file at intervals defined by the config_interval parameter. By default, the interval is 1 second, but you can modify this in your YAML config.

3. What happens if I delete a parameter or section from the config file?

   If you remove a parameter from the YAML file, the client reverts that parameter to the value which is set programmatically in the application code, or to its internal default if it is absent in both code and configuration file. The order of precedence is:

   • YAML configuration file dynamic values
   • YAML configuration file static values
   • Programmatic/code values
   • Client defaults

4. What happens if I delete the entire YAML file associated with a client?

   If you remove the entire configuration file, the client continues operating with the last valid configuration loaded into memory. This prevents configuration errors or outages due to accidental file deletions.

5. How can I roll back a configuration change or revert to a previous configuration?

   To revert a parameter to its prior (code or default) value, simply delete or comment out that parameter in the YAML configuration file and save. For a full reset to pre-dynamic configuration, erase or comment out the entire contents of the file, allowing it to remain present if the application expects the file. We recommend leaving a comment so others viewing the configuration file know that the file has been purposefully disabled.

6. What if I enter an invalid value or the configuration file contains errors?

   If the YAML file is invalid (for example, bad syntax or unsupported schema/fields), the client logs an error or warning and ignores the faulty file. It continues running using the last valid configuration loaded. If the client is started with only an invalid YAML file and no previous valid configuration, it falls back to programmatic/code values or defaults. Unknown or misspelled keys are ignored, and a warning may be logged, but they do not prevent the application from loading valid parameters.

7. How can I check the client’s current applied configuration?

   You can see the currently loaded configuration settings by inspecting your application logs at INFO or DEBUG level. Each time the configuration is loaded or reloaded, the log shows which parameters were applied.

8. What happens if the version in my configuration file does not match the client’s supported schema version?

   If the version field in your YAML file does not match what your client library supports, the client ignores the file and logs a warning. It continues using prior settings or default values until a valid configuration is provided.

9. Are there special setup steps for logs to verify dynamic configuration functionality?

   Yes. Your application must have logging enabled prior to instantiating the Aerospike client to see configuration application and error messages. For example, in Python, ensure that the log handler and desired log level are set before creating the client.

   def as_logger(level, func, myfile, line, msg):
       print(f"{LOG_LEVEL_NAMES[level]} ({func}@{myfile}:{line}) - {msg}")
   aerospike.set_log_level(aerospike.LOG_LEVEL_TRACE)
   aerospike.set_log_handler(as_logger)

10. Is there a performance impact from dynamic configuration checks?

    Configuration checks are lightweight. The polling interval can be adjusted via the config_interval parameter. Decreasing the interval increases check frequency and may have a minor performance impact, while increasing it lowers check frequency and reduces overhead. The default settings are appropriate for most installations.