KubeBlocks
BlogsKubeBlocks Cloud
⌘K
​

Introduction

ApeCloud MySQL introduction
KubeBlocks for ApeCloud MySQL

Cluster Management

Create and connect
Scale
Expand volume
Restart
Stop/Start
Switchover
Delete protection

Configuration

Configuration

High Availability

Failure simulation and automatic recovery

Proxy

Introduction
ApeCloud MySQL Proxy Cluster
  1. Before you start
  2. Create a Proxy Cluster
  3. Enable/Disable Proxy dynamically
  4. Connect Proxy Cluster
    1. Connect Proxy Cluster by VTGate
    2. Connect Proxy Cluster by MySQL Server
  5. Configure Proxy Cluster parameters
    1. View parameter details
    2. Reconfigure parameters
  6. Log
  7. Read-write splitting
  8. Transparent failover

ApeCloud MySQL Proxy

Before you start

  1. Install kbcli.

  2. Install Helm.

  3. Install KubeBlocks.

    You can run kbcli playground init to install a k3d cluster and KubeBlocks. For details, refer to Try KubeBlocks on your laptop or Try KubeBlocks on cloud.

    kbcli playground init # Use --version to specify a version kbcli playground init --version='x.y.z'

    Or if you already have a Kubernetes cluster, you can install KubeBlocks directly.

  4. Prepare an ApeCloud MySQL RaftGroup named mycluster for demonstrating how to enable the proxy function for an existing cluster. Refer to Create a MySQL cluster for details.

Create a Proxy Cluster

It is recommended to use kbcli to create an ApeCloud MySQL Proxy Cluster.

  1. Add the KubeBlocks repository.

    helm repo add kubeblocks https://apecloud.github.io/helm-charts
  2. View the repository list to verify whether the KubeBlocks repository is added successfully.

    helm repo list
  3. Run the update command to make sure you have added the latest version.

    helm repo update
  4. Install etcd to create the external service reference.

    1. View all versions of etcd.

      helm search repo kubeblocks/etcd --devel --versions
    2. Install the etcd Addon.

      helm install etcd kubeblocks/etcd --version=v0.6.5
    3. Install the etcd cluster.

      helm install etcd-cluster kubeblocks/etcd-cluster
    4. view the status of the etcd cluster and make sure it is running.

      kubectl get cluster > NAME CLUSTER-DEFINITION VERSION TERMINATION-POLICY STATUS AGE etcd-cluster etcd etcd-v3.5.6 Halt Running 10s
    5. View the service address of this etcd clsuter.

      kubectl get service > NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE etcd-cluster-etcd ClusterIP 10.110.23.89 <none> 2379/TCP 55s etcd-cluster-etcd-headless ClusterIP None <none> 2379/TCP,2380/TCP,3501/TCP,50001/TCP 55s kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 13m

      You can combine the service address to get the endpoint or you can use the IP of the service address as the access address.

      Here is an example of combining the service address.

      etcd-cluster-etcd.default.svc.cluster.local:2379
  5. Create an ApeCloud MySQL Proxy Cluster.

    1. View all versions of ApeCloud MySQL Proxy.

      helm search repo kubeblocks/apecloud-mysql --devel --versions
    2. (Optional) If you disable the apecloud-mysql Addon when installing KuebBlocks, run the command below to specify a version and install the cluster definition of ApeCloud MySQL. Skip this step if you install KubeBlocks with the default settings.

      helm install myproxy kubeblocks/apecloud-mysql --version=v0.9.0
    3. Create an ApeCloud MySQL Proxy Cluster.

      helm install myproxy kubeblocks/apecloud-mysql-cluster --version=v0.9.0 --set mode=raftGroup,proxyEnabled=true,etcd.serviceReference.endpoint="etcd-cluster-etcd.default.svc.cluster.local:2379"
NOTE

If you only have one node for deploying a RaftGroup Cluster, set the extra.availabilityPolicy as none when creating a RaftGroup Cluster.

