API 概述

本节提供 Kubernetes API 的参考信息。

REST API 是 Kubernetes 的基本架构。所有组件之间的操作和通信，以及外部用户命令，都是 API 服务器处理的 REST API 调用。因此，Kubernetes 平台中的所有内容都被视为 API 对象，并在 API 中有对应的条目。

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

有关一般背景信息，请阅读 Kubernetes API。控制对 Kubernetes API 的访问 描述了客户端如何向 Kubernetes API 服务器进行身份验证，以及其请求如何获得授权。

API 版本控制

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

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

不同的 API 版本表示不同的稳定性和支持级别。你可以在 API 变更文档 中找到有关每个级别标准的更多信息。

以下是每个级别的摘要：

  • Alpha

    • 版本名称包含 alpha (例如，v1alpha1)。
    • 内置的 alpha API 版本默认禁用，必须在 kube-apiserver 配置中显式启用才能使用。
    • 软件可能包含 Bug。启用某个功能可能会暴露 Bug。
    • 对 alpha API 的支持可能随时取消，恕不另行通知。
    • API 可能在后续的软件版本中以不兼容的方式更改，恕不另行通知。
    • 由于 Bug 风险增加且缺乏长期支持，该软件建议仅在短生命周期的测试集群中使用。

  • Beta

    • 版本名称包含 beta (例如，v2beta3)。

    • 内置的 beta API 版本默认禁用，必须在 kube-apiserver 配置中显式启用才能使用（除了 Kubernetes 1.22 之前引入的 API 的 beta 版本，它们默认启用）。

    • 内置的 beta API 版本从引入到废弃的最长生命周期为 9 个月或 3 个次要版本（以较长者为准），从废弃到移除的最长生命周期为 9 个月或 3 个次要版本（以较长者为准）。

    • 该软件经过充分测试。启用某个功能被认为是安全的。

    • 对某个功能的支持不会取消，尽管细节可能会改变。

    • 对象的模式和/或语义可能在后续的 beta 或稳定 API 版本中以不兼容的方式更改。发生这种情况时，将提供迁移说明。适应后续的 beta 或稳定 API 版本可能需要编辑或重新创建 API 对象，并且可能不直接。迁移可能需要依赖该功能的应用程序停机。

    • 该软件不建议用于生产环境。后续版本可能会引入不兼容的更改。一旦 beta API 版本被废弃且不再提供服务，就必须使用 beta API 版本才能过渡到后续的 beta 或稳定 API 版本。

  • 稳定

    • 版本名称为 vX，其中 X 是一个整数。
    • 稳定 API 版本在 Kubernetes 的所有未来主要版本中保持可用，目前没有计划对 Kubernetes 进行重大版本修订以移除稳定 API。

API 组

API 组 使扩展 Kubernetes API 变得更容易。API 组在 REST 路径和序列化对象的 apiVersion 字段中指定。

Kubernetes 中有几个 API 组：

  • 核心（也称为传统）组位于 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
  • 要启用特定版本的 API，例如 storage.k8s.io/v1beta1/csistoragecapacities，请设置 --runtime-config=storage.k8s.io/v1beta1/csistoragecapacities

持久性

Kubernetes 通过将 API 资源写入 etcd 来存储其序列化状态。

下一步

上次修改时间为 2025 年 8 月 19 日上午 8:01 PST：docs: add declarative validation tag reference documentation and link doc in appropriate places (0429fde14b)