KubeBlocks
BlogsKubeBlocks Cloud
Overview
Quickstart

Topologies

MySQL Semi-Synchronous Cluster
MySQL Cluster with ProxySQL
MySQL Group Replication Cluster
MySQL Group Replication with ProxySQL
MySQL Cluster with Orchestrator
MySQL with Orchestrator & ProxySQL

Operations

Lifecycle Management
Vertical Scaling
Horizontal Scaling
Volume Expansion
Manage MySQL Services
Minor Version Upgrade
Modify MySQL Parameters
Planned Switchover in MySQL
Decommission MySQL Replica
Recovering MySQL Replica

Backup And Restores

Create BackupRepo
Create Full Backup
Scheduled Backups
Scheduled Continuous Backup
Restore MySQL Cluster
Restore with PITR

Custom Secret

Custom Password
Custom Password Policy

TLS

MySQL Cluster with TLS
MySQL Cluster with User-Provided TLS
MySQL Cluster with mTLS

Monitoring

Observability for MySQL Clusters

Advanced Pod Management

Custom Scheduling Policies
Custom Pod Resources
Pod Management Parallelism
Using OnDelete for Controlled Pod Updates
Gradual Rolling Update
  1. Benefits of Switchover
  2. Switchover vs. Failover
  3. Prerequisites
  4. Deploy a MySQL Semi-Synchronous Cluster
  5. Verifying the Deployment
  6. Check Roles
  7. Performing a Planned Switchover
  8. Monitoring the Switchover
  9. Verify the Switchover
  10. Summary

Planned Switchover in a MySQL Cluster

A switchover is a planned operation where the primary instance in a MySQL cluster proactively transfers its role to a secondary instance. Unlike an unplanned failover, which occurs during unexpected failures, a switchover ensures a controlled and predictable role transition with minimal service disruption.

Benefits of Switchover

  1. Minimal Downtime: The primary instance actively transfers its role to the secondary instance, resulting in very short service downtime (typically a few hundred milliseconds)
  2. Controlled Transition: Ensures a seamless and predictable role change compared to failover, which involves detecting and recovering from a failure, often causing longer delays (several seconds or more).
  3. Maintenance-Friendly: Ideal for planned maintenance tasks, such as node upgrades or decommissioning, while ensuring uninterrupted service.

Switchover vs. Failover

AspectSwitchoverFailover
InitiationPlanned and manually triggeredUnplanned and automatically triggered
DowntimeFew hundred millisecondsSeveral seconds or more
Primary Role TransitionProactively transferredReactively promoted
Use CasePlanned maintenance (e.g., upgrades)Handling unexpected failures

Using a switchover ensures smooth transitions and minimal service disruption, making it the preferred choice for planned maintenance activities.

Prerequisites

Before proceeding, ensure the following:

  • Environment Setup:
    • A Kubernetes cluster is up and running.
    • The kubectl CLI tool is configured to communicate with your cluster.
    • KubeBlocks CLI and KubeBlocks Operator are installed. Follow the installation instructions here.
  • Namespace Preparation: To keep resources isolated, create a dedicated namespace for this tutorial:
kubectl create ns demo
namespace/demo created

Deploy a MySQL Semi-Synchronous Cluster

Deploy a 2-node semi-sync MySQL cluster (1 primary, 1 secondary):

kubectl apply -f - <<EOF
apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: example-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:
            storageClassName: ""
            accessModes:
              - ReadWriteOnce
            resources:
              requests:
                storage: 20Gi
EOF

Verifying the Deployment

Monitor the status of the MySQL cluster as it is created:

kubectl get cluster -n demo -w

Example Output:

NAME                    CLUSTER-DEFINITION   TERMINATION-POLICY   STATUS     AGE
example-mysql-cluster   mysql                Delete               Creating   4s
example-mysql-cluster   mysql                Delete               Running    62s

Check Roles

List the Pods and their roles (primary or secondary):

kubectl get pods -n demo -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.labels.kubeblocks\.io/role}{"\n"}{end}'

Example Output:

example-mysql-cluster-mysql-0	primary
example-mysql-cluster-mysql-1	secondary

Performing a Planned Switchover

To initiate a planned switchover, create an OpsRequest resource as shown below:

kubectl apply -f - <<EOF
apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: example-mysql-switchover-ops
  namespace: demo
spec:
  clusterName: example-mysql-cluster
  type: Switchover
  switchover:
  - componentName: mysql
    instanceName: example-mysql-cluster-mysql-0
EOF

Key Parameters:

  • instanceName: Specifies the instance (Pod) that is primary or leader before a switchover operation.

Monitoring the Switchover

You can check the progress of the scaling operation with the following command:

kubectl describe ops example-mysql-switchover-ops -n demo

Expected Result:

Status:
  Phase:            Succeed
  Progress:         1/1
  ...

Verify the Switchover

After the switchover is executed, the specified instance ('example-semisync-mysql-mysql-0') will be promoted to the primary role, while the previously primary instance ('example-semisync-mysql-mysql-1') will take on the secondary role.

kubectl get pods -n demo -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.labels.kubeblocks\.io/role}{"\n"}{end}'
example-mysql-cluster-mysql-0	secondary
example-mysql-cluster-mysql-1	primary

In this example:

  • Pod 'example-mysql-cluster-mysql-1' has been promoted to the primary role.
  • Pod 'example-mysql-cluster-mysql-0' has transitioned to the secondary role.

Summary

Key Benefits of Planned Switchover:

  1. Minimal Downtime: The operation completes within a few hundred milliseconds, ensuring service continuity.
  2. Controlled Transition: Switchover ensures a predictable and seamless role change, unlike failovers, which are reactive and take longer.
  3. Ideal for Maintenance: Enables tasks like upgrades, node decommissioning, or rebalancing without impacting application availability.

In this guide, you learned how to:

  • Deploy a MySQL cluster managed by KubeBlocks.
  • Perform a planned switchover to transfer the primary role from one instance to another.
  • Verify the success of the switchover operation and the updated roles of the Pods.

Planned switchover is a critical operation for maintaining high availability during maintenance tasks, ensuring minimal service disruption and predictable transitions in highly available systems.

© 2025 ApeCloud PTE. Ltd.