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.

1. 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'

2. 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.

3. 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.

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.