Kubernetes 棄用策略

本文件詳細說明了系統各個方面的棄用策略。

Kubernetes 是一個大型系統，包含許多元件和許多貢獻者。與任何此類軟體一樣，功能集會隨著時間的推移自然演變，有時可能需要移除某個功能。這可能包括 API、標誌甚至整個功能。為了避免破壞現有使用者，Kubernetes 對系統中計劃移除的方面遵循棄用策略。

棄用 API 的部分內容

由於 Kubernetes 是一個 API 驅動的系統，API 隨著時間的推移不斷演進，以反映對問題空間的不斷深入理解。Kubernetes API 實際上是一組 API，稱為“API 組”，每個 API 組獨立版本化。API 版本分為 3 個主要級別，每個級別都有不同的棄用策略：

給定版本的 Kubernetes 可以支援任意數量的 API 組以及每個 API 組的任意數量版本。

以下規則管理 API 元素的棄用。這包括

• REST 資源（又稱 API 物件）
• REST 資源的欄位
• REST 資源上的註解，包括 "beta" 註解但不包括 "alpha" 註解。
• 列舉或常量值
• 元件配置結構

這些規則在正式釋出之間執行，而不是在 master 或釋出分支的任意提交之間執行。

規則 #1：API 元素只能透過遞增 API 組的版本來移除。

一旦某個 API 元素以特定版本新增到 API 組，就不能從該版本中移除或對其行為進行顯著更改，無論其處於哪個階段。

規則 #2：API 物件必須能夠在給定釋出的不同 API 版本之間往返而不會丟失資訊，除了某些版本中不存在的整個 REST 資源。

例如，一個物件可以作為 v1 寫入，然後作為 v2 讀回並轉換為 v1，並且生成的 v1 資源將與原始資源相同。v2 中的表示可能與 v1 不同，但系統知道如何在兩者之間雙向轉換。此外，v2 中新增的任何新欄位都必須能夠在 v1 和 v2 之間往返，這意味著 v1 可能需要新增一個等效欄位或將其表示為註解。

規則 #3：給定軌道中的 API 版本不能被更不穩定的 API 版本棄用。

• GA API 版本可以替換 Beta 和 Alpha API 版本。
• Beta API 版本可以替換早期的 Beta 和 Alpha API 版本，但 **不能** 替換 GA API 版本。
• Alpha API 版本可以替換早期的 Alpha API 版本，但 **不能** 替換 GA 或 Beta API 版本。

規則 #4a：API 生命週期由 API 穩定性級別決定

• GA API 版本可能被標記為已棄用，但在 Kubernetes 的主版本中不得移除
• Beta API 版本在引入後不超過 9 個月或 3 個次要版本（以較長者為準）後棄用，並在棄用後不超過 9 個月或 3 個次要版本（以較長者為準）後停止服務
• Alpha API 版本可在任何版本中移除，無需事先棄用通知

這確保了 Beta API 支援涵蓋最大支援版本偏差為 2 個釋出版本，並且 API 不會停滯在不穩定的 Beta 版本上，從而累積生產使用量，當 Beta API 支援結束時，這將導致中斷。

規則 #4b：給定組的“首選”API 版本和“儲存版本”不得提前，直到釋出了一個同時支援新版本和舊版本的版本。

使用者必須能夠升級到 Kubernetes 的新版本，然後回滾到舊版本，而無需將任何內容轉換為新的 API 版本或遭受破壞（除非他們明確使用了僅在新版本中可用的功能）。這在物件的儲存表示中尤為明顯。

所有這些最好透過示例來說明。想象一個 Kubernetes 釋出版本 X，它引入了一個新的 API 組。Kubernetes 大約每 4 個月釋出一個新版本（每年 3 個）。下表描述了在後續一系列釋出中支援的 API 版本。

REST 資源（又稱 API 物件）

考慮一個名為 Widget 的假設 REST 資源，它出現在上述時間線的 API v1 中，並且需要被棄用。我們與釋出版本 X+1 同步地記錄並宣佈棄用。Widget 資源仍然存在於 API 版本 v1（已棄用）中，但不存在於 v2alpha1 中。Widget 資源在包括 X+8 在內的釋出版本中繼續存在並執行。直到釋出版本 X+9，當 API v1 過期時，Widget 資源才停止存在，並且行為被移除。

從 Kubernetes v1.19 開始，向已棄用的 REST API 端點發出 API 請求

1. 在 API 響應中返回一個 `Warning` 頭（如 RFC7234，第 5.5 節中所定義）。

2. 為請求記錄的審計事件新增一個`"k8s.io/deprecated":"true"`註解。

