@ -13,81 +9,71 @@ Must be one of `provisional`, `implementable`, `implemented`, `deferred`, `rejec
**Creation date:** 2023-12-08
**Creation date:** 2023-12-08
**Last update:** 2024-02-09
**Last update:** 2024-03-13
## Summary
## Summary
This RFC proposes to add a `receiver` type to Flux that can handle CDEvents.
This RFC proposes to add a `Receiver` type to the Flux notification-controller API
The `receiver` will receive `CDEvent` events, sent to the receiver's webhook URL. It will verify the received events, check their `event type`, and eventually trigger reconciliation of the configured resources.
for handling [CDEvents](https://cdevents.dev/).
<!--
One paragraph explanation of the proposed feature or enhancement.
For `Receiver` objects configured to accept CDEvents,
-->
notification-controller will verify the events sent to the receiver's webhook URL,
check that their type matches the expected type, and trigger the reconciliation
of the configured resources.
## Motivation
## Motivation
CDEvents enables interoperability between supported tools in a workflow, and flux is a very popular continuous delivery tool, and consequently we have received many questions about implementing CDEvents into the tool.
CDEvents enables interoperability between CI/CD tools in a workflow, and Flux is a
<!--
very popular continuous delivery tool, and consequently the CDF team received many questions
This section is for explicitly listing the motivation, goals, and non-goals of
about integrating CDEvents with Flux.
this RFC. Describe why the change is important and the benefits to users.
-->
### Goals
### Goals
Integrate CDEvents into Flux with a CDEvents Receiver.
Allow Flux to receive CDEvents and trigger the reconciliation of resources based on the received events.
<!--
List the specific goals of this RFC. What is it trying to achieve? How will we
know that this has succeeded?
-->
### Non-Goals
### Non-Goals
A CDEvent provider will be handled as a separate RFC in the future.
Make the Flux controllers emit CDEvents.
<!--
What is out of scope for this RFC? Listing non-goals helps to focus discussion
and make progress.
-->
## Proposal
## Proposal
Add CDEvents to the list of available receivers in Flux Notification controller. Similar to other receivers such as the github, the user will be able to use `spec.events` in order to specify which event types the receiver will allow. The receiver will also verify using the [CDEvents Go SDK](https://github.com/cdevents/sdk-go) that the payload sent to the webhook URL is a valid CDEvent.
Add CDEvents to the list of available receivers in Flux notification-controller.
Similar to other receivers such as GitHub, Flux users will be able to use `spec.events`
<!--
in order to specify which event types the receiver will allow.
This is where we get down to the specifics of what the proposal actually is.
The receiver will also verify using the [CDEvents Go SDK](https://github.com/cdevents/sdk-go) that the
This should have enough detail that reviewers can understand exactly what
payload sent to the webhook URL is a valid CDEvent.
you're proposing, but should not include things like API designs or
implementation.
If the RFC goal is to document best practices,
then this section can be replaced with the actual documentation.
-->
### User Stories
### User Stories
<!--
Users of multiple CI/CD tools such as Tekton and Flux
Optional if existing discussions and/or issues are linked in the motivation section.
could use CDEvents as a way to enable interoperability.
-->
Users of multiple different CI/CD tools such as Tekton and Flux could use CDEvents as a potential way to enable interoperability. For example, a user may want a Flux resource to reconcile as part of a Tekton `pipeline`.
For example, a user may want a Flux resource to reconcile as part of a Tekton `pipeline`.
The Tekton `pipeline` will fire off a CDEvent to the CloudEvents Broker. A subscription that the user will have set up externally, e.g. with the [knative broker](https://knative.dev/docs/eventing/brokers/) will then send a relevant CDEvent to the CDEvent Receiver within Flux.
The Tekton `pipeline` will fire off a CDEvent to the CloudEvents Broker.
A subscription that the user will have set up externally, e.g. with the [knative broker](https://knative.dev/docs/eventing/brokers/), will then
send a relevant CDEvent to the Flux webhook receiver endpoint.
### Alternatives
### Alternatives
Certain use cases for CDEvents could be done alternatively using available receivers such as the generic webhook.
Certain use cases for CDEvents could be done alternatively using
available receivers such as the generic webhook.
<!--
## Design Details
List plausible alternatives to the proposal and explain why the proposal is superior.
This is a good place to incorporate suggestions made during discussion of the RFC.
Adding a Flux `Receiver` for CDEvents that works much like the other event-based receivers already implemented.
-->
## Design Details
The user will be able to define a Flux `Receiver` custom resource and deploy it to their cluster.
The receiver takes the payload sent to the webhook URL by an external events broker,
checks the headers for the event type, and filters out events based on the user-defined
list of events in `spec.events`. If left empty, it will act on all valid CDEvents.
It then validates the payload body using the [CDEvents Go SDK](https://github.com/cdevents/sdk-go).
Valid events will then trigger the reconciliation of all Flux objects specified in `.spec.resources`.
Adding a receiver for CDEvents that works much like the other event-based receivers already implemented. The user will be able to write a yaml file for the receiver and deploy it to their cluster. The receiver takes the payload sent to the webhook URL by an external events broker, checks the headers for the event type, and filters out events based on the user-defined list of events in spec.Events. If left empty, it will act on all valid CDEvents. It then validates the payload body using the [CDEvents Go SDK](https://github.com/cdevents/sdk-go). Valid events will then trigger reconciliation of the resources. The events broker is not a part of this design and is left to the user to set up however they wish.
The CDEvents broker is not a part of this design and is left to the users to set up however they wish.
Example Receiver YAML:
Example Receiver:
```yaml
```yaml
apiVersion: notification.toolkit.fluxcd.io/v1
apiVersion: notification.toolkit.fluxcd.io/v1
@ -102,26 +88,14 @@ spec:
secretRef:
secretRef:
name: receiver-token
name: receiver-token
resources:
resources:
- kind: GitRespository
- apiVersion: source.toolkit.fluxcd.io/v1
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
name: webapp
name: webapp
namespace: flux-system
namespace: flux-system
```
```
<!--
This section should contain enough information that the specifics of your
change are understandable. This may include API specs and code snippets.
The design details should address at least the following questions:
- How can this feature be enabled / disabled?
- Does enabling the feature change any default behavior?
- Can the feature be disabled once it has been enabled?
- How can an operator determine if the feature is in use?
- Are there any drawbacks when enabling this feature?
Stefan Prodan
10 months ago
committed by
GitHub
