Dynamic configuration for Aerospike on Kubernetes

This page explains how to enable dynamic configuration updates in the AerospikeCluster custom resource (CR). After you enable this feature, AKO can apply supported Aerospike Database configuration changes without a rolling restart, and the changes persist after future pod restarts.

AKO applies dynamic configuration changes from the CR one parameter at a time. This lets you update supported settings in place while still keeping the CR as the source of truth for the cluster configuration.

Note

Not all parameters are dynamic. Check the Configuration Reference to see which parameters are tagged as static or dynamic. Changes to static configuration parameters trigger a rolling restart of Aerospike Database instances.

Adding a new Secret or PVC counts as a storage change and triggers a rolling cold restart, even if related to a dynamic parameter.

Enable dynamic configuration updates

1. Edit the aerospike-cluster.yaml CR file and set spec.enableDynamicConfigUpdate to true.

   spec:
     enableDynamicConfigUpdate: true
     aerospikeConfig:
       ...

2. Apply the updated CR file.

   kubectl apply -f aerospike-cluster.yaml

3. Verify that the setting is enabled in the AerospikeCluster CR.

   kubectl describe aerospikecluster CLUSTER_NAME -n aerospike

   Check the spec section for enableDynamicConfigUpdate: true.

Update one database parameter at a time, and wait for the change to succeed before you make another update. This reduces the risk of partially applied configuration changes that can leave a pod in a non-functional state and require a manual restart.

For AP namespaces in AKO 4.4.0 and later, use this flow to update replication-factor.

Failure handling

Internally, each configuration change is translated into an asadm command. The commands are executed on the Aerospike database one at a time in the order they appear in the CR file, top to bottom.

If all commands succeed, AKO proceeds to the next pod.

These commands can fail in two ways:

• Partial failure: If some parameters are applied successfully and others fail, AKO triggers a rolling restart as a fallback.

• Full failure: If none of the changes are applied successfully, AKO keeps trying to apply them dynamically until the change succeeds or you revert it in the CR.

Limitations

When AKO updates the Aerospike configuration dynamically, certain fields may cause a command failure if they fail to meet certain conditions.

This list is non-exhaustive and only represents the most common potential failures. See the Configuration Reference for more information about each parameter.

Name	Context/sub-context	Required Conditions
microsecond-histograms	Service	This is a static configuration for the auto-enabled histograms.
connect-timeout-ms	Network/heartbeat	This value must be at least 50. It cannot be larger than one-third of the product of heartbeat.interval and heartbeat.timeout.
default-ttl	Namespace, Namespace/Set	To set a non-zero value for default-ttl, you must configure a non-zero nsup-period or allow-ttl-without-nsup to true.
disable-write-dup-res	Namespace	Only applicable for AP namespaces
disallow-expunge	Namespace	Only applicable for AP namespaces
conflict-resolution-policy	Namespace	Only applicable for AP namespaces
max-throughput	XDR/Namespace	Value should be a multiple of 100
transaction-queue-limit	XDR/Namespace	Value should be a power of 2

Note

In the XDR configuration, ignore-bins, ignore-sets, ship-bins, and ship-sets are list-typed fields. Removing an entry from any of these lists is never applied through the dynamic configuration flow: the Aerospike server does not support dropping list elements dynamically. When a CR change removes items from any of these lists, AKO applies it with a rolling restart instead of dynamic in-place updates.