Kubernetes 支援 OpenAPI 的新功能

Open API 讓 API 提供者可以定義自己的操作和模型，並讓開發者可以自動化的生成喜歡語言的客戶端，用以和 API 伺服器通訊。Kubernetes 已經支援 Swagger 1.2（OpenAPI 規範的前身）有一段時間了，但是這一標準不夠完整和有效，憑藉這一支援，非常難生成工具或客戶端。

在 Kubernetes 1.4，我們對目前的模型和操作進行了升級，引入了 Open API 規範（在沒被捐獻給 Open API 之前被稱作 Swagger 2.0）支援的 Alpha 版本。從 Kubernetes 1.5 開始，OpenAPI 規範的支援已經完備，能夠直接從 Kubernetes 原始碼生成規範，對於模型和方法的任何變更，都會保障文件和規範的完全同步。

新規範讓我們有了更好的 API 文件，甚至還有了一個 Python 客戶端。

這一模組化的規範用 GroupVersion 進行分隔，這一做法屬於未雨綢繆，我們想要讓不同的 API Server 使用不同的 GroupVersion。

規範的結構在 Open API spec definition 中有解釋。我們用 operation 標記 來拆分每個 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，就可以據此來呼叫介面了（/api/v1/namespaces/{namespace}/pods/{name}），引數包括 name、exact 以及 export 等，呼叫結果會返回 Pod 資訊。客戶庫生成器也會使用這些資訊來建立一個 API 函式呼叫來讀取 Pod 資訊。例如 Python 客戶端 能夠很簡單的進行如下呼叫：

from kubernetes import client
 ret = client.CoreV1Api().read_namespaced_pod(name="pods_name", namespace="default")
 

一個簡化版的 read_namespaced_pod;Python Client：https://github.com/kubernetes-incubator/client-python還可以使用 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

從 kube-apiserver/swagger.json。這個檔案會包含所有啟用的 GroupVersion 方法和模型，其中的內容會是該 API Server 所對應的最新版本。

Kubernetes 的 Github 倉庫，可以訪問 master 或者其他指定的 Release。

有很多工具 能和這些 API 協同工作，例如可以用 swagger editor 來開啟規範檔案並渲染文件，或者生成客戶端；還可以直接利用 swagger codegen 來生成文件和客戶端。自動生成的客戶端多數時候是開箱即用的。不過可能需要做一些登入和 Kubernetes 相關的設定。