Kubernetes API

Kubernetes API 可讓您查詢和操作 Kubernetes 中物件的狀態。Kubernetes 控制平面的核心是 API 伺服器及其公開的 HTTP API。使用者、叢集的不同部分和外部元件都透過 API 伺服器相互通訊。

Kubernetes 控制平面的核心是 API 伺服器。API 伺服器公開 HTTP API，可讓終端使用者、叢集的不同部分和外部元件相互通訊。

Kubernetes API 可讓您查詢和操作 Kubernetes 中 API 物件的狀態 (例如：Pod、命名空間、ConfigMap 和事件)。

大多數操作可以透過 kubectl 命令列介面或其他命令列工具 (例如 kubeadm，後者又使用 API) 執行。但是，您也可以使用 REST 呼叫直接存取 API。Kubernetes 為希望使用 Kubernetes API 編寫應用程式的人員提供了一組用戶端程式庫。

每個 Kubernetes 叢集都會發布叢集服務的 API 規格。Kubernetes 使用兩種機制來發布這些 API 規格；兩者都對於啟用自動互通性很有用。例如，kubectl 工具會提取並快取 API 規格，以啟用命令列完成和其他功能。支援的兩種機制如下

  • 探索 API 提供關於 Kubernetes API 的資訊：API 名稱、資源、版本和支援的操作。這是一個 Kubernetes 特有的術語，因為它是一個與 Kubernetes OpenAPI 分開的 API。它的目的是簡要概述可用的資源，並且不詳細說明資源的特定結構描述。有關資源結構描述的參考資訊，請參閱 OpenAPI 文件。

  • Kubernetes OpenAPI 文件為所有 Kubernetes API 端點提供（完整的）OpenAPI v2.0 和 3.0 結構描述。OpenAPI v3 是存取 OpenAPI 的首選方法，因為它提供了更全面和準確的 API 視圖。它包括所有可用的 API 路徑，以及每個端點上每個操作所消耗和產生的所有資源。它還包括叢集支援的任何擴充性元件。這些資料是一個完整的規範，並且比探索 API 的資料量大得多。

探索 API

Kubernetes 透過探索 API 發布所有群組版本和支援資源的列表。這包括每個資源的以下資訊

  • 名稱
  • 叢集或命名空間範圍
  • 端點 URL 和支援的動詞
  • 替代名稱
  • 群組、版本、種類

此 API 以聚合和非聚合形式提供。聚合探索服務兩個端點，而非聚合探索則為每個群組版本服務一個單獨的端點。

聚合探索

功能狀態： Kubernetes v1.30 [穩定] (預設啟用：true)

Kubernetes 為聚合探索提供穩定支援，透過兩個端點（/api 和 /apis）發布叢集支援的所有資源。請求此端點可大幅減少從叢集擷取探索資料的請求數量。您可以透過請求各自的端點，並使用 Accept 標頭指示聚合探索資源來存取資料：Accept: application/json;v=v2;g=apidiscovery.k8s.io;as=APIGroupDiscoveryList。

如果不使用 Accept 標頭指示資源類型，則 /api 和 /apis 端點的預設回應是非聚合探索文件。

內建資源的 探索文件可以在 Kubernetes GitHub 儲存庫中找到。如果 Kubernetes 叢集無法查詢，則可以使用此 Github 文件作為可用資源基本集合的參考。

此端點也支援 ETag 和 protobuf 編碼。

非聚合探索

在沒有探索聚合的情況下，探索是以層級發布的，根端點發布下游文件的探索資訊。

叢集支援的所有群組版本的列表發布在 /api 和 /apis 端點。範例

