docs: added OpenSearch admin password guide

[chideat]

Summary by CodeRabbit

• Documentation
  • Added a comprehensive guide for setting and updating OpenSearch admin passwords covering: initial custom-password setup, switching from built-in to custom credentials, and updating existing custom passwords.
  • Includes steps for creating and managing credential secrets, hashing passwords, applying security configuration updates, expected pod behavior during changes, built-in users, and security considerations.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

Walkthrough

Adds a new how-to document detailing end-to-end steps to set and update the OpenSearch admin password: initial custom-password configuration, updating when a custom password exists, and enabling/updating custom passwords on clusters without prior custom configuration; includes appendix on built-in users and security considerations.

Changes

Cohort / File(s)

Summary

OpenSearch Admin Password Documentation docs/en/solutions/ecosystem/opensearch/How_to_update_opensearch_admin_password.md

New guide covering: creating an OpenSearchCluster with a custom admin password (create admin-credentials-secret, hash password, create securityconfig-secret with internal_users.yml, keep kibanaserver, enable dashboards with dashboards-credentials-secret); updating when a custom password already exists (update securityconfig-secret, admin-credentials-secret, optional dashboards-credentials-secret; a Job applies the new security config and pods are not restarted); enabling/updating when no custom password existed (create secrets, hash password, export/modify internal_users.yml, update CR; a Job applies security config and triggers rolling restart). Appendix: built-in users, security notes, operator doc references.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 I hopped through secrets, nibbling at a key,

I hashed a password beneath a willow tree,
I nudged a tiny Job to whisper “apply,”
OpenSearch sighed safe beneath the sky,
🥕🔐

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: adding documentation for the OpenSearch admin password guide.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This pull request adds comprehensive documentation for setting and updating OpenSearch admin passwords. The guide covers three main scenarios: creating a cluster with custom passwords, updating passwords when custom passwords are already configured, and updating passwords when using default credentials.

Changes:

• Added a complete guide for managing OpenSearch admin passwords with step-by-step instructions
• Included Python commands for generating password hashes using bcrypt
• Documented security best practices and warnings about production password management

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In
`@docs/en/solutions/ecosystem/opensearch/How_to_update_opensearch_admin_password.md`:
- Around line 35-37: The Python bcrypt example currently uses prefix=b"2a" which
produces $2a$ hashes, while the YAML examples use $2y$; change the inline
command to use prefix=b"2y" (i.e., bcrypt.gensalt(12, prefix=b"2y")) so the
generated hash format matches the YAML examples, and verify the example bcrypt
output strings in the document match the new $2y$ prefix for consistency.

🧹 Nitpick comments (4)

docs/en/solutions/ecosystem/opensearch/How_to_update_opensearch_admin_password.md (4)

67-80: Clarify that kibanaserver should use a different password than admin.

While line 56 recommends a "separate complex password for kibanaserver," the example in line 74 uses the same admin123 password shown earlier for the admin user. The note on line 79 should explicitly state that the kibanaserver password should be different from the admin password to reinforce security best practices.

📝 Suggested clarification

 > **Note**:
 >
-> - Replace `admin123` with your new password.
+> - Replace `admin123` with a different password than the admin user (should match the kibanaserver password set in internal_users.yml).
 > - If you have already created `dashboards-credentials-secret`, skip this step.

---

118-125: Consider adding a reminder to generate the new password hash.

The instructions mention updating the hash in internal_users.yml (line 120) but don't explicitly remind users to generate the new hash using the Python bcrypt command shown in Section 1.2. Users might forget this step and try to manually edit the hash.

📝 Suggested addition

Add a reminder before step 1:

+   - First, generate the new password hash using the Python command from Section 1.2:
+     ```bash
+     python3 -c 'import bcrypt; print(bcrypt.hashpw("newpassword".encode("utf-8"), bcrypt.gensalt(12, prefix=b"2a")).decode("utf-8"))'
+     ```
+
 1. **Update `securityconfig-secret`**
    - Generate the new password hash.
    - Modify `internal_users.yml` in the Secret to update the `hash` field.

---

169-179: Add guidance for finding the correct pod name and reference security warnings.

Line 172 uses <instance-name>-masters-0 as a placeholder, but users might not know how to find their actual instance name. Additionally, the extracted internal_users.yml will contain all built-in users with default passwords (as noted in the Appendix), but there's no reminder to review and update those passwords.

📝 Suggested improvements

 Export the `internal_users.yml` file from a running OpenSearch instance Pod.

