CRDs

cert-manager 使用 Kubernetes 自訂資源來定義使用者在使用 cert-manager 時會互動的資源，例如 Certificate 和 Issuer。

當程式碼中的 CRD 發生變更時，需要額外執行一些步驟。

產生 CRD 更新

我們使用 controller-gen 來更新我們的 CRD，並使用 k8s-code-generator 進行程式碼產生。

驗證和更新 CRD 以及產生的程式碼可以完全透過 make 來完成。有兩個步驟：一個會更新 CRD，另一個會更新產生的程式碼。

# Check that CRDs and codegen are up to date
make verify-crds verify-codegen

# Update CRDs based on code
make update-crds

# Update generated code based on CRD defintions in code
make update-codegen

版本

cert-manager 目前有一個公開使用的 v1 API 版本。

cert-manager API 類型定義於 pkg/apis/certmanager。

ACME 相關資源位於 pkg/apis/acme。

程式碼註解

API 類型欄位的程式碼註解會轉換為本網站上的文件，並會出現在 kubectl explain 的輸出中。

這表示 API 欄位的 go doc 風格註解應該撰寫成面向使用者，而不是面向開發者。因此，在編輯這些欄位時，也可以打破關於程式碼註解的常見 Go 標準。

內部 API 版本

cert-manager 也有一個內部 API 版本，位於 internal/apis 底下。

內部版本僅用於驗證和轉換，控制器通常不應使用它；它並非設計為使用者友善或穩定，並且可能會變更。但是，所有新的欄位也必須在此處新增，才能使轉換邏輯運作。

有關轉換和版本的詳細資訊，請參閱 CRD 版本控制的官方 Kubernetes 文件。

Kubebuilder

雖然 cert-manager 並未完全使用 Kubebuilder，但 CRD 可以使用特殊的 Kubebuilder 標記，例如驗證標記。

變更 API

請參閱我們的 API 相容性承諾，以了解哪些類型的 API 變更是可接受的。

一般而言，重點是可以新增欄位，但不能移除現有的欄位。

這也表示當將欄位新增至 API 的版本時，它是永久性的，且其名稱無法變更。因此，我們在新增欄位時會盡量謹慎。

相同的原則適用於常數和列舉類型。