Kubernetes API

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

Kubernetes 的核心 控制平面 是 API 服务器。API 服务器暴露一个 HTTP API，允许最终用户、集群的不同部分和外部组件相互通信。

Kubernetes API 允许您查询和操作 Kubernetes 中 API 对象的状态（例如：Pod、Namespace、ConfigMap 和 Event）。

大多数操作可以通过 kubectl 命令行界面或其他命令行工具（例如 kubeadm）执行，后者反过来使用 API。但是，您也可以使用 REST 调用直接访问 API。Kubernetes 提供了一组 客户端库 供希望使用 Kubernetes API 编写应用程序的人员使用。

每个 Kubernetes 集群都会发布集群所服务的 API 的规范。Kubernetes 使用两种机制来发布这些 API 规范；两者都有助于实现自动互操作性。例如，kubectl 工具会获取并缓存 API 规范，以启用命令行补全和其他功能。Kubernetes 支持的两种机制如下

  • 发现 API 提供有关 Kubernetes API 的信息：API 名称、资源、版本和受支持的操作。这是 Kubernetes 特定的术语，因为它与 Kubernetes OpenAPI 不同的 API。它旨在简要概述可用的资源，并且不详细说明资源的特定模式。有关资源模式的参考，请参阅 OpenAPI 文档。

  • Kubernetes OpenAPI 文档 提供所有 Kubernetes API 端点的 (完整) OpenAPI v2.0 和 3.0 模式。 OpenAPI v3 是访问 OpenAPI 的首选方法，因为它提供了对 API 更全面和准确的视图。它包括所有可用的 API 路径，以及每个端点上的每个操作消耗和生成的所有资源。它还包括集群支持的任何可扩展性组件。该数据是完整的规范，并且比来自发现 API 的数据大得多。

发现 API

Kubernetes 通过发现 API 发布集群支持的所有组版本和资源。这包括每个资源的以下内容

  • 名称
  • 集群或命名空间范围
  • 端点 URL 和受支持的动词
  • 备用名称
  • 组、版本、种类

API 以聚合和未聚合的形式提供。聚合发现服务两个端点，而未聚合发现为每个组版本提供一个单独的端点。

聚合发现

特性状态： Kubernetes v1.30 [稳定](默认启用)

Kubernetes 对聚合发现提供稳定支持，通过两个端点 (/api 和 /apis) 发布集群支持的所有资源。请求此端点可以大大减少发送以从集群获取发现数据的请求数量。您可以通过使用指示聚合发现资源的 Accept 标头来访问数据：Accept: application/json;v=v2;g=apidiscovery.k8s.io;as=APIGroupDiscoveryList。

如果不使用 Accept 标头指示资源类型，则 /api 和 /apis 端点的默认响应是未聚合的发现文档。

可以在 Kubernetes GitHub 存储库中找到 发现文档，用于内置资源。如果无法查询 Kubernetes 集群，可以使用此 Github 文档作为可用资源的参考。

该端点还支持 ETag 和 protobuf 编码。

未聚合发现

在没有发现聚合的情况下，发现以层级方式发布，根端点发布下游文档的发现信息。

集群支持的所有组版本的列表在 /api 和 /apis 端点发布。示例

