Flux CD change integration

Plan requirement: This feature requires an On-call Standard or higher subscription. Learn more

Flux’s kustomize-controller and helm-controller emit events when they apply a new revision, and the notification-controller generic Provider can push those events out as JSON. This integration receives them: each Git or OCI revision that a Kustomization applies, and each chart version that a HelmRelease installs or upgrades, becomes one Flashduty change.

Kustomization: recorded as Processing when the revision starts to apply, updated to Done when the reconciliation succeeds, and to Failed when it fails
HelmRelease: helm-controller only sends an event when an action ends, so Flashduty records the change directly as Done or Failed

Flashduty doesn’t record other kinds of events (GitRepository, HelmChart, ImageUpdateAutomation, and so on) or events without a revision, such as an invalid Kustomization spec or a missing source. A Flux Provider can also push the same events as alerts. See Flux CD alert integration; you can use both integrations at the same time.

Configure flux

The steps below need Kubernetes permission to create Providers, Alerts, and Secrets in the flux-system namespace (or the namespace where you keep notification config). The notification-controller must be able to reach the domain of the push URL.

Create a Secret that holds the push URL

The push URL contains the integration_key, so do not write it into the Provider. Store it under the address key of a Secret:

kubectl -n flux-system create secret generic flashduty-change \
  --from-literal=address='{integration_url}'

Create the Provider and Alert

Save the following as flashduty-change.yaml and run kubectl apply -f flashduty-change.yaml:

apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Provider
metadata:
  name: flashduty-change
  namespace: flux-system
spec:
  type: generic
  secretRef:
    name: flashduty-change
---
apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Alert
metadata:
  name: flashduty-change
  namespace: flux-system
spec:
  providerRef:
    name: flashduty-change
  eventSeverity: info
  eventSources:
    - kind: Kustomization
      name: '*'
      namespace: flux-system
    - kind: HelmRelease
      name: '*'
      namespace: flux-system
  eventMetadata:
    cluster: prod-eu

eventSeverity must be info. Flux’s info level includes error events; with error you would miss the start and success events, and changes could never finish
List eventSources for the scope you need: name: '*' matches every object of that kind in the namespace, and objects in other namespaces need their own entry with namespace
The keys and values in eventMetadata are written to the change as labels. Use them for cluster, env, and other information the Flux event does not carry, to tell clusters apart and to match in routes. Use the same values in every Alert of one cluster
The Provider type can also be generic-hmac, which adds an X-Signature header; Flashduty does not verify that header

Verify the change record

Flux has no way to send a test message. Change the source of a Kustomization that the Alert selects, for example by committing to its Git repository. Confirm the change appears in the Flashduty change list. When the Kustomization applies the new revision, the change updates to Done. Use these commands to check that the Provider and Alert are ready and to see why a push failed:

kubectl -n flux-system get provider,alert
kubectl -n flux-system describe alert flashduty-change

How changes are merged

One change is one revision applied by one Flux object (a Kustomization or HelmRelease). For a Kustomization the revision is that of its source (GitRepository, OCIRepository, or Bucket), such as main@sha1:731f7ead...; for a HelmRelease it is the chart version, such as 6.5.4.

The start, success, and failure of one revision update the same change
Two revisions of the same object are two changes
Same-named objects in different clusters, and objects deleted and recreated, are never merged
A HelmRelease uninstall (UninstallSucceeded, UninstallFailed) is a separate change

Flux events carry no operation ID, so in two cases Flashduty updates an existing change instead of creating one:

The same revision is applied again. This happens when you edit the Kustomization or HelmRelease without changing the revision, roll back to an earlier revision, or retry after a failure
A HelmRelease changes only its values and keeps the chart version: the upgrade event belongs to the same change as the previous install or upgrade

Status mapping

Kustomization

