Reset User Passwords

How you rotate the default user’s password depends on how the cluster was given it.

Rotate a password stored in a Secret

For clusters deployed with account.passwordSecretRef, point the cluster at a new Secret rather than editing the current one. The change then goes through Helm, so it stays in your IaC instead of being reverted by the next sync, and the old Secret is your rollback until you remove it.

Create the new Secret alongside the current one:

kubectl create secret generic clickhouse-admin-password-v2 -n ns-default-xx-01 --from-literal=password='new-p@$$w0rd'

Point account.passwordSecretRef.name at clickhouse-admin-password-v2 in your Helm values, then run helm upgrade to apply it. The operator applies the new password within seconds of the CR changing.
Confirm a login with the new password, then delete the old Secret:

kubectl delete secret clickhouse-admin-password -n ns-default-xx-01

Existing connections are unaffected; the new password applies to subsequent logins.

Rotate a password supplied inline

The steps below apply to clusters that supply the password with the account.hashedPassword value.

Prerequisites

ClickHouse Private API installed and accessible (e.g., via port-forward to http://localhost:8080/)
At least one ClickHouse cluster deployed (this guide uses default-xx-01)

1. Generate a Hashed Password

Hash the new password using SHA-256 and base64-encode the result:

PASSWORD='My super secret p@$$w0rd'
if command -v sha256sum &> /dev/null; then
  HASHED_PASSWORD=$(echo -n "$PASSWORD" | sha256sum | awk '{printf $1}' | base64 | tr -d '\n')
else
  HASHED_PASSWORD=$(echo -n "$PASSWORD" | shasum -a 256 | awk '{printf $1}' | base64 | tr -d '\n')
fi

2. Create the Request Body

Create a JSON file with the hashed password:

{
  "user_hashed_password": "<base64-encoded-sha256-hash>",
  "hashing_function": "sha256",
  "username": "default"
}

Save this as password_reset.json.

Field	Required	Default	Description
`user_hashed_password`	Yes	—	Base64-encoded hash of the new password
`hashing_function`	No	`sha256`	Hashing algorithm used
`username`	No	`default`	Username to reset the password for

3. Send the Request

curl -X POST "http://localhost:8080/api/v1/instances/default-xx-01/reset-user-password" \
    -H "Content-Type: application/json" \
    --data-binary "@password_reset.json"

A successful response:

{
  "message": "User password reset successfully"
}

4. Verify the Change

The password reset takes effect after the operator processes the change. Verify by connecting to the cluster with the new password. You can also monitor the operation via the status endpoint:

curl "http://localhost:8080/api/v1/instances/default-xx-01/status"

Limitation for Compute-Compute Separation

Password resets cannot be performed on child instances. To reset the password for a child instance, reset it on the parent instance instead.

Get started

Services and infrastructure

Bring Your Own Cloud

Data and integrations

Connect and query

Access management

Security and compliance

Monitoring and backups

AI tools and agents

Cloud API

Billing

Support

ClickHouse Private

Rotate a password stored in a Secret

Rotate a password supplied inline

Prerequisites

1. Generate a Hashed Password

2. Create the Request Body

3. Send the Request

4. Verify the Change

Limitation for Compute-Compute Separation

​Rotate a password stored in a Secret

​Rotate a password supplied inline

​Prerequisites

​1. Generate a Hashed Password

​2. Create the Request Body

​3. Send the Request

​4. Verify the Change

​Limitation for Compute-Compute Separation

Rotate a password stored in a Secret

Rotate a password supplied inline

Prerequisites

1. Generate a Hashed Password

2. Create the Request Body

3. Send the Request

4. Verify the Change

Limitation for Compute-Compute Separation