kubeblocks-addon-mysql

name	kubeblocks-addon-mysql
metadata	{"version":"0.1.0"}
description	Legacy compatibility shim for MySQL provisioning on KubeBlocks. The primary create-time entry is kubeblocks-engine-mysql. Keep this skill callable for older references, but do not recommend it as the main path for cold-start agents.

Deploy MySQL on KubeBlocks

Legacy compatibility shim. Primary entry: kubeblocks-engine-mysql. Keep the preserved workflow below for detailed reference, but do not recommend this skill as the main path for cold-start agents.

Overview

Deploy highly-available MySQL clusters using KubeBlocks. Multiple topologies are available — from simple semi-synchronous replication to full orchestrator-managed setups with ProxySQL.

Official docs: https://kubeblocks.io/docs/preview/user_docs/kubeblocks-for-mysql/cluster-management/create-and-connect-a-mysql-cluster Full doc index: https://kubeblocks.io/llms-full.txt

Prerequisites

• A running Kubernetes cluster with KubeBlocks installed (see install-kubeblocks)
• For first-time rollout or unknown environment readiness, run kubeblocks-preflight first and carry its recommendation bundle into this skill.
• The MySQL addon must be enabled:

# Check if mysql addon is installed
helm list -n kb-system | grep mysql

# Install if missing
helm install kb-addon-mysql kubeblocks/mysql --namespace kb-system --version 1.0.0

Available Topologies

Topology	Value	Components	Use Case
Semi-Synchronous	semisync	mysql	Standard HA, 2+ replicas
Semi-Sync + ProxySQL	semisync-proxysql	mysql + proxysql	HA with query routing
Group Replication	mgr	mysql	Multi-primary capable, 3+ replicas
MGR + ProxySQL	mgr-proxysql	mysql + proxysql	MGR with load balancing
Orchestrator	orc	mysql + orchestrator	External HA manager
Orc + ProxySQL	orc-proxysql	mysql + orc + proxysql	Full HA stack

Default recommendation: semisync — simplest, most widely deployed.

Keep these decisions visible in this engine-entry skill:

• topology
• serviceVersion
• storageClassName from preflight
• demo vs production sizing

Supported Versions

Version	serviceVersion
MySQL 5.7	5.7.44
MySQL 8.0	8.0.33, 8.0.35
MySQL 8.4	8.4.2

Workflow

- [ ] Step 1: Ensure addon is installed
- [ ] Step 2: Create namespace
- [ ] Step 3: Create cluster
- [ ] Step 4: Wait for cluster to be ready
- [ ] Step 5: Connect to MySQL

Step 1: Ensure Addon Is Installed

helm list -n kb-system | grep mysql

If not found, install it:

helm install kb-addon-mysql kubeblocks/mysql --namespace kb-system --version 1.0.0

Step 2: Create Namespace

kubectl create namespace demo --dry-run=client -o yaml | kubectl apply -f -

Step 3: Create Cluster

Semi-Synchronous Replication (Recommended)

This is the most common topology. One primary + one or more replicas with semi-sync replication for data safety.

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: mysql-cluster
  namespace: demo
spec:
  clusterDef: mysql
  topology: semisync
  terminationPolicy: Delete
  componentSpecs:
    - name: mysql
      serviceVersion: "8.0.35"
      replicas: 2
      resources:
        limits: {cpu: "0.5", memory: "0.5Gi"}
        requests: {cpu: "0.5", memory: "0.5Gi"}
      volumeClaimTemplates:
        - name: data
          spec:
            accessModes: [ReadWriteOnce]
            storageClassName: <storageClassName-from-preflight>
            resources: {requests: {storage: 20Gi}}

Apply:

kubectl apply -f mysql-cluster.yaml

Group Replication (MGR)

Multi-primary capable. Requires 3+ replicas:

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: mysql-mgr
  namespace: demo
spec:
  clusterDef: mysql
  topology: mgr
  terminationPolicy: Delete
  componentSpecs:
    - name: mysql
      serviceVersion: "8.0.35"
      replicas: 3
      resources:
        limits: {cpu: "0.5", memory: "0.5Gi"}
        requests: {cpu: "0.5", memory: "0.5Gi"}
      volumeClaimTemplates:
        - name: data
          spec:
            accessModes: [ReadWriteOnce]
            storageClassName: <storageClassName-from-preflight>
            resources: {requests: {storage: 20Gi}}

For topologies with ProxySQL or Orchestrator, see reference.md.

Step 4: Wait for Cluster Ready

kubectl -n demo get cluster mysql-cluster -w

Wait until STATUS shows Running. Typical startup time: 1-3 minutes.

Check component status:

kubectl -n demo get pods -l app.kubernetes.io/instance=mysql-cluster

Step 5: Connect to MySQL

Get Credentials

The root password is stored in a Kubernetes secret:

# Secret name format: <cluster>-mysql-account-root
kubectl -n demo get secret mysql-cluster-mysql-account-root -o jsonpath='{.data.password}' | base64 -d

Connect via kubectl exec

kubectl -n demo exec -it mysql-cluster-mysql-0 -- bash -c 'mysql -uroot -p"$(cat /etc/mysql/secret/password)"'

Connect via Port-Forward

kubectl -n demo port-forward svc/mysql-cluster-mysql 3306:3306
# Then from another terminal:
mysql -h 127.0.0.1 -P 3306 -u root -p

Backup

MySQL supports three backup methods:

Method	ActionSet	Use Case
XtraBackup	xtrabackup	Physical backup, fast for large DBs
Volume Snapshot	mysql-volumesnapshot	Storage-level snapshots, fastest
Binlog Archive	archive-binlog	Continuous archiving for PITR

Example backup:

apiVersion: dataprotection.kubeblocks.io/v1alpha1
kind: Backup
metadata:
  name: mysql-backup
  namespace: demo
spec:
  backupMethod: xtrabackup
  backupPolicyName: mysql-cluster-mysql-backup-policy

Troubleshooting

Cluster stuck in Creating:

kubectl -n demo describe cluster mysql-cluster
kubectl -n demo get events --sort-by='.lastTimestamp'

Pod CrashLoopBackOff:

kubectl -n demo logs mysql-cluster-mysql-0

Semi-sync replica not connecting:

• Ensure replicas >= 2 for semisync topology
• Check network policies between pods

Day-2 Operations

Operation	Skill	External Docs
Stop / Start / Restart	cluster-lifecycle	Docs
Scale CPU / Memory	vertical-scaling	Docs
Add / Remove replicas	horizontal-scaling	Docs
Expand storage	volume-expansion	Docs
Change parameters	reconfigure-parameters	Docs
Switchover primary	switchover	Docs
Upgrade engine version	minor-version-upgrade	Docs
Expose externally	expose-service	Docs
Backup	backup	Docs
Restore	restore	Docs

Safety Patterns

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

Next Steps

• For detailed YAML examples of all topologies, see reference.md