API 概述

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

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

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

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

API 版本控制

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

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

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

以下是每个级别的摘要

  • Alpha

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

  • 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 来存储其序列化状态。

下一步

最后修改时间：2022 年 11 月 4 日太平洋标准时间下午 11:37：在参考文档部分更新页面权重 (98f310ab58)