Kubernetes API

Kubernetes API 使你可以查询和操纵 Kubernetes 中对象的状态。Kubernetes 控制平面的核心是 API 服务器和它暴露的 HTTP API。 用户、集群的不同部分以及外部组件都通过 API 服务器相互通信。

Kubernetes 控制面 的核心是 API 服务器。 API 服务器负责提供 HTTP API，以供用户、集群中的不同部分和集群外部组件相互通信。

Kubernetes API 使你可以查询和操纵 Kubernetes API 中对象（例如：Pod、Namespace、ConfigMap 和 Event）的状态。

API 末端、资源类型以及示例都在API 参考中描述。

API 变更

任何成功的系统都要随着新的使用案例的出现和现有案例的变化来成长和变化。 为此，Kubernetes 的功能特性设计考虑了让 Kubernetes API 能够持续变更和成长的因素。 Kubernetes 项目的目标是 不要 引发现有客户端的兼容性问题，并在一定的时期内 维持这种兼容性，以便其他项目有机会作出适应性变更。

一般而言，新的 API 资源和新的资源字段可以被频繁地添加进来。 删除资源或者字段则要遵从 API 废弃策略。

关于什么是兼容性的变更，如何变更 API 等详细信息，可参考 API 变更。

OpenAPI 规范

完整的 API 细节是用 OpenAPI 来表述的。

Kubernetes API 服务器通过 /openapi/v2 末端提供 OpenAPI 规范。 你可以按照下表所给的请求头部，指定响应的格式：

头部可选值说明
Accept-Encodinggzip不指定此头部也是可以的
Acceptapplication/com.github.proto-openapi.spec.v2@v1.0+protobuf主要用于集群内部
application/json默认值
*提供application/json
OpenAPI v2 查询请求的合法头部值

Kubernetes 为 API 实现了一种基于 Protobuf 的序列化格式，主要用于集群内部的通信。 相关文档位于设计提案。 每种 Schema 对应的 IDL 位于定义 API 对象的 Go 包中。

API 版本

为了简化删除字段或者重构资源表示等工作，Kubernetes 支持多个 API 版本， 每一个版本都在不同 API 路径下，例如 /api/v1 或 /apis/rbac.authorization.k8s.io/v1alpha1。

版本化是在 API 级别而不是在资源或字段级别进行的，目的是为了确保 API 为系统资源和行为提供清晰、一致的视图，并能够控制对已废止的和/或实验性 API 的访问。

JSON 和 Protobuf 序列化模式遵循 schema 更改的相同准则 - 下面的所有描述都同时适用于这两种格式。

请注意，API 版本控制和软件版本控制只有间接相关性。 Kubernetes 发行版本提案 中描述了 API 版本与软件版本之间的关系。

不同的 API 版本名称意味着不同级别的软件稳定性和支持程度。 每个级别的判定标准在 API 变更文档 中有更详细的描述。 这些标准主要概括如下：

  • Alpha 级别：

    • 版本名称包含 alpha（例如：v1alpha1）
    • API 可能是有缺陷的。启用该功能可能会带来问题，默认情况是禁用的
    • 对相关功能的支持可能在没有通知的情况下随时终止
    • API 可能在将来的软件发布中出现不兼容性的变更，此类变更不会另行通知
    • 由于缺陷风险较高且缺乏长期支持，推荐仅在短暂的集群测试中使用

  • Beta 级别：

    • 版本名称包含 beta（例如：v2beta3）
    • 代码已经充分测试过。启用该功能被认为是安全的，功能默认已启用。
    • 所支持的功能作为一个整体不会被删除，尽管细节可能会发生变更。
    • 对象的模式和/或语义可能会在后续的 beta 发行版或稳定版中以不兼容的方式进行更改。 发生这种情况时，我们将提供如何迁移到新版本的说明。 迁移操作可能需要删除、编辑和重新创建 API 对象。 执行编辑操作时可能需要动些脑筋。 迁移过程中可能需要停用依赖该功能的应用程序。
    • 建议仅用于非业务关键性用途，因为后续版本中可能存在不兼容的更改。 如果你有多个可以独立升级的集群，则可以放宽此限制。
    • 请尝试我们的 beta 版本功能并且给出反馈！一旦它们结束 beta 阶段，进一步变更可能就不太现实了。

  • 稳定级别：

    • 版本名称是 vX，其中 X 是整数。
    • 功能的稳定版本将出现在许多后续版本的发行软件中。

API 组

为了更容易地扩展 Kubernetes API，Kubernetes 实现了 API组。 API 组在 REST 路径和序列化对象的 apiVersion 字段中指定。

集群中存在若干 API 组：

  1. *核心（Core）*组，通常被称为 遗留（Legacy） 组，位于 REST 路径 /api/v1， 使用 apiVersion: v1。

  2. 命名（Named） 组 REST 路径 /apis/$GROUP_NAME/$VERSION，使用 apiVersion: $GROUP_NAME/$VERSION（例如 apiVersion: batch/v1）。 Kubernetes API 参考中枚举了可用的 API 组的完整列表。

有两种途径来扩展 Kubernetes API 以支持 自定义资源：

  1. 使用 CustomResourceDefinition， 你可以用声明式方式来定义 API 如何提供你所选择的资源 API。

  2. 你也可以选择实现自己的扩展 API 服务器 并使用聚合器 为客户提供无缝的服务。

启用或禁用 API 组

某些资源和 API 组默认情况下处于启用状态。可以通过为 kube-apiserver 设置 --runtime-config 命令行选项来启用或禁用它们。 --runtime-config 接受逗号分隔的值。 例如：要禁用 batch/v1，设置 --runtime-config=batch/v1=false； 要启用 batch/v2alpha1，设置--runtime-config=batch/v2alpha1。 该标志接受逗号分隔的一组”key=value”键值对，用以描述 API 服务器的运行时配置。

说明： 启用或禁用组或资源需要重新启动 kube-apiserver 和 kube-controller-manager 来使得 --runtime-config 更改生效。

持久性

Kubernetes 也将其 API 资源的序列化状态保存起来，写入到 etcd。

接下来