新着: プロジェクトの最新情報をTwitterとMastodonで入手してください。

cert-manager のビルド

cert-managerは、可能な限り標準のGoツールを使用し、システムの依存関係を最小限に抑えることに重点を置いて、makeを使用して構築およびテストされています。cert-managerのビルドシステムは、必要に応じて、Goを含むほとんどの依存関係を自動的にプロビジョニングできます。

cert-managerのビルドシステムは、Linux amd64、macOS amd64、およびmacOS arm64を使用する開発者を完全にサポートしています。

Linux arm64も限定的にサポートしていますが、このプラットフォームはほとんどテストされておらず、完全にはサポートされていません。

他のオペレーティングシステムやアーキテクチャでも動作する可能性がありますが、開発するにはハックや回避策が必要になる可能性があります。

前提条件

cert-managerの開発に必要な要件は非常に少なく、特にビルドシステムは、不足しているものがあれば、わかりやすいエラーメッセージで知らせてくれます。依存関係の欠落に関するエラーメッセージが役に立たないと思われる場合は、それをバグとみなし、issueを提起して教えていただけると幸いです！

cert-managerの開発を開始する前に、次のツールをインストールする必要があります

macOSに関する注意事項

cert-managerはmacOSでの開発をサポートしていますが、注意すべき点がいくつかあります。

  1. cert-managerのMakefile設定ではbashを使用していますが、macOSのシステムバージョンのbashは非常に古いものです。 homebrewからbashをインストールすることをお勧めします。インストールしないと、Makefileでパフォーマンスが非常に低下する可能性があります。
  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呼び出しに使用される「sticky」になります。

システムの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モジュールのreplaceステートメントがあります。

このセットアップは、これらのサブモジュールがサードパーティによってインポートされることを意図していないことを伝え、各サブモジュールが常に同じコミット時にcert-managerコアモジュールのバージョンを使用するようにするためのものです。ただし、この構造には、特定の開発ツールやスクリプトが期待どおりに動作しないという副作用が生じる可能性があります。

例として、go test ./...は、デフォルトではコアモジュールのみに影響します。たとえば、コントローラーをテストするには、cd cmd/controller && go test ./...を使用する必要があります。

これは、ローカルの置換を処理し、VS Codeなどのエディターでより適切に動作するgoワークスペースを使用することで回避できます。

make go-workspaceを実行してgo.workファイルを生成できます。これにより、go test ./...がリポジトリ全体で動作し、エディターがモジュール構造を理解できるようになります。

goワークスペースは、CIでプルリクエストをテストするときには使用されないことに注意してください。ローカルで再現できないCIでエラーが発生する場合は、GOWORK環境変数をoffに設定するか、go.workファイルを削除してビルドしてみてください。

並列処理

cert-managerのMakefileは、可能な限り高度に並列化されるように設計されています。すべてのビルドコマンドとテストコマンドは、標準のMake機能を使用して並行して実行できる必要があります。

重要な注意点の1つは、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でテストした際に壊れる心配はほとんどないはずです。

クラスター内でローカルの変更を実行する

手動テストのために、ローカルで変更したcert-managerのコピーを組み込んだローカルKubernetesクラスタを実行したい場合があるでしょう。

これを支援する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

注：これらのチェックの1つは現在、コードベースに固有の要件であるPython 3がインストールされている必要があります。将来的にはその要件を削除したいと考えています。

CRDの更新とコード生成

cert-managerのCRDの変更には、コード生成が必要であり、これはすべてのプルリクエストでチェックされます。

cert-managerのCRDに変更を加える場合は、PRを提出する前にローカルでいくつかのコマンドを実行する必要があります。

これについては、CRDセクションで説明されています。

ビルド

cert-managerは、次のような、さまざまなOS/アーキテクチャの組み合わせに対応する多数の成果物を生成します。

  • コンテナイメージ
  • クライアントバイナリ（cmctlおよびkubectl_cert-manager）
  • マニフェスト（Helmチャート、静的YAML）

これらの成果物はすべて、makeを使用してローカルでビルドできます。

コンテナ

cert-managerの最も重要な成果物は、クラスタ内でcert-managerを実際に実行するコンテナです。デフォルトでは、これにはdockerを使用しますが、podmanなどのdocker互換のCLIツールもサポートすることを目指しています。詳細については、コンテナエンジンを参照してください。

ローカルでさまざまな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