本文已超過一年。較舊的文章可能包含過時的內容。請檢查頁面中的資訊自發布以來是否已變得不正確。

Kubernetes 支援 OpenAPI

作者：Mehdy Bohlool (Google) |

編者註： 這篇文章是 Kubernetes 1.5 新功能深入文章系列 的一部分

OpenAPI 允許 API 提供者定義其操作和模型，並使開發人員能夠自動化其工具並產生他們最喜歡的語言用戶端，以與該 API 伺服器對話。Kubernetes 一直以來都支援 swagger 1.2（較舊版本的 OpenAPI 規範），但該規範不完整且無效，因此難以根據其產生工具/用戶端。

在 Kubernetes 1.4 中，我們透過升級目前的模型和操作，引入了對 OpenAPI 規範（在捐贈給 Open API Initiative 之前稱為 swagger 2.0）的 alpha 支援。從 Kubernetes 1.5 開始，對 OpenAPI 規範的支援已完成，方法是直接從 Kubernetes 原始碼自動產生規範，這將使規範和文件與未來操作/模型的變更完全同步。

新的規範使我們能夠擁有更好的 API 文件，甚至還引入了受支援的 python 用戶端。

該規範是模組化的，按 GroupVersion 劃分：這是面向未來的，因為我們打算允許從單獨的 API 伺服器提供單獨的 GroupVersion。

規範的結構在 OpenAPI 規範定義 中詳細說明。我們使用 操作的標籤 來分隔每個 GroupVersion，並盡可能填寫有關路徑/操作和模型的資訊。對於特定操作，所有參數、呼叫方法和回應都已記錄在案。

例如，用於讀取 Pod 資訊的 OpenAPI 規範為

{

...  
  "paths": {

"/api/v1/namespaces/{namespace}/pods/{name}": {  
    "get": {  
     "description": "read the specified Pod",  
     "consumes": [  
      "\*/\*"  
     ],  
     "produces": [  
      "application/json",  
      "application/yaml",  
      "application/vnd.kubernetes.protobuf"  
     ],  
     "schemes": [  
      "https"  
     ],  
     "tags": [  
      "core\_v1"  
     ],  
     "operationId": "readCoreV1NamespacedPod",  
     "parameters": [  
      {  
       "uniqueItems": true,  
       "type": "boolean",  
       "description": "Should the export be exact.  Exact export maintains cluster-specific fields like 'Namespace'.",  
       "name": "exact",  
       "in": "query"  
      },  
      {  
       "uniqueItems": true,  
       "type": "boolean",  
       "description": "Should this value be exported.  Export strips fields that a user can not specify.",  
       "name": "export",  
       "in": "query"  
      }  
     ],  
     "responses": {  
      "200": {  
       "description": "OK",  
       "schema": {  
        "$ref": "#/definitions/v1.Pod"  
       }  
      },  
      "401": {  
       "description": "Unauthorized"  
      }  
     }  
    },

…

}

…

使用此資訊和 kube-apiserver 的 URL，應該能夠使用諸如 name、exact、export 等參數呼叫給定的 URL (/api/v1/namespaces/{namespace}/pods/{name})，以取得 Pod 的資訊。用戶端程式庫產生器也會使用此資訊來建立 API 函數呼叫，以讀取 Pod 的資訊。例如，python 用戶端 使呼叫此操作變得容易，如下所示

from kubernetes import client

ret = client.CoreV1Api().read\_namespaced\_pod(name="pods\_name", namespace="default")

可以在 這裡 找到簡化版本的產生的 read_namespaced_pod。

Swagger-codegen 文件產生器也將能夠使用相同的資訊建立文件

GET /api/v1/namespaces/{namespace}/pods/{name}

(readCoreV1NamespacedPod)

read the specified Pod

Path parameters

name (required)

Path Parameter — name of the Pod

namespace (required)

Path Parameter — object name and auth scope, such as for teams and projects

Consumes

This API call consumes the following media types via the Content-Type request header:

-
\*/\*


Query parameters

pretty (optional)

Query Parameter — If 'true', then the output is pretty printed.

exact (optional)

Query Parameter — Should the export be exact. Exact export maintains cluster-specific fields like 'Namespace'.

export (optional)

Query Parameter — Should this value be exported. Export strips fields that a user can not specify.

Return type

v1.Pod


Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.

-
application/json
-
application/yaml
-
application/vnd.kubernetes.protobuf

Responses

200

OK v1.Pod

401

Unauthorized

有兩種方法可以存取 OpenAPI 規範

  • 從 kuber-apiserver/swagger.json。此檔案將包含所有已啟用的 GroupVersion 路徑和模型，並且將是具有特定 kube-apiserver 的最新檔案。
  • 從 Kubernetes GitHub 儲存庫，其中啟用了所有核心 GroupVersion。您可以在 master 或特定版本（例如 1.5 版本）上存取它。

有許多與此規範搭配使用的 工具。例如，您可以使用 swagger 編輯器 開啟規範檔案並呈現文件，以及產生用戶端；或者您可以直接使用 swagger codegen 來產生文件和用戶端。此產生器產生的用戶端大多可以直接使用，但您將需要一些授權支援和一些 Kubernetes 特定公用程式。使用 python 用戶端 作為範本來建立您自己的用戶端。

如果您想參與 OpenAPI 支援、用戶端程式庫的開發，或回報錯誤，您可以透過 SIG-API-Machinery 與開發人員聯繫。