From f958a6bd969eb2ec294352fac0bae7dc472bb939 Mon Sep 17 00:00:00 2001
From: windsonsea <haifeng.yao@daocloud.io>
Date: Thu, 29 Sep 2022 09:44:36 +0800
Subject: [PATCH] [zh] Sync /reference/using-api/_index.md

---
 .../zh-cn/docs/reference/using-api/_index.md  | 70 +++++++++++--------
 1 file changed, 40 insertions(+), 30 deletions(-)

diff --git a/content/zh-cn/docs/reference/using-api/_index.md b/content/zh-cn/docs/reference/using-api/_index.md
index ba1defcecde..6d6407c78d5 100644
--- a/content/zh-cn/docs/reference/using-api/_index.md
+++ b/content/zh-cn/docs/reference/using-api/_index.md
@@ -58,9 +58,8 @@ describes how clients can authenticate to the Kubernetes API server, and how the
 requests are authorized.
 -->
 如需了解一般背景信息，请查阅 [Kubernetes API](/zh-cn/docs/concepts/overview/kubernetes-api/)。
-[Kubernetes API 控制访问](/zh-cn/docs/concepts/security/controlling-access/)描述了客户端如何
-向 Kubernetes API 服务器进行身份认证以及他们的请求如何被鉴权。
-
+[Kubernetes API 控制访问](/zh-cn/docs/concepts/security/controlling-access/)描述了客户端如何向
+Kubernetes API 服务器进行身份认证以及他们的请求如何被鉴权。
 
 <!--
 ## API versioning
