Skip to content

Commit 5c941ad

Browse files
authored
Clarify ECH node bootlooping documentation (#1093)
## Description Per an internal discussion (`sdh-cp #9409`), we would like to update the ECH doc to clarify the node bootlooping related doc. ### Background A setting is configured in Elasticsearch but it reports error ```bash org.elasticsearch.common.settings.SettingsException: The configuration setting [xpack.security.authc.realms.foobar.foobar1.foobar2.client_secret] is required ``` And during the troubleshooting, we found the setting is configured via client tooling and it's not properly configured (zero byte). Based on that, we logically thought to solve the issue, users should - understand this may happen if the keystore setting (`[xpack.security.authc.realms.foobar.foobar1.foobar2.client_secret]` to be configured on ECH side) is invalid, missing or improperly configured - understand the way to solve is to check if the keystore is valid or not and make sure it's configured properly - additionally if users configured this via client tooling, they should try configuring this in cloud UI directly as a way to isolate the cause ### After PR being merged The following orange section will be added ![image](https://github.com/user-attachments/assets/11210aa0-00d0-45ad-8e0c-2d6a15fb6b60) ![image](https://github.com/user-attachments/assets/bfc67644-a79e-465e-b4af-7a85d4650548)
1 parent 6021553 commit 5c941ad

File tree

1 file changed

+15
-1
lines changed

1 file changed

+15
-1
lines changed

troubleshoot/monitoring/node-bootlooping.md

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,8 +49,16 @@ If you’re unable to remediate the failing plan’s root cause, you can attempt
4949
The most frequent cause of a failed deployment configuration change is due to invalid or mislocated [secure settings](/deploy-manage/security/secure-settings.md). This can frequently be discovered by searching {{es}} logs for one of the following error messages:
5050
5151
```sh
52+
# Typical Error Message
53+
#------------------------------
54+
[ERROR][org.elasticsearch.bootstrap.Elasticsearch] ... fatal exception while booting Elasticsearch
5255
IllegalStateException: security initialization failed
56+
5357
java.lang.IllegalArgumentException: unknown secure setting
58+
59+
org.elasticsearch.common.settings.SettingsException:
60+
The configuration setting [xpack.security.authc.realms.foobar.foobar1.foobar2.client_secret] is required
61+
#------------------------------
5462
```
5563
5664
These are settings typically added to the keystore for the purpose of:
@@ -62,7 +70,6 @@ The keystore allows you to safely store sensitive settings, such as passwords, a
6270
6371
The following sections detail some secure settings problems that can result in a configuration change error that can prevent a deployment from restarting. You might diagnose these plan failures via the logs or via their [related exit codes](/deploy-manage/maintenance/start-stop-services/start-stop-elasticsearch.md#fatal-errors) `1`, `3`, and `78`.
6472
65-
6673
### Invalid or outdated values [ec-config-change-errors-old-values]
6774
6875
The keystore does not validate any settings that you add, so invalid or outdated values are a common source of errors when you apply a configuration change to a deployment.
@@ -91,6 +98,13 @@ When you configure third-party authentication, it’s important that all require
9198
9299
In some cases, settings may accidentally be added to the keystore that should have been added to the [{{es}} user settings file](/deploy-manage/deploy/elastic-cloud/edit-stack-settings.md). It’s always a good idea to check the [lists of reloadable settings](/deploy-manage/security/secure-settings.md) to determine if a setting can be stored in the keystore. Settings that can safely be added to the keystore are flagged as `Secure`.
93100
101+
### Missing or improperly configured
102+
103+
The error message `The configuration setting [...] is required` indicates that the corresponding setting is configured and present in the Elasticsearch instance via [Elasticsearch user settings](/deploy-manage/deploy/elastic-cloud/edit-stack-settings.md#ec-add-user-settings), but is either missing or improperly configured in [secure settings](/deploy-manage/security/secure-settings.md). Please review your [secure settings](/deploy-manage/security/secure-settings.md) to ensure they are configured correctly.
104+
105+
Additionally, if you configure these settings via a client tool, such as the [Terraform Provider for Elastic Cloud](https://github.com/elastic/terraform-provider-ec), or through an API and encounter the error, try configuring the settings directly in the Cloud UI to isolate the cause. If configuring in the Cloud UI does not result in the same error, it suggests that the keystore setting is valid, and the method of configuration should be examined. Conversely, if the same error is reported, it suggests that the keystore setting may be invalid and should be reviewed.
106+
107+
94108
95109
## Expired custom plugins or bundles [ec-config-change-errors-expired-bundle-extension]
96110

0 commit comments

Comments
 (0)