pingcap · liubog2008 · Nov 28, 2025 · Nov 28, 2025 · Nov 28, 2025
diff --git a/en/TOC.md b/en/TOC.md
@@ -16,6 +16,7 @@
   - [Component Configuration](component-configuration.md)
   - [Storage Volume Configuration](volume-configuration.md)
   - [Customize the Configuration of Kubernetes Native Resources](overlay.md)
+  - [Feature Gates](feature-gates.md)
 - Manage
   - Security
     - [Enable TLS for the MySQL Client](enable-tls-for-mysql-client.md)

diff --git a/en/feature-gates.md b/en/feature-gates.md
@@ -0,0 +1,66 @@
+---
+title: Feature Gates
+summary: Introduce how to configure feature gates of a TiDB cluster
+---
+
+# Feature Gates
+
+TiDB Operator supports to enable/disable feature gates by the field `spec.featureGates` in the Cluster CR.
+
+## Feature gates list
+
+| Feature | Default | Stage | Since | Until | Restart |
+|:---|:---|:---|:---|:---|:---|
+| FeatureModification            | false | Alpha | 2.0 | - |      |
+| VolumeAttributesClass          | false | Alpha | 2.0 | - |      |
+| DisablePDDefaultReadinessProbe | false | Alpha | 2.0 | - | PD   |
+| UsePDReadyAPI                  | false | Alpha | 2.0 | - | PD   |
+| SessionTokenSigning            | false | Alpha | 2.0 | - | TiDB |
+
+## Stage
+
+### Alpha
+
+Alpha feature means:
+
+- Disabled by default.
+- Recommanded to enable only when create a new TiDB cluster.
+- Might not support to enable/disable for an existing TiDB cluster.
+- Not recommanded to enable in prod env if not well tested.
+
+### Beta
+
+Beta feature means:
+
+- Normally the feature is well tested.
+- Recommanded to enable for all new created TiDB clusters.
+- Normally enable/disable the feature for an existing TiDB cluster has been supported.
+
+### GA
+
+GA feature means:
+
+- Normally the feature has been tested in a long time.
+- Enabled by default. And cannot be disabled.
+
+## Description of features
+
+### FeatureModification
+
+Support to change `spec.featureGates` if enabled.
+
+### VolumeAttributesClass
+
+Support to change `VolumeAttributesClass` of PVCs. This feature should also be enabled in Kubernetes, see [VolumeAttributesClass](https://kubernetes.io/docs/concepts/storage/volume-attributes-classes/)
+
+### DisablePDDefaultReadinessProbe
+
+If enabled, default tcp readiness probe of PD will be removed.
+
+### UsePDReadyAPI
+
+If enabled, use `/ready` api as readiness probe of PD. See [tikv/pd#8749](https://github.com/tikv/pd/pull/8749)
+
+### SessionTokenSigning
+
+If enabled, `session-token-signing-cert` and `session-token-signing-key` will be configured. See [TiDB ConfigFile](https://docs.pingcap.com/tidb/stable/tidb-configuration-file/#session-token-signing-cert-new-in-v640)
diff --git a/zh/TOC.md b/zh/TOC.md
@@ -16,6 +16,7 @@
   - [组件配置](component-configuration.md)
   - [存储卷配置](volume-configuration.md)
   - [自定义 Kubernetes 原生资源的配置](overlay.md)
+  - [特性门控](feature-gates.md)
 - 运维管理
   - 安全
     - [为 MySQL 客户端开启 TLS](enable-tls-for-mysql-client.md)

diff --git a/zh/feature-gates.md b/zh/feature-gates.md
@@ -0,0 +1,67 @@
+---
+title: 特性门控
+summary: 介绍如何配置 TiDB 集群的特性门控
+---
+
+# 特性门控
+
+TiDB Operator 支持通过 Cluster CR 上的 `spec.featureGates` 开启或关闭一些不成熟或者可能导致组件重启的特性。
+
+## 特性门控列表
+
+| 特性 | 默认值 | 阶段 | 自从 | 直到 | 重启 |
+|:---|:---|:---|:---|:---|:---|
+| FeatureModification            | false | Alpha | 2.0 | - |      |
+| VolumeAttributesClass          | false | Alpha | 2.0 | - |      |
+| DisablePDDefaultReadinessProbe | false | Alpha | 2.0 | - | PD   |
+| UsePDReadyAPI                  | false | Alpha | 2.0 | - | PD   |
+| SessionTokenSigning            | false | Alpha | 2.0 | - | TiDB |
+
+## 阶段
+
+### Alpha
+
+Alpha 阶段的特性有如下特征
+
+- 默认关闭
+- 建议只在新建集群时开启。
+- 不一定支持对已经创建的集群开启或关闭
+- 启用此特性可能会有错误
+- 建议未充分测试的情况不在生产环境下开启
+
+### Beta
+
+Beta 阶段的特性有如下特征
+
+- 通常已经经过良好的测试
+- 建议对所有新建集群开启
+- 通常支持对已经创建的集群开启或关闭(可能重启组件)
+
+### GA
+
+GA 阶段的特性有如下特征
+
+- 通常已经经过长期的测试
+- 默认开启，并不支持关闭
+
+## 特性说明
+
+### FeatureModification
+
+开启后支持变更 `spec.featureGates`.
+
+### VolumeAttributesClass
+
+开启后支持变更 PVC 的 VolumeAttributesClass. 需要 Kubernetes 支持对应功能, 详见 [VolumeAttributesClass](https://kubernetes.io/docs/concepts/storage/volume-attributes-classes/)
+
+### DisablePDDefaultReadinessProbe
+
+开启后不再通过 tcp ping 来检查 PD 的 readiness
+
+### UsePDReadyAPI
+
+开启后通过 `/ready` 来检查 PD 的 readiness, 详见 [tikv/pd#8749](https://github.com/tikv/pd/pull/8749)
+
+### SessionTokenSigning
+
+开启后 TiDB 会配置 `session-token-signing-cert` 和 `session-token-signing-key`, 详见 [TiDB 配置文件](https://docs.pingcap.com/tidb/stable/tidb-configuration-file/#session-token-signing-cert-new-in-v640)