zh,en: add feature gates doc

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)

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 typically experimental, and enabling them might require restarting certain cluster components.
+
+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 the definition 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 maturity: Alpha, Beta, and GA.
+
+### Alpha
+
+Alpha-stage features have the following characteristics:
+
+- Disabled by default.
+- Recommended for use only in newly created clusters.
+- Dynamic enabling or disabling in existing clusters is not guaranteed.
+- Known or unknown issues might occur after enabling.
+- **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 on 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.

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)

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) 阶段的特性具有以下特点：
+
+- 通常已经过长期和大规模测试。
+- 默认开启。
+- 不支持关闭。