# TiOP > **Credits:** This repository was developed with great help from Claude Sonnet 4.5. TiDB Operator is being updated to V2 (sometimes called `TiOperator`). It is much more modern, flexible, and elegant. TiOP is a set of tools to help you bootstrap a TiDB Cluster with TiOperator. Specifically, TiOP helps you: - Start TiDB (X) playgrounds with (hopefully) zero configuration. - Deploy an ad-hoc Kubernetes cluster to quickly bootstrap a cluster for testing. - Describe your cluster using Jsonnet, a template language for generating JSON (also a pure functional language, which makes it reproducible!). - Integrate dashboards with your existing monitoring system based on `kube-prometheus` (see `./dashboards/README.md`). - And more... ## Limitations - Kubernetes is complex. It's nearly impossible to hide all its details. `tiop` doesn't attempt to wrap all Kubernetes operations. It is better to has basic knowledge about kubernetes and Jsonnet to use this. - TiOP was aimed to deploy ad-hoc testing clusters. It isn't recommended to use TiOP to deploy long-term running TiDB X clusters. (Now lacking: GC, lifecycle rule for DFS.) - This project is originally aim to only be internally used by Data Protection & Recover team. So you may encounter unexpected behaviors as our team's workload cannot cover all scenarios. Great thanks to you who fixed them or figured them out! ## tiop.py A dependency-free Python script that installs dependencies for the rest of the `tiop` toolset. It also serves as the main entry point for `tiop`. You can run it directly without any additional setup. Usage: - Use `tiop.py {minikube,helm,kubectl,jsonnet}` to execute the corresponding binary directly. - Use `tiop.py kube` to choose which Kubernetes environment to use. - Use `tiop.py cluster` to manage TiDB clusters in the current Kubernetes environment. To get started, just clone this repository: ```bash git clone https://github.com/pingcap/tiop.git ``` Then run `tiop.py` directly in the root of this repository, or add it to your `$PATH`: ```bash ln -sf $PWD/tiop.py anywhere/in/PATH/you/like/tiop ``` ## TiOP Recipe: Managed Kube ### Choose Your Cluster TiOP supports switching between a managed minikube cluster, your own Kubernetes cluster, or using your current kubectl context. By default, TiOP uses minikube mode for safety (to avoid accidentally affecting your existing clusters). **Use minikube (default):** ```bash tiop kube use # or explicitly: tiop kube use --minikube ``` If you want to deploy TiDB clusters to your own kubernetes cluster, you can **switch to current kubectl context:** ```bash tiop kube use --current ``` This Kubernetes cluster will be used by `tiop.py cluster`. > [!NOTE] > When using `--current`, the commands `init`, `status`, and `destroy` are disabled since they only work with the managed minikube cluster. ### Minikube **Initialize the minikube cluster:** ```bash tiop kube init ``` This will bootstrap a minikube cluster and configure TiDB Operator for it. > [!NOTE] > If you don't have either `docker` or `podman` installed, initialization may fail. Please follow the advice provided by `minikube` in that case. ## TiOP Recipe: Cluster ### Quick Start with Playground Configurations TiOP provides two built-in playground configurations for quick testing: - `--playground`: Uses `playground/normal.jsonnet` for standard TiDB clusters - `--x-playground`: Uses `playground/next-gen.jsonnet` for TiDB X (next-generation) clusters > [!NOTE] > > Due to the `NodePort` service in the playground config, playground is only available in a `minikube` cluster. > > (You don't want to export a TiDB without root password to everyone right?) > > If you are insisting on deploying playground in `current` kubernetes, you can: > > ```bash > tiop cluster create -f ./playground/.jsonnet > ``` **Create a cluster with normal playground config:** ```bash tiop cluster create my-cluster --playground ``` **Create a cluster with next-gen playground config (TiDB X):** ```bash tiop cluster create my-cluster --x-playground ``` When using `minikube`, you can use the following command to get resources bounded to the cluster. ```bash tiop cluster status my-cluster ``` Example output: ``` ... [INFO] Cluster resource: NAME PD TIKV TIDB TIFLASH TIPROXY AVAILABLE AGE playground 1 1 1 True 82m [INFO] All resources: NAME READY STATUS RESTARTS AGE pod/playground-pd-rnlre7 1/1 Running 0 82m pod/playground-tidb-a6n51f 1/1 Running 0 82m pod/playground-tikv-ubppni 1/1 Running 0 82m NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/export-playground-playground NodePort 10.96.167.188 4000:32163/TCP 82m ``` You can connect to the cluster by the `NodePort` service: ```bash mycli --port 32163 --host 127.0.0.1 -uroot ``` Specifically, if you are running with `minikube`, you need to export this port from Docker environment: ```bash tiop minikube service export-playground-playground ``` Example output: ```console > /tiop.py minikube service export-playground-playground --url [INFO] TiOP home: /DATA/disk3/juncen/.tiop [INFO] Using minikube kubeconfig (profile: tiop-hillium-30bf141e) http://192.168.49.2:32163 ``` Then connect to TiDB with the url provided above: ```bash mycli --port 32163 --host 192.168.49.2 -uroot ``` Or you may export internal services by `kubectl port-forward`: ```console > ./tiop.py kubectl get svc [INFO] TiOP home: /DATA/disk3/juncen/.tiop [INFO] Using minikube kubeconfig (profile: tiop-hillium-30bf141e) NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE export-playground-playground NodePort 10.96.167.188 4000:32163/TCP 87m kubernetes ClusterIP 10.96.0.1 443/TCP 44h playground-pd ClusterIP 10.100.180.173 2379/TCP,2380/TCP 87m playground-pd-peer ClusterIP None 2379/TCP,2380/TCP 87m playground-tidb ClusterIP 10.101.183.112 4000/TCP,10080/TCP 87m playground-tidb-peer ClusterIP None 10080/TCP 87m playground-tikv-peer ClusterIP None 20160/TCP,20180/TCP 87m > ./tiop.py kubectl port-forward svc/playground-tidb 10080:10080 ``` ### Using Custom Configurations **Create a cluster with a custom config file:** ```bash tiop cluster create my-cluster --config=./configs/my-config.jsonnet ``` To create your own configuration, you can use the `template` subcommand: ```bash # List all templates tiop cluster template # Generate a template file to `./configs/my-conf.jsonnet` tiop cluster template next-gen > ./configs/my-conf.jsonnet ``` > [!TIP] > If you're editing the configuration in VS Code, you can install [Jsonnet Language Server](https://marketplace.visualstudio.com/items?itemName=Grafana.vscode-jsonnet) and add `tiop/tisonnet` to the library path like this: > > ```json > "jsonnet.languageServer.jpath": [ > "/path/to/tiop/tisonnet/" > ] > ``` > > This will enable auto-complete for configurations. ### Managing Clusters **Check cluster status:** ```bash tiop cluster status my-cluster ``` **List all clusters:** ```bash tiop cluster list ``` This command displays all NodePort services for the cluster and provides connection commands for TiDB. **Delete a cluster:** ```bash tiop cluster delete my-cluster ``` ## Learn More - The configuration DSL and [TiSonnet](./tisonnet/README.md). - To configure [Prometheus & Grafana Dashboards](./dashboards/README.md).