API 概述

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

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

Kubernetes API 参考 列出了 Kubernetes 版本 v1.30 的 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 个次要版本（以较长者为准）。

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

    • 对功能的支持不会被取消，尽管详细信息可能会更改。

    • 对象的模式和/或语义可能会在随后的 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 通过将其写入 etcd 来存储其序列化状态，这些状态以 API 资源的形式表示。

下一步

上次修改时间：2022 年 11 月 4 日下午 11:37 PST：更新参考文档部分中的页面权重 (98f310ab58)