diff --git a/rfcs/0006-cdevents/CDEvents-Flux-RFC-Adapter.png b/rfcs/0006-cdevents/CDEvents-Flux-RFC-Adapter.png new file mode 100644 index 0000000000..270a98a8d1 Binary files /dev/null and b/rfcs/0006-cdevents/CDEvents-Flux-RFC-Adapter.png differ diff --git a/rfcs/0006-cdevents/CDEvents-Flux-RFC-Broker.png b/rfcs/0006-cdevents/CDEvents-Flux-RFC-Broker.png new file mode 100644 index 0000000000..2d1ab50ebe Binary files /dev/null and b/rfcs/0006-cdevents/CDEvents-Flux-RFC-Broker.png differ diff --git a/rfcs/0006-cdevents/Flux-CDEvents-RFC.png b/rfcs/0006-cdevents/Flux-CDEvents-RFC.png new file mode 100644 index 0000000000..8d49225e5c Binary files /dev/null and b/rfcs/0006-cdevents/Flux-CDEvents-RFC.png differ diff --git a/rfcs/0006-cdevents/README.md b/rfcs/0006-cdevents/README.md new file mode 100644 index 0000000000..de4bc43c3b --- /dev/null +++ b/rfcs/0006-cdevents/README.md @@ -0,0 +1,135 @@ +# RFC-0006 Flux CDEvents Receiver + + + +**Status:** provisional + + + +**Creation date:** 2023-12-08 + +**Last update:** 2024-02-09 + +## Summary + +This RFC proposes to add a `receiver` type to Flux that can handle CDEvents. +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. + + +## 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. + + +### Goals + +Integrate CDEvents into Flux with a CDEvents Receiver. + + +### Non-Goals + +A CDEvent provider will be handled as a separate RFC in the future. + + + +## 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. + + + +### User Stories + + + +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`. +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. + +![usecase](cdevents-flux-tekton.png) + +### Alternatives + +Certain use cases for CDEvents could be done alternatively using available receivers such as the generic webhook. + + + +## Design Details + +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. + +Example Receiver YAML: + +```yaml +apiVersion: notification.toolkit.fluxcd.io/v1 +kind: Receiver +metadata: + name: cdevents-receiver + namespace: flux-system +spec: + type: cdevents + events: + - "dev.cdevents.change.merged" + secretRef: + name: receiver-token + resources: + - kind: GitRespository + apiVersion: source.toolkit.fluxcd.io/v1 + name: webapp + namespace: flux-system +``` + +![User Flowchart](Flux-CDEvents-RFC.png) + + + +![Adapter](CDEvents-Flux-RFC-Adapter.png) + + +## Implementation History + + diff --git a/rfcs/0006-cdevents/cdevents-flux-tekton.png b/rfcs/0006-cdevents/cdevents-flux-tekton.png new file mode 100644 index 0000000000..72223a0a1e Binary files /dev/null and b/rfcs/0006-cdevents/cdevents-flux-tekton.png differ