MySQL Architecture in KubeBlocks

KubeBlocks supports three distinct MySQL HA architectures:

Each architecture can optionally be combined with a ProxySQL frontend component, which provides connection pooling, query routing, and read/write splitting.

Semisync Architecture

MySQL Semisync uses native binlog replication between a primary and one or more replicas. Semi-synchronous mode requires at least one replica to acknowledge each transaction before the primary commits, reducing the risk of data loss on failover. KubeBlocks drives failover via a syncer-based roleProbe that runs /tools/syncerctl getrole inside the mysql container.

Resource Hierarchy

Cluster  →  Component (mysql)  →  InstanceSet  →  Pod × N

Containers Inside Each Pod

Each pod also runs multiple init containers on startup: init-syncer (copies syncer and syncerctl to /tools), init-data (sets up data directories and copies MySQL plugins), init-xtrabackup (copies Percona XtraBackup to /tools), and init-jemalloc (copies the jemalloc library to /tools).

High Availability

Failover typically completes within 30–60 seconds.

Traffic Routing

KubeBlocks headless Services follow the InstanceSet pattern: every declared container port appears as a ServicePort (semisync / non‑Orchestrator builds: 3306, 3601, exporter).

• Write traffic: {cluster}-mysql:3306 (always routes to current primary)
• Direct pod access: {pod-name}.{cluster}-mysql-headless.{namespace}.svc.cluster.local:3306

Semisync ± ProxySQL

Adding proxysql to the topology inserts a ProxySQL Component in front of MySQL. ProxySQL provides connection pooling, automatic read/write splitting, and query caching. Client traffic goes to {cluster}-proxysql-proxy-server:6033 (the ClusterIP Service from the ProxySQL ComponentDefinition, where serviceName is proxy-server) instead of directly to MySQL pods. Per-pod Services {cluster}-proxysql-proxy-ordinal-<n> expose the same DB port on each ProxySQL pod when you need ordinal-specific endpoints.

MGR Architecture (Group Replication)

MySQL Group Replication (MGR) runs a Paxos-based group consensus protocol on port :33061 across all member pods. All transaction commits require certification by the group. In single-primary mode, one pod is elected PRIMARY by the group; the others are SECONDARY. On primary failure, the group autonomously elects a new primary without external coordination.

Resource Hierarchy

Cluster  →  Component (mysql)  →  InstanceSet  →  Pod × N

The resource hierarchy is identical to Semisync. The difference is the replication protocol running inside each pod (group_replication_start_on_boot=off, group_replication_single_primary_mode=ON). KubeBlocks starts group replication manually via the lifecycle action rather than relying on start_on_boot.

Containers Inside Each Pod

The roleProbe runs /tools/syncerctl getrole inside the mysql container. Each pod also runs multiple init containers on startup: init-syncer (copies syncer and syncerctl to /tools), init-data (sets up data directories and copies plugins), and init-jemalloc (copies the jemalloc library to /tools).

High Availability

Failover typically completes within 5–15 seconds. Group-internal primary election is near-instant after expulsion; the subsequent kubeblocks.io/role label update and Service endpoint switch still depend on the syncer roleProbe cycle.

Traffic Routing

Traffic routing matches Semisync except the headless Service also publishes 33061 from the mysql container.

The roleSelector: primary mechanism on the ClusterIP service works the same way — the syncer roleProbe detects the current GR role and updates the pod label accordingly.

MGR ± ProxySQL

The mgr-proxysql topology adds ProxySQL for connection pooling and read/write splitting, identical to the Semisync+ProxySQL variant — clients connect to {cluster}-proxysql-proxy-server:6033 (and optionally per-pod {cluster}-proxysql-proxy-ordinal-<n>).

Orchestrator Architecture

The Orchestrator topology pairs semi-sync MySQL replication with an external Orchestrator component. Orchestrator continuously monitors the replication topology via MySQL's SHOW SLAVE STATUS and performance_schema, detects failures, and drives automated failover and topology recovery.

Resource Hierarchy

Orchestrator is a separate KubeBlocks addon — it is deployed as an independent KubeBlocks Cluster (using the orchestrator ClusterDefinition), not as a Component inside the MySQL Cluster. The MySQL orc topology provisions only the MySQL Component, which then connects to a separately deployed Orchestrator cluster via serviceRefs (backed by the serviceRefDeclarations in the ComponentDefinition).

MySQL Cluster   →  Component (mysql)  →  InstanceSet  →  Pod × N

Orchestrator Cluster  →  Component (orchestrator)  →  InstanceSet  →  Pod × N

Containers Inside Each Pod

Each pod also runs two init containers on startup: init-data (sets up data directories and copies MySQL plugins) and init-jq (copies jq, orchestrator-client, and curl to /kubeblocks for use by the roleProbe and lifecycle scripts).

How Orchestrator Manages Failover

1. Orchestrator polls all MySQL pods on port 3306 at a configurable interval
2. On primary failure, Orchestrator identifies the most eligible replica (most advanced relay log)
3. Orchestrator promotes the chosen replica and reconnects all other replicas to it
4. KubeBlocks detects the new primary via an exec roleProbe that runs orchestrator-client -c which-cluster-master and updates the kubeblocks.io/role label on the new primary pod
5. The kubeblocks.io/role label update is consumed by the control plane and observability tooling (e.g. kbcli describe cluster); the mysql-server ClusterIP service has no roleSelector and continues to load-balance across all ready pods — it does not automatically become a single-primary endpoint

Orchestrator also provides a web UI for visualizing and manually managing the replication topology, which is useful for large clusters with complex topologies or when manual intervention is needed.

Traffic Routing

Orchestrator ± ProxySQL

The orc-proxysql topology adds ProxySQL for connection pooling and read/write splitting, as in other variants — clients connect to {cluster}-proxysql-proxy-server:6033 (and optionally per-pod {cluster}-proxysql-proxy-ordinal-<n>).

System Accounts

KubeBlocks automatically creates and manages the following MySQL system accounts. Passwords are stored in Secrets named {cluster}-{component}-account-{name}.