4-Overview-Kubernetes API

cucytoman發表於2019-09-23
ViewAPI

Overall API conventions are described in the API文件描述及約定規範 API conventions doc.

API endpoints, 資源型別和示例在api引用中進行了描述。

Remote access to the API is discussed in the api文件遠端訪問  Controlling API Access doc.

kubernetes api還充當系統宣告性配置模式的基礎。kubectl命令列工具可用於建立、更新、刪除和獲取api物件。

kubernetes還根據api資源儲存其序列化狀態（當前在etcd中）。
kubernetes本身被分解為多個元件，這些元件通過其api進行互動。

api-changes

根據我們的經驗，任何成功的系統都需要隨著新用例的出現或現有用例的改變而增長和改變。因此，我們期望kubernetes api不斷變化和增長。但是，我們打算在很長一段時間內不破壞與現有客戶機的相容性。通常，新的API資源和新的資源欄位可以被頻繁地新增。消除資源或欄位將需要遵循API棄用策略。
什麼構成相容的更改以及如何更改api由api更改文件詳細說明。

簡而言之api的規範
修改策略
API change document.
遺棄策略
API deprecation policy

openapi和swagger定義

OpenAPI詳細介紹.

Header Possible Values
Accept application/json, application/com.github.proto-openapi.spec.v2@v1.0+protobuf (the default content-type is application/json for */* or not passing this header)
Accept-Encoding gzip (not passing this header is acceptable)

在1.14之前，格式分離的端點（/swagger.json，/swagger-2.0.0.json，/swagger-2.0.0.pb-v1，/swagger-2.0.0.pb-v1.gz）以不同的格式提供openapi規範。這些端點已棄用，並在Kubernetes 1.14中刪除。
獲取openapi規範的示例：

Before 1.10 Starting with Kubernetes 1.10
GET /swagger.json GET /openapi/v2 Accept: application/json
GET /swagger-2.0.0.pb-v1 GET /openapi/v2 Accept: application/com.github.proto-openapi.spec.v2@v1.0+protobuf
GET /swagger-2.0.0.pb-v1.gz GET /openapi/v2 Accept: application/com.github.proto-openapi.spec.v2@v1.0+protobuf Accept-Encoding: gzip

kubernetes為api實現了另一種基於protobuf的序列化格式，該格式主要用於叢集內通訊，在設計方案中有記錄，每個模式的idl檔案位於定義api物件的go包中。
在1.14之前，Kubernetes apiserve還公開了一個API，可以用來檢索Swagger v1.2 Kubernetes API規範//swaggerapi。此方法已棄用，並將在Kubernetes 1.14中刪除。

API版本控制

為了更容易消除欄位或重新構造資源表示，kubernetes支援多個api版本，每個版本位於不同的api路徑，例如/api/v1 or /apis/extensions/v1beta1.

我們選擇在api級別而不是在資源或欄位級別進行版本轉換，以確保api呈現出系統資源和行為的清晰、一致的檢視，並允許控制對生命週期結束和/或實驗性api的訪問。json和protobuf序列化模式遵循相同的模式更改準則-下面的所有描述都涵蓋這兩種格式。

注意，api版本控制和軟體版本控制只是間接相關的。api和釋出版本控制建議描述了api版本控制和軟體版本控制之間的關係。
不同的api版本意味著不同的穩定性和支援級別。每個級別的標準在api更改文件中有更詳細的描述。總結如下：

Alpha level:

  • 版本名包含alpha (e.g. v1alpha1).
  • 可能有很多bug.啟用此功能可能會暴露錯誤. 預設是禁止
  • 對功能的支援隨時可能被放棄,恕不另行通知.
  • 在以後的軟體版本中，API可能會以不相容的方式更改，恕不另行通知.
  • 由於錯誤風險增加和缺乏長期支援，建議僅在短期測試叢集中使用.

Beta level:

  • 版本名包含beta (e.g. v2beta3).
  • 程式碼經過測試.啟用該功能被認為是安全的。預設情況下啟用
  • 對整體功能的支援不會被放棄，儘管細節可能會改變
  • 在隨後的beta版或穩定版中，物件的模式和/或語義可能會以不相容的方式發生變化。當這種情況發生時，我們將提供遷移到下一個版本的說明。這可能需要刪除、編輯和重新建立api物件。編輯過程可能需要一些思考。對於依賴於該功能的應用程式，這可能需要停機。
  • 建議僅用於非業務關鍵型用途，因為後續版本中可能會發生不相容的更改。如果你有多個可以獨立升級的叢集，你可以放鬆這個限制。
  • 請嘗試我們的測試版功能並給出反饋！一旦他們退出beta版，我們可能就不太現實了.

Stable level(穩定版):

  • 版本名為“vx”，其中“x”是整數。
  • 功能的穩定版本將出現在許多後續版本的釋出軟體中。

API groups

為了更容易擴充套件kubernetes api，我們實現了api組 API groups。api組在rest路徑和序列化物件的apiversion欄位中指定。
目前有幾個API組正在使用：

  • 核心組: is at the REST path /api/v1 and uses apiVersion: v1
  • api組位於REST path /apis/$GROUP_NAME/$VERSION, 資源定義使用apiVersion: $GROUP_NAME/$VERSION (e.g. apiVersion: batch/v1)所有的api組Kubernetes API reference

我們有兩種方式自定義API擴充套件:

  1. CustomResourceDefinition 給使用者提供基本的增刪改查而設計的
  2. 需要完整的Kubernetes API語義的使用者可以實現自己的ApServer，並使用 aggregator 來為客戶端無縫連線。

啟用api group

預設情況下會啟用某些資源和API組. 可以通過 --runtime-config 來設定在apiserver啟動時r. --runtime-config 接受逗號分隔的值. 例如: 禁用 batch/v1, 設定--runtime-config=batch/v1=false, 啟用 batch/v2alpha1, 設定 --runtime-config=batch/v2alpha1. 該引數接收以逗號分隔 key=value 在apiserver啟動時進行傳參

重要提示: 啟用或禁用組或資源需要重新啟動APIServer和控制器管理器以獲取--runtime配置更改。

DaemonSets, Deployments, HorizontalPodAutoscalers,Ingresses, Jobs and ReplicaSets 預設是啟用的,可以通過設定啟用其他擴充套件資源 --runtime-config, 在apiserver啟動前接收以逗號分隔方式進行傳參; 例如:要禁用 Deployments和Ingresses可以這樣傳參 --runtime-config=extensions/v1beta1/deployments=false,extensions/v1beta1/ingresses=false

本作品採用《CC 協議》，轉載必須註明作者和本文連結

相關文章