CRD

cert-managerは、Kubernetes カスタムリソースを使用して、CertificateやIssuerなど、ユーザーがcert-managerを使用する際にやり取りするリソースを定義します。

コード内でCRDに変更を加えた場合、いくつかの追加手順が必要です。

CRDの更新を生成する

CRDの更新にはcontroller-genを、コード生成にはk8s-code-generatorを使用します。

CRDと生成されたコードの検証と更新は、makeを通じて完全に実行できます。2つのステップがあり、1つはCRDを更新し、もう1つは生成されたコードを更新します。

# 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タイプのフィールドのコードコメントは、このWebサイトのドキュメントに変換されるだけでなく、kubectl explainの出力にも表示されます。

つまり、APIフィールドに関するgo docスタイルのコメントは、開発者向けではなく、ユーザー向けに書く必要があります。このため、これらのフィールドを編集する際は、コードコメントに関する通常のGoの標準から逸脱してもかまいません。

内部APIバージョン

cert-managerには、internal/apisの下にある内部APIバージョンもあります。

内部バージョンは検証と変換にのみ使用され、コントローラーは一般的に使用すべきではありません。ユーザーフレンドリーまたは安定していることを意図しておらず、変更される可能性があります。ただし、変換ロジックが機能するためには、すべての新しいフィールドもここに追加する必要があります。

変換とバージョンの詳細については、CRDバージョニングに関するKubernetesの公式ドキュメントを参照してください。

Kubebuilder

cert-managerはKubebuilderを完全には使用していませんが、CRDは検証フラグなどの特別なKubebuilderフラグを利用できます。

APIの変更

APIへの変更のどのタイプが受け入れ可能かの詳細については、API互換性に関する約束を参照してください。

一般的に、新しいフィールドを追加することはできますが、既存のフィールドを削除することはできません。

これは、APIのバージョンにフィールドが追加されると、そのフィールドが永続的になり、その名前を変更できないことも意味します。このため、新しいフィールドを追加する際には慎重を期しています。

同じ原則が定数および列挙型にも適用されます。