Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pingcap/tidb/llms.txt

Use this file to discover all available pages before exploring further.

TiDB Operator is the official Kubernetes operator for TiDB. It manages the full lifecycle of TiDB clusters — provisioning, scaling, upgrading, backup, and recovery — through Kubernetes Custom Resources. You interact with your cluster by applying YAML manifests rather than running manual commands on individual nodes.
TiDB Operator automates operations that would otherwise require significant manual coordination across TiDB, TiKV, PD, and TiFlash components. It is the recommended approach for any Kubernetes-based deployment.

​
Prerequisites

Before you begin, ensure you have the following:
  • A running Kubernetes cluster (version 1.24 or later)
  • kubectl configured to communicate with your cluster
  • Helm 3 installed on your local machine
  • Sufficient cluster resources: at minimum 3 nodes with 4 CPU and 8 GB RAM each for a basic cluster
Verify your tools: 
kubectl version --client
helm version
kubectl cluster-info

​
Install TiDB Operator

1

Install the CRDs

TiDB Operator uses Custom Resource Definitions (CRDs) to extend the Kubernetes API. Install them first:
kubectl create -f https://raw.githubusercontent.com/pingcap/tidb-operator/master/manifests/crd.yaml
Verify the CRDs are registered:
kubectl get crd | grep pingcap
2

Add the PingCAP Helm repository

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

Install TiDB Operator

Create a dedicated namespace and install the operator:
kubectl create namespace tidb-admin

helm install tidb-operator pingcap/tidb-operator \
  --namespace tidb-admin \
  --version v1.5.0
Wait for the operator pod to become ready:
kubectl -n tidb-admin get pods --watch
The operator is ready when its pod reaches Running status.

​
Create a TiDB cluster

TiDB Operator manages clusters through the TidbCluster Custom Resource. Apply a manifest to create your cluster.
1

Create the cluster namespace

kubectl create namespace tidb-cluster
2

Apply the TidbCluster manifest

Create a file named tidb-cluster.yaml with the following content:
apiVersion: pingcap.com/v1alpha1
kind: TidbCluster
metadata:
  name: basic
  namespace: tidb-cluster
spec:
  version: v8.1.0
  timezone: UTC
  pvReclaimPolicy: Retain

  pd:
    baseImage: pingcap/pd
    maxFailoverCount: 0
    replicas: 3
    requests:
      storage: 10Gi
      cpu: 500m
      memory: 1Gi
    config: {}

  tidb:
    baseImage: pingcap/tidb
    maxFailoverCount: 0
    replicas: 2
    requests:
      cpu: 500m
      memory: 1Gi
    service:
      type: ClusterIP
    config: {}

  tikv:
    baseImage: pingcap/tikv
    maxFailoverCount: 0
    replicas: 3
    requests:
      storage: 100Gi
      cpu: 1000m
      memory: 2Gi
    config: {}
Apply the manifest:
kubectl apply -f tidb-cluster.yaml
3

Monitor cluster startup

Watch the pods come up. TiDB Operator starts PD first, then TiKV, then TiDB:
kubectl -n tidb-cluster get pods --watch
The cluster is ready when all pods show Running status and their containers are ready (e.g., 1/1). This typically takes 3–5 minutes.Check the overall cluster status:
kubectl -n tidb-cluster get tidbcluster basic

​
Access TiDB

TiDB Operator creates a ClusterIP service for TiDB by default. Other pods in the cluster can connect using the service DNS name:
# Service name follows the pattern: <cluster-name>-tidb.<namespace>
mysql -h basic-tidb.tidb-cluster -P 4000 -u root
Connect from a temporary pod for quick testing:
kubectl run -it --rm mysql-client \
  --image=mysql:8.0 \
  --restart=Never \
  --namespace=tidb-cluster \
  -- mysql -h basic-tidb -P 4000 -u root

​
Scale the cluster

TiDB Operator reconciles the desired state you declare in the TidbCluster resource. To scale, update the replicas field and re-apply. Scale TiDB to 3 replicas: 
kubectl -n tidb-cluster patch tidbcluster basic \
  --type=merge \
  --patch '{"spec":{"tidb":{"replicas":3}}}'
Scale TiKV to 5 replicas: 
kubectl -n tidb-cluster patch tidbcluster basic \
  --type=merge \
  --patch '{"spec":{"tikv":{"replicas":5}}}'
Add TiFlash for analytical workloads: 
tiflash:
  baseImage: pingcap/tiflash
  replicas: 2
  storageClaims:
    - resources:
        requests:
          storage: 100Gi
Apply the updated manifest: 
kubectl apply -f tidb-cluster.yaml
Scaling TiKV down (reducing replicas) triggers data migration to ensure replicas remain balanced. Do not interrupt the cluster during a scale-down operation. Monitor progress with kubectl -n tidb-cluster get tidbcluster basic until the status returns to Normal.

​
Storage classes and persistent volumes

TiDB Operator creates PersistentVolumeClaims for PD, TiKV, and TiFlash. By default, it uses your cluster’s default StorageClass. To specify a storage class explicitly, add storageClassName to each component: 
tikv:
  requests:
    storage: 100Gi
  storageClassName: fast-ssd
For production deployments, use a StorageClass backed by local NVMe SSDs or a high-performance block storage service. Avoid using network-attached storage for TiKV, as latency directly affects write performance.
The pvReclaimPolicy: Retain setting in the TidbCluster spec preserves PersistentVolumes when pods are deleted, protecting data during maintenance. Set it to Delete only in development environments where data loss is acceptable.

​
Upgrade TiDB

To upgrade to a new TiDB version, update the spec.version field in your TidbCluster manifest: 
spec:
  version: v8.2.0
Apply the change: 
kubectl apply -f tidb-cluster.yaml
TiDB Operator performs a rolling upgrade — it upgrades components in order (PD → TiKV → TiDB) and waits for each to be healthy before proceeding. Monitor the upgrade: 
kubectl -n tidb-cluster get pods --watch
kubectl -n tidb-cluster get tidbcluster basic
TiDB Operator does not support downgrading to a previous version. Take a backup before upgrading a production cluster.

​
Next steps

Configuration Reference

Configure TiDB server settings, storage, logging, security, and performance options using a TOML file.

Local Deployment

Run TiDB on your local machine for development using TiUP Playground, Docker, or building from source.

Build docs developers (and LLMs) love

Get started for freeTalk to us