Kubernetes API

最新推荐文章于 2025-03-21 13:29:59 发布

qichengzong_right

最新推荐文章于 2025-03-21 13:29:59 发布

阅读量1k

点赞数 16

CC 4.0 BY-SA版权

分类专栏：云原生 kubernetes linux 文章标签：云原生 kubernetes linux

本文链接：https://blog.csdn.net/qichengzong_right/article/details/144772598

linux 同时被 3 个专栏收录

81 篇文章

订阅专栏

云原生

46 篇文章

订阅专栏

kubernetes

36 篇文章

订阅专栏

The Kubernetes API

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

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

Kubernetes API 允许查询和操作 Kubernetes 中 API 对象的状态（例如：Pod、命名空间、ConfigMap 和事件）。

大多数操作可以通过 kubectl 命令行界面或其他命令行工具（如 kubeadm）执行，这些工具进一步调用 API。同样，也可以使用 REST 调用直接访问 API。Kubernetes 为那些希望使用 Kubernetes API 编写应用程序的人提供了一组客户端库。

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

发现 API 提供描述 Kubernetes API 的信息：API 名称、资源、版本和支持的操作。这是一个特定于 Kubernetes 的术语，因为它是独立于 Kubernetes OpenAPI 的 API。其目的是为可用资源提供简要总结，它没有详细说明资源的特定模式。有关资源模式的参考，请参考 OpenAPI 文档。
Kubernetes OpenAPI 文档为所有 Kubernetes API 端点提供（完整的）OpenAPI v2.0 和 3.0 模式。OpenAPI v3 是访问 OpenAPI 的首选方法，因为它提供了更全面、更准确的 API 视图。它包括所有可用的 API 路径，以及每个端点上的每个操作消耗和生成的所有资源。它还包括集群支持的任何可扩展性组件。该数据是一个完整的规范，并且明显大于 Discovery API 中的数据。

Discovery API【需要再次整理】

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

Name 名字
Cluster or namespaced scope 集群或命名空间作用域
Endpoint URL and supported verbs 端点 URL 和所支持的动词
Alternative names 别名
Group, version, kind 组、版本、类别

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

聚合发现

特性状态：Kubernetes v1.30 [stable] （默认启用：true）

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 v3 是访问 OpenAPI 的首选方法，因为它提供了对 Kubernetes 资源更全面（无损）的表示。由于 OpenAPIversion 2 的限制，某些字段已从发布的 OpenAPI 中弃用，包括但不限于 default，nullable，oneOf。

OpenAPI V2

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

Header	允许的值	说明
Accept-Encoding	gzip	不提供此头部也是可以接受的
Accept	application/com.github.proto-openapi.spec.v2@v1.0+protobuf	主要用于集群内部
Accept	application/json	默认值
Accept	*	提供application/json

OpenAPI V3

特性状态：Kubernetes v1.27 [stable]（默认启用：是）

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规范。

有关接受的请求标头，请参阅下表。

Header	允许的值	说明
Accept-Encoding	gzip	不提供此头部也是可以接受的
Accept	application/com.github.proto-openapi.spec.v3@v1.0+protobuf	主要用于集群内部
Accept	application/json	默认值
Accept	*	提供 application/json

在包 k8s.io/client-go/openapi3 中提供了获取 OpenAPI V3 的 Golang 实现。

Kubernetes 1.32 发布 OpenAPI v2.0和v3.0；近期并没有支持3.1的计划。

protobuf 序列化

Kubernetes 为 API 实现了一种基于 Protobuf 的序列化格式，主要用于集群内通信。有关此格式的更多信息，请参阅 Kubernetes 协议序列化设计方案。每个模式的接口定义语言（IDL）文件位于定义 API 对象的 Go 包中。

持久化

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。如果最初使用 v1beta1 版本的 API 创建了一个对象，则可以稍后使用 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 版本。