Kubernetes 1.27：伺服器端欄位驗證和 OpenAPI V3 進入 GA 階段

在 Kubernetes v1.8 之前 (!)，YAML 檔案中的拼寫錯誤、縮排錯誤或微小錯誤都可能導致災難性後果（例如，像在 `replica: 1000` 中忘記結尾的 s 這樣的拼寫錯誤可能會導致服務中斷，因為該值會被忽略和缺失，從而強制將副本數重置回 1）。這個問題在當時是透過在 kubectl 中獲取 OpenAPI v2 並用它來驗證欄位在應用前是否正確和存在來解決的。不幸的是，那時 Custom Resource Definitions 還不存在，程式碼是在這個假設下編寫的。當後來引入 CRD 時，校驗程式碼的靈活性不足迫使我們在 CRD 暴露其 Schema 的方式上做出一些艱難的決定，使我們陷入了校驗不佳導致 OpenAPI 不佳，反之亦然的惡性迴圈。隨著新的 OpenAPI v3 和伺服器端欄位校驗在 1.27 中進入 GA 階段，我們現在已經解決了這兩個問題。

伺服器端欄位校驗為對 apiserver 的建立、更新和補丁請求提供了資源校驗功能，該功能在 Kubernetes v1.25 中被新增，v1.26 中進入 Beta 階段，現在在 v1.27 中已進入 GA 階段。它在伺服器端提供了 kubectl validate 的所有功能。

OpenAPI 是一種標準的、與語言無關的介面，用於發現 Kubernetes 叢集支援的操作和型別集。OpenAPI V3 是 OpenAPI 的最新標準，是對 OpenAPI V2 的改進，後者自 Kubernetes 1.5 起就得到支援。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 的正確表示。

自定義資源定義（Custom Resource Definitions）

在 Kubernetes 中，自定義資源定義使用一種結構化的 OpenAPI V3 Schema，這種 Schema 無法在不丟失某些欄位的情況下表示為 OpenAPI V2。其中一些欄位包括 nullable、default、anyOf、oneOf、not 等。OpenAPI V3 是 CustomResourceDefinition 結構化 Schema 的完全無損表示。

我該如何使用它？

OpenAPI V3 的根發現端點位於 Kubernetes API 伺服器的 `/openapi/v3` 端點。OpenAPI V3 文件按組版本（group-version）進行分組，以減少傳輸的資料量，各個文件可以透過 `/openapi/v3/apis/<group>/<version>` 和 `/openapi/v3/api/v1`（代表遺留的組版本）訪問。請參閱 Kubernetes API 文件 以獲取有關此端點的更多資訊。

OpenAPI 的各種消費者已經被更新以使用 V3，包括整個 kubectl 和伺服器端應用（Server Side Apply）。在 client-go 中提供了一個 OpenAPI V3 的 Golang 客戶端。

伺服器端欄位校驗

查詢引數 `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

• ←上一篇
• 下一篇→