helm install myproxy kubeblocks/apecloud-mysql-cluster --version=v0.9.0 --set mode=raftGroup,proxyEnabled=true,etcd.serviceReference.endpoint="etcd-cluster-etcd.default.svc.cluster.local:2379" --set extra.availabilityPolicy=none
  1. Check the status of the clusters.

    kubectl get cluster kubectl get pods

    You can also enter the etcd container or wesql-scale container to view the configuration of wesql-scale or to check the availability of the etcd service.

    etcdctl --endpoints=http://etcd-cluster-etcd.default.svc.cluster.local:2379 get /vitess --prefix --keys-only
  1. Enable the etcd Addon and create an etcd cluster.

    1. Install and enable the etcd Addon. You need to install the etcd Addon first since the etcd Addon is not installed by default. Refer to Addons installation tutorial for details.

      # 1. Check whether the KubeBlocks Addon index is added kbcli addon index list # If the list is empty, add the index kbcli addon index add kubeblocks https://github.com/apecloud/block-index.git # 2. Search the etcd Addon kbcli addon search etcd # 3. Install the etcd Addon kbcli addon install etcd --index kubeblocks --version 0.9.2 # 4. Enable the etcd Addon kbcli addon enable etcd # 5. Check whether the etcd Addon is enabled. kbcli addon list
    2. Create an etcd cluster.

      kbcli cluster create myetcd --cluster-definition etcd
    3. Check the status of the etcd service

      kbcli cluster list myetcd
  2. View the etcd service address or the etcd pod address.

    kubectl get service > NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 85d myetcd-etcd ClusterIP 10.101.227.143 <none> 2379/TCP 111s myetcd-etcd-headless ClusterIP None <none> 2379/TCP,2380/TCP,3501/TCP,50001/TCP 111s
  3. Create an ApeCloud MySQL Proxy cluster.

    helm repo add kubeblocks https://apecloud.github.io/helm-charts helm install myproxy kubeblocks/apecloud-mysql-cluster --set mode=raftGroup,proxyEnabled=true,etcd.serviceReference.endpoint="etcd-cluster-etcd.default.svc.cluster.local:2379"
  4. Check the status of the clusters.

    kbcli get cluster kbcli get pods

    You can also enter the etcd container or wesql-scale container to view the configuration of wesql-scale or to check the availability of the etcd service.

    etcdctl --endpoints=http://etcd-cluster-etcd.default.svc.cluster.local:2379 get /vitess --prefix --keys-only

Enable/Disable Proxy dynamically

As its name suggests, ApeCloud MySQL Proxy in nature is a database proxy. An ApeCloud MySQL RaftGroup Cluster that already exists can be switched to an ApeCloud MySQL Proxy Cluster by setting proxyEnabled=true.

helm upgrade mycluster kubeblocks/apecloud-mysql-cluster --set mode=raftGroup,proxyEnabled=true,etcd.serviceReference.endpoint="etcd-cluster-etcd.default.svc.cluster.local:2379"

If you want to disable proxy, run the command below.

helm upgrade mycluster kubeblocks/apecloud-mysql-cluster --set mode=raftGroup

Connect Proxy Cluster

ApeCloud MySQL Proxy is routed through the vtgate component, and the way the MySQL Server accesses vtgate is similar to the way of accessing mysqld. The external SQL access address provided by ApeCloud MySQL Proxy is the vtgate address and port. The vtgate address created by KubeBlocks by default is myproxy-cluster-vtgate-headless, and the port number is 15306. You can visit ApeCloud MySQL Proxy through the MySQL Server in any pod under the same namespace as ApeCloud MySQL Proxy.

Connect Proxy Cluster by VTGate

  1. Expose the port of VTGate to the localhost so that the localhost can access the Proxy.

    kubectl port-forward svc/vt-vtgate-headless 15306:15306
  2. Connect to the cluster.

    mysql -h 127.0.0.1 -P 15306

Run the command below to connect to the Proxy Cluster.

kbcli cluster connect myproxy --components vtgate

Connect Proxy Cluster by MySQL Server

  1. Expose the port of the MySQL Server to the localhost so that the localhost can access the MySQL Server.

    kubectl port-forward svc/vt-mysql 3306:3306
  2. Connect to the cluster.

    mysql -h 127.0.0.1 -P 3306

