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")
 https://gist.github.com/mbohlool/d5ec1dace27ef90cf742555c05480146

一個簡化版的 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

有兩種方式訪問 OpenAPI ：

• 從 kube-apiserver/swagger.json。這個文件會包含全部啓用的 GroupVersion 方法和模型，其中的內容會是該 API Server 所對應的最新版本。
• Kubernetes 的 Github 倉庫，能夠訪問 master 或者其餘指定的 Release。

有不少工具 能和這些 API 協同工做，例如能夠用 swagger editor 來打開規範文件並渲染文檔，或者生成客戶端；還能夠直接利用 swagger codegen 來生成文檔和客戶端。自動生成的客戶端多數時候是開箱即用的。不過可能須要作一些登陸和 Kubernetes 相關的設置。可使用 Python 客戶端 做爲模板來開發本身的客戶端

 

https://kubernetes.io/docs/concepts/overview/kubernetes-api/