diff --git a/rfcs/NNNN-cdevents-provider/README.md b/rfcs/NNNN-cdevents-provider/README.md new file mode 100644 index 0000000000..4a38e403cb --- /dev/null +++ b/rfcs/NNNN-cdevents-provider/README.md @@ -0,0 +1,159 @@ +# Flux CDEvents Provider + + + +**Status:** provisional + + + +**Creation date:** 2024-01-19 + +**Last update:** 2024-06-05 + +## Summary + +This RFC proposes to add a `Provider` type to the Flux notification-controller API for sending +[CDEvents](https://github.com/cdevents). + +When `Provider` objects configured to send CDEvents are alerted by a Flux event, they will utilise an already defined +mapping of Flux and CDEvents events to send an appropriate CDEvent payload to a defined URL. + + +## Motivation + +CDEvents enables interoperability between supported tools in a workflow, and flux is a very popular continuous delivery +tool, as such we have received many questions about implementing CDEvents into the tool. The receiver part of this +integration is already implemented in flux 2.3.0 + + +### Goals + +Integrate [CDEvents](https://github.com/cdevents) into Flux with a CDEvents Provider that supports sending CDEvent +events. + + + +### Non-Goals + +Implementing CDEvents into every Flux controller that is not the notification controller. + + + +## Proposal + +Add CDEvents to the list of available `Providers` in Flux Notification controller. The relevant CDEvent sent by the +`Provider` will be determined by a pre-defined mapping of Flux events and relevant CDEvents. These CDEvent payloads +should have meaningful data from the source event. There will be an initial focus on HelmRelease and related events as +the format within Flux for those events is much more consistent. + + +### User Stories + +Users of multiple CI/CD tools such as Tekton and Flux could use CDEvents as a way to enable interoperability. + +For example, a user may want a Tekton `pipeline` to run once a HelmRelease flux resource has succeeded in a Helm +install. On successful helm install, Flux will emit an event with reason `InstallSucceeded` which will be mapped to an +`Environment.Modified` CDEvent. The CDEvent `Provider` will then send a payload with that CDEvent, which will also +contain data from the Flux event, to a CloudEvents broker that Tekton is subscribed to, and trigger a Pipeline Run +within Tekton. + +![User Stories Tekton](user-stories-provider.drawio.png) + + + + +### Alternatives + +There are currently no viable alternatives for the CDEvent Provider. + + +## Design Details + +Adding a Flux `Provider` for CDEvents that will send a CDEvent payload upon receiving a flux event from an alert. + +Once an alert is triggered for this provider, it will send a CDEvent that corresponds to the Flux event that caused the +alert. This CDEvent will be created using the [CDEvents Go SDK](https://github.com/cdevents/sdk-go). The implementation +will include a defined mapping of which Flux events trigger a corresponding CDEvent. + +The CDEvents broker is not a part of this design and is left to the users to set up however they wish. + +Example Provider YAML: + +```yaml +apiVersion: notification.toolkit.fluxcd.io/v1beta2 +kind: Provider +metadata: + name: cdevents-provider + namespace: flux-system +spec: + type: cdevents + secretRef: + name: generic-token + address: http://10.100.0.17:5000 +``` + +Example Default Mappings (Please note these are not final and will be open to discussion): + +| Helm Event | CDEvent | +| ------------------------- | ------------------------------- | +| InstallSucceeded | Service.Deployed | +| InstallFailed | Incident.Detected | +| UpgradeSucceeded | Service.Upgraded | +| UpgradeFailed | Incident.Detected | +| TestSucceeded | TestCaseRun.finished (outcome pass) | +| TestFailed | TestCaseRun.finished (outcome fail) | +| RollbackSucceeded | Service.RolledBack | +| RollbackFailed | Incident.Detected | +| UninstallSucceeded | Service.Removed | +| UninstallFailed | Incident.Detected | + + + +## Implementation History + + diff --git a/rfcs/NNNN-cdevents-provider/user-stories-provider.drawio.png b/rfcs/NNNN-cdevents-provider/user-stories-provider.drawio.png new file mode 100644 index 0000000000..de5d2ea097 Binary files /dev/null and b/rfcs/NNNN-cdevents-provider/user-stories-provider.drawio.png differ