doc: Adapt overrides page

Author: siegfriedweber

docs/modules/opensearch/pages/index.adoc

@@ -32,7 +32,7 @@ It creates a number of different Kubernetes resources based on this {crs}[custom
 The OpenSearchCluster is the resource for the configuration of the OpenSearch instance.
 The resource defines only one xref:concepts:roles-and-role-groups.adoc[role], the `nodes`.
 The various configuration options are explained in the xref:usage-guide/index.adoc[].
-It helps you tune your cluster to your needs by configuring xref:usage-guide/storage-resource-configuration.adoc[resource usage], xref:usage-guide/security.adoc[security], xref:usage-guide/logging.adoc[logging] and more.
+It helps you tune your cluster to your needs by configuring xref:usage-guide/storage-resource-configuration.adoc[resource usage] and more.
 
 === Kubernetes resources
 

docs/modules/opensearch/pages/usage-guide/configuration-environment-overrides.adoc

@@ -1,15 +1,15 @@
 = Configuration & Environment Overrides
 
-The cluster definition also supports overriding configuration properties and environment variables,
+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).
 
-IMPORTANT: Overriding certain properties which are set by the operator (such as the `STATS_LOGGER`) can interfere with the operator and can lead to problems.
+IMPORTANT: 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 `superset_config.py`.
-For example, if you want to set the CSV export encoding and the preferred databases adapt the `nodes` section of the cluster resource as follows:
+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`, then adapt the `nodes` section of the cluster resource as follows:
 
 [source,yaml]
 ----
@@ -18,16 +18,8 @@ nodes:
     default:
       config: {}
       configOverrides:
-        superset_config.py:
-          CSV_EXPORT: "{'encoding': 'utf-8'}"
-          PREFERRED_DATABASES: |-
-            [
-                'PostgreSQL',
-                'Presto',
-                'MySQL',
-                'SQLite',
-                # etc.
-            ]
+        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:
@@ -36,53 +28,95 @@ Just as for the `config`, it is possible to specify this at the role level as we
 ----
 nodes:
   configOverrides:
-    superset_config.py:
-      CSV_EXPORT: "{'encoding': 'utf-8'}"
-      PREFERRED_DATABASES: |-
-        [
-            'PostgreSQL',
-            'Presto',
-            'MySQL',
-            'SQLite',
-            # etc.
-        ]
+    opensearch.yml:
+      plugins.security.restapi.roles_enabled: all_access
   roleGroups:
     default:
       config: {}
 ----
 
 All override property values must be strings.
-They are treated as Python expressions.
+They are added unchanged to the configuration file.
 So care must be taken to produce a valid configuration.
 
-For a full list of configuration options we refer to the
-https://github.com/apache/superset/blob/master/superset/config.py[main config file for Superset].
+For a list of configuration options, we refer to the
+https://docs.opensearch.org/docs/latest/install-and-configure/configuring-opensearch/index/[Configuring OpenSearch] section in the OpenSearch documentation.
 
-As Superset can be configured with python code too, arbitrary code can be added to the `superset_conf.py`.
-You can use either `EXPERIMENTAL_FILE_HEADER` to add code to the top or `EXPERIMENTAL_FILE_FOOTER` to add to the bottom.
+The file `opensearch.yml` is a YAML file, where deep structures are possible.
+On the other hand, `configOverrides` are only flat key-value pairs.
+Fortunately, this is not a problem because the OpenSearch YAML parser allows both representations.
+Keys can be flattened as follows:
 
-IMPORTANT: This is an experimental feature
+[source,yaml]
+----
+# File: opensearch.yml
+
+plugins.security.restapi.roles_enabled: all_access
+
+# is equivalent to
+
+plugins:
+  security:
+    restapi:
+      roles_enabled: all_access
+----
+
+Lists can be flattened as follows:
 
 [source,yaml]
 ----
-nodes:
-  configOverrides:
-    superset_config.py:
-      CSV_EXPORT: "{'encoding': 'utf-8'}"
-      EXPERIMENTAL_FILE_HEADER: |
-        from modules.my_module import my_class
-      EXPERIMENTAL_FILE_FOOTER: |
-        import logging
-        from superset.security import SupersetSecurityManager
-
-        class myCustomSecurityManger(SupersetSecurityManager):
-          def __init__():
-            init()
-
-        CUSTOM_SECURITY_MANAGER = myCustomSecurityManger
-  roleGroups:
-    default:
-      config: {}
+# File: opensearch.yml
+
+# as a comma-separated list: <1>
+plugins.security.restapi.roles_enabled: role1,role2,role3
+
+# as a JSON list: <2>
+plugins.security.restapi.roles_enabled: ["role1", "role2", "role3"]
+
+# as an indexed flat list: <3>
+plugins.security.restapi.roles_enabled.0: role1
+plugins.security.restapi.roles_enabled.1: role2
+plugins.security.restapi.roles_enabled.2: role3
+
+# All options above are equivalent to
+
+plugins:
+  security:
+    restapi:
+      roles_enabled:
+        - role1
+        - role2
+        - role3
+----
+<1> Commas in list entries cannot be escaped.
+<2> The brackets must be escaped in `configOverrides` as follows: `"[\"role1\", \"role2\", \"role3\"]"`
+<3> Indexed flat lists are considered "legacy" in the OpenSearch code.
+// see https://github.com/opensearch-project/OpenSearch/blob/3.1.0/server/src/main/java/org/opensearch/common/settings/Settings.java#L1049
+
+Other types can be set as strings in `configOverrides` because OpenSearch parses them:
+
+[source,yaml]
+----
+# File: opensearch.yml
+
+# Boolean as string
+cluster.blocks.read_only: "true"
+
+# Integer as string
+cluster.max_shards_per_node: "10000"
+
+# Floating point as string
+cluster.routing.allocation.balance.index: "0.6"
+
+# Time unit as string
+cluster.info.update.interval: "10s"
+
+# The options above are equivalent to
+
+cluster.blocks.read_only: true
+cluster.max_shards_per_node: 10000
+cluster.routing.allocation.balance.index: 0.6
+cluster.info.update.interval: 10s
 ----
 
 == Environment Variables
@@ -97,7 +131,7 @@ nodes:
     default:
       config: {}
       envOverrides:
-        FLASK_ENV: development
+        OPENSEARCH_PATH_CONF: /etc/opensearch
 ----
 
 or per role:
@@ -106,15 +140,39 @@ or per role:
 ----
 nodes:
   envOverrides:
-    FLASK_ENV: development
+    OPENSEARCH_PATH_CONF: /etc/opensearch
   roleGroups:
     default:
       config: {}
 ----
 
-// cliOverrides don't make sense for this operator, so the feature is omitted for now
+== CLI parameters
+
+CLI parameters can be set with `cliOverrides` per role group:
+
+[source,yaml]
+----
+nodes:
+  roleGroups:
+    default:
+      config: {}
+      cliOverrides:
+        --pidfile: /tmp/mypidfile.pid
+----
+
+or per role:
+
+[source,yaml]
+----
+nodes:
+  cliOverrides:
+    --pidfile: /tmp/mypidfile.pid
+  roleGroups:
+    default:
+      config: {}
+----
 
 == Pod overrides
 
-The Superset operator also supports Pod overrides, allowing you to override any property that you can set on a Kubernetes Pod.
+The OpenSearch operator also supports Pod overrides, allowing you to override any property that you can set on a Kubernetes Pod.
 Read the xref:concepts:overrides.adoc#pod-overrides[Pod overrides documentation] to learn more about this feature.