3. 在 `kube-apiserver` 程序中，將 `apiserver_requested_deprecated_apis` 儀表指標設定為 `1`。該指標具有 `group`、`version`、`resource`、`subresource` 標籤，這些標籤可以與 `apiserver_request_total` 指標連線，還有一個 `removed_release` 標籤，表示 API 將在哪個 Kubernetes 版本中停止服務。以下 Prometheus 查詢返回有關對將在 v1.22 中移除的已棄用 API 發出的請求的資訊

   apiserver_requested_deprecated_apis{removed_release="1.22"} * on(group,version,resource,subresource) group_right() apiserver_request_total
   

REST 資源的欄位

與整個 REST 資源一樣，API v1 中存在的單個欄位必須存在並正常執行，直到 API v1 被移除。與整個資源不同，v2 API 可以為該欄位選擇不同的表示方式，只要它能夠進行往返轉換即可。例如，一個名為“magnitude”的 v1 欄位被棄用後，在 API v2 中可能被稱為“deprecatedMagnitude”。當 v1 最終被移除時，該棄用欄位可以從 v2 中移除。

列舉或常量值

與整個 REST 資源及其欄位一樣，API v1 中支援的常量值必須存在並正常執行，直到 API v1 被移除。

元件配置結構

元件配置版本化和管理方式與 REST 資源類似。

未來工作

隨著時間的推移，Kubernetes 將引入更細粒度的 API 版本，屆時這些規則將根據需要進行調整。

棄用標誌或 CLI

Kubernetes 系統由幾個相互協作的不同程式組成。有時，Kubernetes 釋出版本可能會在這些程式中移除標誌或 CLI 命令（統稱為“CLI 元素”）。各個程式自然分為兩個主要組——面向使用者的程式和麵向管理員的程式，它們的棄用策略略有不同。除非一個標誌明確地帶有“alpha”或“beta”字首或文件說明，否則它被視為 GA。

CLI 元素實際上是系統 API 的一部分，但由於它們不像 REST API 那樣進行版本控制，因此棄用規則如下：

規則 #5a：面向使用者元件（例如 kubectl）的 CLI 元素在其宣佈棄用後，必須至少執行

• GA：12 個月或 2 個釋出版本（以較長者為準）
• Beta：3 個月或 1 個釋出版本（以較長者為準）
• Alpha：0 個釋出版本

規則 #5b：面向管理員的元件（例如 kubelet）的 CLI 元素在其宣佈棄用後，必須至少執行

• GA：6 個月或 1 個釋出版本（以較長者為準）
• Beta：3 個月或 1 個釋出版本（以較長者為準）
• Alpha：0 個釋出版本

規則 #5c：命令列介面 (CLI) 元素不能被棄用以支援穩定性更低的 CLI 元素

與 API 的規則 #3 類似，如果命令列介面的某個元素被替代實現替換，例如透過重新命名現有元素，或者透過切換使用來自檔案而非命令列引數的配置，則推薦的替代方案必須具有相同或更高的穩定性級別。

規則 #6：已棄用的 CLI 元素在使用時必須發出警告（可選停用）。

棄用功能或行為

有時 Kubernetes 釋出版本需要棄用系統中不受 API 或 CLI 控制的某些功能或行為。在這種情況下，棄用規則如下：

規則 #7：已棄用的行為在其宣佈棄用後必須至少執行 1 年。

如果正在用需要工作才能適應更改的替代實現來替換功能或行為，則應儘可能簡化過渡。如果替代實現受 Kubernetes 組織控制，則適用以下規則：

規則 #8：功能或行為不得因更不穩定的替代實現而被棄用

例如，一個普遍可用的功能不能被棄用，轉而支援 Beta 版替代品。然而，Kubernetes 專案鼓勵使用者即使在替代實現達到相同成熟度之前也採用並過渡到它們。這對於探索功能的新用例或儘早獲得替代品的反饋尤為重要。

替代實現有時可能是外部工具或產品，例如，某個功能可能從 kubelet 移到不受 Kubernetes 專案控制的容器執行時。在這種情況下，此規則無法適用，但必須努力確保存在不會損害元件成熟度級別的過渡路徑。在容器執行時的示例中，這項工作可能涉及嘗試確保流行的容器執行時具有在實現該替代行為時提供相同穩定性級別的版本。

功能和行為的棄用規則並不意味著系統的所有更改都受此策略的約束。這些規則僅適用於影響 Kubernetes 上執行應用程式的正確性或影響 Kubernetes 叢集管理的重大、使用者可見的行為，並且這些行為將被完全移除。

