Deploy TiDB in the Minikube Cluster

This document describes how to deploy a TiDB cluster in the minikube cluster.


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

Start a Kubernetes cluster with minikube

Minikube can start a local Kubernetes cluster inside a VM on your laptop. It works on macOS, Linux, and Windows.


Although Minikube supports --vm-driver=none that uses host docker instead of VM, it is not fully tested with TiDB Operator and may not work. If you want to try TiDB Operator on a system without virtualization support (e.g., on a VPS), you might consider using kind instead.

Install minikube and start a Kubernetes cluster

See Installing Minikube to install minikube (1.0.0+) on your machine.

After you installed minikube, you can run the following command to start a Kubernetes cluster.

minikube start

For Chinese mainland users, you may use local mirrors such as

minikube start --image-repository

Or you can configure HTTP/HTTPS proxy environments in your Docker:

# change to your http/https proxy server IP:PORT
minikube start --docker-env https_proxy= \
  --docker-env http_proxy=


As minikube is running with VMs (default), the is the VM itself, you might want to use your real IP address of the host machine in some cases.

See minikube setup for more options to configure your virtual machine and Kubernetes cluster.

Install kubectl to access the cluster

The Kubernetes command-line tool, kubectl, allows you to run commands against Kubernetes clusters.

Install kubectl according to the instructions in Install and Set Up kubectl.

After kubectl is installed, test your minikube Kubernetes cluster:

kubectl cluster-info

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 Helm client.

  2. Install Helm server.

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

    kubectl apply -f && \
    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

    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 && \
kubectl get crd

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

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 -n demo
  3. Deploy the TiDB cluster monitor:

    kubectl apply -f -n demo
  4. View the Pod status:

    kubectl get po -n demo

Test the TiDB cluster

Before you start testing your TiDB cluster, make sure you have installed a MySQL client. Note that there can be a small delay between the time when the pod is up and running, and when the service is available. You can watch the list of available services with:

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 your MySQL client to the TiDB server, take the following steps:

  1. Forward a local port to the TiDB port.

    kubectl -n demo port-forward svc/basic-tidb 4000:4000
  2. In another terminal window, connect the TiDB server with a MySQL client:

    mysql -h -P 4000 -uroot

    Or you can run a SQL command directly:

    mysql -h -P 4000 -uroot -e 'select tidb_version();'

Monitor the TiDB cluster

To monitor the status of the TiDB cluster, take the following steps.

  1. Forward a local port to the Grafana port.

    kubectl -n demo port-forward svc/basic-grafana 3000:3000
  2. Open your browser, and access Grafana at http://localhost:3000.

    Alternatively, Minikube provides minikube service that exposes Grafana as a service for you to access more conveniently.

    minikube service basic-grafana -n demo

    And it will automatically set up the proxy and open the browser for Grafana.

Delete the TiDB cluster

To destroy a TiDB cluster, 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

Update the reclaim policy of PVs used by the demo cluster to Delete:

kubectl get pv -l -o name | xargs -I {} kubectl patch {} -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}}'

Delete PVCs:

kubectl delete pvc -l


TiDB cluster in minikube is not responding or responds slow

The minikube VM is configured by default to only use 2048MB of memory and 2 CPUs. You can allocate more resources during minikube start using the --memory and --cpus flag. Note that you'll need to recreate minikube VM for this to take effect.

minikube delete
minikube start --cpus 4 --memory 4096 ...