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/