上述規則的一個例外是**特性門控**。特性門控是鍵值對，允許使用者啟用/停用實驗性功能。

特性門控旨在涵蓋功能的開發生命週期——它們不打算成為長期 API。因此，預計它們將在功能達到 GA 或被刪除後棄用和移除。

隨著功能在各個階段的演進，關聯的特性門控也隨之演變。功能生命週期與其對應的特性門控匹配如下：

• Alpha：特性門控預設停用，使用者可以啟用。
• Beta：特性門控預設啟用，使用者可以停用。
• GA：特性門控被棄用（參見“棄用”）並變得無法操作。
• GA，棄用期完成：特性門控被移除，不再接受對其的呼叫。

棄用

功能可以在 GA 之前的生命週期任何時候被移除。當功能在 GA 之前被移除時，其關聯的特性門控也會被棄用。

當呼叫嘗試停用無法操作的特性門控時，呼叫失敗，以避免可能悄無聲息地執行的不受支援的場景。

在某些情況下，移除預 GA 功能需要相當長的時間。特性門控可以保持執行，直到其關聯功能完全移除，屆時特性門控本身可以被棄用。

當移除 GA 功能的特性門控也需要相當長的時間時，如果特性門控對功能沒有影響，並且特性門控不會引起任何錯誤，則對特性門控的呼叫可以保持執行。

旨在由使用者停用的功能應包含在相關特性門控中停用該功能的機制。

特性門控的版本控制與前面討論的元件不同，因此棄用規則如下：

規則 #9：特性門控必須在其所控制的相應功能按以下方式轉換生命週期階段時被棄用。特性門控必須至少執行

• Beta 功能到 GA：6 個月或 2 個釋出版本（以較長者為準）
• Beta 功能到 EOL：3 個月或 1 個釋出版本（以較長者為準）
• Alpha 功能到 EOL：0 個釋出版本

規則 #10：已棄用的特性門控在使用時必須發出警告。當特性門控被棄用時，它必須在釋出說明和相應的 CLI 幫助中進行文件說明。警告和文件都必須指明特性門控是否處於非操作狀態。

棄用指標

Kubernetes 控制平面的每個元件都會暴露指標（通常是 `/metrics` 端點），這些指標通常由叢集管理員攝取。並非所有指標都相同：一些指標通常用作 SLI 或用於確定 SLO，這些指標往往更重要。其他指標在本質上更具實驗性，或者主要用於 Kubernetes 開發過程。

因此，指標分為三個穩定性類別（`ALPHA`、`BETA`、`STABLE`）；這會影響 Kubernetes 釋出期間指標的移除。這些類別由指標的感知重要性決定。棄用和移除指標的規則如下：

規則 #11a：指標，對於相應的穩定性類別，必須至少執行

• 穩定版 (STABLE)：4 個釋出週期或 12 個月（以較長者為準）
• 測試版 (BETA)：2 個釋出週期或 8 個月（以較長者為準）
• Alpha：0 個釋出版本

規則 #11b：指標在其**宣佈棄用**後，必須至少執行

• 穩定版 (STABLE)：3 個釋出週期或 9 個月（以較長者為準）
• 測試版 (BETA)：1 個釋出週期或 4 個月（以較長者為準）
• Alpha：0 個釋出版本

已棄用指標的描述文字將以棄用通知字串“（從 x.y 棄用）”為字首，並在指標註冊期間發出警告日誌。與穩定的未棄用指標一樣，已棄用指標將自動註冊到指標端點，因此可見。

在隨後的釋出中（當指標的 `deprecatedVersion` 等於 `current_kubernetes_version - 3` 時），已棄用指標將成為**隱藏**指標。**與**已棄用指標**不同**，隱藏指標將**不再**自動註冊到指標端點（因此是隱藏的）。但是，它們可以透過二進位制檔案上的命令列標誌（`--show-hidden-metrics-for-version=`）顯式啟用。這為叢集管理員提供了一個退出通道，如果他們未能對較早的棄用警告做出反應，則可以適當地從已棄用指標遷移。隱藏指標應在一個釋出版本後刪除。

例外

沒有任何策略能涵蓋所有可能的情況。本策略是一份動態文件，並將隨著時間的推移而演變。在實踐中，會存在不完全符合本策略的情況，或者本策略會成為嚴重障礙的情況。對於這些特定情況，應與 SIG 和專案負責人討論，以找到最佳解決方案，始終牢記 Kubernetes 致力於成為一個穩定的系統，儘可能不破壞使用者。例外情況將始終在所有相關釋出說明中公佈。