@@ -80,8 +79,8 @@ The [API and release versioning proposal](https://git.k8s.io/sig-release/release
 describes the relationship between API versioning and software versioning.
 -->
 API 版本控制和软件版本控制是间接相关的。
-[API 和发布版本控制提案](https://git.k8s.io/sig-release/release-engineering/versioning.md)
-描述了 API 版本控制和软件版本控制间的关系。
+[API 和发布版本控制提案](https://git.k8s.io/sig-release/release-engineering/versioning.md)描述了
+API 版本控制和软件版本控制间的关系。
 
 <!--
 Different API versions indicate different levels of stability and support. You
@@ -100,52 +99,59 @@ Here's a summary of each level:
 <!--
 - Alpha:
   - The version names contain `alpha` (for example, `v1alpha1`).
-  - The software may contain bugs. Enabling a feature may expose bugs. A
-    feature may be disabled by default.
-  - The support for a feature may be dropped at any time without notice.
+  - Built-in alpha API versions are disabled by default and must be explicitly enabled in the `kube-apiserver` configuration to be used.
+  - The software may contain bugs. Enabling a feature may expose bugs.
+  - Support for an alpha API may be dropped at any time without notice.
   - The API may change in incompatible ways in a later software release without notice.
   - The software is recommended for use only in short-lived testing clusters,
     due to increased risk of bugs and lack of long-term support.
 -->
 - Alpha：
   - 版本名称包含 `alpha`（例如：`v1alpha1`）。
+  - 内置的 Alpha API 版本默认被禁用且必须在 `kube-apiserver` 配置中显式启用才能使用。
   - 软件可能会有 Bug。启用某个特性可能会暴露出 Bug。
-    某些特性可能默认禁用。
-  - 对某个特性的支持可能会随时被删除，恕不另行通知。
+  - 对某个 Alpha API 特性的支持可能会随时被删除，恕不另行通知。
   - API 可能在以后的软件版本中以不兼容的方式更改，恕不另行通知。
   - 由于缺陷风险增加和缺乏长期支持，建议该软件仅用于短期测试集群。
 
 <!--
 - Beta:
   - The version names contain `beta` (for example, `v2beta3`).
+  - Built-in beta API versions are disabled by default and must be explicitly enabled in the `kube-apiserver` configuration to be used
+    (**except** for beta versions of APIs introduced prior to Kubernetes 1.22, which were enabled by default).
+  - Built-in beta API versions have a maximum lifetime of 9 months or 3 minor releases (whichever is longer) from introduction
+    to deprecation, and 9 months or 3 minor releases (whichever is longer) from deprecation to removal.
   - The software is well tested. Enabling a feature is considered safe.
-    Features are enabled by default.
   - The support for a feature will not be dropped, though the details may change.
 -->
 - Beta：
   - 版本名称包含 `beta`（例如：`v2beta3`）。
+  - 内置的 Alpha API 版本默认被禁用且必须在 `kube-apiserver` 配置中显式启用才能使用
+    （例外情况是 Kubernetes 1.22 之前引入的 Beta 版本的 API，这些 API 默认被启用）。
+  - 内置 Beta API 版本从引入到弃用的最长生命周期为 9 个月或 3 个次要版本（以较长者为准），
+    从弃用到移除的最长生命周期为 9 个月或 3 个次要版本（以较长者为准）。
   - 软件被很好的测试过。启用某个特性被认为是安全的。
-    特性默认开启。
   - 尽管一些特性会发生细节上的变化，但它们将会被长期支持。
 
   <!--
   - The schema and/or semantics of objects may change in incompatible ways in
-    a subsequent beta or stable release. When this happens, migration
-    instructions are provided. Schema changes may require deleting, editing, and
-    re-creating API objects. The editing process may not be straightforward.
+    a subsequent beta or stable API version. When this happens, migration
+    instructions are provided. Adapting to a subsequent beta or stable API version
+    may require editing or re-creating API objects, and may not be straightforward.
     The migration may require downtime for applications that rely on the feature.
   - The software is not recommended for production uses. Subsequent releases
-    may introduce incompatible changes. If you have multiple clusters which
-    can be upgraded independently, you may be able to relax this restriction.
+    may introduce incompatible changes. Use of beta API versions is
+    required to transition to subsequent beta or stable API versions
+    once the beta API version is deprecated and no longer served.
   -->
   - 在随后的 Beta 版或 Stable 版中，对象的模式和（或）语义可能以不兼容的方式改变。
     当这种情况发生时，将提供迁移说明。
-    模式更改可能需要删除、编辑和重建 API 对象。
-    编辑过程可能并不简单。
+    适配后续的 Beta 或 Stable API 版本可能需要编辑或重新创建 API 对象，这可能并不简单。
     对于依赖此功能的应用程序，可能需要停机迁移。
   - 该版本的软件不建议生产使用。
     后续发布版本可能会有不兼容的变动。
-    如果你有多个集群可以独立升级，可以放宽这一限制。
+    一旦 Beta API 版本被弃用且不再提供服务，
+    则使用 Beta API 版本的用户需要转为使用后续的 Beta 或 Stable API 版本。
 
   {{< note >}}
   <!--
@@ -159,11 +165,14 @@ Here's a summary of each level:
 <!--
 - Stable:
   - The version name is `vX` where `X` is an integer.
-  - The stable versions of features appear in released software for many subsequent versions.
+  - Stable API versions remain available for all future releases within a Kubernetes major version,
+    and there are no current plans for a major version revision of Kubernetes that removes stable APIs.
 -->
 - Stable：
   - 版本名称如 `vX`，其中 `X` 为整数。
   - 特性的 Stable 版本会出现在后续很多版本的发布软件中。
+    Stable API 版本仍然适用于 Kubernetes 主要版本范围内的所有后续发布，
+    并且 Kubernetes 的主要版本当前没有移除 Stable API 的修订计划。
 
 <!--
 ## API groups
@@ -176,9 +185,8 @@ make it easier to extend the Kubernetes API.
 The API group is specified in a REST path and in the `apiVersion` field of a
 serialized object.
 -->
-[API 组](https://git.k8s.io/design-proposals-archive/api-machinery/api-group.md)
-能够简化对 Kubernetes API 的扩展。
-API 组信息出现在REST 路径中，也出现在序列化对象的 `apiVersion` 字段中。
+[API 组](https://git.k8s.io/design-proposals-archive/api-machinery/api-group.md)能够简化对
+Kubernetes API 的扩展。API 组信息出现在 REST 路径中，也出现在序列化对象的 `apiVersion` 字段中。
 
 <!--
 There are several API groups in Kubernetes:
@@ -195,7 +203,7 @@ There are several API groups in Kubernetes:
 *  **核心（core）**（也被称为 **legacy**）组的 REST 路径为 `/api/v1`。
    核心组并不作为 `apiVersion` 字段的一部分，例如， `apiVersion: v1`。
 *  指定的组位于 REST 路径 `/apis/$GROUP_NAME/$VERSION`，
-   并且使用 `apiVersion: $GROUP_NAME/$VERSION` （例如， `apiVersion: batch/v1`）。
+   并且使用 `apiVersion: $GROUP_NAME/$VERSION` （例如，`apiVersion: batch/v1`）。
    你可以在 [Kubernetes API 参考文档](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#-strong-api-groups-strong-)
    中查看全部的 API 组。
 
@@ -213,15 +221,17 @@ part is omitted, it is treated as if `=true` is specified. For example:
  - to enable a specific version of an API, such as `storage.k8s.io/v1beta1/csistoragecapacities`, set `--runtime-config=storage.k8s.io/v1beta1/csistoragecapacities` 
 -->
 ## 启用或禁用 API 组   {#enabling-or-disabling}
+
 资源和 API 组是在默认情况下被启用的。
 你可以通过在 API 服务器上设置 `--runtime-config` 参数来启用或禁用它们。
 `--runtime-config` 参数接受逗号分隔的 `<key>[=<value>]` 对，
 来描述 API 服务器的运行时配置。如果省略了 `=<value>` 部分，那么视其指定为 `=true`。
 例如：
- - 禁用 `batch/v1`，对应参数设置 `--runtime-config=batch/v1=false`
- - 启用 `batch/v2alpha1`，对应参数设置 `--runtime-config=batch/v2alpha1`
- - 要启用特定版本的 API，如 `storage.k8s.io/v1beta1/csistoragecapacities`，可以设置
-   `--runtime-config=storage.k8s.io/v1beta1/csistoragecapacities`
+
+- 禁用 `batch/v1`，对应参数设置 `--runtime-config=batch/v1=false`
+- 启用 `batch/v2alpha1`，对应参数设置 `--runtime-config=batch/v2alpha1`
+- 要启用特定版本的 API，如 `storage.k8s.io/v1beta1/csistoragecapacities`，可以设置
+  `--runtime-config=storage.k8s.io/v1beta1/csistoragecapacities`
 
 {{< note >}}
 <!--
@@ -251,4 +261,4 @@ Kubernetes 通过 API 资源来将序列化的状态写到 {{< glossary_tooltip
   [aggregator](https://git.k8s.io/design-proposals-archive/api-machinery/aggregated-api-servers.md)
 -->
 - 进一步了解 [API 惯例](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#api-conventions)
-- 阅读 [聚合器](https://git.k8s.io/design-proposals-archive/api-machinery/aggregated-api-servers.md)
+- 阅读[聚合器](https://git.k8s.io/design-proposals-archive/api-machinery/aggregated-api-servers.md)