+First, find your OpenSearch master pod name:
+```bash
+kubectl -n <namespace> get pods -l opensearch.role=master
+```
+
+Then extract the internal_users.yml file (replace `<pod-name>` with the actual pod name):
+
 ```bash
-kubectl -n <namespace> exec <instance-name>-masters-0 -- cat config/opensearch-security/internal_users.yml > internal_users.yml
+kubectl -n <namespace> exec <pod-name> -- cat config/opensearch-security/internal_users.yml > internal_users.yml

-Modify the hash field in the internal_users.yml file to update the admin user's password. Then create the Secret:
+Modify the hash field in the internal_users.yml file to update the admin user's password. Important: Review the Appendix for security warnings about other built-in users and their default passwords. Then create the Secret:

</details>

---

`204-223`: **Excellent security guidance in the Appendix.**

The comprehensive table of built-in users and the strong security warnings are valuable additions to this documentation. The warnings about changing default passwords and disabling unused accounts follow security best practices.



**Optional enhancement**: Consider mentioning in Section 1.4 (around line 69) that `kibanaserver` is a service account that cannot be used for UI login, which is why the admin account is still needed for administrative access. This information from line 211 would help users understand why both accounts are necessary.

</blockquote></details>

</blockquote></details>

<details>
<summary>📜 Review details</summary>

**Configuration used**: Organization UI

**Review profile**: CHILL

**Plan**: Pro

<details>
<summary>📥 Commits</summary>

Reviewing files that changed from the base of the PR and between b739efb3937b5fbb82a9316860bb83126c14ce53 and 97026cf9f0040691237d62319a290d766150252b.

</details>

<details>
<summary>📒 Files selected for processing (1)</summary>

* `docs/en/solutions/ecosystem/opensearch/How_to_update_opensearch_admin_password.md`

</details>

<details>
<summary>⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)</summary>

* GitHub Check: Cleanup artifacts

</details>

<details>
<summary>🔇 Additional comments (1)</summary><blockquote>

<details>
<summary>docs/en/solutions/ecosystem/opensearch/How_to_update_opensearch_admin_password.md (1)</summary><blockquote>

`1-228`: **Well-structured and comprehensive documentation.**

This guide provides clear, step-by-step instructions for managing OpenSearch admin passwords across different scenarios. The warnings about operational impacts (such as pod restart behavior and the critical requirement to update both secrets simultaneously) are particularly valuable. The security warnings in the Appendix demonstrate good awareness of security best practices.

The documentation will help users avoid common pitfalls when managing OpenSearch credentials in Kubernetes environments.

</blockquote></details>

</blockquote></details>

<sub>✏️ Tip: You can disable this entire section by setting `review_details` to `false` in your review settings.</sub>

</details>

<!-- This is an auto-generated comment by CodeRabbit for review status -->

[shibalu]

lgtm

[sinbadonline]

1. Title should be all-capital-letter

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In
`@docs/en/solutions/ecosystem/opensearch/How_to_update_opensearch_admin_password.md`:
- Line 115: Clarify the recovery steps when pods enter 0/1 after changing
securityconfig-secret: instruct operators to either immediately update the
admin-credentials-secret to contain the new admin password (so secrets are
consistent) or revert securityconfig-secret to its previous content, then
restart or let pods reconcile and monitor pod status until the OpenSearch
cluster health returns to green; reference the secrets by name
(securityconfig-secret, admin-credentials-secret) and include verifying steps
such as checking pod READY counts and cluster health before retrying the
password update.
- Line 172: The current kubectl exec example hardcodes a pod name
(<instance-name>-masters-0) which fails for clusters without dedicated master
nodes; add a note before the kubectl exec line explaining how to list available
OpenSearch pods (e.g., use kubectl -n <namespace> get pods -l app=opensearch)
and instruct the user to replace <instance-name>-masters-0 with the actual pod
name (reference the internal_users.yml export step and the kubectl exec command
shown) so the export of config/opensearch-security/internal_users.yml works for
non-default topologies.

🧹 Nitpick comments (2)

docs/en/solutions/ecosystem/opensearch/How_to_update_opensearch_admin_password.md (2)

225-228: Consider adding a link to the latest documentation.

The version-specific links (v2.8.0) are good for ensuring consistency with the documented version, but users might benefit from also having a link to the latest documentation for reference.

📝 Optional addition

## References

1. [Custom Admin User (v2.8.0)](https://github.com/opensearch-project/opensearch-k8s-operator/blob/v2.8.0/docs/userguide/main.md#custom-admin-user)
2. [User and Role Management (v2.8.0)](https://github.com/opensearch-project/opensearch-k8s-operator/blob/v2.8.0/docs/userguide/main.md#user-and-role-management)
3. [Latest OpenSearch Operator Documentation](https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/docs/userguide/main.md)

---

145-202: Consider reducing duplication between Section 1 and Section 3.

Sections 3.1, 3.2, and 3.4 are nearly identical to sections 1.1, 1.2, and 1.5. The only significant difference is section 3.3 (extracting internal_users.yml from an existing pod). Consider referencing Section 1 for common steps to improve maintainability.

♻️ Potential restructuring

Section 3 could be rewritten as:

## 3. Updating the Instance Password (When Custom Password Is Not Configured)

:::warning Applicable Scenario
The following steps apply only when no custom password was configured during OpenSearch cluster creation (i.e., `admin` account password is `admin`).
:::

To enable a custom password on an existing cluster with default credentials, follow these steps:

### 3.1 Export the Current Security Configuration

Export the `internal_users.yml` file from a running OpenSearch instance Pod.

> **Note**: Replace `<instance-name>-masters-0` with an actual pod name from your cluster.

```bash
kubectl -n <namespace> exec <instance-name>-masters-0 -- cat config/opensearch-security/internal_users.yml > internal_users.yml

3.2 Set Up Custom Credentials

Follow the steps in Section 1 to:

1. Create the admin-credentials-secret (Section 1.1)
2. Generate a password hash (Section 1.2)
3. Modify the exported internal_users.yml to update the admin user's hash
4. Create the securityconfig-secret (Section 1.3)
5. Configure the OpenSearchCluster CR (Section 1.5)

:::note
After updating the OpenSearchCluster CR, the Operator will start a Job to apply the new Security Config, and OpenSearch instance pods will perform a rolling restart.
:::

This approach maintains all necessary information while reducing repetition.
</details>

</blockquote></details>

</blockquote></details>

<!-- This is an auto-generated comment by CodeRabbit for review status -->