Kubernetes 1.27：伺服器端欄位驗證與 OpenAPI V3 移至 GA

在 Kubernetes v1.8 (!) 之前，YAML 中的錯字、縮排錯誤或小錯誤可能會造成災難性的後果（例如，像在 replica: 1000 中忘記尾隨的 s 這樣的錯字可能會導致服務中斷，因為該值會被忽略且遺失，強制將副本重置回 1）。當時透過在 kubectl 中獲取 OpenAPI v2 並使用它來驗證欄位是否正確且存在才解決了這個問題。不幸的是，當時自訂資源定義 (CRD) 尚不存在，並且程式碼是在該假設下編寫的。當稍後引入 CRD 時，驗證程式碼缺乏彈性迫使人們在 CRD 公開其 schema 的方式上做出一些艱難的決定，使我們陷入了不良驗證導致不良 OpenAPI，反之亦然的循環。隨著新的 OpenAPI v3 和伺服器端欄位驗證在 1.27 中正式發布 (GA)，我們現在已經解決了這兩個問題。

伺服器端欄位驗證在 Kubernetes v1.25 中新增，在 v1.26 中進入 Beta 階段，現在在 v1.27 中正式發布 (GA)，在建立、更新和修補請求時提供對 apiserver 的資源驗證。它提供了 kubectl validate 在伺服器端的所有功能。

OpenAPI 是一個標準、語言無關的介面，用於發現 Kubernetes 叢集支援的一組操作和類型。OpenAPI V3 是 OpenAPI 的最新標準，並且是對自 Kubernetes 1.5 以來一直支援的 OpenAPI V2 的改進。Kubernetes 在 v1.23 中新增了 OpenAPI V3 支援，在 v1.24 中移至 Beta 階段，現在在 v1.27 中正式發布 (GA)。

OpenAPI V3

OpenAPI V3 相較於 V2 提供了什麼

內建類型

Kubernetes 在欄位上提供某些在 OpenAPI V2 中無法表示的註釋，或者有時在 Kubernetes 產生的 OpenAPI v2 中未表示的註釋。最值得注意的是，「default」欄位在 OpenAPI V3 中發布，而在 OpenAPI V2 中省略。可以在 OpenAPI V3 中使用 oneOf 欄位正確表達可以表示多種類型的單一類型。這包括 IntOrString 和 Quantity 的正確表示。

自訂資源定義

在 Kubernetes 中，自訂資源定義使用結構化的 OpenAPI V3 schema，如果沒有某些欄位的遺失，則無法表示為 OpenAPI V2。其中一些包括 nullable、default、anyOf、oneOf、not 等。OpenAPI V3 是 CustomResourceDefinition 結構化 schema 的完全無損表示。

我該如何使用它？

OpenAPI V3 根探索可以在 Kubernetes API 伺服器的 /openapi/v3 端點找到。OpenAPI V3 文件按群組版本分組，以減少傳輸的資料大小，可以在 /openapi/v3/apis/<group>/<version> 和 /openapi/v3/api/v1 存取單獨的文件，後者代表舊版群組版本。請參閱 Kubernetes API 文件 以取得有關此端點的更多資訊。

OpenAPI 的各種消費者已經更新為使用 v3，包括 kubectl 的全部內容和伺服器端套用。OpenAPI V3 Golang 客戶端可在 client-go 中取得。

伺服器端欄位驗證

查詢參數 fieldValidation 可用於指示伺服器應執行的欄位驗證層級。如果未傳遞參數，則預設情況下，伺服器端欄位驗證處於 Warn 模式。

• Strict：嚴格欄位驗證，驗證失敗時會產生錯誤
• Warn：執行欄位驗證，但錯誤會作為警告顯示，而不是使請求失敗
• Ignore：不執行伺服器端欄位驗證

kubectl 將跳過客戶端驗證，並自動在 Strict 模式下使用伺服器端欄位驗證。預設情況下，控制器在 Warn 模式下使用伺服器端欄位驗證。

使用客戶端驗證，我們必須格外寬鬆，因為 OpenAPI V2 中缺少某些欄位，而且我們不想拒絕可能有效的物件。這一切都在伺服器端驗證中得到修正。其他文件可以在 此處 找到

下一步是什麼？

隨著伺服器端欄位驗證和 OpenAPI V3 作為正式發布 (GA) 版本發布，我們引入了更準確的 Kubernetes 資源表示。建議使用伺服器端欄位驗證而不是客戶端，但使用 OpenAPI V3，客戶端可以自由實作自己的驗證（如果需要「將事情提前」），並且我們保證 OpenAPI 發布的完整無損 schema。

一些現有的努力將進一步改進透過 OpenAPI 提供的資訊，包括 CEL 驗證和准入，以及內建類型的 OpenAPI 註釋。

可以使用 OpenAPI v3 中找到的類型資訊，為撰寫和轉換資源建構許多其他工具。

如何參與？

這兩個功能由 SIG API Machinery 社群驅動，可在 Slack 頻道 #sig-api-machinery 上取得，透過 郵件列表，我們每隔週三太平洋時間上午 11:00 在 Zoom 上聚會。

我們非常感謝所有協助設計、實作和審查這兩個功能的貢獻者。

• Alexander Zielenski
• Antoine Pelisse
• Daniel Smith
• David Eads
• Jeffrey Ying
• Jordan Liggitt
• Kevin Delgado
• Sean Sullivan

• ←上一篇
下一篇→