导航：首页 > 服务器 >

如何理解Kubernetes OpenAPI接口

发表于：2026-11-01 作者：千家信息网编辑

千家信息网最后更新 2026年11月01日，本篇文章给大家分享的是有关如何理解Kubernetes OpenAPI接口，小编觉得挺实用的，因此分享给大家学习，希望大家阅读完这篇文章后可以有所收获，话不多说，跟着小编一起来看看吧。Kubernet

千家信息网最后更新 2026年11月01日如何理解Kubernetes OpenAPI接口

本篇文章给大家分享的是有关如何理解Kubernetes OpenAPI接口，小编觉得挺实用的，因此分享给大家学习，希望大家阅读完这篇文章后可以有所收获，话不多说，跟着小编一起来看看吧。

Kubernetes会根据代码自动生成符合OpenAPI规范的接口文档。

查询OpenAPI文档

kube-apiserver提供了/openapi/v2接口用于查询API文档，通过接口名称可以看出该文档符合OpenAPI 2.0规范。如下所示：

[root@ecs-d8b6 kubernetes]# curl localhost:8080/openapi/v2{"swagger":"2.0","info":{"title":"Kubernetes","version":"v1.19.0"},...}

该接口会返回完整的API文档，限于篇幅只展示少量输出内容。

该接口默认返回JSON格式文件。除了支持JSON格式外，还支持protocol buffer格式，客户端可以在HTTP头部的Accept字段来指定需求的格式。 Accept字段值application/json和application/com.github.proto-openapi.spec.v2@v1.0+protobuf分别对应两种文件格式。

接口演进

Kubernetes早在 1.10版本就已经支持了/openapi/v2接口，在1.14版本之前，Kubernetes还提供了其他接口来提供多个规范版本以及多种格式的API文档。

例如，在Kubernetes 1.13版本中查询kube-apiserver的接口，如下所示：

[root@ecs-d8b6 kubernetes]# curl localhost:8080/{  "paths": [    "/api",    "/api/v1",    "/apis",    "/apis/",   ...    "/openapi/v2",    "/swagger-2.0.0.json",    "/swagger-2.0.0.pb-v1",    "/swagger-2.0.0.pb-v1.gz",    "/swagger.json",    "/swaggerapi",    ...  ]}

/swagger-2.0.0.json：以JSON格式返回API文档（Swagger 2.0规范）；
/swagger-2.0.0.pb-v1：以protocol buffer格式返回API文档（Swagger 2.0规范）；
/swagger-2.0.0.pb-v1.gz：同/swagger-2.0.0.pb-v1，但是返回压缩后的API文档；
/swagger.json：同/swagger-2.0.0.json；
/swaggerapi：以JSON格式返回API文档（Swagger v1.2）。

Kubernetes在1.14版本中将这些接口全部归一到了/openapi/v2接口中。

设计思考

在介绍完前面这些接口后，请读者先自行思考下面的问题，再向下阅读：

为什么要支持protocol buffer格式？
为什么要将众多的接口归一到/openapi/v2接口？

为什么支持protocol buffer

使用OpenAPI规范描述API有一个好处是方便程序处理，程序可以根据API文档校验请求信息。

比如kubectl就会根据OpenAPI 文档来校验每个请求，在Kubernetes早期版本中，kube-apiserver还未支持eTag，所以kubectl向kube-apiserver发起请求时必须每次都从kube-apiserver获取一份完整的API文档。当时Kubernetes的API文档已经增长到1.5MB大小，kubectl每次下载这个文档都会消耗较多的时间，严重影响了kubectl的性能和使用体验。

为了提升kubectl的性能和使用体验，可以让作为HTTP服务端的kube-apiserver支持eTag，这样作为HTTP客户端的kubectl可以将API文档缓存在本地。但kube-apiserver支持eTag工作量巨大，短期内不太容易实现，因为需要同时修改几乎所有的API。

另一种解决办法是减小API文档的体积。protocol buffer作为一种数据交换格式，它比JSON格式传输效率更高。根据当时的测试记录，使用protocol buffer格式可以让API文档体积下降44%，文档下载时间也自然会下降，另外，由于protocol buffer的反序列化性能也要优于JSON，所以通过使用protocol buffer格式的接口文档，kubectl不仅减少了文档下载时间，也提高了反序列化时间。

根据OpenAPI规范，JSON格式的接口描述文件是首选， Kubernetes之所以支持protocol buffer格式的接口文档，其主要驱动力正是为了解决kubectl的性能问题。