Skip to content

Commit b980af7

Browse files
chideatchideat
authored
docs: added OpenSearch admin password guide (#105)
* docs: added OpenSearch admin password guide * fix: fix config samples * fix: fix doc format
1 parent 929f2fd commit b980af7

File tree

1 file changed

+229
-0
lines changed

1 file changed

+229
-0
lines changed

‎docs/en/solutions/ecosystem/opensearch/How_to_update_opensearch_admin_password.md‎

Lines changed: 229 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
1+
---
2+
products:
3+
- Alauda Application Services
4+
kind:
5+
- Solution
6+
---
7+
8+
# How to Set and Update the OpenSearch Admin Password
9+
10+
> **Note**: Applicable Version: OpenSearch Operator ~= 2.8.x
11+
12+
To use a non-default `admin:admin` administrator account when creating a cluster, or to update the admin password after cluster creation, follow these steps.
13+
14+
## 1. Creating an OpenSearchCluster Instance with a Custom Password
15+
16+
### 1.1 Create the Admin Credentials Secret
17+
18+
First, create a Secret containing the administrator user credentials (e.g., `admin-credentials-secret`). This Secret will be used by the Operator to connect to the cluster for health checks and other operations.
19+
20+
```bash
21+
kubectl -n <namespace> create secret generic admin-credentials-secret --from-literal=username=admin --from-literal=password=admin123
22+
```
23+
24+
> **Note**:
25+
>
26+
> - Replace `admin123` with your new password.
27+
> - If you have already created `admin-credentials-secret`, skip this step.
28+
29+
### 1.2 Generate the Password Hash
30+
31+
Before creating the Security Configuration, you need to generate a hash for the new password. If you have Python 3.x installed, use the following command (replace `admin123` with your new password):
32+
33+
```bash
34+
python3 -c 'import bcrypt; print(bcrypt.hashpw("admin123".encode("utf-8"), bcrypt.gensalt(12, prefix=b"2a")).decode("utf-8"))'
35+
```
36+
37+
### 1.3 Create the Security Config Secret
38+
39+
Create a Secret containing `internal_users.yml` (e.g., `securityconfig-secret`). Ensure the `hash` field in `internal_users.yml` matches the password in `admin-credentials-secret`. It is **strongly recommended to retain the `kibanaserver` user**, as it is required for OpenSearch Dashboards to function properly.
40+
41+
Example `internal_users.yml` content:
42+
43+
```yaml
44+
_meta:
45+
type: "internalusers"
46+
config_version: 2
47+
admin:
48+
hash: "$2y$12$lJsHWchewGVcGlYgE3js/O4bkTZynETyXChAITarCHLz8cuaueIyq" # Replace with the hash generated in the previous step
49+
reserved: true
50+
backend_roles:
51+
- "admin"
52+
description: "Demo admin user"
53+
kibanaserver:
54+
hash: "$2y$12$7N9cKpE4qvVvFQkHh8q6yeTqF5qYzGZQeO9Tn3lYp7dS5h3bC2u3a" # It is recommended to set a separate complex password for kibanaserver; this is just an example
55+
reserved: true
56+
description: "Demo kibanaserver user"
57+
```
58+
59+
Create the Secret using `kubectl`:
60+
61+
```bash
62+
kubectl -n <namespace> create secret generic securityconfig-secret --from-file=internal_users.yml
63+
```
64+
65+
### 1.4 Configure the OpenSearch Dashboards User
66+
67+
By default, OpenSearch Dashboards may be configured to use the `admin` user (not recommended for production). For security, configure Dashboards to use the dedicated `kibanaserver` user.
68+
69+
Create a Secret containing the Dashboards credentials (e.g., `dashboards-credentials-secret`):
70+
71+
```bash
72+
kubectl -n <namespace> create secret generic dashboards-credentials-secret --from-literal=username=kibanaserver --from-literal=password=admin123
73+
```
74+
75+
> **Note**:
76+
>
77+
> - Replace `admin123` with your new password.
78+
> - If you have already created `dashboards-credentials-secret`, skip this step.
79+
80+
### 1.5 Configure the OpenSearch Cluster Spec
81+
82+
Finally, reference the above Secrets in your `OpenSearchCluster` CR:
83+
84+
```yaml
85+
spec:
86+
security:
87+
config:
88+
adminCredentialsSecret:
89+
name: admin-credentials-secret # Admin credentials Secret used by the Operator
90+
securityConfigSecret:
91+
name: securityconfig-secret # Secret containing the custom Security Config
92+
tls:
93+
transport:
94+
generate: true
95+
http:
96+
generate: true
97+
dashboards:
98+
enable: true
99+
opensearchCredentialsSecret:
100+
name: dashboards-credentials-secret # Credentials used by Dashboards to connect to OpenSearch
101+
```
102+
103+
## 2. Updating the Instance Password (When Custom Password Is Already Configured)
104+
105+
:::warning Applicable Scenario
106+
The following steps apply only when a custom password was configured during OpenSearch cluster creation.
107+
:::
108+
109+
When changing the admin password after cluster creation, you must **update both Secrets simultaneously**.
110+
111+
:::warning Important
112+
113+
**You must update both `securityconfig-secret` and `admin-credentials-secret`!** If you only update one of them, the OpenSearch Operator will be unable to connect to the cluster, causing health checks to fail and management functions to become unavailable.
114+
115+
> If you only modified `securityconfig-secret`, all pods in the instance will enter `0/1` status. In this case, revert the changes and wait for the instance to return to `green` status before trying again.
116+
117+
:::
118+
119+
1. **Update `securityconfig-secret`**
120+
- Generate the new password hash.
121+
- Modify `internal_users.yml` in the Secret to update the `hash` field.
122+
- If you also changed the `kibanaserver` password, update it at this time as well.
123+
124+
```bash
125+
kubectl -n <namespace> create secret generic securityconfig-secret --from-file=internal_users.yml --dry-run=client -o yaml | kubectl apply -f -
126+
```
127+
128+
2. **Update `admin-credentials-secret`**
129+
- Update the `password` field in the Secret to the new password (Base64 encoded).
130+
131+
```bash
132+
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 -
133+
```
134+
135+
3. **Update `dashboards-credentials-secret` (If kibanaserver password was changed)**
136+
- If you modified the `kibanaserver` password in step 1, make sure to update this Secret as well, otherwise Dashboards will be unable to connect.
137+
138+
```bash
139+
kubectl -n <namespace> create secret generic dashboards-credentials-secret --from-literal=username=kibanaserver --from-literal=password=<newpassword> --dry-run=client -o yaml | kubectl apply -f -
140+
```
141+
142+
> **Note**: After updating the related secrets, the Operator will start a Job to apply the new Security Config. OpenSearch pods will not restart.
143+
144+
## 3. Updating the Instance Password (When Custom Password Is Not Configured)
145+
146+
:::warning Applicable Scenario
147+
148+
The following steps apply only when no custom password was configured during OpenSearch cluster creation (i.e., `admin` account password is `admin`).
149+
150+
:::
151+
152+
### 3.1 Create the Admin Credentials Secret
153+
154+
Create a Secret containing the administrator user credentials (e.g., `admin-credentials-secret`). This Secret will be used by the Operator to connect to the cluster for health checks and other operations.
155+
156+
```bash
157+
kubectl -n <namespace> create secret generic admin-credentials-secret --from-literal=username=admin --from-literal=password=admin123
158+
```
159+
160+
### 3.2 Generate the Password Hash
161+
162+
Before creating the Security Configuration, you need to generate a hash for the new password. If you have Python 3.x installed, use the following command (replace `admin123` with your new password):
163+
164+
```bash
165+
python3 -c 'import bcrypt; print(bcrypt.hashpw("admin123".encode("utf-8"), bcrypt.gensalt(12, prefix=b"2a")).decode("utf-8"))'
166+
```
167+
168+
### 3.3 Create the Security Config Secret
169+
170+
Export the `internal_users.yml` file from a running OpenSearch instance Pod.
171+
172+
```bash
173+
kubectl -n <namespace> exec <instance-name>-masters-0 -- cat config/opensearch-security/internal_users.yml > internal_users.yml
174+
```
175+
176+
Modify the `hash` field in the `internal_users.yml` file to update the `admin` user's password. Then create the Secret:
177+
178+
```bash
179+
kubectl -n <namespace> create secret generic securityconfig-secret --from-file=internal_users.yml
180+
```
181+
182+
### 3.4 Configure the OpenSearch Cluster Spec
183+
184+
Finally, reference the above Secrets in your `OpenSearchCluster` CR:
185+
186+
```yaml
187+
spec:
188+
security:
189+
config:
190+
adminCredentialsSecret:
191+
name: admin-credentials-secret # Admin credentials Secret used by the Operator
192+
securityConfigSecret:
193+
name: securityconfig-secret # Secret containing the custom Security Config
194+
tls:
195+
transport:
196+
generate: true
197+
http:
198+
generate: true
199+
```
200+
201+
> **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.
202+
203+
## Appendix: OpenSearch Built-in Users Reference
204+
205+
The OpenSearch Security plugin includes several built-in internal users. In the default configuration (Demo Configuration), **the default password for these users is typically the same as their username**.
206+
207+
| Username | Purpose | Default Roles |
208+
| :--- | :--- | :--- |
209+
| **`admin`** | **Super Administrator**. Has full cluster permissions for operations and management. | `admin` |
210+
| **`kibanaserver`** | **OpenSearch Dashboards service account**. Used by Dashboards to connect to OpenSearch and manage system indices (e.g., `.kibana`). **Cannot be used to log in to the UI**. | `kibana_server` |
211+
| **`kibanaro`** | **Dashboards read-only user**. A demo user with view-only permissions, unable to modify data or configuration. | `kibanauser`, `readall` |
212+
| **`logstash`** | **Data ingestion user**. Typically used with Logstash, has write permissions. | `logstash` |
213+
| **`readall`** | **Global read-only user**. Has permission to view all index data but cannot modify. | `readall` |
214+
| **`snapshotrestore`** | **Backup and restore user**. Dedicated to performing Snapshot and Restore operations. | `snapshotrestore` |
215+
| **`anomalyadmin`** | **Anomaly Detection admin**. Administrator user for managing OpenSearch Anomaly Detection plugin features. | `anomaly_full_access` |
216+
217+
:::warning Security Warning
218+
219+
**Do not use default passwords in production environments!**
220+
221+
- You **must change** the passwords for `admin` and `kibanaserver`.
222+
- For other unused built-in users (such as `logstash`, `kibanaro`, etc.), it is recommended to **delete** or **disable** them in `internal_users.yml`, or at least change them to strong passwords to prevent potential security risks.
223+
224+
:::
225+
226+
## References
227+
228+
1. [Custom Admin User](https://github.com/opensearch-project/opensearch-k8s-operator/blob/v2.8.0/docs/userguide/main.md#custom-admin-user)
229+
2. [User and Role Management](https://github.com/opensearch-project/opensearch-k8s-operator/blob/v2.8.0/docs/userguide/main.md#user-and-role-management)

0 commit comments

Comments
 (0)