diff --git a/content/zh/docs/reference/using-api/_index.md b/content/zh/docs/reference/using-api/_index.md index 8d2c4b502c..20bad38482 100644 --- a/content/zh/docs/reference/using-api/_index.md +++ b/content/zh/docs/reference/using-api/_index.md @@ -2,3 +2,226 @@ title: 使用 Kubernetes API weight: 10 --- + + + + +本文提供了 Kubernetes API 的参考信息。 + + +REST API 是 Kubernetes 的基本结构。 +所有操作和组件之间的通信及外部用户命令都是调用 API 服务器处理的 REST API。 +因此,Kubernetes 平台视一切皆为 API 对象, +且它们在 [API](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/) 中有相应的定义。 + + +[Kubernetes API 参考](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/)列 +出了 Kubernetes {{< param "version" >}} 版本的 API。 + + +如需了解一般背景信息,请查阅 [Kubernetes API](/zh/docs/concepts/overview/kubernetes-api/)。 +[Kubernetes API 控制访问](/zh/docs/concepts/security/controlling-access/)描述了客户端如何 +向 Kubernetes API 服务器进行身份认证以及他们的请求如何被鉴权。 + + + +## API 版本控制 + + +JSON 和 Protobuf 序列化模式遵循相同的模式更改原则。 +以下描述涵盖了这两种格式。 + + +API 版本控制和软件版本控制是间接相关的。 +[API 和发布版本控制提案](https://git.k8s.io/community/contributors/design-proposals/release/versioning.md) +描述了 API 版本控制和软件版本控制间的关系。 + + +不同的 API 版本代表着不同的稳定性和支持级别。 +你可以在 [API 变更文档]https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#alpha-beta-and-stable-versions) +中查看到更多的不同级别的判定标准。 + + +下面是每个级别的摘要: + +<-- +- 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. + - 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`)。 + - 软件可能会有 Bug。启用某个特性可能会暴露出 Bug。 + 某些特性可能默认禁用。 + - 对某个特性的支持可能会随时被删除,恕不另行通知。 + - API 可能在以后的软件版本中以不兼容的方式更改,恕不另行通知。 + - 由于缺陷风险增加和缺乏长期支持,建议该软件仅用于短期测试集群。 + + +- Beta: + - 版本名称包含 `beta` (例如, `v2beta3`)。 + - 软件被很好的测试过。启用某个特性被认为是安全的。 + 特性默认开启。 + - 尽管一些特性会发生细节上的变化,但它们将会被长期支持。 + + + - 在随后的 Beta 版或稳定版中,对象的模式和(或)语义可能以不兼容的方式改变。 + 当这种情况发生时,将提供迁移说明。 + 模式更改可能需要删除、编辑和重建 API 对象。 + 编辑过程可能并不简单。 + 对于依赖此功能的应用程序,可能需要停机迁移。 + - 该版本的软件不建议生产使用。 + 后续发布版本可能会有不兼容的变动。 + 如果你有多个集群可以独立升级,可以放宽这一限制。 + + + {{< note >}} + 请试用测试版特性时并提供反馈。特性完成 Beta 阶段测试后, + 就可能不会有太多的变更了。 + {{< /note >}} + + +- Stable: + - 版本名称如 `vX`,其中 `X` 为整数。 + - 特性的稳定版本会出现在后续很多版本的发布软件中。 + + +## API 组 + + +[API 组](https://git.k8s.io/community/contributors/design-proposals/api-machinery/api-group.md) +能够简化对 Kubernetes API 的扩展。 +API 组信息出现在REST 路径中,也出现在序列化对象的 `apiVersion` 字段中。 + + +以下是 Kubernetes 中的几个组: +* *核心*(也叫 *legacy*)组的 REST 路径为 `/api/v1`。 + 核心组并不作为 `apiVersion` 字段的一部分,例如, `apiVersion: v1`。 +* 指定的组位于 REST 路径 `/apis/$GROUP_NAME/$VERSION`, + 并且使用 `apiVersion: $GROUP_NAME/$VERSION` (例如, `apiVersion: batch/v1`)。 + 你可以在 [Kubernetes API 参考文档](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#-strong-api-groups-strong-) + 中查看全部的 API 组。 + + +## 启用或禁用 API 组 {#enabling-or-disabling} +资源和 API 组是在默认情况下被启用的。 +你可以通过在 API 服务器上设置 `--runtime-config` 参数来启用或禁用它们。 +`--runtime-config` 参数接受逗号分隔的 `[=]` 对, +来描述 API 服务器的运行时配置。如果省略了 `=` 部分,那么视其指定为 `=true`。 +例如: + - 禁用 `batch/v1`, 对应参数设置 `--runtime-config=batch/v1=false` + - 启用 `batch/v2alpha1`, 对应参数设置 `--runtime-config=batch/v2alpha1` + + +{{< note >}} +启用或禁用组或资源时, +你需要重启 API 服务器和控制器管理器来使 `--runtime-config` 生效。 +{{< /note >}} + + +## 持久化 + + +Kubernetes 通过 API 资源来将序列化的状态写到 {{< glossary_tooltip term_id="etcd" >}} 中存储。 + +## {{% heading "whatsnext" %}} + + +- 进一步了解 [API 惯例](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#api-conventions) +- 阅读 [聚合器](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/aggregated-api-servers.md)