Kubeblocks Manage Accounts

Manage Database Accounts and Passwords

This skill belongs to the access-security capability layer for already-created clusters.

Entry Contract

• Prefer this skill only after the cluster already exists, or when a create-time path explicitly asks for credential preconfiguration.
• Use ops-capability-matrix to confirm whether the target engine has account support, and use addon-capability-matrix for supporting docs/example evidence.
• Keep this skill focused on system accounts, Secrets, and password policy. Do not treat it as SQL-level user management for arbitrary application users.
• Route TLS / mTLS requests to kubeblocks-configure-tls, and broken-state credential recovery to kubeblocks-troubleshoot.

Engine-Aware Boundaries

• Safe default path: mysql, postgresql, redis, and mongodb currently show account: supported in the ops truth, so root/admin credential retrieval and Secret-based preconfiguration are normal follow-ups.
• Confirm before promising: kafka, elasticsearch, milvus, qdrant, rabbitmq, clickhouse, mariadb, minio, opensearch, pulsar, and tidb do not all expose the same first-class account story. Check the matrix before claiming this skill is supported.
• Do not confuse system accounts with application users: creating arbitrary application users inside the database still belongs to engine-native SQL or admin tooling after initial connection.

Overview

KubeBlocks automatically creates database accounts (e.g., root, admin) when provisioning a cluster. Credentials are stored in Kubernetes Secrets. You can:

• Retrieve current credentials
• Set a custom password via Secret reference
• Configure password generation policies (length, complexity)
• Preconfigure systemAccounts for engines that actually expose this contract

Official docs: https://kubeblocks.io/docs/preview/user_docs/connect-databases/overview

Workflow

- [ ] Step 1: Get current credentials
- [ ] Step 2: (Optional) Set custom password or password policy

Step 1: Get Current Credentials

Find Account Secrets

KubeBlocks stores account credentials in Secrets following the naming pattern <cluster>-<component>-account-<account>:

kubectl get secrets -n <ns> | grep <cluster>.*account

Example output:

mycluster-mysql-account-root     Opaque   2    5m

Retrieve Password

kubectl get secrets -n <ns> <cluster>-<component>-account-root \
  -o jsonpath='{.data.password}' | base64 -d

Retrieve Username

kubectl get secrets -n <ns> <cluster>-<component>-account-root \
  -o jsonpath='{.data.username}' | base64 -d

Quick Connection Test

# MySQL
kubectl exec -it <cluster>-<component>-0 -n <ns> -- \
  mysql -u root -p$(kubectl get secrets -n <ns> <cluster>-<component>-account-root -o jsonpath='{.data.password}' | base64 -d)

# PostgreSQL
kubectl exec -it <cluster>-<component>-0 -n <ns> -- \
  psql -U postgres

# Redis
kubectl exec -it <cluster>-<component>-0 -n <ns> -- \
  redis-cli -a $(kubectl get secrets -n <ns> <cluster>-<component>-account-root -o jsonpath='{.data.password}' | base64 -d)

Step 2: Customize Passwords

Option A: Custom Password via Secret Reference

Create a Secret with the desired password, then reference it in the Cluster CR:

1. Create the password Secret:

apiVersion: v1
kind: Secret
metadata:
  name: <cluster>-custom-password
  namespace: <ns>
type: Opaque
stringData:
  password: "MySecureP@ssw0rd!"

kubectl apply -f custom-password-secret.yaml

2. Reference in Cluster CR systemAccounts:

spec:
  componentSpecs:
  - name: <component>
    systemAccounts:
    - name: root
      secretRef:
        name: <cluster>-custom-password
        namespace: <ns>

This tells KubeBlocks to use the password from the referenced Secret instead of auto-generating one.

Option B: Password Generation Policy

Configure automatic password generation rules in the Cluster CR:

spec:
  componentSpecs:
  - name: <component>
    systemAccounts:
    - name: root
      passwordConfig:
        length: 16
        numDigits: 4
        numSymbols: 2
        letterCase: MixedCases

Password policy fields:

Option C: Change Password After Cluster Creation

To change the password of an existing cluster, update the Secret directly:

# Encode the new password
NEW_PASSWORD=$(echo -n "NewSecureP@ss123!" | base64)

# Patch the existing secret
kubectl patch secret <cluster>-<component>-account-root -n <ns> \
  --type merge -p "{\"data\":{\"password\":\"$NEW_PASSWORD\"}}"

Then execute the password change in the database:

# MySQL
kubectl exec -it <cluster>-<component>-0 -n <ns> -- \
  mysql -u root -p<old-password> -e "ALTER USER 'root'@'%' IDENTIFIED BY 'NewSecureP@ss123!';"

# PostgreSQL
kubectl exec -it <cluster>-<component>-0 -n <ns> -- \
  psql -U postgres -c "ALTER USER postgres PASSWORD 'NewSecureP@ss123!';"

Troubleshooting

Secret not found:

• Verify cluster and component names: kubectl get cluster <cluster> -n <ns> -o jsonpath='{.spec.componentSpecs[*].name}'
• Secrets are created when the cluster is first provisioned

Password doesn't work:

• Ensure the Secret and the actual database password are in sync
• If you changed the Secret, you also need to change the password in the database itself

Custom password not applied on new cluster:

• Ensure the Secret exists before creating the Cluster CR
• Verify the secretRef namespace and name are correct

Safety Patterns

Follow safety-patterns.md for dry-run before apply, status confirmation after watch, and pre-deletion checklist.