Kubernetes 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 路径，以及每个端点上每个操作所消耗和生成的所有资源。它还包括集群支持的任何可扩展性组件。数据是一个完整的规范，比发现 API 中的数据大得多。
发现 API（发现 API）
Kubernetes 通过发现 API 发布受支持的所有组版本和资源的列表。这包括每个资源的以下内容：
- 名称（名称）
- 集群或命名空间范围（集群或命名空间范围）
- 端点 URL 和支持的动词（端点 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 规范的详细信息，请参阅 OpenAPI 文档。
Kubernetes 支持 OpenAPI v2.0 和 OpenAPI v3.0。OpenAPI v3 是访问 OpenAPI 的首选方法，因为它提供了更全面（无损）的 Kubernetes 资源表示。由于 OpenAPI 版本 2 的限制，某些字段从发布的 OpenAPI 中删除，包括但不限于 default、nullable、oneOf。
OpenAPI V2（OpenAPI V2）
Kubernetes API 服务器通过 /openapi/v2 端点提供聚合的 OpenAPI v2 规范。您可以使用请求标头请求响应格式，如下所示：
| 标头（标头） | 可能的值（可能的值） | 备注（备注） |
|---|---|---|
Accept-Encoding（Accept-Encoding） | gzip（gzip） | 不提供此标头也是可以接受的（不提供此标头也是可以接受的） |
Accept（Accept） | application/com.github.proto-openapi.spec.v2@v1.0+protobuf（application/com.github.proto-openapi.spec.v2@v1.0+protobuf） | 主要用于集群内使用（主要用于集群内使用） |
application/json（application/json） | 默认（默认） | |
* | 提供 application/json（提供 application/json） |
OpenAPI V3（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 规范。
有关可接受的请求标头，请参阅下表。
| 标头（标头） | 可能的值（可能的值） | 备注（备注） |
|---|---|---|
Accept-Encoding（Accept-Encoding） | gzip（gzip） | 不提供此标头也是可以接受的（不提供此标头也是可以接受的） |
Accept（Accept） | application/com.github.proto-openapi.spec.v3@v1.0+protobuf（application/com.github.proto-openapi.spec.v3@v1.0+protobuf） | 主要用于集群内使用（主要用于集群内使用） |
application/json（application/json） | 默认（默认） | |
* | 提供 application/json（提供 application/json） |
在包 k8s.io/client-go/openapi3 中提供了一个用于获取 OpenAPI V3 的 Golang 实现。
Kubernetes 1.30 发布了 OpenAPI v2.0 和 v3.0；近期内没有支持 3.1 的计划。
Protobuf 序列化（Protobuf 序列化）
Kubernetes 实现了一种基于 Protobuf 的替代序列化格式，主要用于集群内通信。有关此格式的更多信息，请参阅 Kubernetes Protobuf 序列化 设计提案以及位于定义 API 对象的 Go 包中的每个架构的接口定义语言 (IDL) 文件。
持久性（持久性）
Kubernetes 通过将对象的序列化状态写入 etcd 来存储它们。
API 组和版本控制（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 的测试版 API 版本持久化的数据的兼容性，并确保在功能稳定后可以通过 GA API 版本转换和访问数据。
如果您采用测试版 API 版本，则在 API 升级后，您需要过渡到后续的测试版或稳定版 API 版本。执行此操作的最佳时间是在测试版 API 处于弃用期内，因为可以通过两个 API 版本同时访问对象。一旦测试版 API 完成其弃用期并且不再提供服务，则必须使用替换 API 版本。
注意
尽管 Kubernetes 也致力于维护Alpha API 版本的兼容性，但在某些情况下这是不可能的。如果您使用任何 Alpha API 版本，请在升级集群时查看 Kubernetes 的发行说明，以防 API 以不兼容的方式发生变化，需要在升级之前删除所有现有的 Alpha 对象。有关 API 版本级别定义的更多详细信息，请参阅API 版本参考。
API 扩展
可以通过以下两种方式之一扩展 Kubernetes API
下一步
- 了解如何通过添加您自己的CustomResourceDefinition来扩展 Kubernetes API。
- 控制对 Kubernetes API 的访问描述了集群如何管理 API 访问的身份验证和授权。
- 通过阅读API 参考，了解 API 端点、资源类型和示例。
- 从API 更改中了解构成兼容更改的内容，以及如何更改 API。