本文發表於一年多前。舊文章可能包含過時內容。請檢查頁面中的資訊自發布以來是否已變得不正確。
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 獲取最新更新