docs: Document typed config overrides

Author: siegfriedweber

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

@@ -35,89 +35,36 @@ nodes:
       config: {}
 ----
 
-All override property values must be strings.
-They are added unchanged to the configuration file.
-Care must be taken to produce a valid configuration.
-
-For a list of configuration options, we refer to the
-https://docs.opensearch.org/docs/latest/install-and-configure/configuring-opensearch/index/[Configuring OpenSearch{external-link-icon}^] section in the OpenSearch documentation.
-
-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:
+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`:
 
 [source,yaml]
 ----
-# File: opensearch.yml
-
-plugins.security.restapi.roles_enabled: all_access
-
-# is equivalent to
-
-plugins:
-  security:
-    restapi:
-      roles_enabled: all_access
+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
 ----
 
-Lists can be flattened as follows:
+The entire configuration file can be replaced using the `userProvided` property:
 
 [source,yaml]
 ----
-# 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.4.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]
+nodes:
+  configOverrides:
+    opensearch.yml:
+      userProvided:
+        plugins.security.restapi.roles_enabled: all_access
 ----
-# File: opensearch.yml
 
-# Boolean as string
-cluster.blocks.read_only: "true"
+NOTE: 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.
 
-# 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
-----
+For a list of configuration options, we refer to the
+https://docs.opensearch.org/docs/latest/install-and-configure/configuring-opensearch/index/[Configuring OpenSearch{external-link-icon}^] section in the OpenSearch documentation.
 
 == Environment Variables