kubeblocks-manage-accounts

name	kubeblocks-manage-accounts
version	0.2.0
description	Access-security capability entry for account, password, and credential handling on existing KubeBlocks clusters. Use when the user wants to retrieve, rotate, reset, or preconfigure database credentials. Do not use this as a create-time primary entry; create-time routing still starts at preflight plus the dedicated engine skill.

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:

Field	Description	Default
length	Total password length	16
numDigits	Minimum number of digits	4
numSymbols	Minimum number of symbols	0
letterCase	Letter case: UpperCases, LowerCases, MixedCases	MixedCases

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.