SPI Configuration

This document contains specifics for the a9s Search SPI.

General information about the a9s SPIs are described in the a9s SPI documentation.

Custom Parameter Configuration

The a9s Search SPI configures, handles, and validates custom parameters for all Service Instances.

The a9s Search 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 Search SPI configuration. The Platform Operator has to configure the property opensearch-spi.service_instance.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 parameter 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:

opensearch-spi:
  service_instance:
    custom_param_config:
      tls-protocols:
        default_value: ['TLSv1.2', 'TLSv1.3']
        modifiable: true

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 found below.

Name	Default value	Is modifiable	Parameter Configuration
plugins	[]	true	allowed_values
tls-ciphers	null	true	-
tls-protocols	null	true	-

Plugins

The plugins custom parameter is an array of plugins to be enabled on the a9s Search Service Instance, as long as they are in the list of allowed plugins. This list can include any of the supported plugins in a9s Search.

Configuration Properties

• default_value: The list of plugins enabled by default for all Service Instances (default: []).
• modifiable: Whether the Application Developer can modify the plugins list (default: true).
• parameter_configuration.allowed_values : An array specifying which plugins the Application Developer is allowed to enable.

Default Allowed Values

By default, parameter_configuration.allowed_values is configured to include only ['analysis-phonetic'].

Configuration Examples

The following example sets a default list of plugins and allows the Application Developer to enable additional ones:

opensearch-spi:
  service_instance:
    custom_param_config:
      plugins:
        default_value: ['analysis-phonetic', 'opensearch-knn']
        modifiable: true
        parameter_configuration:
          allowed_values:
            - analysis-phonetic
            - opensearch-knn
            - opensearch-alerting
            - opensearch-ml

To always enforce a specific set of plugins without allowing Application Developer modifications, set modifiable: false:

opensearch-spi:
  service_instance:
    custom_param_config:
      plugins:
        default_value: ['analysis-phonetic', 'opensearch-knn']
        modifiable: false
        parameter_configuration:
          allowed_values:
            - analysis-phonetic
            - opensearch-knn

Communicating Configuration to Application Developers

The default_value and allowed_values are not directly exposed to Application Developers via the a9s Framework. It is recommended to communicate this information through the Service Plan description or other accessible documentation, so that Application Developers are aware of which plugins are supported and allowed.

caution

• The allowed_values must contain all plugins listed in default_value. Otherwise, the Application Developer will not be able to keep the default plugins when modifying the list. There is no automatic validation for this. It is the Platform Operator's responsibility to ensure consistency.
• By allowing any plugins besides analysis-phonetic in allowed_values, the Platform Operator acknowledges that this is done under their discretion and responsibility.

Supported Plugins

The following OpenSearch plugins are supported in a9s Search. However, a plugin can only be enabled if it is also present in the list of allowed plugins configured by the Platform Operator.

• analysis-phonetic
• opensearch-alerting
• opensearch-anomaly-detection
• opensearch-asynchronous-search
• opensearch-cross-cluster-replication
• opensearch-custom-codecs
• opensearch-flow-framework
• opensearch-geospatial
• opensearch-index-management
• opensearch-job-scheduler
• opensearch-knn
• opensearch-ltr
• opensearch-ml
• opensearch-neural-search
• opensearch-notifications
• opensearch-notifications-core
• opensearch-observability
• opensearch-performance-analyzer
• opensearch-reports-scheduler
• opensearch-security-analytics
• opensearch-skills
• opensearch-sql
• opensearch-system-templates
• query-insights

For more information about OpenSearch plugins, refer to the OpenSearch Plugins Documentation.

Allowed Plugins

The Platform Operator maintains a list of allowed plugins. This is a curated set of plugins that have been approved for use in the environment. Only plugins that are part of this allowed list can be enabled. By default, only analysis-phonetic is allowed.

If additional plugins are needed, the Platform Operator should be contacted to have them added to the allowed plugins configuration.

Important Notes

• The plugins opensearch-security, repository-azure, and repository-s3 are always enabled and cannot be disabled. They do not need to be included in the plugins array.
• Some plugins have dependencies on other plugins in the given list. Please refer to the official documentation of the plugin of interest before attempting to enable it. Otherwise, enabling a plugin without its dependencies could cause errors.
• The allowed plugins validation does not check for plugin dependencies. It is the Platform Operator's responsibility to ensure that all required dependencies of a plugin are also included in the allowed plugins list before adding it. Failure to do so may cause Service Instance failures when an Application Developer enables the plugin.

tls-protocols

The parameter tls-protocols maps to OpenSearch's configuration parameter plugins.security.ssl.http.enabled_protocols. For more information, see Limiting TLS Protocols Used by the Server.

Because it is insecure, the OpenSearch security plugin disables TLSv1 by default.

The value for tls-protocols must be an array with the values TLSv1.3 and/or TLSv1.2. Only Java format is supported.

tls-ciphers

The parameter tls-ciphers maps to OpenSearch's configuration parameter plugins.security.ssl.http.enabled_ciphers. For more information, see Configuring Cipher Suites.

The value for tls-ciphers must be an array of strings that list the cipher names. Only Java format is supported.

a9s Search SPI does no validation for the tls-ciphers value except that it must be an array of strings or null.

Example Configuration

The following is an example for the default custom parameter configuration.

The default value for the custom parameter tls-protocols is TLSv1.3. Additionally, the Application Developer should not be allowed to change it.

Then the configuration must look the following way:

opensearch-spi:
  service_instance:
    custom_param_config:
      tls-protocols:
        default_value: ['TLSv1.3']
        modifiable: false

Per Plan Configuration

Take a look at Service Plans documentation if you want to configure the custom parameters per plan.

Notes

Additional custom parameters will be made available over time. We do not make all available custom parameters the SPIs knows 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.