如何理解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的性能问题。

为什么要将接口归一

前面展示了Kubernetes 1.13版本中OpenAPI相关的接口，从中可以明显地感觉到杂乱无章，它方便人类阅读，但对程序非常不友好，比如程序无法查询Kubernetes支持的OpenAPI规范的版本列表。

正是出于此原因，Kubernetes将所有OpenAPI相关的接口全部整合到/openapi接口中，完整的接口设计如下所示：

• /openapi：用于查询支持的OpenAPI规范版本列表，比如v2、v3等。

• /openapi/v2：对应OpenAPI v2

• /openapi/v3：对应OpenAPI v3

接口中不再体现文档的格式，而是由客户端在HTTP请求头部通过Accept字段指定。

这样的接口设计不仅清晰，也有很好的扩展性，可以轻松支持多个版本的OpenAPI规范。

截止到v1.18.0，虽然Kubernetes仅实现了/openapi/v2接口，但它清晰地指出了未来的演进方向。

以上就是如何理解Kubernetes OpenAPI接口，小编相信有部分知识点可能是我们日常工作会见到或用到的。希望你能通过这篇文章学到更多知识。更多详情敬请关注亿速云行业资讯频道。