Run the command below to connect to the MySQL Server.

kbcli cluster connect myproxy
NOTE

If you need to test the failover of MySQL, you need to delete the Pod first and continue to port-forward the port, and you can also write a shell script. Here are examples.

For VTGate,

while true; do date; kubectl port-forward svc/vt-vtgate-headless 15306:15306; sleep 0.5; done

For the MySQL Server,

while true; do date; kubectl port-forward svc/vt-mysql 3306:3306; sleep 0.5; done

Configure Proxy Cluster parameters

  1. Get the configuration file of this cluster.

    kubectl edit configurations.apps.kubeblocks.io myproxy-vtgate
  2. Configure parameters according to your needs. The example below adds the spec.configFileParams part to configure max_connections.

    spec: clusterRef: myproxy componentName: vtgate configItemDetails: - configFileParams: vtgate.cnf: parameters: healthcheck_timeout: "5s" configSpec: constraintRef: mysql-scale-vtgate-config-constraints name: vtgate-config namespace: kb-system templateRef: vtgate-config-template volumeName: mysql-scale-config name: vtgate-config payload: {}
  3. Connect to this cluster to verify whether the configuration takes effect.

    1. Expose the port of the MySQL Server to the localhost so that the localhost can access the MySQL Server.

      kubectl port-forward svc/vt-vtgate-headless 15306:15306
    2. Connect to this cluster and verify whether the parameters are configured as expected.

      mysql -h 127.0.0.1 -P 3306 > mysql> show variables like 'healthcheck_timeout'; +---------------------+-------+ | Variable_name | Value | +---------------------+-------+ | healthcheck_timeout | 5s | +---------------------+-------+ 1 row in set (0.00 sec)

Apply an OpsRequest to the specified cluster. Configure the parameters according to your needs.

  • An example of configuring VTTablet

    apiVersion: apps.kubeblocks.io/v1alpha1 kind: OpsRequest metadata: name: acmysql-vttablet-reconfiguring namespace: default spec: clusterName: acmysql-cluster force: false reconfigure: componentName: mysql configurations: - keys: - key: vttablet.cnf parameters: - key: health_check_interval value: 4s name: vttablet-config preConditionDeadlineSeconds: 0 type: Reconfiguring
  • An example of configuring VTGate

    apiVersion: apps.kubeblocks.io/v1alpha1 kind: OpsRequest metadata: name: acmysql-vtgate-reconfiguring namespace: default spec: clusterName: acmysql-cluster force: false reconfigure: componentName: vtgate configurations: - keys: - key: vtgate.cnf parameters: - key: healthcheck_timeout value: 2s name: vtgate-config preConditionDeadlineSeconds: 0 type: Reconfiguring

VTGate, VTConsensus, and VTTablet support parameter configuration. You can configure VTGate and VTConsensus by using --components to specify a component and configure VTTablet by using --components=mysql --config-specs=vttablet-config to specify both a component and a configuration file template since VTTablet is the sidecar of the MySQL component.

View parameter details

  • View the details of the current configuration file.

    # vtgate kbcli cluster describe-config myproxy --components vtgate --show-detail # vtcontroller kbcli cluster describe-config myproxy --components vtcontroller --show-detail # vttablet kbcli cluster describe-config myproxy --components mysql --show-detail --config-specs vttablet-config
  • View the parameter descriptions.

    # vtgate kbcli cluster explain-config myproxy --components vtgate # vttablet kbcli cluster explain-config myproxy --components mysql --config-specs=vttablet-config
  • View the definition of a specified parameter.

    kbcli cluster explain-config myproxy --components vtgate --param=healthcheck_timeout

