pingcap · Lloyd-Pottiger · Jan 21, 2026 · Feb 3, 2026
diff --git a/components/cluster/command/template.go b/components/cluster/command/template.go
@@ -43,6 +43,7 @@ type LocalTemplate struct {
 	PDServers           []string // pd_servers in yaml template
 	TiDBServers         []string // tidb_servers in yaml template
 	TiKVServers         []string // tikv_servers in yaml template
+	TiKVWorkerServers   []string // tikv_worker_servers in yaml template
 	TiFlashServers      []string // tiflash_servers in yaml template
 	MonitoringServers   []string // monitoring_servers in yaml template
 	GrafanaServers      []string // grafana_servers in yaml template
@@ -131,6 +132,7 @@ func newTemplateCmd() *cobra.Command {
 	cmd.Flags().StringSliceVar(&localOpt.PDServers, "pd-servers", []string{"127.0.0.1"}, "List of PD servers")
 	cmd.Flags().StringSliceVar(&localOpt.TiDBServers, "tidb-servers", []string{"127.0.0.1"}, "List of TiDB servers")
 	cmd.Flags().StringSliceVar(&localOpt.TiKVServers, "tikv-servers", []string{"127.0.0.1"}, "List of TiKV servers")
+	cmd.Flags().StringSliceVar(&localOpt.TiKVWorkerServers, "tikv-worker-servers", nil, "List of TiKV worker servers")
 	cmd.Flags().StringSliceVar(&localOpt.TiFlashServers, "tiflash-servers", nil, "List of TiFlash servers")
 	cmd.Flags().StringSliceVar(&localOpt.MonitoringServers, "monitoring-servers", []string{"127.0.0.1"}, "List of monitor servers")
 	cmd.Flags().StringSliceVar(&localOpt.GrafanaServers, "grafana-servers", []string{"127.0.0.1"}, "List of grafana servers")

diff --git a/embed/examples/cluster/local.tpl b/embed/examples/cluster/local.tpl
@@ -43,6 +43,12 @@ tikv_servers:
   - host: {{ . }}
 {{- end }}
 {{ end }}
+{{ if .TiKVWorkerServers -}}
+tikv_worker_servers:
+{{- range .TiKVWorkerServers }}
+  - host: {{ . }}
+{{- end }}
+{{ end }}
 {{- if .TiFlashServers }}
 tiflash_servers:
  {{- range .TiFlashServers }}

diff --git a/embed/templates/config/prometheus.yml.tpl b/embed/templates/config/prometheus.yml.tpl
@@ -145,6 +145,23 @@ scrape_configs:
     - targets:
 {{- range .TiKVStatusAddrs}}
       - '{{.}}'
+{{- end}}
+{{- if .TiKVWorkerAddrs}}
+  - job_name: "tikv-worker"
+    honor_labels: true # don't overwrite job & instance labels
+{{- if .TLSEnabled}}
+    scheme: https
+    tls_config:
+      insecure_skip_verify: false
+      ca_file: ../tls/ca.crt
+      cert_file: ../tls/prometheus.crt
+      key_file: ../tls/prometheus.pem
+{{- end}}
+    static_configs:
+    - targets:
+{{- range .TiKVWorkerAddrs}}
+      - '{{.}}'
+{{- end}}
 {{- end}}
   - job_name: "pd"
     honor_labels: true # don't overwrite job & instance labels
@@ -377,6 +394,14 @@ scrape_configs:
     {{- end}}
       labels:
         group: 'tikv'
+{{- if .TiKVWorkerAddrs}}
+    - targets:
+    {{- range .TiKVWorkerAddrs}}
+      - '{{.}}'
+    {{- end}}
+      labels:
+        group: 'tikv-worker'
+{{- end}}
     - targets:
     {{- range .PDAddrs}}
       - '{{.}}'
@@ -511,4 +536,4 @@ scrape_configs:
 
 {{- if .RemoteConfig}}
 {{.RemoteConfig}}
-{{- end}}
+{{- end}}
diff --git a/embed/templates/scripts/run_tikv-worker.sh.tpl b/embed/templates/scripts/run_tikv-worker.sh.tpl
@@ -0,0 +1,19 @@
+#!/bin/bash
+set -e
+
+# WARNING: This file was auto-generated. Do not edit!
+#          All your edit might be overwritten!
+cd "{{.DeployDir}}" || exit 1
+
+{{- if and .NumaNode .NumaCores}}
+exec numactl --cpunodebind={{.NumaNode}} --membind={{.NumaNode}} -C {{.NumaCores}} bin/tikv-worker \
+{{- else if .NumaNode}}
+exec numactl --cpunodebind={{.NumaNode}} --membind={{.NumaNode}} bin/tikv-worker \
+{{- else}}
+exec bin/tikv-worker \
+{{- end}}
+    --addr "{{.Addr}}" \
+    --pd-endpoints "{{.PD}}" \
+    --config conf/tikv-worker.toml \
+    --log-file "{{.LogDir}}/tikv_worker.log" 2>> "{{.LogDir}}/tikv_worker_stderr.log"
+
diff --git a/pkg/cluster/manager/patch.go b/pkg/cluster/manager/patch.go
@@ -147,13 +147,18 @@ func checkPackage(specManager *spec.SpecManager, name string, inst spec.Instance
 	}
 
 	ver := inst.CalculateVersion(metadata.GetBaseMeta().Version)
-	repo, err := clusterutil.NewRepository(nodeOS, arch)
-	if err != nil {
-		return err
-	}
-	entry, err := repo.ComponentBinEntry(inst.ComponentSource(), ver)
-	if err != nil {
-		return err
+	var entry string
+	if inst.ComponentName() == spec.ComponentTiKVWorker {
+		entry = spec.ComponentTiKVWorker
+	} else {
+		repo, err := clusterutil.NewRepository(nodeOS, arch)
+		if err != nil {
+			return err
+		}
+		entry, err = repo.ComponentBinEntry(inst.ComponentSource(), ver)
+		if err != nil {
+			return err
+		}
 	}
 
 	checksum, err := utils.Checksum(packagePath)

diff --git a/pkg/cluster/spec/monitoring.go b/pkg/cluster/spec/monitoring.go
@@ -360,6 +360,13 @@ func (i *MonitorInstance) InitConfig(
 			cfig.AddTiKV(kv.Host, uint64(kv.StatusPort))
 		}
 	}
+	if servers, found := topoHasField("TiKVWorkerServers"); found {
+		for i := 0; i < servers.Len(); i++ {
+			worker := servers.Index(i).Interface().(*TiKVWorkerSpec)
+			uniqueHosts.Insert(worker.Host)
+			cfig.AddTiKVWorker(worker.Host, uint64(worker.Port))
+		}
+	}
 	if servers, found := topoHasField("TiDBServers"); found {
 		for i := 0; i < servers.Len(); i++ {
 			db := servers.Index(i).Interface().(*TiDBSpec)

diff --git a/pkg/cluster/spec/spec.go b/pkg/cluster/spec/spec.go
@@ -120,6 +120,7 @@ type (
 	ServerConfigs struct {
 		TiDB            map[string]any    `yaml:"tidb"`
 		TiKV            map[string]any    `yaml:"tikv"`
+		TiKVWorker      map[string]any    `yaml:"tikv_worker"`
 		PD              map[string]any    `yaml:"pd"`
 		TSO             map[string]any    `yaml:"tso"`
 		Scheduling      map[string]any    `yaml:"scheduling"`
@@ -140,6 +141,7 @@ type (
 	ComponentVersions struct {
 		TiDB            string `yaml:"tidb,omitempty"`
 		TiKV            string `yaml:"tikv,omitempty"`
+		TiKVWorker      string `yaml:"tikv_worker,omitempty"`
 		TiFlash         string `yaml:"tiflash,omitempty"`
 		PD              string `yaml:"pd,omitempty"`
 		TSO             string `yaml:"tso,omitempty"`
@@ -162,15 +164,16 @@ type (
 
 	// ComponentSources represents the source of components
 	ComponentSources struct {
-		TiDB      string `yaml:"tidb,omitempty" validate:"tidb:editable"`
-		TiKV      string `yaml:"tikv,omitempty" validate:"tikv:editable"`
-		TiFlash   string `yaml:"tiflash,omitempty" validate:"tiflash:editable"`
-		PD        string `yaml:"pd,omitempty" validate:"pd:editable"`
-		Dashboard string `yaml:"tidb_dashboard,omitempty" validate:"tidb_dashboard:editable"`
-		Pump      string `yaml:"pump,omitempty" validate:"pump:editable"`
-		Drainer   string `yaml:"drainer,omitempty" validate:"drainer:editable"`
-		CDC       string `yaml:"cdc,omitempty" validate:"cdc:editable"`
-		TiKVCDC   string `yaml:"kvcdc,omitempty" validate:"kvcdc:editable"`
+		TiDB       string `yaml:"tidb,omitempty" validate:"tidb:editable"`
+		TiKV       string `yaml:"tikv,omitempty" validate:"tikv:editable"`
+		TiKVWorker string `yaml:"tikv_worker,omitempty" validate:"tikv_worker:editable"`
+		TiFlash    string `yaml:"tiflash,omitempty" validate:"tiflash:editable"`
+		PD         string `yaml:"pd,omitempty" validate:"pd:editable"`
+		Dashboard  string `yaml:"tidb_dashboard,omitempty" validate:"tidb_dashboard:editable"`
+		Pump       string `yaml:"pump,omitempty" validate:"pump:editable"`
+		Drainer    string `yaml:"drainer,omitempty" validate:"drainer:editable"`
+		CDC        string `yaml:"cdc,omitempty" validate:"cdc:editable"`
+		TiKVCDC    string `yaml:"kvcdc,omitempty" validate:"kvcdc:editable"`
 	}
 
 	// Specification represents the specification of topology.yaml
@@ -182,6 +185,7 @@ type (
 		ServerConfigs          ServerConfigs          `yaml:"server_configs,omitempty" validate:"server_configs:ignore"`
 		TiDBServers            []*TiDBSpec            `yaml:"tidb_servers"`
 		TiKVServers            []*TiKVSpec            `yaml:"tikv_servers"`
+		TiKVWorkerServers      []*TiKVWorkerSpec      `yaml:"tikv_worker_servers,omitempty"`
 		TiFlashServers         []*TiFlashSpec         `yaml:"tiflash_servers"`
 		TiProxyServers         []*TiProxySpec         `yaml:"tiproxy_servers"`
 		PDServers              []*PDSpec              `yaml:"pd_servers"`
@@ -570,6 +574,7 @@ func (s *Specification) Merge(that Topology) Topology {
 		ComponentVersions:      s.ComponentVersions.Merge(spec.ComponentVersions),
 		TiDBServers:            append(s.TiDBServers, spec.TiDBServers...),
 		TiKVServers:            append(s.TiKVServers, spec.TiKVServers...),
+		TiKVWorkerServers:      append(s.TiKVWorkerServers, spec.TiKVWorkerServers...),
 		PDServers:              append(s.PDServers, spec.PDServers...),
 		DashboardServers:       append(s.DashboardServers, spec.DashboardServers...),
 		TiFlashServers:         append(s.TiFlashServers, spec.TiFlashServers...),
@@ -595,6 +600,7 @@ func (v *ComponentVersions) Merge(that ComponentVersions) ComponentVersions {
 	return ComponentVersions{
 		TiDB:            utils.Ternary(that.TiDB != "", that.TiDB, v.TiDB).(string),
 		TiKV:            utils.Ternary(that.TiKV != "", that.TiKV, v.TiKV).(string),
+		TiKVWorker:      utils.Ternary(that.TiKVWorker != "", that.TiKVWorker, v.TiKVWorker).(string),
 		PD:              utils.Ternary(that.PD != "", that.PD, v.PD).(string),
 		TSO:             utils.Ternary(that.TSO != "", that.TSO, v.TSO).(string),
 		Scheduling:      utils.Ternary(that.Scheduling != "", that.Scheduling, v.Scheduling).(string),
@@ -812,7 +818,7 @@ func (s *Specification) ComponentsByStopOrder() (comps []Component) {
 
 // ComponentsByStartOrder return component in the order need to start.
 func (s *Specification) ComponentsByStartOrder() (comps []Component) {
-	// "pd", "tso", "scheduling", "resource-manager", "dashboard", "tiproxy", "tikv", "pump", "tidb", "tiflash", "drainer", "cdc", "tikv-cdc", "prometheus", "grafana", "alertmanager"
+	// "pd", "tso", "scheduling", "resource-manager", "dashboard", "tiproxy", "tikv", "tikv-worker", "pump", "tidb", "tiflash", "drainer", "cdc", "tikv-cdc", "prometheus", "grafana", "alertmanager"
 	comps = append(comps, &PDComponent{s})
 	comps = append(comps, &TSOComponent{s})
 	comps = append(comps, &SchedulingComponent{s})
@@ -821,6 +827,7 @@ func (s *Specification) ComponentsByStartOrder() (comps []Component) {
 	comps = append(comps, &DashboardComponent{s})
 	comps = append(comps, &TiProxyComponent{s})
 	comps = append(comps, &TiKVComponent{s})
+	comps = append(comps, &TiKVWorkerComponent{s})
 	comps = append(comps, &PumpComponent{s})
 	comps = append(comps, &TiDBComponent{s})
 	comps = append(comps, &TiFlashComponent{s})
@@ -840,7 +847,7 @@ func (s *Specification) ComponentsByUpdateOrder(curVer string) (comps []Componen
 	// Ref: https://github.com/pingcap/tiup/issues/2166
 	cdcUpgradeBeforePDTiKVTiDB := tidbver.TiCDCUpgradeBeforePDTiKVTiDB(curVer)
 
-	// "tiflash", <"cdc">, "pd", "tso", "scheduling", "resource-manager","router", "dashboard", "tiproxy", "tikv", "pump", "tidb", "drainer", <"cdc>", "prometheus", "grafana", "alertmanager"
+	// "tiflash", <"cdc">, "pd", "tso", "scheduling", "resource-manager","router", "dashboard", "tiproxy", "tikv", "tikv-worker", "pump", "tidb", "drainer", <"cdc>", "prometheus", "grafana", "alertmanager"
 	comps = append(comps, &TiFlashComponent{s})
 	if cdcUpgradeBeforePDTiKVTiDB {
 		comps = append(comps, &CDCComponent{s})
@@ -853,6 +860,7 @@ func (s *Specification) ComponentsByUpdateOrder(curVer string) (comps []Componen
 	comps = append(comps, &DashboardComponent{s})
 	comps = append(comps, &TiProxyComponent{s})
 	comps = append(comps, &TiKVComponent{s})
+	comps = append(comps, &TiKVWorkerComponent{s})
 	comps = append(comps, &PumpComponent{s})
 	comps = append(comps, &TiDBComponent{s})
 	comps = append(comps, &DrainerComponent{s})

diff --git a/pkg/cluster/spec/spec_test.go b/pkg/cluster/spec/spec_test.go
@@ -32,6 +32,7 @@ func TestDefaultDataDir(t *testing.T) {
 	// Test with without global DataDir.
 	topo := new(Specification)
 	topo.TiKVServers = append(topo.TiKVServers, &TiKVSpec{Host: "1.1.1.1", Port: 22})
+	topo.TiKVWorkerServers = append(topo.TiKVWorkerServers, &TiKVWorkerSpec{Host: "1.1.1.2", Port: 22})
 	topo.CDCServers = append(topo.CDCServers, &CDCSpec{Host: "2.3.3.3", Port: 22})
 	topo.TiKVCDCServers = append(topo.TiKVCDCServers, &TiKVCDCSpec{Host: "3.3.3.3", Port: 22})
 	data, err := yaml.Marshal(topo)
@@ -43,6 +44,7 @@ func TestDefaultDataDir(t *testing.T) {
 	require.NoError(t, err)
 	require.Equal(t, "data", topo.GlobalOptions.DataDir)
 	require.Equal(t, "data", topo.TiKVServers[0].DataDir)
+	require.Equal(t, "data", topo.TiKVWorkerServers[0].DataDir)
 	require.Equal(t, "data", topo.CDCServers[0].DataDir)
 	require.Equal(t, "data", topo.TiKVCDCServers[0].DataDir)
 
@@ -54,6 +56,7 @@ func TestDefaultDataDir(t *testing.T) {
 	require.NoError(t, err)
 	require.Equal(t, "data", topo.GlobalOptions.DataDir)
 	require.Equal(t, "data", topo.TiKVServers[0].DataDir)
+	require.Equal(t, "data", topo.TiKVWorkerServers[0].DataDir)
 	require.Equal(t, "data", topo.CDCServers[0].DataDir)
 	require.Equal(t, "data", topo.TiKVCDCServers[0].DataDir)
 
@@ -62,6 +65,8 @@ func TestDefaultDataDir(t *testing.T) {
 	topo.GlobalOptions.DataDir = "/global_data"
 	topo.TiKVServers = append(topo.TiKVServers, &TiKVSpec{Host: "1.1.1.1", Port: 22})
 	topo.TiKVServers = append(topo.TiKVServers, &TiKVSpec{Host: "1.1.1.2", Port: 33, DataDir: "/my_data"})
+	topo.TiKVWorkerServers = append(topo.TiKVWorkerServers, &TiKVWorkerSpec{Host: "1.1.1.3", Port: 22})
+	topo.TiKVWorkerServers = append(topo.TiKVWorkerServers, &TiKVWorkerSpec{Host: "1.1.1.4", Port: 33, DataDir: "/my_worker_data"})
 	topo.CDCServers = append(topo.CDCServers, &CDCSpec{Host: "2.3.3.3", Port: 22})
 	topo.CDCServers = append(topo.CDCServers, &CDCSpec{Host: "2.3.3.4", Port: 22, DataDir: "/cdc_data"})
 	topo.TiKVCDCServers = append(topo.TiKVCDCServers, &TiKVCDCSpec{Host: "3.3.3.3", Port: 22})
@@ -76,6 +81,9 @@ func TestDefaultDataDir(t *testing.T) {
 	require.Equal(t, "/global_data/tikv-22", topo.TiKVServers[0].DataDir)
 	require.Equal(t, "/my_data", topo.TiKVServers[1].DataDir)
 
+	require.Equal(t, "/global_data/tikv-worker-22", topo.TiKVWorkerServers[0].DataDir)
+	require.Equal(t, "/my_worker_data", topo.TiKVWorkerServers[1].DataDir)
+
 	require.Equal(t, "/global_data/cdc-22", topo.CDCServers[0].DataDir)
 	require.Equal(t, "/cdc_data", topo.CDCServers[1].DataDir)