Kubernetes 汰舊政策

本文件詳細說明系統各個方面的汰舊政策。

Kubernetes 是一個大型系統，具有許多元件和許多貢獻者。與任何此類軟體一樣，功能集會隨著時間自然演進，有時可能需要移除某項功能。這可能包括 API、旗標，甚至整個功能。為了避免中斷現有使用者，Kubernetes 對於預定移除的系統方面遵循汰舊政策。

汰舊 API 的部分

由於 Kubernetes 是一個 API 驅動的系統，因此 API 隨著時間演進，以反映對問題空間不斷演進的理解。Kubernetes API 實際上是一組 API，稱為「API 群組」，每個 API 群組都獨立進行版本控制。API 版本分為 3 個主要軌跡，每個軌跡都有不同的汰舊政策

給定的 Kubernetes 發行版本可以支援任意數量的 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 和返回，這表示 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 物件)

假設在上述時間軸的 API v1 中，存在一個名為 Widget 的假設性 REST 資源，且該資源需要被棄用。我們會記錄並在版本 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。該指標具有可與 apiserver_request_total 指標結合的 group、version、resource、subresource 標籤，以及指示 API 將不再提供服務的 Kubernetes 版本的 removed_release 標籤。以下 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 可以為該欄位選擇不同的表示方式，只要它可以往返轉換即可。例如，v1 中名為 "magnitude" 的已棄用欄位在 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 個版本

已棄用的指標將在其描述文字前面加上棄用通知字串「(Deprecated from x.y)」，並且在指標註冊期間會發出警告日誌。與其穩定的未棄用對應項一樣，已棄用的指標將自動註冊到指標端點，因此可見。

在後續版本中（當指標的 deprecatedVersion 等於current_kubernetes_version - 3 時），已棄用的指標將變成隱藏指標。與其已棄用的對應項不同，隱藏指標將不再自動註冊到指標端點（因此為隱藏）。但是，可以透過二進位檔案上的命令列旗標 (--show-hidden-metrics-for-version=) 明確啟用它們。這為叢集管理員提供了一個應急方案，以便在他們未能對先前的棄用警告做出反應時，正確地從已棄用的指標遷移出來。隱藏指標應在一個版本後刪除。

例外情況

沒有任何政策可以涵蓋所有可能的情況。此政策是一份活文件，並且會隨著時間演進。實際上，會有一些情況不完全符合此政策，或者此政策會成為嚴重的阻礙。應與 SIG 和專案負責人討論這些情況，以為這些特定案例找到最佳解決方案，始終牢記 Kubernetes 致力於成為一個穩定的系統，並盡可能永遠不會讓使用者失望。例外情況將始終在所有相關的版本發行說明中公告。