You are viewing documentation for Kubernetes version: v1.23
Kubernetes v1.23 documentation is no longer actively maintained. The version you are currently viewing is a static snapshot. For up-to-date documentation, see the latest version.
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.23 [alpha]
Kubernetes v1.23 提供将其 API 以 OpenAPI v3 形式发布的初始支持；这一功能特性处于 Alpha
状态，默认被禁用。
你可以通过为 kube-apiserver 组件启用 OpenAPIV3
特性门控来启用此
Alpha 特性。
特性被启用时，Kubernetes API 服务器会在端点 /openapi/v3/apis/<group>/<version>
提供按 Kubernetes 组版本聚合的 OpenAPI v3 规范。
请参阅下表了解可接受的请求头部。
| 头部 | 可选值 | 说明 |
|---|---|---|
Accept-Encoding |
gzip |
不提供此头部也是可接受的 |
Accept |
application/com.github.proto-openapi.spec.v3@v1.0+protobuf |
主要用于集群内部使用 |
application/json |
默认 | |
* |
以 application/json 形式返回 |
发现端点 /openapi/v3 被提供用来查看可用的所有组、版本列表。
此列表仅返回 JSON。
API 变更
任何成功的系统都要随着新的使用案例的出现和现有案例的变化来成长和变化。 为此，Kubernetes 的功能特性设计考虑了让 Kubernetes API 能够持续变更和成长的因素。 Kubernetes 项目的目标是 不要 引发现有客户端的兼容性问题，并在一定的时期内 维持这种兼容性，以便其他项目有机会作出适应性变更。
一般而言，新的 API 资源和新的资源字段可以被频繁地添加进来。 删除资源或者字段则要遵从 API 废弃策略。
Kubernetes 对维护达到正式发布（GA）阶段的官方 API 的兼容性有着很强的承诺，
通常这一 API 版本为 v1。此外，Kubernetes 在可能的时候还会保持 Beta API
版本的兼容性：如果你采用了 Beta API，你可以继续在集群上使用该 API，
即使该功能特性已进入稳定期也是如此。
尽管 Kubernetes 也努力为 Alpha API 版本维护兼容性，在有些场合兼容性是无法做到的。 如果你使用了任何 Alpha API 版本，需要在升级集群时查看 Kubernetes 发布说明， 以防 API 的确发生变更。
关于 API 版本分级的定义细节，请参阅 API 版本参考页面。
API 扩展
有两种途径来扩展 Kubernetes API：
What's next
- 了解如何通过添加你自己的 CustomResourceDefinition 来扩展 Kubernetes API。
- 控制 Kubernetes API 访问页面描述了集群如何针对 API 访问管理身份认证和鉴权。
- 通过阅读 API 参考了解 API 端点、资源类型以及示例。
- 阅读 API 变更（英文） 以了解什么是兼容性的变更以及如何变更 API。