本記事では、PipeCDの実運用において非常に重要な「EventWatcher」という機能の基礎を解説します。
- 「PipeCDを使う時に、CIとの連携方法が分からない🫤」
- 「EventWatcherなる機能にたどり着いたが、動作イメージが掴めない🫤」
という方に読んでいただければと思います。
EventWatcherが必要となる背景
PipeCDはCDツールであり、指定されたconfig/manifestを継続的にデプロイします。
PipeCDの基本的なデプロイフロー
デプロイのためにはmanifestの変更が原則必要であり、CIからの直接Pushでデプロイを起動するわけではないです。
では「アプリのCIが完了したら、その新しいイメージ(等)を利用してデプロイ」するには、どうすればよいでしょうか？
都度manifest repoに手動で更新をかけるのは面倒です。
CIからCDに繋ぐには？
ここで登場するのが、EventWatcher機能です。
EventWatcherとは
EventWatcherは、PipeCDにおいてCIとCDとをシームレスに繋ぐための機能です。
CI等からのイベントに基づいてmanifest repoを更新し、CDに繋げます。図を見た方が分かりやすいです。
仕組み
EventWatcherの全体像は下図のようになっています。初見だとフローが分かりにくいです。
EventWatcherの処理フロー(4〜6)
EventWatcher機能自体は4~6.の処理を担っています。
1~3. 新しいappコードを開発し、その結果(コンテナイメージ等)をコンテナレジストリなどに格納する
4. CIの中でイベントを発行し、新しいイメージURIをPipeCDに伝達する
5. Pipedがイベントを検知する
6. 新しいイメージURIに書き換えて、manifest repoにCommitする
7~8. PipeCDの標準的なデプロイフローにより、自動でデプロイされる
使い方
設定・コマンドは大きく3点必要です。
1. Pipedの設定
- どのmanifest repo向けのイベントをハンドリングするか
- manifest repoへのCommit権限系
2. app.pipecd.yamlの設定
- そのApplicationでどのイベントをハンドルするか (
matcher) -
matcherにマッチしたイベントに対して、どんな処理を行うか (handler)
（例）helloworld-image-updateというイベントが発火されると、deployment.yamlのspec.template.spec.containers[0].imageフィールドを更新する設定：
apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
name: helloworld
eventWatcher:
- matcher: # どのイベントをハンドルするか
name: helloworld-image-update
handler: # どんな処理を行うか
type: GIT_UPDATE
config:
replacements:
- file: deployment.yaml
yamlField: $.spec.template.spec.containers[0].image
設定項目の一覧はこちら：
3. pipectl or GitHub Actionsによるイベント発火
- イベント名 (
app.pipecd.yamlで設定したmatcher.name) - 新しい値 (イメージURI等)
（例）helloworld-image-updateという名前で、イメージURIをghcr.io/xxx/helloworld:v0.2.0に変更させるためのイベント：
pipectl event register \
--address={CONTROL_PLANE_API_ADDRESS} \
--api-key={API_KEY} \
--name=helloworld-image-update \
--data=ghcr.io/xxx/helloworld:v0.2.0
GitHub Actionsからイベントを発火する場合は、PipeCD公式のactions-event-registerの利用がおすすめです。（設定項目は同じです）
また、--labelsによって、同名イベントでも環境別にイベントハンドリングなども可能です。
応用的な使い方: --contextsオプション
pipectl event register実行時に--contextsを追加することで、manifest repoへのCommit時に様々な情報を追加できます。
例えば、「イベントを発火したapp repoのcommit hashやURL」を渡すことで、manifest repoにおいて「このイベントがどのapp repoの変更によって発生したのか」を追跡しやすくなります。デプロイが頻繁に発生する場合に便利です。
Appendix: コードリーディング
EventWatcherのコードは1ファイルにまとまっています。（が、かなり長いです）
EventWatcherが「Piped起動時から常にgoroutineとして動作し続けていること」を頭に入れておくと、少し読みやすくなると思います。
おわりに
EventWatcherを使うことで、CIからCDへの連携をシームレスに行えます。様々な応用方法があるので、事例がどんどん公開されると嬉しいです。
また、CIとPipeCDとの連携をより充実させるための計画が進行中です。詳しくはこちらの記事をご覧ください：
関連記事
- replacementでのエスケープ方法:
-
--contexts, git trailerの詳細:
Discussion