{
  "kind": "APIGroupList",
  "apiVersion": "v1",
  "groups": [
    {
      "name": "apiregistration.k8s.io",
      "versions": [
        {
          "groupVersion": "apiregistration.k8s.io/v1",
          "version": "v1"
        }
      ],
      "preferredVersion": {
        "groupVersion": "apiregistration.k8s.io/v1",
        "version": "v1"
      }
    },
    {
      "name": "apps",
      "versions": [
        {
          "groupVersion": "apps/v1",
          "version": "v1"
        }
      ],
      "preferredVersion": {
        "groupVersion": "apps/v1",
        "version": "v1"
      }
    },
    ...
}

需要额外的请求才能在 /apis/<group>/<version> (例如：/apis/rbac.authorization.k8s.io/v1alpha1) 处获取每个组版本的发现文档，该文档会通告在特定组版本下提供的资源列表。这些端点由 kubectl 用于获取集群支持的资源列表。

OpenAPI 接口定义

有关 OpenAPI 规范的详细信息，请参阅 OpenAPI 文档。

Kubernetes 提供 OpenAPI v2.0 和 OpenAPI v3.0。由于 OpenAPI 版本 2 的限制，某些字段从发布的 OpenAPI 中删除，包括但不限于 default、nullable、oneOf。OpenAPI v3 是访问 OpenAPI 的首选方法，因为它提供了 Kubernetes 资源的更全面的 (无损) 表示。

OpenAPI V2

Kubernetes API 服务器通过 /openapi/v2 端点提供聚合的 OpenAPI v2 规范。您可以使用请求标头请求响应格式，如下所示

OpenAPI v2 查询的有效请求标头值
标头可能的值备注
Accept-Encodinggzip不提供此标头也可以接受
Acceptapplication/com.github.proto-openapi.spec.v2@v1.0+protobuf主要用于集群内部使用
application/json默认值
*提供 application/json

OpenAPI V3

特性状态： Kubernetes v1.27 [稳定](默认启用)

Kubernetes 支持将 API 的描述作为 OpenAPI v3 发布。

提供了一个发现端点 /openapi/v3，以查看所有组/版本列表。此端点仅返回 JSON。这些组/版本以以下格式提供

{
    "paths": {
        ...,
        "api/v1": {
            "serverRelativeURL": "/openapi/v3/api/v1?hash=CC0E9BFD992D8C59AEC98A1E2336F899E8318D3CF4C68944C3DEC640AF5AB52D864AC50DAA8D145B3494F75FA3CFF939FCBDDA431DAD3CA79738B297795818CF"
        },
        "apis/admissionregistration.k8s.io/v1": {
            "serverRelativeURL": "/openapi/v3/apis/admissionregistration.k8s.io/v1?hash=E19CC93A116982CE5422FC42B590A8AFAD92CDE9AE4D59B5CAAD568F083AD07946E6CB5817531680BCE6E215C16973CD39003B0425F3477CFD854E89A9DB6597"
        },
        ....
    }
}

相对 URL 指向不可变的 OpenAPI 描述，以便改善客户端缓存。API 服务器也为此目的设置了适当的 HTTP 缓存标头 (Expires 设置为未来 1 年，Cache-Control 设置为 immutable)。当使用过时的 URL 时，API 服务器会返回重定向到最新的 URL。

Kubernetes API 服务器在 /openapi/v3/apis/<group>/<version>?hash=<hash> 端点为每个 Kubernetes 组版本发布 OpenAPI v3 规范。

请参阅下表了解接受的请求标头。

OpenAPI v3 查询的有效请求标头值
标头可能的值备注
Accept-Encodinggzip不提供此标头也可以接受
Acceptapplication/com.github.proto-openapi.spec.v3@v1.0+protobuf主要用于集群内部使用
application/json默认值
*提供 application/json

提供了一个 Golang 实现来获取 OpenAPI V3，位于包 k8s.io/client-go/openapi3 中。

Kubernetes 1.35 发布 OpenAPI v2.0 和 v3.0；在不久的将来没有计划支持 3.1。

Protobuf 序列化

Kubernetes 实现了一种替代的基于 Protobuf 的序列化格式，主要用于集群内部通信。有关此格式的更多信息，请参阅 Kubernetes Protobuf 序列化 设计提案以及定义 API 对象的 Go 包中位于 Interface Definition Language (IDL) 文件。

持久性

Kubernetes 将对象的序列化状态存储到 etcd 中。

API 分组和版本控制

为了更容易地删除字段或重构资源表示形式，Kubernetes 支持多个 API 版本，每个版本位于不同的 API 路径下，例如 /api/v1 或 /apis/rbac.authorization.k8s.io/v1alpha1。

版本控制是在 API 级别完成的，而不是在资源或字段级别完成的，以确保 API 提供系统资源和行为的清晰、一致的视图，并能够控制对生命周期结束和/或实验性 API 的访问。

为了更容易地演进和扩展其 API，Kubernetes 实现了 API 分组，这些分组可以 启用或禁用。

API 资源通过其 API 分组、资源类型、命名空间（对于命名空间资源）和名称来区分。API 服务器透明地处理 API 版本之间的转换：所有不同的版本实际上都是相同持久化数据的表示。API 服务器可以通过多个 API 版本提供相同的底层数据。

例如，假设对于相同的资源，有两个 API 版本，v1 和 v1beta1。如果您最初使用其 API 的 v1beta1 版本创建了一个对象，则以后可以使用 v1beta1 或 v1 API 版本读取、更新或删除该对象，直到 v1beta1 版本被弃用并删除。 此时，您可以使用 v1 API 继续访问和修改该对象。

API 变更

任何成功的系统都需要随着新的用例出现或现有用例发生变化而发展和改变。 因此，Kubernetes 设计了 Kubernetes API 以持续改变和发展。 Kubernetes 项目旨在不破坏与现有客户端的兼容性，并保持这种兼容性一段时间，以便其他项目有机会进行调整。

通常，可以经常且频繁地添加新的 API 资源和新的资源字段。 删除资源或字段需要遵循 API 弃用策略。

Kubernetes 强烈致力于在官方 Kubernetes API 达到通用可用性 (GA) 后（通常在 API 版本 v1 时）保持兼容性。 此外，Kubernetes 保持与通过官方 Kubernetes API 的 beta API 版本持久化的数据的兼容性，并确保在功能稳定后可以通过 GA API 版本转换和访问该数据。

如果您采用 beta API 版本，则需要在 API 毕业后过渡到后续的 beta 或稳定 API 版本。 在 beta API 处于弃用期间执行此操作是最佳时机，因为对象可以同时通过两个 API 版本访问。 一旦 beta API 完成其弃用期并且不再提供服务，就必须使用替换 API 版本。

有关 API 版本级别定义的更多详细信息，请参阅 API 版本参考。

API 扩展

Kubernetes API 可以通过以下两种方式之一进行扩展

  1. 自定义资源 允许您声明性地定义 API 服务器应该如何提供您选择的资源 API。
  2. 您还可以通过实现 聚合层 来扩展 Kubernetes API。

接下来

最后修改时间为 2025 年 1 月 8 日上午 10:50 PST：修复功能门名称冲突 (2/2) (3782732ce4)