Custom Parameters
As mentioned in Getting Started - Custom Parameters as an end user, an Application Developer has the opportunity to customize their Service Instance by using custom parameters.
Change RDB Persistence Settings
a9s KeyValue supports RDB persistence with point in time snapshots. This setting can be changed by the user.
By default, the persistency is disabled for a9s KeyValue Service Instances.
When persistency is disabled, the a9s KeyValue ensures state consistency, which means no RDB should exist. Therefore, manually creating an RDB via the API must be avoided, as it could lead to inconsistent behavior, such as recovering undesired data in some cases.
Please note that in a non-persistent scenario, if the Service Instance is a single plan and the Valkey process is restarted, data will be cleaned up. However, if the Service Instance is a replica plan, the replica will recover the data even if one of the nodes of the Service Instance has restarted the Valkey process.
RDB can be configured according to the needs of the application by providing custom parameters as settings. This setting
must follow the original Valkey configuration for RDB -c "{\"snapshot\": \"['save 900 1','save 300 10']\"}.
cf update-service my-keyvalue-service -c "{\"snapshot\": \"['save 900 1','save 300 10']\"}"
In this example, it configures to snapshot the Valkey database according to the following rules:
| Setting | Effect |
|---|---|
save 900 1 | Create a snapshot after 900 seconds if 1 write operations occurred. |
save 300 10 | Create a snapshot after 300 seconds if 10 write operations occurred. |
Cache Only
Snapshots can be disabled in order to use Valkey as cache only, by creating the service with the following custom parameter:
-c "{\"snapshot\": \"[]\"}".
The command is:
cf update-service my-keyvalue-service -c "{\"snapshot\": \"[]\"}"
For more information, see the snapshot settings in the documentation of Valkey Persistence.
Replication
| Parameter | Type | Default Value | Description |
|---|---|---|---|
repl-backlog-size | String | '1mb' | Set the replication backlog size for the cluster. See repl-backlog-size. |
min-replicas-to-write | Integer | 1 | The amount of connected replicas that are required for the primary to accept write operations. It can be set to 0 to disable it. See min-replicas-to-write. |
min-replicas-max-lag | Integer | 10 | The max lag in seconds that replicas can have without being recognized as disconnected. It needs to be higher then 0. See min-replicas-max-lag. |
These replication parameters could lead to unexpected behavior, or could turn the cluster into a read-only Service Instance. Therefore, these parameters should be handled with caution.
Changes in the replication parameters could also affect the functionality of the Lazy Freeing settings.
repl-backlog-size
The parameter repl-backlog-size corresponds to the Valkey configuration repl-backlog-size.
It sets the size of the backlog, which is used as a buffer to temporarily store replication data if a node is disconnected for some time. The backlog helps to prevent a full synchronization by making it possible to replay only the last changes.
The minimal value of the backlog is 16 KB. The memory format like kb will be interpreted as KiB by valkey. So, in
this case 16KB will be equal to 16384 bytes.
If the repl-backlog-size parameter is set too low, it can increase the likelihood of a full-synchronization and affect
the performance and availability of the cluster.
min-replicas-to-write
The parameter min-replicas-to-write corresponds to the Valkey configuration min-replicas-to-write.
With this parameter it is possible to specify a minimal amount of connected replicas that are required so that the primary will accept write operations. If there are fewer connected replicas then the specific amount, the primary will only perform read operations.
This functionality can be disabled by setting the parameter to 0.
The replicas are considered as connected if they send a ping within the specified time window of the
min-replicas-max-lag configuration.
The min-replicas-to-write parameter can affect the availability of the cluster or turn the cluster into a read-only
service.
min-replicas-max-lag
The parameter min-replicas-max-lag corresponds to the Valkey configuration min-replicas-max-lag.
It sets the lag in seconds, which should not be exceeded between two ping messages from the replicas to the primary
node. If the lag is exceeded, the replica is recognized as disconnected and this could block write operations of the
cluster, depending on the min-replicas-to-write configuration.
The min-replicas-max-lag parameter can affect the availability of the cluster or turn the cluster into a read-only
service.
Lazy Freeing
Lazy freeing (also known as asynchronous freeing) allows to release memory in a non-blocking way. This allows for keys to be deleted in constant time, via a separate thread that will incrementally free the objects in the background as fast as possible.
| Parameter | Type | Default Value | Description |
|---|---|---|---|
lazyfree-lazy-eviction | String | no | Objects are deleted on eviction, because of maxmemory and its policy configurations. |
lazyfree-lazy-expire | String | no | Objects are deleted when a key has reached its associated time to live. |
maxmemory | String | 'dynamic' | It sets a memory usage limit to a specified amount, a dynamic value or disabling it. See maxmemory. |
maxmemory-policy | String | volatile-lru | Policy specifying what kind of keys to remove when maxmemory is reached. See Change Maxmemory Policy. |
maxmemory-samples | Integer | 5 | Amount of samples to check before an eviction. The value must be an integer >= 0. |
maxmemory
The maxmemory parameter could lead to unexpected behaviour and therefore need to be handled cautiously.
The parameter maxmemory corresponds to the Valkey configuration maxmemory.
It limits the memory usage to the specified amount. The default value is dynamic, hence the optimal amount determined
by a9s KeyValue is used. When the memory limit is reached the server will try to remove keys according to the eviction
policy selected by the maxmemory-policy parameter.
If the parameter is set to 0, there will be no limit for the amount of used memory. The memory format like mb will
be interpreted as MiB by Valkey. So, in this case 1MB will be equal to 1048576 bytes.
Change Maxmemory Policy
With the maxmemory-policy, a9s KeyValue can be configured to remove certain keys when maxmemory is reached. There
are several configurable behaviors.
| Value | Effect |
|---|---|
volatile-lru | Remove the key with an expire set using an LRU algorithm This is the default value. |
allkeys-lru | Remove any key according to the LRU algorithm |
volatile-random | Remove a random key with an expire set |
allkeys-random | Remove a random key |
volatile-ttl | Remove the key with the nearest expire time (minor TTL) |
noeviction | Don't expire at all, just return an error on write operations |
For more information, see the maxmemory-policy settings in the self documented valkey.conf.
Client Handling
The following parameters are available to configure how a9s KeyValue handles clients at the network level:
| Parameter | Type | Default Value | Description |
|---|---|---|---|
maxclients | Integer | 10000 | Maximum amount of clients that can be simultaneously connected. |
Valkey Sentinel Settings
The following parameters can be used to specify settings in Valkey sentinel.
| Parameter | Type | Default Value | Description |
|---|---|---|---|
down-after-milliseconds | Integer | 10000 | Specifies the milliseconds a node is unreacheable in order to consider it subjectively down. The value must be >= 0. |
failover-timeout | Integer | 30000 | Specifies the failover timeout in milliseconds. The value must be >= 0. |
hostname-resolution | String | disabled | Provides the option to enable and disable DNS/hostname support in Valkey and Sentinel. For more information, see the section below. |
hostname-resolution
- This feature specifically applies to a9s KeyValue Cluster instances.
- When enabling or disabling the feature in an existing a9s Service Instance, there might be an increased downtime during the first cluster update due to a temporary divergence in Sentinel's settings when switching between IP address and hostname.
- When enabled, unexpected delays in address resolution may have a negative impact on Sentinel. For more information, refer to the Valkey documentation.
The feature provides the option to enable and disable DNS/hostname support in Valkey and Sentinel. When enabled, it will utilize the hostname for internal cluster communication and announce Valkey and Sentinel node information using the hostname instead of the typical IP address.
Using this feature is useful when Valkey clients use TLS to connect to Service Instances and require a hostname rather than an IP address in order to perform certificate ASN matching.
Using it
To enable or disable hostname-resolution, it is important to follow a series of steps to ensure safety and prevent
significant downtime or data loss. Depending on its current state, the process may require adjusting a custom parameter
in two steps. See the cases below:
- To enable it in an existing Service Instance, follow these steps:
disabled → resolve-only → enabled. - To disable it in an existing Service Instance, follow these steps:
enabled → resolve-only → disabled. - When creating a new Service Instance, any value can be set directly. We suggest using either
enabledordisabled.
Please note that transitioning directly from disabled to enabled, and vice versa, is not possible in an existing
Service Instance.
| Value | Description |
|---|---|
disabled | Hostname resolution and announcement are fully disabled. |
resolve-only | Hostname resolution is enabled but announcement is disabled. |
enabled | Hostname resolution and announcement are fully enabled. |
The default value is disabled.
TLS Settings
tls-protocols
The supported TLS versions can b explicitly specified . Allowed values are "TLSv1.2" and "TLSv1.3" or any combination.
- Improper changes to this value can easily break existing instances.
- When using TLSv1.3 only, Valkey specific metrics will not be provided.
The default value is null. In this case Valkey uses TLSv1.2 and TLSv1.3.
tls-ciphers
Configure allowed ciphers. See the ciphers(1ssl) manpage for more information about the syntax of this string.
There is no validation enabled for the user provided values and therefore existing instances can break when applying this parameter.
The default value is null which comments out the Valkey config tls-ciphers in the Valkey and Sentinel configuration
files.
tls-ciphersuites
Configure allowed ciphersuites. See the ciphers(1ssl) manpage for more information about the syntax of this string, and specifically for TLSv1.3 ciphersuites.
There is no validation enabled for the user provided values and therefore existing instances can break when applying this parameter.
The default value is null which comments out the Valkey config tls-ciphersuites in the Valkey and Sentinel
configuration files.
Other Settings
| Parameter | Type | Default Value | Description |
|---|---|---|---|
lua-time-limit | Integer | 5000 | Maximum amount of time (in ms) that a script is allowed to run. |
notify-keyspace-events | String | '' | Sets the Valkey Keyspace Notifications. |