CRDs

cert-manager 使用 Kubernetes 自定义资源 来定义用户在使用 cert-manager 时交互的资源，例如 Certificate 和 Issuer。

当代码中的 CRDs 发生变化时，需要执行一些额外的步骤。

生成 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 版本中时，它将永久存在，并且其名称不能被更改。因此，我们在添加新字段时会非常谨慎。

相同的原则适用于 常量和枚举类型。