Skip to content

Commit f17dc86

Browse files
authored
Add a blog: Introduction to EventWatcher (#5787)
* add a blog: eventwatcher-intro Signed-off-by: t-kikuc <[email protected]> * set background color Signed-off-by: t-kikuc <[email protected]> * refine title Signed-off-by: t-kikuc <[email protected]> --------- Signed-off-by: t-kikuc <[email protected]>
1 parent 5318ee5 commit f17dc86

File tree

4 files changed

+138
-0
lines changed

4 files changed

+138
-0
lines changed
Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
---
2+
date: 2025-04-28
3+
title: "Introduction to EventWatcher: Connecting CI to PipeCD"
4+
linkTitle: "Introduction to EventWatcher"
5+
weight: 983
6+
author: Tetsuya Kikuchi ([@t-kikuc](https://github.com/t-kikuc))
7+
categories: ["Introduction"]
8+
tags: ["Feature Guide"]
9+
---
10+
11+
This article explains the basics of "**EventWatcher**", a crucial feature in practical PipeCD usage.
12+
13+
This article is intended for those who:
14+
- "Don't know how to integrate CI with PipeCD"
15+
- "Have found the EventWatcher feature but can't grasp how it works"
16+
17+
_This article is based on PipeCD v0.51.2 (latest at the time of writing)._
18+
19+
## Background: Why EventWatcher is needed
20+
21+
Basically, PipeCD is a CD tool that continuously deploys specified config/manifests.
22+
23+
![](/images/eventwatcher-only-cd.drawio.png)
24+
25+
Deployment typically requires manifest changes. So, how can we "**deploy using a new image (etc.) after CI completion**"? It's annoying to update the manifest repo manually each time.
26+
27+
![](/images/eventwatcher-problem.drawio.png)
28+
29+
This is where the EventWatcher feature comes into play!
30+
31+
## What is EventWatcher?
32+
33+
EventWatcher is a feature in PipeCD that seamlessly connects CI and CD. It updates the manifest repo based on events from CI, triggering CD.
34+
35+
https://pipecd.dev/docs-v0.51.x/user-guide/event-watcher/
36+
37+
### Mechanism
38+
39+
The overall picture of EventWatcher looks like the diagram below.
40+
41+
![](/images/eventwatcher-overview.drawio.png)
42+
43+
The EventWatcher feature itself handles steps 4-6:
44+
45+
- 1-3. Develop new app code and store the results (container images, etc.) in a container registry
46+
- **4.** Publish an event in CI to pass the new image URI to PipeCD
47+
- **5.** Piped detects the event
48+
- **6.** Update the manifest repo using the data provided by the event (image URI, etc.)
49+
50+
- 7-8. Automatic deployment occurs through the standard deployment flow of PipeCD
51+
52+
## Usage
53+
54+
You need to setup three areas:
55+
56+
#### 1. Piped Configuration
57+
58+
1. Which manifest repo events to handle
59+
2. Commit permissions for the manifest repo
60+
61+
https://pipecd.dev/docs-v0.51.x/user-guide/managing-piped/configuring-event-watcher/
62+
63+
#### 2. app.pipecd.yaml Configuration
64+
65+
1. Which events to handle for the Application (`matcher`)
66+
2. What actions to take for matched events (`handler`)
67+
68+
(Example) Configuration to update the `spec.template.spec.containers[0].image` field in `deployment.yaml` when the `helloworld-image-update` event is triggered:
69+
70+
```yaml
71+
apiVersion: pipecd.dev/v1beta1
72+
kind: KubernetesApp
73+
spec:
74+
name: helloworld
75+
eventWatcher:
76+
- matcher: # Which events to handle
77+
name: helloworld-image-update
78+
handler: # What actions to take
79+
type: GIT_UPDATE
80+
config:
81+
replacements:
82+
- file: deployment.yaml
83+
yamlField: $.spec.template.spec.containers[0].image
84+
```
85+
86+
Full configuration reference:
87+
https://pipecd.dev/docs-v0.51.x/user-guide/configuration-reference/#eventwatcher
88+
89+
#### 3. Event Triggering via pipectl or GitHub Actions
90+
91+
1. Event name (set in `app.pipecd.yaml` as `matcher.name`)
92+
2. New value (image URI, etc.)
93+
94+
(Example) Command to trigger an event named `helloworld-image-update` to change the image URI to `ghcr.io/xxx/helloworld:v0.2.0`:
95+
96+
```sh
97+
pipectl event register \
98+
--address={CONTROL_PLANE_API_ADDRESS} \
99+
--api-key={API_KEY} \
100+
--name=helloworld-image-update \
101+
--data=ghcr.io/xxx/helloworld:v0.2.0
102+
```
103+
104+
If you use GitHub Actions for your CI, using PipeCD's official `actions-event-register` is recommended (configurations are the same):
105+
106+
https://github.com/marketplace/actions/pipecd-register-event
107+
108+
For example, triggering an event named `helloworld-image-update` to change the image URI to `ghcr.io/xxx/helloworld:v0.2.0`:
109+
```yaml
110+
- uses: pipe-cd/[email protected]
111+
with:
112+
api-address: ${{ secrets.API_ADDRESS }}
113+
api-key: ${{ secrets.API_KEY }}
114+
event-name: helloworld-image-update
115+
data: ghcr.io/xxx/helloworld:v0.2.0
116+
```
117+
118+
You can also handle events differently by environment using the `--labels` option, even for events with the same name.
119+
120+
##### Advanced: `--contexts` Option
121+
122+
Adding `--contexts` to `pipectl event register` allows you to include various information in the manifest repo commit. For example, passing the **"commit hash and URL of the app repo that triggered the event"** makes it easier to track "which app repo changes caused this event" in the manifest repo. This is particularly useful when deployments occur frequently.
123+
124+
https://pipecd.dev/docs-v0.51.x/user-guide/event-watcher/#optional-using-contexts
125+
126+
## Appendix: Code Reading
127+
128+
The EventWatcher code is consolidated in one file (though it's quite long). Remembering that "EventWatcher runs continuously as a goroutine from Piped startup" makes it slightly easier to read.
129+
130+
https://github.com/pipe-cd/pipecd/blob/v0.50.2/pkg/app/piped/eventwatcher/eventwatcher.go
131+
132+
## Conclusion
133+
134+
Using EventWatcher enables seamless integration between CI and CD. There are various advanced applications, and it would be great to see more examples being shared.
135+
136+
Additionally, **Deployment Traces** feature enhances the integration of CI and PipeCD. For more details, please see this article:
137+
138+
https://pipecd.dev/blog/2024/12/26/the-gap-between-ci/cd-and-how-pipecd-appeared-to-fulfill-the-gap/
Loading
Loading
Loading

0 commit comments

Comments
 (0)