Configuration Server client properties

This page documents Java system properties that control how Deephaven processes connect to the Configuration Server. These properties tune connection behavior, load balancing, timeouts, and retry logic.

Note

These are Java system properties, not Deephaven properties file settings. Set them using the -D flag when starting a Java process (e.g., -Dconfiguration.server.load.balancer.policy=round_robin).

Connection properties

Property	Default	Description
`configuration.server.load.balancer.policy`	`pick_first`	gRPC load balancing policy for connecting to configuration servers. See Load balancer policies.
`configuration.server.rearrange.hosts`	`true`	Whether to randomly shuffle the order of configuration servers before connecting.
`configuration.server.connection.timeout.millis.single`	`30000`	Connection timeout in milliseconds when only one configuration server is configured.
`configuration.server.connection.timeout.millis.multi`	`6000`	Connection timeout in milliseconds when multiple configuration servers are configured. The shorter default allows faster failover.

Retry properties

Property	Default	Description
`configuration.server.max.retries.limit`	`60`	Maximum number of retry attempts for gRPC calls. Set to `0` to disable retries.
`configuration.server.connectTimeoutMs`	`60000`	Overall timeout in milliseconds for loading configuration from the server.
`configuration.server.retryPauseMs`	`1000`	Pause in milliseconds between retry attempts when connecting to the configuration server.

Service configuration

Property	Default	Description
`configuration.server.service.config.json`	`configuration_service_config.json`	Name of the gRPC service configuration JSON file.

Load balancer policies

The configuration.server.load.balancer.policy property accepts gRPC load balancing policy names:

pick_first (default) — Tries configuration servers in order. Connects to the first available server and stays connected. If the connection fails, it moves to the next server. Best for most deployments.
round_robin — Maintains connections to all configuration servers and distributes requests across them. Useful for high-availability deployments where you want active connections to all servers.

When configuration.server.rearrange.hosts is true (the default), the order of servers is randomized before applying the load balancing policy. This helps distribute load across servers even with pick_first.

Examples

High-availability configuration

To use round-robin load balancing with active connections to all configuration servers:

java -Dconfiguration.server.load.balancer.policy=round_robin \
     -Dconfiguration.server.connection.timeout.millis.multi=10000 \
     -jar my-application.jar

Troubleshooting connectivity issues

If clients are timing out before reaching the Configuration Server, increase the timeout values:

java -Dconfiguration.server.connection.timeout.millis.single=60000 \
     -Dconfiguration.server.connectTimeoutMs=120000 \
     -jar my-application.jar

Disabling retries for debugging

To disable automatic retries and see failures immediately:

java -Dconfiguration.server.max.retries.limit=0 \
     -jar my-application.jar

Kubernetes configuration

In Kubernetes deployments, set these properties via Helm values in your override file. For example, to set the connection timeout in milliseconds when multiple Configuration Servers are configured:

process:
  configuration-server:
    jvmArgsUser: "-Dconfiguration.server.connection.timeout.millis.multi=60000"

Apply the configuration with helm upgrade. For more Helm configuration options, see Kubernetes configuration settings.