最新：在 Twitter 和 Mastodon 获取项目更新。

构建 cert-manager

cert-manager 是使用 make 构建和测试的，重点是尽可能使用标准 Go 工具，并将系统依赖项降至最低。cert-manager 构建系统可以在需要时自动配置其大部分依赖项，包括 Go。

cert-manager 的构建系统完全支持使用 Linux amd64、macOS amd64 和 macOS arm64 的开发者。

它还对 Linux arm64 提供有限的支持，但该平台很大程度上未经测试，并且不受完全支持。

其他操作系统和架构可能可以使用，但可能需要进行修改和变通才能进行开发。

先决条件

开发 cert-manager 所需的其他要求很少，而且最重要的是，构建系统应该在缺少任何内容时以友好的错误消息通知您。如果您认为与缺少依赖项相关的错误消息对用户不友好，我们认为这是一个错误，我们很乐意如果您能 提交问题 向我们反馈！

在开始开发 cert-manager 之前，您应该安装以下工具

  • git
  • curl
  • GNU make，v3.82 或更高版本
  • GNU Coreutils（通常已安装在 Linux 上，可通过 homebrew 为 macOS 提供）
  • jq（在 Linux 包管理器和 homebrew 中可用）
  • docker（或 podman，请参见下面的 容器引擎）
  • Go（可选；请参见下面的 Go 版本）

macOS 说明

cert-manager 支持在 macOS 上进行开发，但需要注意一些额外的要求

  1. cert-manager 的 Makefile 设置使用 bash，而 macOS 上的系统 bash 版本非常古老。我们建议您从 homebrew 安装 bash；如果您没有安装，您可能会在 Makefiles 中看到非常糟糕的性能
  2. 如上所述，GNU Coreutils 是必需的，可以通过 homebrew 安装
  3. make 在 macOS 上也非常古老；我们建议您从 homebrew 安装一个更新的版本

总之，我们建议所有使用 macOS 的开发者执行以下操作

brew install make bash git jq coreutils

入门

您可能需要使用的绝大多数命令都已在 make help 中进行了说明。如果您正在开发 cert-manager，这可能是您开始的第一个地方。我们还将在本页面上概述一些关键目标和需要注意的事项。

Go 版本

cert-manager 默认使用您在系统本地安装的 Go 版本。如果您想使用系统 Go，这完全没问题。

或者，make 可以专门为 cert-manager 配置和“供应商化” Go，这有助于确保您使用与 CI 中使用的相同版本，并使开发更容易上手。

要开始使用供应商化的 Go，请运行：make vendor-go。

您只需要运行一次 vendor-go，它将“粘贴”到您的本地检出中，并在所有将来的 make 调用中使用。

要返回使用系统的 Go 版本，请运行：make unvendor-go。

要检查当前使用的 Go 版本，请运行：make which-go，它将打印 Go 的版本号和 Go 二进制文件的路径。

# Use a vendored version of go
$ make vendor-go
cd _bin/tools/ && ln -f -s ../downloaded/tools/_go-1.XY.Z-linux-amd64/goroot .
cd _bin/tools/ && ln -f -s ../downloaded/tools/_go-1.XY.Z-linux-amd64/goroot/bin/go .


# A path to go inside the cert-manager directory indicates that a vendored Go is being used
$ make which-go
go version go1.XY.Z linux/amd64
go binary used for above version information: /home/user/workspace/cert-manager/_bin/tools/go


# Go back to the system Go
$ make unvendor-go
rm -rf _bin/tools/go _bin/tools/goroot


# The binary is now "go" which should be found in $PATH
$ make which-go
go version go1.AB.C linux/amd64
go binary used for above version information: go

Go 工作区

简而言之：一些开发工具会抱怨 cert-manager 的模块布局；为了解决这个问题，请使用 make go-workspace 生成一个 go.work 文件。

截至 cert-manager 1.12，cert-manager 存储库包含多个 Go 模块，在一个只有核心模块 github.com/cert-manager/cert-manager 预计会被第三方模块导入的设置中。存在单独的模块（我们称之为子模块），它们都对核心 cert-manager 模块具有替换语句。

这种设置的目的是为了表明这些子模块不打算被第三方导入，并确保每个子模块始终使用与 cert-manager 核心模块在同一提交处的版本 - 但这种结构可能会产生副作用，导致某些开发工具和脚本无法按预期工作。

例如，go test ./... 默认情况下只会影响核心模块。要测试，例如，控制器，您需要使用 cd cmd/controller && go test ./...。

可以通过使用 Go 工作区来避免这种情况，它将为您处理本地替换，并与 VS Code 等编辑器配合得更好。

您可以运行 make go-workspace 来生成一个 go.work 文件，该文件应该使 go test ./... 在整个存储库中运行，并应该帮助编辑器理解模块结构。

请注意，在 CI 中测试拉取请求时不使用 Go 工作区。如果您在 CI 中看到无法在本地复制的错误，请尝试使用 GOWORK 环境变量设置为 off 或删除 go.work 文件进行构建。

并行性

cert-manager Makefile 旨在尽可能地高度并行。任何构建和测试命令都应该能够使用标准的 Make 功能并行执行。

一个重要的注意事项是，Go 默认会检测系统上可用的核心数量，并尽可能多地启动线程。如果您正在使用 Make 功能并行运行多个构建，那么线程数量可能会过多，实际上会导致构建速度变慢。

