---
title: "Dynamic configuration for Aerospike on Kubernetes"
description: "How to enable and manage dynamic Aerospike configuration updates in the AerospikeCluster CR on Kubernetes."
---

# Dynamic configuration for Aerospike on Kubernetes

> For the complete documentation index see: [llms.txt](https://aerospike.com/docs/llms.txt)
> 
> All documentation pages available in markdown.

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](https://aerospike.com/docs/database/reference/config) 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`.
    
    ```yaml
    spec:
    
      enableDynamicConfigUpdate: true
    
      aerospikeConfig:
    
        ...
    ```
    
2.  Apply the updated CR file.
    
    Terminal window
    
    ```shell
    kubectl apply -f aerospike-cluster.yaml
    ```
    
3.  Verify that the setting is enabled in the `AerospikeCluster` CR.
    
    Terminal window
    
    ```shell
    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`](https://aerospike.com/docs/kubernetes/manage/configure/replication-factor).

## Failure handling

Internally, each configuration change is translated into an [`asadm`](https://aerospike.com/docs/database/tools/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](https://aerospike.com/docs/database/reference/config) for more information about each parameter.

| **Name** | **Context/sub-context** | **Required Conditions** |
| --- | --- | --- |
| `microsecond-histograms` | `Service` | This is a static configuration for the [auto-enabled](https://aerospike.com/docs/database/observe/latency#auto-enabled-benchmarks) 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.
:::