本文已超过一年。较旧的文章可能包含过时的内容。请检查页面中的信息自发布以来是否已变得不正确。

Kubernetes 支持 OpenAPI

作者：Mehdy Bohlool (Google) |

编者注：这篇文章是关于 Kubernetes 1.5 中新功能的深度文章系列的一部分

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

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

新的规范使我们能够拥有更好的 API 文档，并且我们甚至引入了受支持的 python 客户端。

该规范是模块化的，按 GroupVersion 划分：这是面向未来的，因为我们打算允许不同的 GroupVersion 从不同的 API 服务器提供服务。

该规范的结构在 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 的信息。客户端库生成器还将使用此信息来创建用于读取 pod 信息的 API 函数调用。例如，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。此文件将包含所有已启用的 GroupVersions 路由和模型，并且将是具有特定 kube-apiserver 的最新文件。
  • 来自 Kubernetes GitHub 存储库，其中启用了所有核心 GroupVersions。您可以在 master 或特定版本（例如 1.5 版本）上访问它。

有许多与此规范一起使用的工具。例如，您可以使用 swagger 编辑器 打开规范文件并呈现文档以及生成客户端；或者您可以直接使用 swagger codegen 生成文档和客户端。此生成的客户端将主要开箱即用，但您将需要对授权和一些 Kubernetes 特定实用程序提供一些支持。使用 python 客户端 作为创建您自己的客户端的模板。

如果您想参与 OpenAPI 支持、客户端库的开发或报告错误，您可以在 SIG-API-Machinery 与开发人员联系。