本文发表于一年多前。旧文章可能包含过时内容。请检查页面中的信息自发布以来是否已变得不正确。
Kubernetes 支持 OpenAPI
编者按:这篇博文是关于 Kubernetes 1.5 新功能系列深度文章的一部分。
OpenAPI 允许 API 提供商定义其操作和模型,并使开发人员能够自动化其工具并生成其偏好语言的客户端来与该 API 服务器通信。Kubernetes 已经支持 swagger 1.2(OpenAPI 规范的旧版本)一段时间,但该规范不完整且无效,导致难以基于它生成工具/客户端。
在 Kubernetes 1.4 中,我们通过升级当前模型和操作,引入了对 OpenAPI 规范(以前称为 swagger 2.0,在捐赠给 Open API Initiative 之前)的 Alpha 支持。从 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 仓库,所有核心 GroupVersion 均已启用。您可以在master或特定版本(例如1.5 版本)上访问它。
有许多与此规范兼容的工具。例如,您可以使用Swagger 编辑器打开规范文件并渲染文档,以及生成客户端;或者您可以直接使用Swagger Codegen生成文档和客户端。它生成的客户端大部分都可以直接使用——但您需要一些授权支持和一些 Kubernetes 特定的实用程序。使用Python 客户端作为模板来创建您自己的客户端。
如果您想参与 OpenAPI 支持、客户端库的开发或报告错误,可以通过 SIG-API-Machinery 联系开发人员。
- 下载 Kubernetes
- 在 GitHub 上参与 Kubernetes 项目
- 在 Stack Overflow 上提问(或回答问题)
- 在 Slack 上与社区联系
- 在 Twitter 上关注我们 @Kubernetesio 获取最新更新