Kubernetes API

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

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

Kubernetes API 允許你查詢和操作 Kubernetes 中 API 物件的狀態（例如：Pod、Namespace、ConfigMap 和 Event）。

大多數操作都可以透過 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 [stable] (預設啟用：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 v2 的限制，某些欄位已從釋出的 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 [stable]（預設啟用：true）

Kubernetes 支援將其 API 描述釋出為 OpenAPI v3。

提供了一個發現端點 `/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.34 釋出 OpenAPI v2.0 和 v3.0；目前沒有在不久的將來支援 3.1 的計劃。

Protobuf 序列化

Kubernetes 實現了一種基於 Protobuf 的替代序列化格式，主要用於叢集內部通訊。有關此格式的更多資訊，請參閱 Kubernetes Protobuf 序列化設計提案以及 Go 包中定義 API 物件的每個模式的介面定義語言 (IDL) 檔案。

永續性

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` 版本被棄用和移除之前，使用 `v1beta1` 或 `v1` API 版本來讀取、更新或刪除該物件。屆時，你可以繼續使用 `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。

下一步

上次修改時間：2025 年 1 月 8 日，上午 10:50 （太平洋標準時間）：修復功能門名稱衝突 (2/2) (3782732ce4)