diff --git a/docs/content/en/docs-dev/user-guide/configuration-reference.md b/docs/content/en/docs-dev/user-guide/configuration-reference.md index c712bb5d41..4327bd6b1c 100644 --- a/docs/content/en/docs-dev/user-guide/configuration-reference.md +++ b/docs/content/en/docs-dev/user-guide/configuration-reference.md @@ -37,6 +37,7 @@ spec: | notification | [DeploymentNotification](#deploymentnotification) | Additional configuration used while sending notification to external services. | No | | postSync | [PostSync](#postsync) | Additional configuration used as extra actions once the deployment is triggered. | No | | variantLabel | [KubernetesVariantLabel](#kubernetesvariantlabel) | The label will be configured to variant manifests used to distinguish them. | No | +| eventWatcher | [][EventWatcher](#eventWatcher) | List of configurations for event watcher. | No | ## Terraform application @@ -64,6 +65,7 @@ spec: | timeout | duration | The maximum length of time to execute deployment before giving up. Default is 6h. | No | | notification | [DeploymentNotification](#deploymentnotification) | Additional configuration used while sending notification to external services. | No | | postSync | [PostSync](#postsync) | Additional configuration used as extra actions once the deployment is triggered. | No | +| eventWatcher | [][EventWatcher](#eventWatcher) | List of configurations for event watcher. | No | ## Cloud Run application @@ -91,6 +93,7 @@ spec: | timeout | duration | The maximum length of time to execute deployment before giving up. Default is 6h. | No | | notification | [DeploymentNotification](#deploymentnotification) | Additional configuration used while sending notification to external services. | No | | postSync | [PostSync](#postsync) | Additional configuration used as extra actions once the deployment is triggered. | No | +| eventWatcher | [][EventWatcher](#eventWatcher) | List of configurations for event watcher. | No | ## Lambda application @@ -116,6 +119,7 @@ spec: | timeout | duration | The maximum length of time to execute deployment before giving up. Default is 6h. | No | | notification | [DeploymentNotification](#deploymentnotification) | Additional configuration used while sending notification to external services. | No | | postSync | [PostSync](#postsync) | Additional configuration used as extra actions once the deployment is triggered. | No | +| eventWatcher | [][EventWatcher](#eventWatcher) | List of configurations for event watcher. | No | ## ECS application @@ -142,6 +146,7 @@ spec: | timeout | duration | The maximum length of time to execute deployment before giving up. Default is 6h. | No | | notification | [DeploymentNotification](#deploymentnotification) | Additional configuration used while sending notification to external services. | No | | postSync | [PostSync](#postsync) | Additional configuration used as extra actions once the deployment is triggered. | No | +| eventWatcher | [][EventWatcher](#eventWatcher) | List of configurations for event watcher. | No | ## Analysis Template Configuration @@ -163,7 +168,7 @@ spec: |-|-|-|-| | metrics | map[string][AnalysisMetrics](#analysismetrics) | Template for metrics. | No | -## Event Watcher Configuration +## Event Watcher Configuration (deprecated) ```yaml apiVersion: pipecd.dev/v1beta1 @@ -636,3 +641,31 @@ A wrapper of type `int` to represent percentage data. Basically, you can pass `1 | op | string | The operation type. This must be one of `yaml-replace`, `yaml-add`, `yaml-remove`, `json-replace`, `text-regex`. Default is `yaml-replace`. | No | | path | string | The path string pointing to the manipulated field. For yaml operations it looks like `$.foo.array[0].bar`. | No | | value | string | The value string whose content will be used as new value for the field. | No | + +## EventWatcher + +| Field | Type | Description | Required | +|-|-|-|-| +| matcher | EventWatcherMatcher | Which event will be handled. | Yes | +| handler | EventWatcherHandler | What to do for the event which matched by the above matcher. | Yes | + +### EventWatcherMatcher + +| Field | Type | Description | Required | +|-|-|-|-| +| name | string | The event name. | Yes | +| labels | map[string]string | Additional attributes of event. This can make an event definition unique even if the one with the same name exists. | No | + +### EventWatcherHandler + +| Field | Type | Description | Required | +|-|-|-|-| +| type | string | The handler type. Currently, only `GIT_UPDATE` is supported. Default is `GIT_UPDATE`. | No | +| config | EventWatcherHandlerConfig | Configuration for the event watcher handler. | Yes | + +### EventWatcherHandlerConfig + +| Field | Type | Description | Required | +|-|-|-|-| +| commitMessage | string | The commit message used to push after replacing values. Default message is used if not given. | No | +| replacements | [][EventWatcherReplacement](#eventwatcherreplacement) | List of places where will be replaced when the new event matches. | Yes | diff --git a/docs/content/en/docs-dev/user-guide/event-watcher.md b/docs/content/en/docs-dev/user-guide/event-watcher.md index af3736b8c7..0d74503d7b 100644 --- a/docs/content/en/docs-dev/user-guide/event-watcher.md +++ b/docs/content/en/docs-dev/user-guide/event-watcher.md @@ -18,7 +18,8 @@ While it empowers you to build pretty versatile workflows, the canonical use cas This guide walks you through configuring Event watcher and how to push an Event. ## Prerequisites -Before we get into configuring EventWatcher, be sure to configure Piped. See [here](/docs/operator-manual/piped/configuring-event-watcher/) for more details. +If you want to use EventWatcher configuration files under the `.pipe/` directory, before we get into configuring EventWatcher, be sure to configure Piped. See [here](/docs/operator-manual/piped/configuring-event-watcher/) for more details. +In other cases, there is no prerequisite. Let's move on to Usage. ## Usage File updating can be done by registering the latest value corresponding to the Event in the Control Plane and comparing it with the current value. @@ -28,6 +29,9 @@ Therefore, you mainly need to: 1. integrate a step to push an Event to the Control Plane using `pipectl` into your CI workflow. ### 1. Defining Events +#### Use the `.pipe/` directory +>NOTE: This way is deprecated and will be removed in the future, so please use the application configuration. + Prepare EventWatcher configuration files under the `.pipe/` directory at the root of your Git repository. In that files, you define which values in which files should be updated when the Piped found out a new Event. @@ -46,6 +50,31 @@ spec: The full list of configurable `EventWatcher` fields are [here](/docs/user-guide/configuration-reference/#event-watcher-configuration). +#### Use the application configuration + +Define what to do for which event in the application configuration file of the target application. + +- `matcher`: Which event should be handled. +- `handler`: What to do for the event which is specified by matcher. + +For instance, suppose you want to update the Kubernetes manifest defined in `helloworld/deployment.yaml` when an Event with the name `helloworld-image-update` occurs: +```yaml +apiVersion: pipecd.dev/v1beta1 +kind: KubernetesApp +spec: + name: helloworld + eventWatcher: + - matcher: + name: helloworld-image-update + handler: + config: + replacements: + - file: deployment.yaml + yamlField: $.spec.template.spec.containers[0].image +``` + +The full list of configurable `eventWatcher` fields are [here](/docs-dev/user-guide/configuration-reference/#eventwatcher). + ### 2. Pushing an Event with `pipectl` To register a new value corresponding to Event such as the above in the Control Plane, you need to perform `pipectl`. And we highly recommend integrating a step for that into your CI workflow. @@ -88,6 +117,7 @@ Event watcher is a project-wide feature, hence an event name is unique inside a On the contrary, if you want to explicitly distinguish those, we recommend using labels. You can make an event definition unique by using any number of labels with arbitrary keys and values. Suppose you define an event with the labels `env: dev` and `appName: helloworld`: +When you use the `.pipe/` directory, you can configure like below. ```yaml apiVersion: pipecd.dev/v1beta1 kind: EventWatcher @@ -102,6 +132,25 @@ spec: yamlField: $.spec.template.spec.containers[0].image ``` +The other example is like below. +```yaml +apiVersion: pipecd.dev/v1beta1 +kind: ApplicationKind +spec: + name: helloworld + eventWatcher: + - matcher: + name: image-update + labels: + env: dev + appName: helloworld + handler: + config: + replacements: + - file: deployment.yaml + yamlField: $.spec.template.spec.containers[0].image +``` + The file update will be executed only when the labels are explicitly specified with the `--labels` flag. ```bash @@ -118,20 +167,27 @@ Note that it is considered a match only when labels are an exact match. ## Examples Suppose you want to update your configuration file after releasing a new Helm chart. -You define `.pipe/event-watcher.yaml` like: +You define the configuration for event watcher in `helloworld/app.pipecd.yaml` file like: ```yaml apiVersion: pipecd.dev/v1beta1 -kind: EventWatcher +kind: KubernetesApp spec: - events: - - name: helm-release - labels: - env: dev - appName: helloworld - replacements: - - file: helloworld/app.pipecd.yaml - yamlField: $.spec.input.helmChart.version + input: + helmChart: + name: helloworld + version: 0.1.0 + eventWatcher: + - matcher: + name: image-update + labels: + env: dev + appName: helloworld + handler: + config: + replacements: + - file: app.pipecd.yaml + yamlField: $.spec.input.helmChart.version ``` Push a new version `0.2.0` as data when the Helm release is completed. @@ -156,6 +212,17 @@ spec: name: helloworld - version: 0.1.0 + version: 0.2.0 + eventWatcher: + - matcher: + name: image-update + labels: + env: dev + appName: helloworld + handler: + config: + replacements: + - file: app.pipecd.yaml + yamlField: $.spec.input.helmChart.version ``` See [here](https://github.com/pipe-cd/examples/blob/master/.pipe) for more examples. diff --git a/pkg/config/event_watcher.go b/pkg/config/event_watcher.go index 427ec49ac5..ee4d6af641 100644 --- a/pkg/config/event_watcher.go +++ b/pkg/config/event_watcher.go @@ -56,7 +56,7 @@ type EventWatcherMatcher struct { type EventWatcherHandler struct { // The handler type of event watcher. Type EventWatcherHandlerType `json:"type,omitempty"` - // The config for the event watcher handler. + // The config for event watcher handler. Config EventWatcherHandlerConfig `json:"config"` }