可以限制 Go 使用的线程数量，我们在使用 Make 并行性时通常建议这样做。

要使用的最佳值将取决于您的系统，但我们在使用大约一半可用的核心数量进行 Make，并将每个核心的 Go 线程限制在 2 到 4 个之间时取得了成功。

例如，使用 8 核机器

# Run 4 make targets in parallel, and limit each `go build` to 2 threads.
make GOMAXPROCS=2 -j4 release-artifacts

测试

cert-manager 的构建管道和 CI 基础设施使用与您在本地开发时使用的相同 Makefile，因此测试运行的内容与您运行的内容之间不应有差异。这意味着您应该能够非常有信心，您所做的任何更改在 CI 中测试时都不会出现问题。

在集群中运行本地更改

您可能希望在本地 Kubernetes 集群中运行您本地更改的 cert-manager 副本，以进行手动测试。

有一些 make 目标可以帮助您完成此操作；有关更多信息，请参见 使用 Kind 进行开发。

单元测试和集成测试

首先：如果您想使用 go test 进行测试，请随时！对于单元测试（我们将其定义为 test/ 目录之外的任何测试），go test 将在新的检出上工作。

请注意，cert-manager 存储库被拆分为多个模块，除非您使用 Go 工作区，否则 go test ./... 实际上不会运行所有测试。有关更多详细信息，请参见上面的 Go 工作区。

集成测试可能需要先设置一些外部工具，因此要运行 test/ 中的集成测试，您可能需要运行

make setup-integration-tests

还提供了一些辅助目标，它们使用 gotestsum 来生成更漂亮的输出。也可以配置这些目标来运行特定的测试。

# Run all unit and integration tests
make test


# Run only unit tests
make unit-test


# Run only integration tests
make integration-test


# Run all tests in pkg
make WHAT=./pkg/... test


# Run unit and integration tests exactly as run in CI
# (NB: usually not needed - this is mostly for JUnit test output for dashboards)
make test-ci

端到端测试

cert-manager 的端到端测试稍微复杂一些，并且有 专门的文档 描述它们的用法。

其他检查

我们在每个拉取请求上运行各种其他工具来检查格式、导入顺序和许可证等内容。所有这些检查都可以本地运行。

make ci-presubmit

注意：其中一项检查目前需要安装 Python 3，这是代码库中一个独特的需求。我们希望将来删除该需求。

更新 CRD 和代码生成

对 cert-manager 的 CRD 进行的更改需要进行一些代码生成，这将在每个拉取请求中进行检查。

如果你对 cert-manager CRD 做出更改，你需要在发起 PR 之前在本地运行一些命令。

这在我们的 CRD 部分有说明。

构建

cert-manager 为许多不同的操作系统/架构组合生成许多工件，包括

  • 容器镜像
  • 客户端二进制文件 (cmctl 和 kubectl_cert-manager)
  • 清单（Helm 图表、静态 YAML）

所有这些工件都可以使用 make 在本地构建。

容器

cert-manager 最重要的工件是实际在集群中运行 cert-manager 的容器。我们默认使用 docker 来完成此操作，但旨在支持与 docker 兼容的 CLI 工具，例如 podman。有关更多信息，请参阅 容器引擎。

在本地构建不同的 cert-manager 容器有多个目标。所有这些都将默认使用 docker

# Build everything for every architecture
make all-containers


# Build just the controller containers on every architecture
make cert-manager-controller-linux


# As above, but for the webhook, cainjector, acmesolver and cmctl containers
make cert-manager-webhook-linux
make cert-manager-cainjector-linux
make cert-manager-acmesolver-linux
make cert-manager-ctl-linux

容器引擎

注意：本节不适用于端到端测试，端到端测试可能无法在编写时在 Docker 之外运行。有关更多信息，请参阅 端到端文档。

可以使用其他容器引擎来构建 cert-manager 容器。使用 podman 已成功测试。

通过设置 CTR 变量来配置其他容器引擎。

# Build everything for every architecture, using podman
make CTR=podman all-containers

客户端二进制文件

可以在本地为发行版构建 cmctl 和 kubectl_cert-manager。这些二进制文件是为跨多个架构的 Linux、macOS 和 Windows 构建的。

# Build all cmctl binaries for all platforms, then for linux only, then for macOS only, then for Windows only
make cmctl
make cmctl-linux
make cmctl-darwin
make cmctl-windows


# As above but for kubectl_cert-manager
make kubectl_cert-manager
make kubectl_cert-manager-linux
make kubectl_cert-manager-darwin
make kubectl_cert-manager-windows

清单

我们将“清单”用作对我们作为发行版一部分构建的非二进制工件的统称，包括静态安装 YAML 和我们的 Helm 图表。

所有这些都可以使用 make 构建

make helm-chart
make static-manifests

所有内容

有时在本地构建所有内容非常有用，以确保更改没有破坏某些不明显的架构，并在发起 PR 时建立信心。

在本地构建完整发行版并不容易，因为完整发行版包括依赖于 KMS 密钥配置的签名。但是，大多数用户可能不需要这样做，并且对于此用例，有一个 make 目标可以构建除签名工件之外的所有内容。

make GOMAXPROCS=2 -j4 release-artifacts