Implement Receiver resource filtering with CEL

api/v1/condition_types.go

@@ -28,4 +28,8 @@ const (
 
 	// TokenNotFoundReason represents the fact that receiver token can't be found.
 	TokenNotFoundReason string = "TokenNotFound"
+
+	// InvalidCELExpressionReason represents the fact that the CEL resource
+	// filter is invalid.
+	InvalidCELExpressionReason string = "InvalidCELExpression"
 )

api/v1/receiver_types.go

@@ -67,6 +67,11 @@ type ReceiverSpec struct {
 	// +required
 	Resources []CrossNamespaceObjectReference `json:"resources"`
 
+	// ResourceFilter is a CEL expression that is applied to each Resource
+	// referenced in the Resources. If the expression returns false then the
+	// Resource 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 a CEL expression that is applied to each Resource
+                  referenced in the Resources. If the expression returns false then the
+                  Resource 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 a CEL expression that is applied to each Resource
+referenced in the Resources. If the expression returns false then the
+Resource 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 a CEL expression that is applied to each Resource
+referenced in the Resources. If the expression returns false then the
+Resource 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 Registry](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` containing the name `hello-world`.
+
+If you want to 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` and `resource.metadata.name`.
+
+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.43.0
 	github.com/getsentry/sentry-go v0.30.0
 	github.com/go-logr/logr v1.4.2
+	github.com/google/cel-go v0.22.0
 	github.com/google/go-github/v64 v64.0.0
 	github.com/hashicorp/go-retryablehttp v0.7.7
 	github.com/ktrysmt/go-bitbucket v0.9.81
@@ -51,6 +52,7 @@ require (
 replace gopkg.in/yaml.v3 => gopkg.in/yaml.v3 v3.0.1
 
 require (
+	cel.dev/expr v0.18.0 // indirect
 	cloud.google.com/go v0.116.0 // indirect
 	cloud.google.com/go/auth v0.12.1 // indirect
 	cloud.google.com/go/auth/oauth2adapt v0.2.6 // indirect
@@ -74,6 +76,7 @@ require (
 	github.com/DataDog/zstd v1.5.2 // indirect
 	github.com/MakeNowJust/heredoc v1.0.0 // indirect
 	github.com/ProtonMail/go-crypto v1.1.3 // 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/bradleyfalzon/ghinstallation/v2 v2.12.0 // indirect
@@ -158,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.3.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

@@ -1,3 +1,5 @@
+cel.dev/expr v0.18.0 h1:CJ6drgk+Hf96lkLikr4rFf19WrU0BOWEihyZnI2TAzo=
+cel.dev/expr v0.18.0/go.mod h1:MrpN08Q+lEBs+bGYdLxxHkZoUSsCp0nSKTs0nTymJgw=
 cloud.google.com/go v0.26.0/go.mod h1:aQUYkXzVsufM+DwF1aE+0xfcU+56JwCaLick0ClmMTw=
 cloud.google.com/go v0.116.0 h1:B3fRrSDkLRt5qSHWe40ERJvhvnQwdZiHu0bJOpldweE=
 cloud.google.com/go v0.116.0/go.mod h1:cEPSRWPzZEswwdr9BxE6ChEn01dWlTaF05LiC2Xs70U=
@@ -77,6 +79,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.1.3 h1:nRBOetoydLeUb4nHajyO2bKqMLfWQ/ZPwkXqXxPxCFk=
 github.com/ProtonMail/go-crypto v1.1.3/go.mod h1:rA3QumHc/FZ8pAHreoekgiAbzpNsfQAosU5td4SnOrE=
+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=
@@ -222,6 +226,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.22.0 h1:b3FJZxpiv1vTMo2/5RDUqAHPxkT8mmMfJIrq1llbf7g=
+github.com/google/cel-go v0.22.0/go.mod h1:BuznPXXfQDpXKWQ9sPW3TzlAJN5zzFe+i9tIs0yC4s8=
 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=
@@ -391,6 +397,8 @@ 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.3.0 h1:g0eASXYtp+yvN9fK8sH94oCIk0fau9uV1/ZdJ0AVEzs=
+github.com/stoewer/go-strcase v1.3.0/go.mod h1:fAH5hQ5pehh+j3nZfvwdk2RgEgQjAoM8wodgtPmh1xo=
 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=

internal/controller/receiver_controller.go

@@ -156,6 +156,8 @@ func (r *ReceiverReconciler) Reconcile(ctx context.Context, req ctrl.Request) (r
 // reconcile steps through the actual reconciliation tasks for the object, it returns early on the first step that
 // produces an error.
 func (r *ReceiverReconciler) reconcile(ctx context.Context, obj *apiv1.Receiver) (ctrl.Result, error) {
+	log := ctrl.LoggerFrom(ctx)
+
 	// Mark the resource as under reconciliation.
 	conditions.MarkReconciling(obj, meta.ProgressingReason, "Reconciliation in progress")
 
@@ -166,6 +168,16 @@ func (r *ReceiverReconciler) reconcile(ctx context.Context, obj *apiv1.Receiver)
 		return ctrl.Result{Requeue: true}, err
 	}
 
+	if filter := obj.Spec.ResourceFilter; filter != "" {
+		err := server.ValidateCELExpression(filter)
+		if err != nil {
+			conditions.MarkFalse(obj, meta.ReadyCondition, apiv1.InvalidCELExpressionReason, "%s", err)
+			obj.Status.WebhookPath = ""
+			log.Error(err, "parsing CEL resource filter expression")
+			return ctrl.Result{}, nil
+		}
+	}
+
 	webhookPath := obj.GetWebhookPath(token)
 	msg := fmt.Sprintf("Receiver initialized for path: %s", webhookPath)
 

internal/controller/receiver_controller_test.go

@@ -144,6 +144,43 @@ func TestReceiverReconciler_Reconcile(t *testing.T) {
 		g.Expect(resultR.Spec.Interval.Duration).To(BeIdenticalTo(10 * time.Minute))
 	})
 
+	t.Run("fails with invalid CEL resource filter", func(t *testing.T) {
+		g := NewWithT(t)
+		g.Expect(k8sClient.Get(context.Background(), client.ObjectKeyFromObject(receiver), resultR)).To(Succeed())
+
+		// Incomplete CEL expression
+		patch := []byte(`{"spec":{"resourceFilter":"has(resource.metadata.annotations"}}`)
+		g.Expect(k8sClient.Patch(context.Background(), resultR, client.RawPatch(types.MergePatchType, patch))).To(Succeed())
+
+		g.Eventually(func() bool {
+			_ = k8sClient.Get(context.Background(), client.ObjectKeyFromObject(receiver), resultR)
+			return !conditions.IsReady(resultR)
+		}, timeout, time.Second).Should(BeTrue())
+
+		g.Expect(conditions.GetReason(resultR, meta.ReadyCondition)).To(BeIdenticalTo(apiv1.InvalidCELExpressionReason))
+		g.Expect(conditions.GetMessage(resultR, meta.ReadyCondition)).To(ContainSubstring("annotations"))
+
+		g.Expect(conditions.Has(resultR, meta.ReconcilingCondition)).To(BeTrue())
+		g.Expect(conditions.GetReason(resultR, meta.ReconcilingCondition)).To(BeIdenticalTo(meta.ProgressingWithRetryReason))
+		g.Expect(conditions.GetObservedGeneration(resultR, meta.ReconcilingCondition)).To(BeIdenticalTo(resultR.Generation))
+	})
+
+	t.Run("recovers when the CEL expression is valid", func(t *testing.T) {
+		g := NewWithT(t)
+		// Incomplete CEL expression
+		patch := []byte(`{"spec":{"resourceFilter":"has(resource.metadata.annotations)"}}`)
+		g.Expect(k8sClient.Patch(context.Background(), resultR, client.RawPatch(types.MergePatchType, patch))).To(Succeed())
+
+		g.Eventually(func() bool {
+			_ = k8sClient.Get(context.Background(), client.ObjectKeyFromObject(receiver), resultR)
+			return conditions.IsReady(resultR)
+		}, timeout, time.Second).Should(BeTrue())
+
+		g.Expect(conditions.GetObservedGeneration(resultR, meta.ReadyCondition)).To(BeIdenticalTo(resultR.Generation))
+		g.Expect(resultR.Status.ObservedGeneration).To(BeIdenticalTo(resultR.Generation))
+		g.Expect(conditions.Has(resultR, meta.ReconcilingCondition)).To(BeFalse())
+	})
+
 	t.Run("fails with secret not found error", func(t *testing.T) {
 		g := NewWithT(t)