建置 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 中看到無法在本機複製的錯誤，請嘗試使用設定為 off 的 GOWORK 環境變數進行建置，或刪除 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 的端對端測試比較複雜，並有專門的文件描述其使用方法。

其他檢查

我們在每個 Pull Request 上運行各種其他工具，以檢查格式、導入順序和許可等事項。這些檢查都可以在本地運行

make ci-presubmit

注意：其中一項檢查目前需要安裝 Python 3，這是程式碼庫中的獨特要求。我們希望未來可以移除這個要求。

更新 CRD 和程式碼生成

對 cert-manager 的 CRD 進行變更需要進行一些程式碼生成，這將在每個 pull request 上進行檢查。

如果您對 cert-manager CRD 進行變更，您需要在提出 PR 之前在本地運行一些指令。

這在我們的 CRDs 部分中記錄。

建置

cert-manager 為許多不同的作業系統/架構組合產生許多成品，包括

• 容器映像檔
• 客戶端二進位檔（cmctl 和 kubectl_cert-manager）
• Manifest（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

Manifest

我們使用「manifest」作為非二進位成品的統稱，我們將其建置為發布的一部分，包括靜態安裝 YAML 和我們的 Helm 圖表。

所有內容都可以使用 make 建置

make helm-chart
make static-manifests

所有內容

有時，在本地建置所有內容會很有用，以確保變更沒有破壞某些不明顯的架構，並在提出 PR 時建立信心。

在本地建置完整版本並不容易，因為完整版本包含依賴於已設定的 KMS 金鑰的簽章。不過，大多數使用者可能不需要這樣做，而對於這種使用情況，有一個 make 目標可以建置除已簽署成品以外的所有內容

make GOMAXPROCS=2 -j4 release-artifacts