pingcap · ti-chi-bot · Dec 3, 2025 · 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,85 @@
+---
+title: Feature Gates
+summary: Learn how to use feature gates to enable or disable specific features in a TiDB cluster.
+---
+
+# Feature Gates
+
+Feature gates are configuration switches that enable or disable specific features in TiDB Operator. These features are generally experimental, and enabling them might require restarting certain components for the changes to take effect.
+
+You can configure feature gates in the `spec.featureGates` field of the Cluster Custom Resource (CR). The following example shows how to enable the `FeatureModification` feature gate:
+
+```yaml
+spec:
+  featureGates:
+    FeatureModification: true
+```
+
+## Supported feature gates
+
+This section describes the feature gates supported by TiDB Operator. For definitions of feature stages, see [Feature gate stages](#feature-gate-stages).
+
+### `FeatureModification`
+
+- When this feature is enabled, you can modify the `spec.featureGates` configuration.
+- Default value: `false`
+- Stage: Alpha in v2.0 and later versions
+- Components requiring restart: None
+
+### `VolumeAttributesClass`
+
+- When this feature is enabled, you can modify the `VolumeAttributesClass` attribute of a PVC. This feature depends on the corresponding Kubernetes capability. For more information, see the [Kubernetes documentation for VolumeAttributesClass](https://kubernetes.io/docs/concepts/storage/volume-attributes-classes/).
+- Default value: `false`
+- Stage: Alpha in v2.0 and later versions
+- Components requiring restart: None
+
+### `DisablePDDefaultReadinessProbe`
+
+- When this feature is enabled, TiDB Operator no longer checks PD readiness using TCP probes.
+- Default value: `false`
+- Stage: Alpha in v2.0 and later versions
+- Components requiring restart: PD
+
+### `UsePDReadyAPI`
+
+- When this feature is enabled, TiDB Operator checks PD readiness using the `/ready` API. For implementation details, see [`tikv/pd` #8749](https://github.com/tikv/pd/pull/8749).
+- Default value: `false`
+- Stage: Alpha in v2.0 and later versions
+- Components requiring restart: PD
+
+### `SessionTokenSigning`
+
+- When this feature is enabled, TiDB Operator automatically configures the [`session-token-signing-cert`](https://docs.pingcap.com/tidb/stable/tidb-configuration-file/#session-token-signing-cert-new-in-v640) and [`session-token-signing-key`](https://docs.pingcap.com/tidb/stable/tidb-configuration-file/#session-token-signing-key-new-in-v640) parameters for TiDB.
+- Default value: `false`
+- Stage: Alpha in v2.0 and later versions
+- Components requiring restart: TiDB
+
+## Feature gate stages
+
+TiDB Operator classifies feature gates into three stages based on feature maturity: Alpha, Beta, and GA.
+
+### Alpha
+
+Alpha-stage features have the following characteristics:
+
+- Disabled by default.
+- Recommended only for newly created clusters.
+- Dynamic enabling or disabling in existing clusters is not guaranteed.
+- Known or unknown issues might occur after being enabled.
+- **Not recommended for production environments** unless risks are fully evaluated and validated.
+
+### Beta
+
+Beta-stage features have the following characteristics:
+
+- Typically have undergone thorough testing.
+- Recommended to enable in all newly created clusters.
+- Usually support enabling or disabling in existing clusters, but might require restarting related components.
+
+### GA
+
+GA (General Availability) features have the following characteristics:
+
+- Typically have undergone long-term and large-scale testing.
+- Enabled by default.
+- Cannot be disabled using feature gates.
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,85 @@
+---
+title: 特性门控
+summary: 介绍如何使用特性门控 (Feature Gates) 在 TiDB 集群中开启或关闭特定功能。
+---
+
+# 特性门控
+
+特性门控 (Feature Gates) 是一组开关，用于控制是否启用 TiDB Operator 中的特定功能。这些功能通常处于实验阶段，启用后可能需要重启部分组件才能生效。
+
+你可以在 Cluster CR 的 `spec.featureGates` 字段中配置特性门控。以下示例展示如何启用 `FeatureModification` 特性：
+
+```yaml
+spec:
+  featureGates:
+    FeatureModification: true
+```
+
+## 支持的特性门控
+
+本节列出了 TiDB Operator 支持的特性门控。关于特性阶段的定义，请参考[特性门控阶段](#特性门控阶段)。
+
+### `FeatureModification`
+
+- 开启该特性后，你可以修改 `spec.featureGates` 配置。
+- 默认值：`false`
+- 阶段：v2.0 及之后版本为 Alpha
+- 需要重启的组件：无
+
+### `VolumeAttributesClass`
+
+- 开启该特性后，你可以修改 PVC 的 `VolumeAttributesClass` 属性。该功能依赖 Kubernetes 的对应能力。更多信息，请参考 [Kubernetes 官方文档 VolumeAttributesClass](https://kubernetes.io/zh-cn/docs/concepts/storage/volume-attributes-classes/)。
+- 默认值：`false`
+- 阶段：v2.0 及之后版本为 Alpha
+- 需要重启的组件：无
+
+### `DisablePDDefaultReadinessProbe`
+
+- 开启该特性后，TiDB Operator 不再通过 TCP 探测方式检查 PD 的就绪状态。
+- 默认值：`false`
+- 阶段：v2.0 及之后版本为 Alpha
+- 需要重启的组件：PD
+
+### `UsePDReadyAPI`
+
+- 开启该特性后，TiDB Operator 将通过 PD 的 `/ready` API 检查就绪状态。有关实现细节，请参阅 [`tikv/pd` #8749](https://github.com/tikv/pd/pull/8749)。
+- 默认值：`false`
+- 阶段：v2.0 及之后版本为 Alpha
+- 需要重启的组件：PD
+
+### `SessionTokenSigning`
+
+- 开启该特性后，TiDB Operator 会自动配置 TiDB 的 [`session-token-signing-cert`](https://docs.pingcap.com/zh/tidb/stable/tidb-configuration-file/#session-token-signing-cert-从-v640-版本开始引入) 和 [`session-token-signing-key`](https://docs.pingcap.com/zh/tidb/stable/tidb-configuration-file/#session-token-signing-key-从-v640-版本开始引入) 参数。
+- 默认值：`false`
+- 阶段：v2.0 及之后版本为 Alpha
+- 需要重启的组件：TiDB
+
+## 特性门控阶段
+
+特性门控根据功能的成熟度分为 Alpha、Beta 和 GA 三个阶段。
+
+### Alpha
+
+Alpha 阶段的特性具有以下特点：
+
+- 默认关闭。
+- 建议仅在新建集群中开启。
+- 不保证支持在已有集群中动态开启或关闭。
+- 开启后可能出现已知或未知问题。
+- **不建议在生产环境中使用**，除非已充分评估并验证风险。
+
+### Beta
+
+Beta 阶段的特性具有以下特点：
+
+- 通常已经过较充分的测试。
+- 建议在所有新建集群中开启。
+- 通常支持在已有集群中开启或关闭，但可能需要重启相关组件。
+
+### GA
+
+GA (General Availability) 阶段的特性具有以下特点：
+
+- 通常已经过长期和大规模测试。
+- 默认开启。
+- 不支持通过特性门控关闭。