Deploy TiDB on Google Cloud

This tutorial is designed to be directly run in Google Cloud Shell.

It takes you through the following steps:

  • Launch a new 3-node Kubernetes cluster (optional)
  • Deploy TiDB Operator and your first TiDB cluster
  • Connect to the TiDB cluster
  • Scale out the TiDB cluster
  • Access the Grafana dashboard
  • Destroy the TiDB cluster
  • Shut down the Kubernetes cluster (optional)

Warning:

This is for testing only. DO NOT USE in production!

Select a project

This tutorial launches a 3-node Kubernetes cluster of n1-standard-1 machines. Pricing information can be found here.

Please select a project before proceeding:

Enable API access

This tutorial requires use of the Compute and Container APIs. Please enable them before proceeding:

Configure gcloud defaults

This step defaults gcloud to your preferred project and zone, which simplifies the commands used for the rest of this tutorial:

gcloud config set project {{project-id}}
gcloud config set compute/zone us-west1-a

Launch a 3-node Kubernetes cluster

It's now time to launch a 3-node kubernetes cluster! The following command launches a 3-node cluster of n1-standard-1 machines.

It takes a few minutes to complete:

gcloud container clusters create tidb

Once the cluster has launched, set it to be the default:

gcloud config set container/cluster tidb

The last step is to verify that kubectl can connect to the cluster, and all three machines are running:

kubectl get nodes

If you see Ready for all nodes, congratulations! You've setup your first Kubernetes cluster.

Install Helm

Helm is a package management tool for Kubernetes. Make sure your Helm version >= 2.11.0 && < 3.0.0 && != 2.16.4. The installation steps are as follows:

  1. Refer to Helm official documentation to install the Helm client.

  2. Install the Helm server.

    Apply the RBAC rule required by the tiller component in the cluster and install tiller:

    kubectl apply -f https://raw.githubusercontent.com/pingcap/tidb-operator/master/manifests/tiller-rbac.yaml && \
    helm init --service-account=tiller --upgrade
    

    To confirm that the tiller Pod is in the running state, run the following command:

    kubectl get po -n kube-system -l name=tiller
    
  3. Add the repository:

    helm repo add pingcap https://charts.pingcap.org/
    

    Use helm search to search the chart provided by PingCAP:

    helm search pingcap -l
    

Deploy TiDB Operator

TiDB Operator uses CRD (Custom Resource Definition) to extend Kubernetes. Therefore, to use TiDB Operator, you must first create the TidbCluster CRD.

kubectl apply -f https://raw.githubusercontent.com/pingcap/tidb-operator/master/manifests/crd.yaml && \
kubectl get crd tidbclusters.pingcap.com

After TidbCluster CRD is created, install TiDB Operator in your Kubernetes cluster.

  1. Get the values.yaml file of the tidb-operator chart you want to install:

    mkdir -p /home/tidb/tidb-operator && \
    helm inspect values pingcap/tidb-operator --version=v1.1.0-rc.1 > /home/tidb/tidb-operator/values-tidb-operator.yaml
    

    Modify the configuration in values.yaml according to your needs.

  2. Install TiDB Operator:

    helm install pingcap/tidb-operator --name=tidb-operator --namespace=tidb-admin --version=v1.1.0-rc.1 -f /home/tidb/tidb-operator/values-tidb-operator.yaml && \
    kubectl get po -n tidb-admin -l app.kubernetes.io/name=tidb-operator
    
  3. Create the pd-ssd StorageClass:

    kubectl apply -f https://raw.githubusercontent.com/pingcap/tidb-operator/master/manifests/gke/persistent-disk.yaml
    

Deploy the TiDB cluster

To deploy the TiDB cluster, perform the following steps:

  1. Create Namespace:

    kubectl create namespace demo
    
  2. Deploy the TiDB cluster:

    kubectl apply -f https://raw.githubusercontent.com/pingcap/tidb-operator/master/examples/basic/tidb-cluster.yaml -n demo
    
  3. Deploy the TiDB cluster monitor:

    kubectl apply -f https://raw.githubusercontent.com/pingcap/tidb-operator/master/examples/basic/tidb-monitor.yaml -n demo
    
  4. View the Pod status:

    kubectl get po -n demo
    

Connect to the TiDB cluster

There can be a small delay between the pod being up and running, and the service being available. You can view the service status using the following command:

kubectl get svc -n demo --watch

When you see basic-tidb appear, the service is ready to access. You can use Ctrl+C to stop the process.

To connect to TiDB within the Kubernetes cluster, you can establish a tunnel between the TiDB service and your Cloud Shell. This is recommended only for debugging purposes, because the tunnel will not automatically be transferred if your Cloud Shell restarts. To establish a tunnel:

kubectl -n demo port-forward svc/basic-tidb 4000:4000 &>/tmp/port-forward.log &

From your Cloud Shell:

sudo apt-get install -y mysql-client && \
mysql -h 127.0.0.1 -u root -P 4000

Try out a MySQL command inside your MySQL terminal:

select tidb_version();

If you did not specify a password during installation, set one now:

SET PASSWORD FOR 'root'@'%' = '<change-to-your-password>';

Note:

This command contains some special characters which cannot be auto-populated in the google cloud shell tutorial, so you might need to copy and paste it into your console manually.

Congratulations, you are now up and running with a distributed TiDB database compatible with MySQL!

Scale out the TiDB cluster

To scale out the TiDB cluster, modify spec.pd.replicas, spec.tidb.replicas, and spec.tikv.replicas in the TidbCluster object of the cluster to your desired value using kubectl.

kubectl -n demo edit tc basic

Access the Grafana dashboard

To access the Grafana dashboards, you can create a tunnel between the Grafana service and your shell. To do so, use the following command:

kubectl -n demo port-forward svc/basic-grafana 3000:3000 &>/dev/null &

In Cloud Shell, click on the Web Preview button and enter 3000 for the port. This opens a new browser tab pointing to the Grafana dashboards. Alternatively, use the following URL https://ssh.cloud.google.com/devshell/proxy?port=3000 in a new tab or window.

If not using Cloud Shell, point a browser to localhost:3000.

Destroy the TiDB cluster

To destroy a TiDB cluster in Kubernetes, run the following command:

kubectl delete tc basic -n demo

To destroy the monitoring component, run the following command:

kubectl delete tidbmonitor basic -n demo

The above commands only delete the running pods, the data is persistent. If you do not need the data anymore, you should run the following commands to clean the data and the dynamically created persistent disks:

kubectl delete pvc -n demo -l app.kubernetes.io/instance=basic,app.kubernetes.io/managed-by=tidb-operator && \
kubectl get pv -l app.kubernetes.io/namespace=demo,app.kubernetes.io/managed-by=tidb-operator,app.kubernetes.io/instance=basic -o name | xargs -I {} kubectl patch {} -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}}'

Shut down the Kubernetes cluster

Once you have finished experimenting, you can delete the Kubernetes cluster with:

gcloud container clusters delete tidb

More Information

A simple [deployment based on Terraform] is also provided.