diff --git a/README.md b/README.md index f4a06228a4..957fa6407d 100644 --- a/README.md +++ b/README.md @@ -54,6 +54,8 @@ Choose one of the following tutorials: * [Deploy TiDB by launching an AWS EKS cluster](./docs/aws-eks-tutorial.md) +* [Deploy TiDB in the minikube cluster](./docs/minikube-tutorial.md) + ## User guide Read the [user guide](./docs/user-guide.md). diff --git a/docs/minikube-tutorial.md b/docs/minikube-tutorial.md new file mode 100644 index 0000000000..e439b4a347 --- /dev/null +++ b/docs/minikube-tutorial.md @@ -0,0 +1,201 @@ +# Deploy TiDB in the minikube cluster + +This document describes how to deploy a TiDB cluster in the [minikube](https://kubernetes.io/docs/setup/minikube/) cluster. + +## Table of Contents + +- [Start a Kubernetes cluster with minikube](#start-a-kubernetes-cluster-with-minikube) + * [What is minikube?](#what-is-minikube) + * [Install minikube and start a Kubernetes cluster](#install-minikube-and-start-a-kubernetes-cluster) + * [Install kubectl to access the cluster](#install-kubectl-to-access-the-cluster) +- [Install TiDB operator and run a TiDB cluster with it](#install-tidb-operator-and-run-a-tidb-cluster-with-it) + * [Install helm](#install-helm) + * [Install TiDB operator in the Kubernetes cluster](#install-tidb-operator-in-the-kubernetes-cluster) + * [Launch a TiDB cluster](#launch-a-tidb-cluster) + * [Test TiDB cluster](#test-tidb-cluster) + * [Delete TiDB cluster](#delete-tidb-cluster) +- [FAQs](#faqs) + * [TiDB cluster in minikube is not responding or responds slow](#tidb-cluster-in-minikube-is-not-responding-or-responds-slow) + +## Start a Kubernetes cluster with minikube + +### What is minikube? + +[Minikube](https://kubernetes.io/docs/setup/minikube/) can start a local +Kubernetes cluster inside a VM on your laptop. It works on macOS, Linux, and +Windows. + +### Install minikube and start a Kubernetes cluster + +See [Installing Minikube](https://kubernetes.io/docs/tasks/tools/install-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 gcr.io mirrors such as +`registry.cn-hangzhou.aliyuncs.com/google_containers`. + +``` +minikube start --image-repository registry.cn-hangzhou.aliyuncs.com/google_containers +``` + +or configure HTTP/HTTPS proxy environments in your docker, e.g. + +``` +# change 127.0.0.1:1086 to your http/https proxy server IP:PORT +minikube start --docker-env https_proxy=http://127.0.0.1:1086 \ + --docker-env http_proxy=http://127.0.0.1:1086 +``` + +See [minikube setup](https://kubernetes.io/docs/setup/minikube/) for more options to +configure your virtual machine and Kubernetes cluster. + +### Install kubectl to access the cluster + +The Kubernetes command-line tool, +[kubectl](https://kubernetes.io/docs/user-guide/kubectl/), allows you to run +commands against Kubernetes clusters. + +Install kubectl according to the instructions in [Install and Set Up kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). + +After kubectl is installed, test your minikube Kubernetes cluster: + +``` +kubectl cluster-info +``` + +## Install TiDB operator and run a TiDB cluster with it + +### Install helm + +Helm is the package manager for Kubernetes and is what allows us to install all of the distributed components of TiDB in a single step. Helm requires both a server-side and a client-side component to be installed. + +``` +curl https://raw.githubusercontent.com/helm/helm/master/scripts/get | bash +``` + +Install helm tiller: + +``` +helm init +``` + +If you have limited access to gcr.io, you can try a mirror, e.g. + +``` +helm init --upgrade --tiller-image registry.cn-hangzhou.aliyuncs.com/google_containers/tiller:$(helm version --client --short | grep -P -o 'v\d+\.\d+\.\d') +``` + +Once it is installed, running `helm version` should show you both the client +and server version, e.g. + +``` +$ helm version +Client: &version.Version{SemVer:"v2.13.1", +GitCommit:"618447cbf203d147601b4b9bd7f8c37a5d39fbb4", GitTreeState:"clean"} +Server: &version.Version{SemVer:"v2.13.1", +GitCommit:"618447cbf203d147601b4b9bd7f8c37a5d39fbb4", GitTreeState:"clean"} +``` + +If it shows only the client version, `helm` cannot yet connect to the server. Use +`kubectl` to see if any tiller pods are running. + +``` +kubectl -n kube-system get pods -l app=helm +``` + +### Install TiDB operator in the Kubernetes cluster + +Clone tidb-operator repository: + +``` +git clone https://github.com/pingcap/tidb-operator +cd tidb-operator +kubectl apply -f ./manifests/crd.yaml +helm install charts/tidb-operator --name tidb-operator --namespace tidb-admin +``` + +Now, we can watch the operator come up with: + +``` +watch kubectl get pods --namespace tidb-admin -o wide +``` + +If you have limited access to gcr.io (pods failed with ErrImagePull), you can +try a mirror of kube-scheduler image. You can upgrade tidb-operator like this: + +``` +helm upgrade tidb-operator charts/tidb-operator --namespace tidb-admin --set \ + scheduler.kubeSchedulerImageName=registry.cn-hangzhou.aliyuncs.com/google_containers/kube-scheduler +``` + +When you see both tidb-scheduler and tidb-controller-manager are running, you +can process to launch a TiDB cluster! + +### Launch a TiDB cluster + +``` +helm install charts/tidb-cluster --name tidb-cluster --set \ + schedulerName=default-scheduler,pd.storageClassName=standard,tikv.storageClassName=standard,pd.replicas=1,tikv.replicas=1,tidb.replicas=1 +``` + +Watch tidb-cluster up and running: + +``` +watch kubectl get pods --namespace default -l app.kubernetes.io/instance=tidb-cluster -o wide +``` + +### Test TiDB cluster + +There can be a small delay between the pod is up and running, and the service +is available. You can watch list services available with: + +``` +watch kubectl get svc +``` + +When you see `tidb-cluster-tidb` appear, it's ready to connect to TiDB server. + +After first, forward local port to tidb port: + +``` +kubectl port-forward svc/tidb-cluster-tidb 4000:4000 +``` + +In another terminal, connect to TiDB server with MySQL client: + +``` +mysql -h 127.0.0.1 -P 4000 -uroot +``` + +Or run SQL command directly: + +``` +mysql -h 127.0.0.1 -P 4000 -uroot -e 'select tidb_version();' +``` + +### Delete TiDB cluster + +``` +helm delete --purge tidb-cluster +kubectl get pv -l app.kubernetes.io/instance=tidb-cluster -o name | xargs -I {} kubectl patch {} -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}} # update reclaim policy of PVs used by tidb-cluster to Delete +kubectl delete pvc -l app.kubernetes.io/managed-by=tidb-operator # delete PVCs +``` + +## FAQs + +### 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 pass more during `minikube start` with 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 ... +```