SPI Configuration
This document contains specifics for the a9s KeyValue SPI.
General information about the a9s SPIs are described in the a9s SPI documentation.
Custom Parameter Configuration
The a9s KeyValue SPI handles custom parameters for all Service Instances. It does configuration and validation of custom parameters.
The a9s KeyValue SPI defines default values for certain custom parameters. Also, it defines whether a custom parameter can be set by the Application Developer.
The Platform Operator can overwrite those choices by changing the a9s KeyValue SPI configuration. The Platform Operator
has to configure the property custom_param_config. The property value must be a hash. Every key
in that hash stands for a custom parameter and the value for every key contains the configuration for that particular
parameter.
The configuration for a particular param is a hash consisting of the following optional keys: default_value
and modifiable. The key default_value specifies the default value for that parameter and modifiable specifies
whether the Application Developer is allowed to set that custom parameter. For example:
custom_param_config:
maxclients:
default_value: 6000
modifiable: false
Default Custom Parameter Configuration
The following table contains custom parameters that are configurable by the Platform Operator. The meaning of those custom parameters can be read in the Application Developer documentation for a9s KeyValue.
| Name | Default value | Is modifiable | Version Compatibility |
|---|---|---|---|
additional_sentinel_acls | [] | false | all |
additional_valkey_acls | [] | false | all |
cluster-update-node-timeout | 10 | false | all |
down-after-milliseconds | 10000 | true | all |
failover-timeout | 30000 | true | all |
hostname-resolution | 'disabled' | true | all |
lazyfree-lazy-eviction | 'no' | true | all |
lazyfree-lazy-expire | 'no' | true | all |
lua-time-limit | 5000 | true | all |
maxclients | 10000 | true | all |
maxmemory | 'dynamic' | true | all |
maxmemory-policy | 'volatile-lru' | true | all |
maxmemory-samples | 5 | true | all |
notify-keyspace-events | '' | true | all |
stop-cluster-update-on-failure | true | false | all |
repl-backlog-size | '1mb' | true | all |
min-replicas-to-write | 1 | true | all |
min-replicas-max-lag | 10 | true | all |
tls-ciphers | null | true | all |
tls-ciphersuites | null | true | all |
tls-protocols | null | true | all |
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 disconnect 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.
maxmemory
The parameter maxmemory corresponds to the Valkey configuration maxmemory.
It sets a memory usage limit to the specified amount. The default value is dynamic, which means
that it is set to the optimal amount determined by a9s KeyValue. 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.
The maxmemory parameter could lead to unexpected behaviour and therefore need to be handled cautiously.
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 an amount of connected replicas that are required so that the primary will accept write operations. If there are less connect replicas then the specific amount, the primary will only perform read operations.
The functionality can be disabled by setting the parameter to 0.
The replcias 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.
additional_sentinel_acls
The parameter additional_sentinel_acls corresponds to the Valkey feature Valkey ACL.
This parameter can be used to modify the ACL rules that are applied by the a9s KeyValue SPI for the Sentinel user.
The ACL rules that are configured using the parameter additional_sentinel_acls will be applied additionally to the ACL
rules that the a9s KeyValue SPI is applying per default.
a9s KeyValue SPI does no validation for the additional_sentinel_acls value except that it must be of type array of
strings or null.
- You need to be careful when setting
modifiabletotrueforadditional_sentinel_aclsas the Application Developer is then able to modify the ACL rules and also to revoke the default ACL rules set by the a9s KeyValue SPI. - Be cautious when setting the ACL rules; configuring them with incorrect or nonexistent values will cause the service key creation to fail.
We recommend to enable to this parameter only for specific plans and not for all service plans. See Per Plan Configuration for more information.
additional_valkey_acls
The parameter additional_valkey_acls corresponds to the Valkey feature Valkey ACL.
This parameter can be used to modify the ACL rules that are applied by the a9s KeyValue SPI for the Valkey user.
The ACL rules that are configured using the parameter additional_valkey_acls will be applied additionally to the ACL
rules that the a9s KeyValue SPI is applying per default.
a9s KeyValue SPI does no validation for the additional_valkey_acls value except that it must be of type array of
strings or null.
- You need to be careful when setting
modifiabletotrueforadditional_valkey_aclsas the Application Developer is then able to modify the ACL rules and also to revoke the default ACL set by the a9s KeyValue SPI. - Be cautious when setting the ACL rules; configuring them with incorrect or nonexistent values will cause the service key creation to fail.
We recommend to enable to this parameter only for specific plans and not for all service plans. See Per Plan Configuration for more information.
tls-protocols
The parameter tls-protocols corresponds to the Valkey configuration parameter tls-protocols.
tls-ciphers
The parameter tls-ciphers corresponds to the Valkey configuration parameter tls-ciphers. This parameter sets the
list of ciphers used for TLS 1.2 and below.
a9s KeyValue SPI does no validation for the tls-ciphers value except that it must be of type string or null
(do not set tls-ciphers in valkey.conf and sentinel.conf).
tls-ciphersuites
The parameter tls-ciphersuites corresponds to the Valkey configuration parameter tls-ciphersuites. This parameter
sets the list of ciphers used for TLS 1.3 and above.
a9s KeyValue SPI does no validation for the tls-ciphersuites value except that it must be of type string or null
(do not set tls-ciphers in valkey.conf and sentinel.conf).
hostname-resolution
For more information, refer to the hostname-resolution section of the Application Developer's documentation.
Example Configuration
Let's build an imaginary example.
The default value for the maxclients custom parameter should be 600. The custom parameter lua-time-limit should
also have a default value of 600 and the Application Developer should not be allowed to change it.
Then the configuration must look the following way:
custom_param_config:
maxclients:
default_value: 600
modifiable: true
lua-time-limit:
default_value: 600
modifiable: false
failover-timeout:
default_value: 30000
modifiable: true
down-after-milliseconds:
default_value: 10000
modifiable: true
Per Plan Configuration
Take a look at Service Plans documentation if you want to configure custom parameters per plan.
Notes
Additional custom parameters will be made available over time. We do not make all available custom parameters the SPIs know available to the Platform Operator from the beginning.
During the SPI startup, the configuration the Platform Operator made will be checked. When it's invalid, the SPI will not start up.