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

Automatic Failover

1. Primary pod crashes — replicas stop receiving binlog events
2. syncer roleProbe fails — syncerctl getrole returns an error repeatedly; detection takes approximately 30 seconds
3. KubeBlocks marks the primary unavailable and selects the replica with the most advanced binlog position as the promotion candidate
4. Chosen replica is promoted — KubeBlocks calls the switchover lifecycle action; the replica stops replicating and takes over as primary
5. Remaining replicas repoint to the new primary via CHANGE REPLICATION SOURCE TO
6. Pod label updated — kubeblocks.io/role=primary applied to the new primary pod
7. Service endpoints switch — the {cluster}-mysql ClusterIP service automatically routes writes to the new primary

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

Automatic Failover

1. Primary pod becomes unreachable — group communication times out for the failed member
2. GCS expulsion — the remaining members detect the failure via the Group Communication System (GCS) and expel the unreachable member
3. Group elects a new PRIMARY — the remaining certified secondaries autonomously elect a new primary; no external coordinator is needed
4. syncer roleProbe detects the new PRIMARY — syncerctl getrole returns primary for the elected pod → kubeblocks.io/role=primary label updated
5. Service endpoints switch — the {cluster}-mysql ClusterIP service automatically routes writes to the new primary

Failover typically completes within 5–15 seconds. Group-internal primary election is near-instant after expulsion; the subsequent label update and service endpoint switch 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}.