Implement Receiver resource filtering with CEL

api/v1/receiver_types.go

@@ -67,6 +67,11 @@ type ReceiverSpec struct {
  // +required
  Resources []CrossNamespaceObjectReference `json:"resources"`
 
+ // ResourceFilter is an expression that is applied to each Resource
+ // referenced in the Resources. If the expression returns false then the
+ // Resource is discarded and will not be notified.
+ ResourceFilter string `json:"resourceFilter,omitempty"`
+
  // SecretRef specifies the Secret containing the token used
  // to validate the payload authenticity.
  // +required

config/crd/bases/notification.toolkit.fluxcd.io_receivers.yaml

@@ -62,6 +62,12 @@ spec:
  Secret references.
  pattern: ^([0-9]+(\.[0-9]+)?(ms|s|m|h))+$
  type: string
+ resourceFilter:
+ description: |-
+ ResourceFilter is an expression that is applied to each Resource
+ referenced in the Resources. If the expression returns false then the
+ Resource is discarded and will not be notified.
+ type: string
  resources:
  description: A list of resources to be notified about changes.
  items:

docs/api/v1/notification.md

@@ -122,6 +122,19 @@ e.g. &lsquo;push&rsquo; for GitHub or &lsquo;Push Hook&rsquo; for GitLab.</p>
 </tr>
 <tr>
 <td>
+<code>resourceFilter</code><br>
+<em>
+string
+</em>
+</td>
+<td>
+<p>ResourceFilter is an expression that is applied to each Resource
+referenced in the Resources. If the expression returns false then the
+Resource is discarded and will not be notified.</p>
+</td>
+</tr>
+<tr>
+<td>
 <code>secretRef</code><br>
 <em>
 <a href="https://pkg.go.dev/github.com/fluxcd/pkg/apis/meta#LocalObjectReference">
@@ -321,6 +334,19 @@ e.g. &lsquo;push&rsquo; for GitHub or &lsquo;Push Hook&rsquo; for GitLab.</p>
 </tr>
 <tr>
 <td>
+<code>resourceFilter</code><br>
+<em>
+string
+</em>
+</td>
+<td>
+<p>ResourceFilter is an expression that is applied to each Resource
+referenced in the Resources. If the expression returns false then the
+Resource is discarded and will not be notified.</p>
+</td>
+</tr>
+<tr>
+<td>
 <code>secretRef</code><br>
 <em>
 <a href="https://pkg.go.dev/github.com/fluxcd/pkg/apis/meta#LocalObjectReference">

docs/spec/v1/receivers.md

@@ -700,6 +700,117 @@ resources:
 **Note:** Cross-namespace references [can be disabled for security
 reasons](#disabling-cross-namespace-selectors).
 
+#### Filtering reconciled objects with CEL
+
+To filter the resources that are reconciled you can use [Common Expression Language (CEL)](https://cel.dev/).
+
+For example to trigger `ImageRepositories` on notifications from [Google Artifact Regisry](https://cloud.google.com/artifact-registry/docs/configure-notifications#examples) you can define a receiver.
+
+```yaml
+apiVersion: notification.toolkit.fluxcd.io/v1
+kind: Receiver
+metadata:
+ name: gar-receiver
+ namespace: apps
+spec:
+ type: gcr
+ secretRef:
+ name: flux-gar-token
+ resources:
+ - apiVersion: image.toolkit.fluxcd.io/v1beta2
+ kind: ImageRepository
+ name: "*"
+ matchLabels:
+ registry: gar
+```
+
+This will trigger the reconciliation of all `ImageRepositories` with matching labels `registry: gar`, but if you want to only notify `ImageRepository` resources that are referenced from the incoming hook you can use CEL to filter the resources.
+
+```yaml
+apiVersion: notification.toolkit.fluxcd.io/v1
+kind: Receiver
+metadata:
+ name: gar-receiver
+ namespace: apps
+spec:
+ type: gcr
+ secretRef:
+ name: flux-gar-token
+ resources:
+ - apiVersion: image.toolkit.fluxcd.io/v1beta2
+ kind: ImageRepository
+ name: "*"
+ matchLabels:
+ registry: gar
+ resourceFilter: 'request.body.tag.contains(resource.metadata.name)'
+```
+
+If the body of the incoming hook looks like this:
+
+```json
+{
+ "action":"INSERT",
+ "digest":"us-east1-docker.pkg.dev/my-project/my-repo/hello-world@sha256:6ec128e26cd5...",
+ "tag":"us-east1-docker.pkg.dev/my-project/my-repo/hello-world:1.1"
+}
+```
+
+This simple example would match `ImageRepositories` with the name `hello-world`.
+
+If you want do do more complex processing:
+
+```yaml
+ resourceFilter: has(resource.metadata.annotations) && request.body.tag.split('/').last().split(":").first() == resource.metadata.annotations['update-image']
+```
+
+This would look for an annotation "update-image" on the resource, and match it to the `hello-world` part of the tag name.
+
+**NOTE**: Currently the `resource` value in the CEL expression only provides the object metadata, this means you can access things like `resource.metadata.labels` and `resource.metadata.annotations`.
+
+There are a number of functions available to the CEL expressions beyond the basic CEL functionality.
+
+The [Strings extension](https://github.com/google/cel-go/tree/master/ext#strings) is available.
+
+In addition the notifications-controller CEL implementation provides the following functions:
+
+#### first
+
+Returns the first element of a CEL array expression.
+
+```
+<list<any>>.first() -> <any>
+```
+
+This is syntactic sugar for `['hello', 'mellow'][0]`
+
+Examples:
+
+```
+['hello', 'mellow'].first() // returns 'hello'
+[].first() // returns nil
+'this/test'.split('/').first() // returns 'this'
+```
+
+#### last
+
+Returns the last element of a CEL array expression.
+
+```
+<list<any>>.last() -> <any>
+```
+
+Examples:
+
+```
+['hello', 'mellow'].last() // returns 'mellow'
+[].last() // returns nil
+'this/test'.split('/').last() // returns 'test'
+```
+
+This is syntactic sugar for `['hello', 'mellow'][size(['hello, 'mellow'])-1]`
+
+For zero-length array values, these will both return `nil`.
+
 ### Secret reference
 
 `.spec.secretRef.name` is a required field to specify a name reference to a

go.mod

@@ -25,6 +25,7 @@ require (
  github.com/fluxcd/pkg/ssa v0.41.1
  github.com/getsentry/sentry-go v0.29.0
  github.com/go-logr/logr v1.4.2
+ github.com/google/cel-go v0.20.1
  github.com/google/go-github/v64 v64.0.0
  github.com/hashicorp/go-retryablehttp v0.7.7
  github.com/ktrysmt/go-bitbucket v0.9.80
@@ -74,6 +75,7 @@ require (
  github.com/DataDog/zstd v1.5.2 // indirect
  github.com/MakeNowJust/heredoc v1.0.0 // indirect
  github.com/ProtonMail/go-crypto v1.0.0 // indirect
+ github.com/antlr4-go/antlr/v4 v4.13.0 // indirect
  github.com/beorn7/perks v1.0.1 // indirect
  github.com/blang/semver/v4 v4.0.0 // indirect
  github.com/cespare/xxhash/v2 v2.3.0 // indirect
@@ -159,6 +161,7 @@ require (
  github.com/russross/blackfriday/v2 v2.1.0 // indirect
  github.com/santhosh-tekuri/jsonschema/v6 v6.0.1 // indirect
  github.com/spf13/cobra v1.8.1 // indirect
+ github.com/stoewer/go-strcase v1.2.0 // indirect
  github.com/x448/float16 v0.8.4 // indirect
  github.com/xlab/treeprint v1.2.0 // indirect
  go.opencensus.io v0.24.0 // indirect

go.sum

@@ -73,6 +73,8 @@ github.com/PagerDuty/go-pagerduty v1.8.0 h1:MTFqTffIcAervB83U7Bx6HERzLbyaSPL/+ox
 github.com/PagerDuty/go-pagerduty v1.8.0/go.mod h1:nzIeAqyFSJAFkjWKvMzug0JtwDg+V+UoCWjFrfFH5mI=
 github.com/ProtonMail/go-crypto v1.0.0 h1:LRuvITjQWX+WIfr930YHG2HNfjR1uOfyf5vE0kC2U78=
 github.com/ProtonMail/go-crypto v1.0.0/go.mod h1:EjAoLdwvbIOoOQr3ihjnSoLZRtE8azugULFRteWMNc0=
+github.com/antlr4-go/antlr/v4 v4.13.0 h1:lxCg3LAv+EUK6t1i0y1V6/SLeUi0eKEKdhQAlS8TVTI=
+github.com/antlr4-go/antlr/v4 v4.13.0/go.mod h1:pfChB/xh/Unjila75QW7+VU4TSnWnnk9UTnmpPaOR2g=
 github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5 h1:0CwZNZbxp69SHPdPJAN/hZIm0C4OItdklCFmMRWYpio=
 github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5/go.mod h1:wHh0iHkYZB8zMSxRWpUBQtwG5a7fFgvEO+odwuTv2gs=
 github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
@@ -215,6 +217,8 @@ github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek
 github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
 github.com/google/btree v1.1.2 h1:xf4v41cLI2Z6FxbKm+8Bu+m8ifhj15JuZ9sa0jZCMUU=
 github.com/google/btree v1.1.2/go.mod h1:qOPhT0dTNdNzV6Z/lhRX0YXUafgPLFUh+gZMl761Gm4=
+github.com/google/cel-go v0.20.1 h1:nDx9r8S3L4pE61eDdt8igGj8rf5kjYR3ILxWIpWNi84=
+github.com/google/cel-go v0.20.1/go.mod h1:kWcIzTsPX0zmQ+H3TirHstLLf9ep5QTsZBN9u4dOYLg=
 github.com/google/gnostic-models v0.6.8 h1:yo/ABAfM5IMRsS1VnXjTBvUb61tFIHozhlYvRgGre9I=
 github.com/google/gnostic-models v0.6.8/go.mod h1:5n7qKqH0f5wFt+aWF8CW6pZLLNOfYuF5OpfBSENuI8U=
 github.com/google/go-cmp v0.2.0/go.mod h1:oXzfMopK8JAjlY9xF4vHSVASa0yLyX7SntLO5aqRK0M=
@@ -381,12 +385,15 @@ github.com/spf13/cobra v1.8.1 h1:e5/vxKd/rZsfSJMUX1agtjeTDf+qv1/JdBF8gg5k9ZM=
 github.com/spf13/cobra v1.8.1/go.mod h1:wHxEcudfqmLYa8iTfL+OuZPbBZkmvliBWKIezN3kD9Y=
 github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA=
 github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/stoewer/go-strcase v1.2.0 h1:Z2iHWqGXH00XYgqDmNgQbIBxf3wrNq0F3feEy0ainaU=
+github.com/stoewer/go-strcase v1.2.0/go.mod h1:IBiWB2sKIp3wVVQ3Y035++gc+knqhUQag1KpM8ahLw8=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
 github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
 github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
 github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.5.1/go.mod h1:5W2xD1RspED5o8YsWQXVCued0rvSQ+mT+I5cxcmMvtA=
 github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
@@ -591,6 +598,7 @@ gopkg.in/evanphx/json-patch.v4 v4.12.0 h1:n6jtcsulIzXPJaxegRbvFNNrZDjbij7ny3gmSP
 gopkg.in/evanphx/json-patch.v4 v4.12.0/go.mod h1:p8EYWUEYMpynmqDbY58zCKCFZw8pRWMG4EsWvDvM72M=
 gopkg.in/inf.v0 v0.9.1 h1:73M5CoZyi3ZLMOyDlQh031Cx6N9NDJ2Vvfl76EDAgDc=
 gopkg.in/inf.v0 v0.9.1/go.mod h1:cWUDdTG/fYaXco+Dcufb5Vnc6Gp2YChqWtbxRZE0mXw=
+gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.2.8/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
 gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=