a9s KeyValue SPI Configuration

This document describes a9s KeyValue SPI configuration.

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:

service_instance:
  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-policy	'volatile-lru'	true	all
maxmemory-samples	5	true	all
notify-keyspace-events	''	true	all
stop-cluster-update-on-failure	true	false	all
tls-ciphers	null	true	all
tls-ciphersuites	null	true	all
tls-protocols	null	true	all

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.

info

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.

caution

• You need to be careful when setting modifiable to true for additional_sentinel_acls as 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.

info

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.

caution

• You need to be careful when setting modifiable to true for additional_valkey_acls as 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.

Protocols

For more details on this property, please refer to the a9s Framework TLS configuration documentation.