API 概述

本文提供了 Kubernetes API 的参考信息。

REST API 是 Kubernetes 的基本结构。 所有操作和组件之间的通信及外部用户命令都是调用 API 服务器处理的 REST API。 因此,Kubernetes 平台视一切皆为 API 对象, 且它们在 API 中有相应的定义。

Kubernetes API 参考列 出了 Kubernetes v1.23 版本的 API。

如需了解一般背景信息,请查阅 Kubernetes APIKubernetes API 控制访问描述了客户端如何 向 Kubernetes API 服务器进行身份认证以及他们的请求如何被鉴权。

API 版本控制

JSON 和 Protobuf 序列化模式遵循相同的模式更改原则。 以下描述涵盖了这两种格式。

API 版本控制和软件版本控制是间接相关的。 API 和发布版本控制提案 描述了 API 版本控制和软件版本控制间的关系。

不同的 API 版本代表着不同的稳定性和支持级别。 你可以在 API 变更文档 中查看到更多的不同级别的判定标准。

下面是每个级别的摘要:

  • Alpha:

    • 版本名称包含 alpha(例如,v1alpha1)。
    • 软件可能会有 Bug。启用某个特性可能会暴露出 Bug。 某些特性可能默认禁用。
    • 对某个特性的支持可能会随时被删除,恕不另行通知。
    • API 可能在以后的软件版本中以不兼容的方式更改,恕不另行通知。
    • 由于缺陷风险增加和缺乏长期支持,建议该软件仅用于短期测试集群。
  • Beta:

    • 版本名称包含 beta (例如, v2beta3)。
    • 软件被很好的测试过。启用某个特性被认为是安全的。 特性默认开启。
    • 尽管一些特性会发生细节上的变化,但它们将会被长期支持。

    • 在随后的 Beta 版或稳定版中,对象的模式和(或)语义可能以不兼容的方式改变。 当这种情况发生时,将提供迁移说明。 模式更改可能需要删除、编辑和重建 API 对象。 编辑过程可能并不简单。 对于依赖此功能的应用程序,可能需要停机迁移。

    • 该版本的软件不建议生产使用。 后续发布版本可能会有不兼容的变动。 如果你有多个集群可以独立升级,可以放宽这一限制。

    Note: 请试用测试版特性时并提供反馈。特性完成 Beta 阶段测试后, 就可能不会有太多的变更了。

  • Stable:

    • 版本名称如 vX,其中 X 为整数。
    • 特性的稳定版本会出现在后续很多版本的发布软件中。

API 组

API 组 能够简化对 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 参考文档 中查看全部的 API 组。

启用或禁用 API 组

资源和 API 组是在默认情况下被启用的。 你可以通过在 API 服务器上设置 --runtime-config 参数来启用或禁用它们。 --runtime-config 参数接受逗号分隔的 <key>[=<value>] 对, 来描述 API 服务器的运行时配置。如果省略了 =<value> 部分,那么视其指定为 =true。 例如:

  • 禁用 batch/v1, 对应参数设置 --runtime-config=batch/v1=false
  • 启用 batch/v2alpha1, 对应参数设置 --runtime-config=batch/v2alpha1

Note: 启用或禁用组或资源时, 你需要重启 API 服务器和控制器管理器来使 --runtime-config 生效。

持久化

Kubernetes 通过 API 资源来将序列化的状态写到 etcd 中存储。

What’s next

最后修改 July 12, 2021 at 5:16 PM PST: [zh] fix the beta summary indentation in using-api (fdcc9de6f)