Deploy TiProxy Load Balancer for an Existing TiDB Cluster

This topic describes how to deploy or remove the TiDB load balancer TiProxy for an existing TiDB cluster on Kubernetes. TiProxy is placed between the client and TiDB server to provide load balancing, connection persistence, and service discovery for TiDB.

Deploy TiProxy

If you need to deploy TiProxy for an existing TiDB cluster, follow these steps:

1. Edit the TidbCluster Custom Resource (CR):

   kubectl edit tc ${cluster_name} -n ${namespace}
   

2. Add the TiProxy configuration as shown in the following example:

   spec:
     tiproxy:
       baseImage: pingcap/tiproxy
       replicas: 3
   

3. Configure the related parameters in spec.tiproxy.config of the TidbCluster CR. For example:

   spec:
     tiproxy:
       config: |
         [log]
         level = "info"
   

   For more information about TiProxy configuration, see TiProxy Configuration.

4. Configure the related parameters in spec.tidb of the TidbCluster CR. For example:

   • It is recommended to configure graceful-wait-before-shutdown to a value greater than the maximum duration of the transactions in your application. This is used together with TiProxy's connection migration feature. For more information, see TiProxy Limitations.

       spec:
         tidb:
           config: |
             graceful-wait-before-shutdown = 30
     

   • If TLS is enabled for the cluster, skip this step. If TLS is not enabled for the cluster, you need to generate a self-signed certificate and manually configure session-token-signing-cert and session-token-signing-key for TiDB:

     spec:
       tidb:
         additionalVolumes:
           - name: sessioncert
             secret:
               secretName: sessioncert-secret
         additionalVolumeMounts:
           - name: sessioncert
             mountPath: /var/session
         config: |
           session-token-signing-cert = "/var/session/tls.crt"
           session-token-signing-key = "/var/session/tls.key"
     

     For more information, see session-token-signing-cert.

After TiProxy is started, you can find the corresponding tiproxy-sql load balancer service by running the following command.

kubectl get svc -n ${namespace}

Remove TiProxy

If your TiDB cluster no longer needs TiProxy, follow these steps to remove it.

1. Modify spec.tiproxy.replicas to 0 to remove the TiProxy Pod by running the following command.

   kubectl patch tidbcluster ${cluster_name} -n ${namespace} --type merge -p '{"spec":{"tiproxy":{"replicas": 0}}}'
   

2. Check the status of the TiProxy Pod.

   kubectl get pod -n ${namespace} -l app.kubernetes.io/component=tiproxy,app.kubernetes.io/instance=${cluster_name}
   

   If the output is empty, the TiProxy Pod has been successfully removed.

3. Delete the TiProxy StatefulSet.

   1. Modify the TidbCluster CR and delete the spec.tiproxy field by running the following command:

      kubectl patch tidbcluster ${cluster_name} -n ${namespace} --type json -p '[{"op":"remove", "path":"/spec/tiproxy"}]'
      

   2. Delete the TiProxy StatefulSet by running the following command:

      kubectl delete statefulsets -n ${namespace} -l app.kubernetes.io/component=tiproxy,app.kubernetes.io/instance=${cluster_name}
      

   3. Check whether the TiProxy StatefulSet has been successfully deleted by running the following command:

      kubectl get sts -n ${namespace} -l app.kubernetes.io/component=tiproxy,app.kubernetes.io/instance=${cluster_name}
      

      If the output is empty, the TiProxy StatefulSet has been successfully deleted.