{
  "kind": "APIGroupList",
  "apiVersion": "v1",
  "groups": [
    {
      "name": "apiregistration.k8s.io",
      "versions": [
        {
          "groupVersion": "apiregistration.k8s.io/v1",
          "version": "v1"
        }
      ],
      "preferredVersion": {
        "groupVersion": "apiregistration.k8s.io/v1",
        "version": "v1"
      }
    },
    {
      "name": "apps",
      "versions": [
        {
          "groupVersion": "apps/v1",
          "version": "v1"
        }
      ],
      "preferredVersion": {
        "groupVersion": "apps/v1",
        "version": "v1"
      }
    },
    ...
}

需要額外的請求才能取得每個群組版本的探索文件，網址為 /apis/<group>/<version>（例如：/apis/rbac.authorization.k8s.io/v1alpha1），其中宣告特定群組版本下提供的資源列表。kubectl 使用這些端點來擷取叢集支援的資源列表。

OpenAPI 介面定義

有關 OpenAPI 規範的詳細資訊，請參閱 OpenAPI 文件。

Kubernetes 同時提供 OpenAPI v2.0 和 OpenAPI v3.0。OpenAPI v3 是存取 OpenAPI 的首選方法，因為它提供了更全面（無損）的 Kubernetes 資源表示。由於 OpenAPI 版本 2 的限制，某些欄位會從發布的 OpenAPI 中刪除，包括但不限於 default、nullable、oneOf。

OpenAPI V2

Kubernetes API 伺服器透過 /openapi/v2 端點提供聚合的 OpenAPI v2 規範。您可以使用請求標頭請求回應格式，如下所示

OpenAPI v2 查詢的有效請求標頭值
標頭可能的值註解
Accept-Encodinggzip不提供此標頭也是可接受的
Acceptapplication/com.github.proto-openapi.spec.v2@v1.0+protobuf主要用於叢集內使用
application/json預設
*提供 application/json

OpenAPI V3

功能狀態： Kubernetes v1.27 [穩定] (預設啟用：true)

Kubernetes 支援以 OpenAPI v3 格式發布其 API 的描述。

提供探索端點 /openapi/v3 以查看所有可用的群組/版本列表。此端點僅傳回 JSON。這些群組/版本以以下格式提供

{
    "paths": {
        ...,
        "api/v1": {
            "serverRelativeURL": "/openapi/v3/api/v1?hash=CC0E9BFD992D8C59AEC98A1E2336F899E8318D3CF4C68944C3DEC640AF5AB52D864AC50DAA8D145B3494F75FA3CFF939FCBDDA431DAD3CA79738B297795818CF"
        },
        "apis/admissionregistration.k8s.io/v1": {
            "serverRelativeURL": "/openapi/v3/apis/admissionregistration.k8s.io/v1?hash=E19CC93A116982CE5422FC42B590A8AFAD92CDE9AE4D59B5CAAD568F083AD07946E6CB5817531680BCE6E215C16973CD39003B0425F3477CFD854E89A9DB6597"
        },
        ....
    }
}

相對 URL 指向不可變的 OpenAPI 描述，以改進用戶端快取。API 伺服器也為此目的設定了適當的 HTTP 快取標頭（Expires 設定為未來 1 年，Cache-Control 設定為 immutable）。當使用過時的 URL 時，API 伺服器會傳回重新導向到最新的 URL。

Kubernetes API 伺服器在 /openapi/v3/apis/<group>/<version>?hash=<hash> 端點發布每個 Kubernetes 群組版本的 OpenAPI v3 規範。

有關接受的請求標頭，請參閱下表。

OpenAPI v3 查詢的有效請求標頭值
標頭可能的值註解
Accept-Encodinggzip不提供此標頭也是可接受的
Acceptapplication/com.github.proto-openapi.spec.v3@v1.0+protobuf主要用於叢集內使用
application/json預設
*提供 application/json

套件 k8s.io/client-go/openapi3 中提供了用於擷取 OpenAPI V3 的 Golang 實作。

Kubernetes 1.32 發布 OpenAPI v2.0 和 v3.0；近期沒有支援 3.1 的計畫。

Protobuf 序列化

Kubernetes 實作了一種替代的基於 Protobuf 的序列化格式，主要用於叢集內通訊。有關此格式的更多資訊，請參閱 Kubernetes Protobuf 序列化 設計提案和 Go 套件中每個結構描述的介面定義語言 (IDL) 檔案，這些套件定義了 API 物件。

持久性

Kubernetes 透過將物件的序列化狀態寫入 etcd 來儲存物件的序列化狀態。

API 群組和版本控制

為了更容易消除欄位或重組資源表示，Kubernetes 支援多個 API 版本，每個版本位於不同的 API 路徑，例如 /api/v1 或 /apis/rbac.authorization.k8s.io/v1alpha1。

版本控制是在 API 層級而不是在資源或欄位層級完成的，以確保 API 提供系統資源和行為的清晰、一致的視圖，並允許控制對生命週期結束和/或實驗性 API 的存取。

為了更容易發展和擴充其 API，Kubernetes 實作了可以啟用或停用的 API 群組。

API 資源透過其 API 群組、資源類型、命名空間（對於命名空間資源）和名稱來區分。API 伺服器透明地處理 API 版本之間的轉換：所有不同的版本實際上是相同持久性資料的表示。API 伺服器可以透過多個 API 版本提供相同的底層資料。

例如，假設同一個資源有兩個 API 版本，v1 和 v1beta1。如果您最初使用其 API 的 v1beta1 版本建立物件，則稍後可以使用 v1beta1 或 v1 API 版本讀取、更新或刪除該物件，直到 v1beta1 版本被棄用和移除。屆時，您可以繼續使用 v1 API 存取和修改物件。

API 變更

任何成功的系統都需要隨著新用例的出現或現有案例的變更而成長和改變。因此，Kubernetes 將 Kubernetes API 設計為持續變更和成長。Kubernetes 專案旨在不破壞與現有用戶端的相容性，並將這種相容性維持一段時間，以便其他專案有機會適應。

一般來說，可以經常且頻繁地新增新的 API 資源和新的資源欄位。刪除資源或欄位需要遵循 API 棄用政策。

Kubernetes 強烈承諾在官方 Kubernetes API 達到正式發行 (GA) 時（通常在 API 版本 v1），維持其相容性。此外，Kubernetes 維持與透過官方 Kubernetes API 的 beta API 版本持久化的資料的相容性，並確保當功能變得穩定時，資料可以透過 GA API 版本轉換和存取。

如果您採用 beta API 版本，則一旦 API 升級，您將需要轉換到後續的 beta 或穩定 API 版本。執行此操作的最佳時間是在 beta API 處於棄用期間，因為物件可以同時透過這兩個 API 版本存取。一旦 beta API 完成其棄用期且不再提供服務，則必須使用替換的 API 版本。

有關 API 版本層級定義的更多詳細資訊，請參閱 API 版本控制參考。

API 擴充

Kubernetes API 可以透過兩種方式擴充

  1. 自訂資源 可讓您宣告式地定義 API 伺服器應如何提供您選擇的資源 API。
  2. 您也可以透過實作聚合層來擴充 Kubernetes API。

下一步

上次修改時間：2024 年 9 月 10 日上午 7:15 PST：Update kubernetes-api.md (b1cc8f7b3d)