Reconfigure parameters

  1. View the current values in the MySQL Server.

    kbcli cluster connect myproxy --components=vtgate
    mysql> show variables like '%healthcheck_timeout%';
    mysql> show variables like '%health_check_interval%';
  2. Configure the healthcheck_timeout for VTGate and the health_check_interval for VTTablet.

    You can use --set flag or edit the parameter configuration file to edit values.

    • By using --set flag

      # vtgate kbcli cluster configure myproxy --components vtgate --set=healthcheck_timeout=2s # vttablet kbcli cluster configure myproxy --set=health_check_interval=4s --components=mysql --config-spec=vttablet-config
    • By editing the parameter configuration file

      kbcli cluster edit-config myproxy --components vtgate
    NOTE

    After the vtgate parameter values configuration command is executed, a new vtgate Pod is started and the old vtgate Pod is terminated. You can run the command below to monitor whether the old Pod is terminated.

    kubectl get pod <vtgate-pod-name> -w
  3. Use the output command to view the configuration status. For example,

    kbcli cluster describe-ops myproxy -reconfiguring-lth8d -n default
    NOTE

    For more information about parameter configuration, refer to Configuration.

Log

You can view the log files of components, Pods, and containers by both kbcli and kubectl.

View the log of VTGate.

kubectl logs myproxy-cluster-vtgate-8659d5db95-4dzt5

View the log of VTTablet and -c is required.

kubectl logs myproxy-cluster-mysql-0 -c vttablet

Enter the container and view more logs of VTGate.

kubectl exec -it myproxy-cluster-vtgate-8659d5db95-4dzt5 -- bash ls /vtdataroot

Enter the container and view more logs of VTTablet.

kubectl exec -it myproxy-cluster-mysql-0 -c vttablet -- bash ls /vtdataroot

View the log of different components.

kbcli cluster list-logs myproxy kbcli cluster list-logs myproxy --components vtgate kbcli cluster list-logs myproxy --components vtcontroller kbcli cluster list-logs myproxy --components mysql

View the log of a Pod.

kbcli cluster logs myproxy --instance myproxy-vtgate-85bdcf99df-wbmnl

View the log of a container in a Pod.

kbcli cluster logs myproxy --instance myproxy-mysql-0 -c vttablet

Read-write splitting

You can enable the read-write splitting function.

  1. Get the configuration file of this cluster.

    kubectl edit configurations.apps.kubeblocks.io myproxy-vtgate
  2. Configure read_write_splitting_policy as random.

    spec: clusterRef: myproxy componentName: vtgate configItemDetails: - configFileParams: vtgate.cnf: parameters: read_write_splitting_policy: "random" configSpec: constraintRef: mysql-scale-vtgate-config-constraints name: vtgate-config namespace: kb-system templateRef: vtgate-config-template volumeName: mysql-scale-config name: vtgate-config payload: {}

You can also set the ratio for read-write splitting and here is an example of directing 70% flow to the read-only node.

spec: clusterRef: myproxy componentName: vtgate configItemDetails: - configFileParams: vtgate.cnf: parameters: read_write_splitting_rati: "70" configSpec: constraintRef: mysql-scale-vtgate-config-constraints name: vtgate-config namespace: kb-system templateRef: vtgate-config-template volumeName: mysql-scale-config name: vtgate-config payload: {}
kbcli cluster configure myproxy --components vtgate --set=read_write_splitting_policy=random

You can also set the ratio for read-write splitting and here is an example of directing 70% flow to the read-only node.

kbcli cluster configure myproxy --components vtgate --set=read_write_splitting_ratio=70

Moreover, you can run show workload in the VTGate terminal to view the flow distribution.

show workload;

Transparent failover

  1. Get the configuration file of this cluster.

    kubectl edit configurations.apps.kubeblocks.io myproxy-vtgate
  2. Configure enable_buffer as true.

    spec: clusterRef: myproxy componentName: vtgate configItemDetails: - configFileParams: vtgate.cnf: parameters: enable_buffer: "true" configSpec: constraintRef: mysql-scale-vtgate-config-constraints name: vtgate-config namespace: kb-system templateRef: vtgate-config-template volumeName: mysql-scale-config name: vtgate-config payload: {}

Run the command below to implement transparent failover.

kbcli cluster configure myproxy --components vtgate --set=enable_buffer=true

© 2025 ApeCloud PTE. Ltd.