Notification API reference v1

ProviderRef specifies which Provider this Alert should use.

EventSeverity specifies how to filter events based on severity. If set to ‘info’ no events will be filtered.

EventSources specifies how to filter events based on the involved object kind, name and namespace.

InclusionList specifies a list of Golang regular expressions to be used for including messages.

EventMetadata adds metadata to events. Sources, from lowest to highest precedence: event.toolkit.fluxcd.io/ annotations on the involved object, Alert .spec.eventMetadata, and controller-defined <controller group>.toolkit.fluxcd.io/ event metadata. Higher precedence wins; conflicts produce an info log and a Warning Event. See the Alert API docs (Event metadata section).

ExclusionList specifies a list of Golang regular expressions to be used for excluding messages.

Suspend tells the controller to suspend subsequent events handling for this Alert.

API version of the referent

Kind of the referent

Name of the referent If multiple resources are targeted * may be set.

Namespace of the referent

MatchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is “key”, the operator is “In”, and the values array contains only “value”. The requirements are ANDed. MatchLabels requires the name to be set to *.

IssuerURL is the OIDC issuer URL used for provider discovery. It must match the ‘iss’ claim of tokens issued by this provider.

Audience is the expected audience (‘aud’ claim) for tokens issued by this provider. Defaults to ‘notification-controller’.

Variables is an optional list of named CEL expressions, evaluated in order and exposed as ‘vars.’. Each expression can read the token claims via ‘claims’ and any variable defined before it. Use it to share sub-expressions across validations.

Validations is the list of CEL boolean expressions evaluated against the token claims and the variables. The request is accepted only if all of them evaluate to true; the message of each failing expression is returned to the caller.

At least one validation is required. A valid signature alone does not authorize a request: public issuers issue tokens to any caller on the platform, so the validations must constrain the caller’s identity claims (e.g. ‘repository_owner’ for GitHub Actions).

Expression is the CEL boolean expression to evaluate.

Message is returned to the caller when the expression evaluates to false.

Name is the variable name; it must be a valid CEL identifier.

Expression is the CEL expression that defines the variable value.

Type specifies which Provider implementation to use.

Channel specifies the destination channel where events should be posted.

Username specifies the name under which events are posted.

Address specifies the endpoint, in a generic sense, to where alerts are sent. What kind of endpoint depends on the specific Provider type being used. For the generic Provider, for example, this is an HTTP/S address. For other Provider types this could be a project ID or a namespace.

Timeout for sending alerts to the Provider.

ProxySecretRef specifies the Secret containing the proxy configuration for this Provider. The Secret should contain an ‘address’ key with the HTTP/S address of the proxy server. Optional ‘username’ and ‘password’ keys can be provided for proxy authentication.

SecretRef specifies the Secret containing the authentication credentials for this Provider.

ServiceAccountName is the name of the Kubernetes ServiceAccount used to authenticate with cloud provider services through object identity. This enables multi-tenant authentication without storing static credentials.

Supported provider types: azureeventhub, azuredevops, googlepubsub

When specified, the controller will: 1. Create an OIDC token for the specified ServiceAccount 2. Exchange it for cloud provider credentials via STS 3. Use the obtained credentials for API authentication

When unspecified, the controller’s workload identity is used (single-tenant).

An error is thrown if static credentials are also defined in SecretRef.

CertSecretRef specifies the Secret containing TLS certificates for secure communication.

Supported configurations: - CA-only: Server authentication (provide ca.crt only) - mTLS: Mutual authentication (provide ca.crt + tls.crt + tls.key) - Client-only: Client authentication with system CA (provide tls.crt + tls.key only)

Legacy keys “caFile”, “certFile”, “keyFile” are supported but deprecated. Use “ca.crt”, “tls.crt”, “tls.key” instead.

Suspend tells the controller to suspend subsequent events handling for this Provider.

CommitStatusExpr is a CEL expression that evaluates to a string value that can be used to generate a custom commit status message for use with eligible Provider types (github, gitlab, gitea, bitbucketserver, bitbucket, azuredevops). Supported variables are: event, provider, and alert.

(Members of CrossNamespaceObjectReference are embedded into this type.)

Filter is a CEL expression expected to return a boolean that is evaluated for each resource matched by this reference when a webhook is received, in addition to the top-level resourceFilter. A reconciliation is requested only when both expressions (when set) return true. The expression can read the resource metadata via ‘res’ and the webhook request body via ‘req’. For generic-oidc receivers, the verified OIDC token claims are also available via ‘claims’. When the expression is specified the controller will parse it and mark the object as terminally failed if the expression is invalid or does not return a boolean.

Type of webhook sender, used to determine the validation procedure and payload deserialization.

Interval at which to reconcile the Receiver with its Secret references.

Events specifies the list of event types to handle, e.g. ‘push’ for GitHub or ‘Push Hook’ for GitLab.

A list of resources to be notified about changes.

ResourceFilter is a CEL expression expected to return a boolean that is evaluated for each resource referenced in the Resources field when a webhook is received. If the expression returns false then the controller will not request a reconciliation for the resource. The expression can read the resource metadata via ‘res’ and the webhook request body via ‘req’. For generic-oidc receivers, the verified OIDC token claims are also available via ‘claims’. When the expression is specified the controller will parse it and mark the object as terminally failed if the expression is invalid or does not return a boolean.

SecretRef specifies the Secret containing the token used to validate the payload authenticity. The Secret must contain a ‘token’ key. For GCR receivers, the Secret must also contain an ‘email’ key with the IAM service account email configured on the Pub/Sub push subscription, and an ‘audience’ key with the expected OIDC token audience.

Required for all receiver types except ‘generic-oidc’, which authenticates requests using the OIDC token instead and must not set this field.

OIDCProviders specifies the OIDC providers used to authenticate incoming requests when Type is ‘generic-oidc’. The provider whose IssuerURL matches the token’s ‘iss’ claim is used to verify the token signature, expiration and audience, and to evaluate the configured CEL validations against the token claims.

Suspend tells the controller to suspend subsequent events handling for this receiver.

(Members of ReconcileRequestStatus are embedded into this type.)

Conditions holds the conditions for the Receiver.

WebhookPath is the generated incoming webhook address in the format of ‘/hook/sha256sum(token+name+namespace)’.

ObservedGeneration is the last observed generation of the Receiver object.