如何理解Kubernetes OpenAPI接口

本篇文章給大家分享的是有關(guān)如何理解Kubernetes OpenAPI接口，小編覺得挺實用的，因此分享給大家學(xué)習(xí)，希望大家閱讀完這篇文章后可以有所收獲，話不多說，跟著小編一起來看看吧。

Kubernetes會根據(jù)代碼自動生成符合OpenAPI規(guī)范的接口文檔。

查詢OpenAPI文檔

kube-apiserver提供了/openapi/v2接口用于查詢API文檔，通過接口名稱可以看出該文檔符合OpenAPI 2.0規(guī)范。如下所示：

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

該接口會返回完整的API文檔，限于篇幅只展示少量輸出內(nèi)容。

該接口默認(rèn)返回JSON格式文件。除了支持JSON格式外，還支持protocol buffer格式，客戶端可以在HTTP頭部的Accept字段來指定需求的格式。 Accept字段值application/json和application/com.github.proto-openapi.spec.v2@v1.0+protobuf分別對應(yīng)兩種文件格式。

接口演進(jìn)

Kubernetes早在 1.10版本就已經(jīng)支持了/openapi/v2接口，在1.14版本之前，Kubernetes還提供了其他接口來提供多個規(guī)范版本以及多種格式的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規(guī)范）；

• /swagger-2.0.0.pb-v1：以protocol buffer格式返回API文檔（Swagger 2.0規(guī)范）；

• /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接口中。

設(shè)計思考

在介紹完前面這些接口后，請讀者先自行思考下面的問題，再向下閱讀：

• 為什么要支持protocol buffer格式？

• 為什么要將眾多的接口歸一到/openapi/v2接口？

為什么支持protocol buffer

使用OpenAPI規(guī)范描述API有一個好處是方便程序處理，程序可以根據(jù)API文檔校驗請求信息。

比如kubectl就會根據(jù)OpenAPI 文檔來校驗每個請求，在Kubernetes早期版本中，kube-apiserver還未支持eTag，所以kubectl向kube-apiserver發(fā)起請求時必須每次都從kube-apiserver獲取一份完整的API文檔。當(dāng)時Kubernetes的API文檔已經(jīng)增長到1.5MB大小，kubectl每次下載這個文檔都會消耗較多的時間，嚴(yán)重影響了kubectl的性能和使用體驗。

為了提升kubectl的性能和使用體驗，可以讓作為HTTP服務(wù)端的kube-apiserver支持eTag，這樣作為HTTP客戶端的kubectl可以將API文檔緩存在本地。但kube-apiserver支持eTag工作量巨大，短期內(nèi)不太容易實現(xiàn)，因為需要同時修改幾乎所有的API。

另一種解決辦法是減小API文檔的體積。protocol buffer作為一種數(shù)據(jù)交換格式，它比JSON格式傳輸效率更高。根據(jù)當(dāng)時的測試記錄，使用protocol buffer格式可以讓API文檔體積下降44%，文檔下載時間也自然會下降，另外，由于protocol buffer的反序列化性能也要優(yōu)于JSON，所以通過使用protocol buffer格式的接口文檔，kubectl不僅減少了文檔下載時間，也提高了反序列化時間。

根據(jù)OpenAPI規(guī)范，JSON格式的接口描述文件是首選， Kubernetes之所以支持protocol buffer格式的接口文檔，其主要驅(qū)動力正是為了解決kubectl的性能問題。

為什么要將接口歸一

前面展示了Kubernetes 1.13版本中OpenAPI相關(guān)的接口，從中可以明顯地感覺到雜亂無章，它方便人類閱讀，但對程序非常不友好，比如程序無法查詢Kubernetes支持的OpenAPI規(guī)范的版本列表。

正是出于此原因，Kubernetes將所有OpenAPI相關(guān)的接口全部整合到/openapi接口中，完整的接口設(shè)計如下所示：

• /openapi：用于查詢支持的OpenAPI規(guī)范版本列表，比如v2、v3等。

• /openapi/v2：對應(yīng)OpenAPI v2

• /openapi/v3：對應(yīng)OpenAPI v3

接口中不再體現(xiàn)文檔的格式，而是由客戶端在HTTP請求頭部通過Accept字段指定。

這樣的接口設(shè)計不僅清晰，也有很好的擴(kuò)展性，可以輕松支持多個版本的OpenAPI規(guī)范。

截止到v1.18.0，雖然Kubernetes僅實現(xiàn)了/openapi/v2接口，但它清晰地指出了未來的演進(jìn)方向。

以上就是如何理解Kubernetes OpenAPI接口，小編相信有部分知識點可能是我們?nèi)粘９ぷ鲿姷交蛴玫降?。希望你能通過這篇文章學(xué)到更多知識。更多詳情敬請關(guān)注億速云行業(yè)資訊頻道。