Event	Flashduty change status
`severity` is `info` and `reason` is `Progressing` (resources applied, resources pruned, health check passed)	Processing
`severity` is `info` and `reason` is `ReconciliationSucceeded`	Done
`severity` is `error`, any `reason` (`BuildFailed`, `HealthCheckFailed`, `PruneFailed`, `ReconciliationFailed`, and so on)	Failed

HelmRelease

`reason`	Flashduty change status
`InstallSucceeded`, `UpgradeSucceeded`, `TestSucceeded`, `RollbackSucceeded`, `UninstallSucceeded`	Done
`InstallFailed`, `UpgradeFailed`, `TestFailed`, `RollbackFailed`, `UninstallFailed`	Failed

Done and Failed are end states, and Flashduty records the change’s end time. These events return success, but Flashduty doesn’t record them:

severity trace
The Kustomization reasons DependencyNotReady and HealthCheckCanceled
The HelmRelease reasons PendingRelease (a stuck release unlocked), DriftCorrected, DriftCorrectionFailed (drift repair), and HealthCheckCanceled
Every event without a revision

Any other reason or severity is rejected.

Change content

Title: <namespace>/<object name>: apply <revision> (<kind>), for example apps/webapp: apply main@sha1:731f7ea (Kustomization); a HelmRelease uninstall reads uninstall. Git commit IDs are shortened to 7 characters in the title
Link: Flux events carry no web address, so changes have no link

Use labels for routing and for filtering the change list:

Label	Description
`kind`	`Kustomization` or `HelmRelease`
`name`	Object name
`namespace`	Namespace of the object
`object_id`	The object’s `metadata.uid`
`revision`	Revision
`origin_revision`	Original revision of the source (when Flux provides it)
`app_version`	Application version of the chart (HelmRelease)
`oci_digest`	OCI digest of the chart (HelmRelease, OCI repositories)
`reason`	`reason` of the latest event
`message`	Message of the latest event, truncated at 1024 bytes
Others	Keys and values from the Alert’s `eventMetadata`, such as `cluster`

Give every event of one revision the same routing labels by using the same eventMetadata in all Alerts. Otherwise, later events may land in another channel and start a second change.

FAQ

Why don't I see any changes?

Run kubectl -n flux-system describe alert flashduty-change. A failed push shows a NotificationDispatchFailed event with the reason
Confirm the Alert’s eventSources include the namespace of the object and that eventSeverity is info
When the resources a Kustomization applies have not changed, it only sends ReconciliationSucceeded and no Progressing
The notification-controller rate limits events with identical content (5 minutes by default), so rate limiting duplicate events in its log is normal

Why is there an event every reconcile interval?

kustomize-controller sends ReconciliationSucceeded after every successful reconciliation, so a revision that is already Done keeps gaining events with each interval while its status stays the same. For the same reason, right after you set this up, the revision each Kustomization currently uses is recorded as a Done change, even though nothing was applied at that moment.

Why do HelmRelease changes have no Processing state?

helm-controller only sends an event when an install, upgrade, test, rollback, or uninstall ends. It sends nothing while the action runs, so Flashduty records the change directly as Done or Failed.

A push returned 400 with 'is not supported' in the message?

The response names the unsupported field: severity "..." is not supported, want info or error, reason "..." is not supported for a Kustomization or for a HelmRelease, involvedObject.uid is required, or timestamp "..." is not an RFC 3339 time. This happens when a Flux release adds a new reason; contact us to add the mapping. That event is not recorded, and later known events of the same change are still recorded.

Does a duplicate delivery of the same event create duplicate records?

No. Flashduty records an event with the same change, time, and status only once.

For the related Flux configuration, see Providers, Alerts, and Events in the Flux docs.

Quick Start

Product Comparison

Channels

Incident Management

Post-Mortem

Status Page

Analytics

Integration Settings

Configuration

Advanced

Integrations

Best Practices

Flux CD change integration

In Flashduty On-call

Configure flux

How changes are merged

Status mapping

Change content

FAQ