Kubernetes API

Kubernetes 控制面的核心是 API 服务器。 API 服务器负责提供 HTTP API，以供用户、集群中的不同部分和集群外部组件相互通信。

Kubernetes API 使你可以在 Kubernetes 中查询和操纵 API 对象（例如 Pod、Namespace、ConfigMap 和 Event）的状态。

大部分操作都可以通过 kubectl 命令行接口或类似 kubeadm 这类命令行工具来执行，这些工具在背后也是调用 API。不过，你也可以使用 REST 调用来访问这些 API。

如果你正在编写程序来访问 Kubernetes API，可以考虑使用客户端库之一。

OpenAPI 规范

完整的 API 细节是用 OpenAPI 来表述的。

OpenAPI v2

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

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

Kubernetes 为 API 实现了一种基于 Protobuf 的序列化格式，主要用于集群内部通信。关于此格式的详细信息，可参考 Kubernetes Protobuf 序列化设计提案。每种模式对应的接口描述语言（IDL）位于定义 API 对象的 Go 包中。

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

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

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

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

API 发现

集群支持的所有组版本列表被发布在 /api 和 /apis 端点。每个组版本还会通过 /apis/<group>/<version> （例如 /apis/rbac.authorization.k8s.io/v1alpha1）广播支持的资源列表。这些端点由 kubectl 用于获取集群支持的资源列表。

Kubernetes 对聚合发现提供 Beta 支持，通过两个端点（/api 和 /apis）发布集群支持的所有资源，而不是每个组版本都需要一个端点。请求此端点显著减少了获取平均 Kubernetes 集群发现而发送的请求数量。通过请求各自的端点并附带表明聚合发现资源 Accept: application/json;v=v2beta1;g=apidiscovery.k8s.io;as=APIGroupDiscoveryList 的 Accept 头部来进行访问。

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

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 版本提供相同的底层数据。

例如，假设针对相同的资源有两个 API 版本：v1 和 v1beta1。如果你最初使用其 API 的 v1beta1 版本创建了一个对象，你稍后可以使用 v1beta1 或 v1 API 版本来读取、更新或删除该对象，直到 v1beta1 版本被废弃和移除为止。此后，你可以使用 v1 API 继续访问和修改该对象。