docs: added OpenSearch admin password guide #105
Conversation
|
Note Other AI code review bot(s) detectedCodeRabbit 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. WalkthroughAdds 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
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~2 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ 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. Comment |
There was a problem hiding this comment.
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.
docs/en/solutions/ecosystem/opensearch/How_to_update_opensearch_admin_password.md
Outdated
Show resolved
Hide resolved
docs/en/solutions/ecosystem/opensearch/How_to_update_opensearch_admin_password.md
Show resolved
Hide resolved
docs/en/solutions/ecosystem/opensearch/How_to_update_opensearch_admin_password.md
Outdated
Show resolved
Hide resolved
docs/en/solutions/ecosystem/opensearch/How_to_update_opensearch_admin_password.md
Show resolved
Hide resolved
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
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
admin123password 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-0as a placeholder, but users might not know how to find their actual instance name. Additionally, the extractedinternal_users.ymlwill 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
hashfield in theinternal_users.ymlfile to update theadminuser's password. Then create the Secret:
+Modify thehashfield in theinternal_users.ymlfile to update theadminuser'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 -->
docs/en/solutions/ecosystem/opensearch/How_to_update_opensearch_admin_password.md
Show resolved
Hide resolved
|
lgtm |
|
…h_admin_password.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
…h_admin_password.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
chideat
force-pushed
the
opensearch-update-password
branch
from
c9e4c51 to
28d78b5
Compare
There was a problem hiding this comment.
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.yml3.2 Set Up Custom Credentials
Follow the steps in Section 1 to:
- Create the admin-credentials-secret (Section 1.1)
- Generate a password hash (Section 1.2)
- Modify the exported
internal_users.ymlto update the admin user's hash- Create the securityconfig-secret (Section 1.3)
- 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 -->
docs/en/solutions/ecosystem/opensearch/How_to_update_opensearch_admin_password.md
Show resolved
Hide resolved
docs/en/solutions/ecosystem/opensearch/How_to_update_opensearch_admin_password.md
Show resolved
Hide resolved
There was a problem hiding this comment.
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 129-132: The doc incorrectly tells users to provide a Base64
encoded password; update the sentence that mentions "Update the `password` field
in the Secret to the new password (Base64 encoded)" to instead say the plaintext
password should be provided because the example `kubectl -n <namespace> create
secret generic admin-credentials-secret --from-literal=username=admin
--from-literal=password=<newpassword> --dry-run=client -o yaml | kubectl apply
-f -` will base64-encode the value automatically; remove the "(Base64 encoded)"
note and make it explicit that users must supply the raw password in the
command.
♻️ Duplicate comments (6)
docs/en/solutions/ecosystem/opensearch/How_to_update_opensearch_admin_password.md (6)
1-6: Fix YAML frontmatter issues.The frontmatter has trailing whitespace after
products:(line 2) and a missing value forkind:(lines 4-5). These issues were previously flagged and should be addressed.
33-35: Bcrypt hash format inconsistency.The Python command generates hashes with prefix
$2a$, but YAML examples use$2y$. This was previously flagged and should be corrected by updating the command to useprefix=b"2y".
48-57: Use different password hashes for admin and kibanaserver.The password hashes for
admin(line 48) andkibanaserver(line 54) are identical. Since the documentation recommends setting separate passwords, the examples should use different hashes to avoid confusion.
72-78: Clarify password relationship.The password used here should match the
kibanaserverhash ininternal_users.yml, not theadminpassword. This was previously flagged and should be clarified in the documentation.
115-115: Recovery procedure needs clarification.The recovery steps are vague. This was previously flagged with a suggestion to specify whether to revert
securityconfig-secretor updateadmin-credentials-secretto match.
172-174: Add pod selection guidance.The command assumes pods named
<instance-name>-masters-0, which requires dedicated master nodes. This was previously flagged with a suggestion to add guidance for identifying the correct pod in different cluster topologies.
🧹 Nitpick comments (3)
docs/en/solutions/ecosystem/opensearch/How_to_update_opensearch_admin_password.md (3)
8-8: Consider all-caps title formatting per reviewer feedback.A reviewer noted that "Title should be all-capital-letter". If your documentation style guide requires all-caps headers, update the title accordingly:
# HOW TO SET AND UPDATE THE OPENSEARCH ADMIN PASSWORD
10-10: Clarify version notation.The version constraint
~= 2.8.xmixes operator syntax with wildcard notation. Consider using standard semantic versioning:> **Note**: Applicable Version: OpenSearch Operator ~2.8.0 (or >= 2.8.0, < 2.9.0)Or express it in plain language:
> **Note**: Applicable to OpenSearch Operator version 2.8.x
186-199: Consider adding dashboards configuration or explanatory note.Section 1 (lines 97-100) includes OpenSearch Dashboards configuration in the cluster spec, but Section 3 omits it. If dashboards should also be configured when updating passwords on clusters without custom passwords, include that configuration here. Otherwise, add a note explaining that dashboards configuration is optional or should be configured separately.
Optional: Add dashboards configuration
spec: security: config: adminCredentialsSecret: name: admin-credentials-secret securityConfigSecret: name: securityconfig-secret tls: transport: generate: true http: generate: true dashboards: enable: true opensearchCredentialsSecret: name: dashboards-credentials-secret
| - Update the `password` field in the Secret to the new password (Base64 encoded). | ||
|
|
||
| ```bash | ||
| kubectl -n <namespace> create secret generic admin-credentials-secret --from-literal=username=admin --from-literal=password=<newpassword> --dry-run=client -o yaml | kubectl apply -f - |
There was a problem hiding this comment.
Remove misleading Base64 encoding reference.
Line 129 states "Update the password field in the Secret to the new password (Base64 encoded)." However, when using kubectl create secret --from-literal (line 132), kubectl automatically base64-encodes the value. The user should provide the plaintext password, not a pre-encoded value.
📝 Suggested fix
- - Update the `password` field in the Secret to the new password (Base64 encoded).
+ - Update the `password` field in the Secret to the new password.🤖 Prompt for AI Agents
In
`@docs/en/solutions/ecosystem/opensearch/How_to_update_opensearch_admin_password.md`
around lines 129 - 132, The doc incorrectly tells users to provide a Base64
encoded password; update the sentence that mentions "Update the `password` field
in the Secret to the new password (Base64 encoded)" to instead say the plaintext
password should be provided because the example `kubectl -n <namespace> create
secret generic admin-credentials-secret --from-literal=username=admin
--from-literal=password=<newpassword> --dry-run=client -o yaml | kubectl apply
-f -` will base64-encode the value automatically; remove the "(Base64 encoded)"
note and make it explicit that users must supply the raw password in the
command.
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.