Configuration & Environment Overrides

The cluster definition also supports overriding configuration properties, environment variables and CLI parameters, either per role or per role group, where the more specific override (role group) has precedence over the less specific one (role).

Overriding certain properties which are set by the operator (such as the network.host) can interfere with the operator and can lead to problems.

Configuration Properties

For a role or role group, at the same level of config, you can specify configOverrides for the opensearch.yml. For example, if you want to enable role-based access to the REST management API for the role all_access (not to be confused with the OpenSearch node role), then adapt the cluster resource as follows:

nodes:
  roleGroups:
    default:
      config: {}
      configOverrides:
        opensearch.yml:
          plugins.security.restapi.roles_enabled: all_access

Just as for the config, it is possible to specify this at the role level as well:

nodes:
  configOverrides:
    opensearch.yml:
      plugins.security.restapi.roles_enabled: all_access
  roleGroups:
    default:
      config: {}

Property values must be strings when defined as key-value pairs. To override properties using other types or nested structures, use a JSON Merge Patch by placing the properties under jsonMergePatch:

nodes:
  configOverrides:
    opensearch.yml:
      jsonMergePatch:
        plugins.security.restapi.roles_enabled: all_access
        cluster.routing.allocation.disk.threshold_enabled: false
        plugins.security.authcz.admin_dn:
          - CN=opensearch-admin-certificate

A JSON Merge Patch is the recommended method for overriding configuration settings.

Use a JSON Patch when you need finer-grained control, e.g. to remove a setting. Define a JSON Patch using the jsonPatch property, which accepts a list of operations:

nodes:
  configOverrides:
    opensearch.yml:
      jsonPatch:
        - op: add
          path: /plugins.security.authcz.admin_dn
          value: CN=opensearch-admin-certificate
        - op: remove
          path: /plugins.security.allow_default_init_securityindex

The operator only logs a warning if the JSON Patch could not be applied and continues with the unpatched configuration.

The entire configuration file can be replaced using the userProvided property:

nodes:
  configOverrides:
    opensearch.yml:
      userProvided:
        plugins.security.restapi.roles_enabled: all_access

Replacing the entire configuration file is not recommended, as all properties normally managed by the operator must be explicitly provided to obtain a working OpenSearch cluster.

For a list of configuration options, we refer to the Configuring OpenSearch section in the OpenSearch documentation.

Environment Variables

In a similar fashion, environment variables can be (over)written. For example per role group:

nodes:
  roleGroups:
    default:
      config: {}
      envOverrides:
        OPENSEARCH_HOME: /usr/share/opensearch

or per role:

nodes:
  envOverrides:
    OPENSEARCH_HOME: /usr/share/opensearch
  roleGroups:
    default:
      config: {}

The environment variables OPENSEARCH_HOME and OPENSEARCH_PATH_CONF are worth mentioning. OPENSEARCH_HOME contains the path in the image where OpenSearch is installed. OPENSEARCH_PATH_CONF contains the path with the OpenSearch configuration files. They are usually set in the image. In the Stackable image, OPENSEARCH_HOME is set to /stackable/opensearch and OPENSEARCH_PATH_CONF to ${OPENSEARCH_HOME}/config. The operator must also know the values of these environment variables to mount volumes to the correct paths. Since the operator cannot read the values from the image, it assumes the ones from the Stackable image. If you use a custom image with different paths, you can override one or both of these environment variables as shown in the example above.

CLI parameters

CLI parameters can be set with cliOverrides per role group:

nodes:
  roleGroups:
    default:
      config: {}
      cliOverrides:
        --pidfile: /tmp/mypidfile.pid

or per role:

nodes:
  cliOverrides:
    --pidfile: /tmp/mypidfile.pid
  roleGroups:
    default:
      config: {}

Pod overrides

The OpenSearch operator also supports Pod overrides, allowing you to override any property that you can set on a Kubernetes Pod. Read the Pod overrides documentation to learn more about this feature.