ECE and ECH: added relation between secure settings and user settings (#1190)

Closes elastic/docs-projects#466

I've added an improvement in ECE docs, explaining the relation between
the secure settings and standard user settings (when a feature requires
both types of settings, secure settings need to be configured first to
avoid cluster restarting issues (bootloops) ).

Let me know your thoughs, @shainaraskas .

I've added cross comments in:
- ECE user settings page (important banner because secure settings
should be updated first)
- ECH user settings page (important banner for the same reason)
- Secure settings page (not marked as important).

On top of that I've changed the headings of all `examples`, as H2 was
showing the titles too big.

---------

Co-authored-by: shainaraskas <[email protected]>

Author: eedugon

deploy-manage/deploy/cloud-enterprise/edit-stack-settings-apm.md

@@ -62,9 +62,9 @@ To change APM settings:
 If a setting is not supported by {{ece}}, you get an error message when you try to save. We suggest changing one setting with each save, so you know which one is not supported.
 ::::
 
+## Examples
 
-
-## Example: Enable RUM and increase the rate limit (legacy) [ece_example_enable_rum_and_increase_the_rate_limit_legacy]
+### Enable RUM and increase the rate limit (legacy) [ece_example_enable_rum_and_increase_the_rate_limit_legacy]
 
 When capturing the user interaction with clients with real user monitoring (RUM), particularly for situations with concurrent clients, you can increase the number of times each IP address can send a request to the RUM endpoint. Version 6.5 includes an additional settings for the LRU cache.
 
@@ -80,7 +80,7 @@ apm-server:
 ```
 
 
-## Example: Disable RUM (legacy) [ece_example_disable_rum_legacy]
+### Disable RUM (legacy) [ece_example_disable_rum_legacy]
 
 If you know that you won’t be tracking RUM data, you can disable the endpoint proactively.
 
@@ -91,7 +91,7 @@ apm-server:
 ```
 
 
-## Example: Adjust the event limits configuration (legacy) [ece_example_adjust_the_event_limits_configuration_legacy]
+### Adjust the event limits configuration (legacy) [ece_example_adjust_the_event_limits_configuration_legacy]
 
 If the size of the HTTP request frequently exceeds the maximum, you might need to change the limit on the APM Server and adjust the relevant settings in the agent.
 

deploy-manage/deploy/cloud-enterprise/edit-stack-settings-elasticsearch.md

@@ -9,13 +9,17 @@ mapped_pages:
 
 # Add {{es}} user settings [ece-add-user-settings]
 
-Change how {{es}} runs by providing your own user settings. User settings are appended to the `elasticsearch.yml` configuration file for your cluster and provide custom configuration options. {{ece}} supports many of the user settings for the version of {{es}} that your cluster is running.
+Change how {{es}} runs by providing your own user settings. User settings are appended to the `elasticsearch.yml` configuration file for your cluster and provide custom configuration options.
 
-::::{note}
-ECE blocks the configuration of certain settings that could break your cluster if misconfigured, including some zen discovery and security settings. For a list of settings that are generally safe in cloud environments, refer to the [{{es}} configuration reference](elasticsearch://reference/elasticsearch/configuration-reference/index.md).
-::::
+:::{important}
+If a feature requires both standard `elasticsearch.yml` settings and [secure settings](/deploy-manage/security/secure-settings.md), configure the secure settings first. Updating standard user settings can trigger a cluster rolling restart, and if the required secure settings are not yet in place, the nodes might fail to start. Adding secure settings does not trigger a restart.
+:::
 
-To change {{es}} user settings:
+{{ece}} automatically rejects `elasticsearch.yml` settings that could break your cluster, including some zen discovery and security settings.
+
+For a list of supported settings, check [Supported {{es}} settings](elasticsearch://reference/elasticsearch/configuration-reference/index.md).
+
+To add or edit {{es}} user settings:
 
 1. [Log into the Cloud UI](./log-into-cloud-ui.md).
 2. On the **Deployments** page, select your deployment.
@@ -31,10 +35,20 @@ To change {{es}} user settings:
     If you encounter the **Edit elasticsearch.yml** carets, be sure to make your changes on all {{es}} node types.
     ::::
 
-## Example: enable email notifications from Gmail [ece_enable_email_notifications_from_gmail]
+## Example: enable email notifications [ece_enable_email_notifications_from_gmail]
+
+To enable email notifications in your {{es}} cluster, you need to configure an email account and related settings. For complete instructions, refer to [Configuring email accounts](/explore-analyze/alerts-cases/watcher/actions-email.md#configuring-email).
 
-You can configure email notifications to Gmail for a user that you specify. For details, refer to [Configuring email actions](../../../explore-analyze/alerts-cases/watcher/actions-email.md).
+```yaml
+xpack.notification.email.account:
+    gmail_account:
+        profile: gmail
+        smtp:
+            auth: true
+            starttls.enable: true
+            host: smtp.gmail.com
+            port: 587
+            user: <username>
+```
 
-::::{important}
-Before you add the `xpack.notification.email*` setting in {{es}} user settings, make sure you add the account SMTP password to the keystore as a [secret value](../../../deploy-manage/security/secure-settings.md).
-::::
+Before you add the `xpack.notification.email*` user settings, make sure to store the SMTP password in the keystore as a [secure setting](../../../deploy-manage/security/secure-settings.md). In the previous example, use the key `xpack.notification.email.account.gmail_account.smtp.secure_password`.

deploy-manage/deploy/cloud-enterprise/edit-stack-settings-kibana.md

@@ -38,8 +38,9 @@ If a setting is not supported by {{ece}}, you will get an error message when you
 If you have a license from 2018 or earlier, you might receive a warning that your cluster license is about to expire. Don’t panic, it isn’t really. {{ece}} manages the cluster licenses so that you don’t have to. In rare cases, such as when a cluster is overloaded, it can take longer for {{ece}} to reapply the cluster license. If you have a license from 2019 and later, you’ll receive a warning only when your full platform license is about to expire, which you’ll need to renew.
 ::::
 
+## Examples
 
-## Example: Increase the timeout for creating reports [ece_example_increase_the_timeout_for_creating_reports]
+### Increase the timeout for creating reports [ece_example_increase_the_timeout_for_creating_reports]
 
 When creating reports, you can adjust the number of milliseconds before a worker times out. This is particularly helpful for instances with a slow or heavy load.
 
@@ -48,7 +49,7 @@ xpack.reporting.queue.timeout: "150000"
 ```
 
 
-## Example: Change the truncation point for CSV exports [ece_example_change_the_truncation_point_for_csv_exports]
+### Change the truncation point for CSV exports [ece_example_change_the_truncation_point_for_csv_exports]
 
 If large exports are causing performance or storage issues, you can increase the number of bytes before the report truncates from the default 250 MB. For stack versions before 8.10, the default is 10 MB.
 

deploy-manage/deploy/elastic-cloud/edit-stack-settings.md

@@ -57,6 +57,10 @@ From the {{ecloud}} Console you can customize {{es}}, {{kib}}, and related produ
 
 Change how {{es}} runs by providing your own user settings. {{ech}} appends these settings to each node’s `elasticsearch.yml` configuration file.
 
+:::{important}
+If a feature requires both standard `elasticsearch.yml` settings and [secure settings](/deploy-manage/security/secure-settings.md), configure the secure settings first. Updating standard user settings can trigger a cluster rolling restart, and if the required secure settings are not yet in place, the nodes may fail to start. In contrast, adding secure settings does not trigger a restart.
+:::
+
 {{ech}} automatically rejects `elasticsearch.yml` settings that could break your cluster.
 
 For a list of supported settings, check [Supported {{es}} settings](elasticsearch://reference/elasticsearch/configuration-reference/index.md).

deploy-manage/security/secure-settings.md

@@ -58,6 +58,8 @@ The instructions below cover how to manage {{es}} keystore settings for each dep
 % ### ECE and ECH
 You can manage {{es}} secure settings in the **Security > {{es}} keystore** section of your deployment page in the {{ecloud}} Console or ECE Cloud UI.
 
+If a feature requires both standard `elasticsearch.yml` settings and secure settings, configure the secure settings first. Updating standard settings can trigger a cluster rolling restart, and if the required secure settings are not yet in place, the nodes may fail to start. In contrast, adding secure settings does not trigger a restart.
+
 :::{note}
 {{ece}} also supports managing {{es}} keystore of your deployments through its [RESTful API](https://www.elastic.co/docs/api/doc/cloud-enterprise/). Refer to [Configure {{es}} keystore through ECE API](cloud://reference/cloud-enterprise/ece-restful-api-examples-configuring-keystore.md) for an example.
 :::