Kubernetes支持OpenAPI

编者注：这篇文章是 系列深入文章 Kubernetes 1.5的新功能

OpenAPI的 允许API提供者定义其操作和模型，并使开发人员能够自动化其工具并生成其喜欢的语言的客户端以与该API服务器进行对话。 Kubernetes一段时间以来一直支持swagger 1.2（OpenAPI规范的旧版本），但该规范不完整且无效，这使得很难基于该规范生成工具/客户端。

在Kubernetes 1.4中，我们引入了对OpenAPI规范的alpha支持（在捐赠给OpenAPI规范之前，以前称为swagger 2.0）。 开放API倡议），以升级当前的模型和操作。开始于 Kubernetes 1.5，通过直接从Kubernetes源自动生成规范来完成对OpenAPI规范的支持，这将使规范和文档完全与将来的操作/模型更改保持同步。

新规范使我们能够拥有更好的API文档，甚至引入了 python客户端.

规范是模块化的，由GroupVersion划分：这是面向未来的，因为我们打算允许从单独的API服务器中提供单独的GroupVersions。

规范的结构在以下详细说明 OpenAPI的规范定义。我们用了 操作的标签 分隔每个GroupVersion，并填充尽可能多的有关路径/操作和模型的信息。对于特定操作，所有参数，调用方法和响应都应记录在案。

例如，用于读取容器信息的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"  
      }  
     }  
    },

…

}

…

Using this information and the URL of kube-apiserver, one should be able to make the call to the given url (/api/v1/namespaces/{namespace}/pods/{name}) with parameters such as name, exact, export, etc. to get pod’s information. Client libraries generators would also use this information to create an API function call for reading pod’s information. For example, 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规范的方法：

  • From kuber-apiserver/swagger.json. This file will have all enabled GroupVersions routes and models and would be most up-to-date file with an specific kube-apiserver.
  • 从启用了所有核心GroupVersions的Kubernetes 的GitHub存储库中。您可以访问 主 或特定版本（例如 1.5发布）。

有很多 工具 符合此规范。例如，您可以使用 昂首阔步的编辑器 打开规范文件并渲染文档，以及生成客户端；或者你可以直接使用 昂首阔步的代码 生成文档和客户。这个生成的客户端几乎可以直接使用-但是您将需要一些授权支持和一些Kubernetes特定的实用程序。采用 python客户端 作为创建自己的客户端的模板。

如果您想参与OpenAPI支持的开发，客户端库或报告错误，可以与开发人员联系，网址为： SIG-API机械.

-Mehdy Bohlool，Google软件工程师