如何理解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接口，小編相信有部分知識點可能是我們日常工作會見到或用到的。希望你能通過這篇文章學到更多知識。更多詳情敬請關注億速云行業資訊頻道。