Awesome
Brigade Cron Event Source
<img width="100" align="left" src="logo.png">The Brigade Cron Event Source offers an easy, low-overhead method of emitting
user-defined events into Brigade's event bus on a user-defined schedule. It will
create a Kubernetes CronJob
resource for each such event. A small program will
wake on the specified schedule to emit its event. That's it.
Why a Cron Event Source?
Before getting started with this event source, do ask yourself if you truly need it. If your only interest is in executing a simple task on a particular schedule, Kubernetes, by itself, gives you everything you need. In such a case, we don't recommend over-complicating things by involving Brigade!
If, however, you wish to execute a more complex workflow on a particular schedule or if your use case is well-served by other Brigade features, do consider utilizing this event source.
A non-exhaustive set of reasons you might wish to use this event source includes:
- Your workflow is complex and involves multiple containers that need to execute concurrently or in serial.
- You also have other events you need to handle.
- You care about capturing and saving logs from your automated task.
Installation
Prerequisites:
-
A Kubernetes cluster:
- For which you have the
admin
cluster role - That is already running Brigade 2
- For which you have the
-
kubectl
,helm
(commands below require Helm 3.7.0+), andbrig
(the Brigade 2 CLI)
1. Create a Service Account for the Event Source
⚠️ To proceed beyond this point, you'll need to be logged into Brigade 2 as the "root" user (not recommended) or (preferably) as a user with the
ADMIN
role. Further discussion of this is beyond the scope of this documentation. Please refer to Brigade's own documentation.
Using Brigade 2's brig
CLI, create a service account for the event source to
use:
$ brig service-account create \
--id brigade-cron-event-source \
--description brigade-cron-event-source
Make note of the token returned. This value will be used in another step. It is your only opportunity to access this value, as Brigade does not save it.
Authorize this service account to create new events:
$ brig role grant EVENT_CREATOR \
--service-account brigade-cron-event-source \
--source brigade.sh/cron
⚠️ The
--source brigade.sh/cron
option specifies that this service account can be used only to create events having a value ofbrigade.sh/cron
in the event'ssource
field. This is a security measure that prevents the event source from using this token for impersonating other sources.
2. Install the Cron Event Source
⚠️ Be sure you are using Helm 3.7.0 or greater and enable experimental OCI support:
$ export HELM_EXPERIMENTAL_OCI=1
As this chart requires custom configuration to function properly, we'll need to create a chart values file with said config.
Use the following command to extract the full set of configuration options into a file you can modify:
$ helm inspect values oci://ghcr.io/brigadecore/brigade-cron-event-source \
--version v1.1.1 > ~/brigade-cron-event-source-values.yaml
Edit ~/brigade-cron-event-source-values.yaml
, making the following changes:
-
brigade.apiAddress
: Address of the Brigade API server, beginning withhttps://
-
brigade.apiToken
: Service account token from step 2 -
events
: By default, this field contains an empty array. It can be modified to enumerate events that should each be emitted to Brigade's event bus on a schedule of your choosing. The file contains extensive comments on how to do this, but some highlights are covered here:-
name
: Give your event a name. It must be unique to this installation of the cron event source. The name may contain only lower case alphanumeric characters and dashes. -
schedule
: The schedule for emitting the event to Brigade. It should follow the syntax described here. -
brigadeEvent
: YAML representation of a Brigade event. It must conform to the v2 event schema and has the following additional restrictions:-
projectID
: MUST be specified -
source
: MUST bebrigade.sh/cron
-
-
Save your changes to ~/brigade-cron-event-source-values.yaml
and use the
following command to install the event source using the above customizations:
$ helm install brigade-cron-event-source \
oci://ghcr.io/brigadecore/brigade-cron-event-source \
--version v1.1.1 \
--create-namespace \
--namespace brigade-cron-event-source \
--values ~/brigade-cron-event-source-values.yaml \
--wait \
--timeout 300s
3. Subscribe a Brigade Project
As noted in the previous section, events emitted by this event source MUST specify a Brigade project by ID. For each event emitted by this event source, create or modify the corresponding project.
In the example (new) project definition below, we subscribe to an event of type
cleanup-requested
emitted by this event source:
apiVersion: brigade.sh/v2
kind: Project
metadata:
id: cron-demo
description: A project that demonstrates integration with the cron event source
spec:
eventSubscriptions:
- source: brigade.sh/cron
types:
- cleanup-requested
workerTemplate:
defaultConfigFiles:
brigade.js: |-
const { events } = require("@brigadecore/brigadier");
events.on("brigade.sh/cron", "cleanup-requested", () => {
console.log("Performing nightly cleanup...");
// ...
});
events.process();
Assuming this file were named project.yaml
, you can create the project like
so:
$ brig project create --file project.yaml
General Guidance
This event source is different than most others in that it has the flexibility to generate user-defined events on a user-defined schedule. With this being the case, this event source's creators wish to offer some guidance on how best to leverage that flexibility without becoming encumbered by it.
In general, what we do not recommend is emitting events with type
values
that reflect times or intervals. midnight
or top-of-the-hour
, are in our
opinion, poor event types. While these might accurately convey real world
events, such as "the stroke of midnight," such events can be problematic for
their corresponding projects. Supposing, for instance, that some project
executes a nightly cleanup process in response to the midnight
event and one
wished to move nightly cleanup to 1:00 AM. Not only would the event source need
to be reconfiguration to emit events with a type
value like (for instance)
one-am
, but the project's subscriptions and script would likewise require
updating.
In contrast, what we do recommend is emitting events with type
values that
reflect some desired effect. If the event source were configured to emit
events with type
value cleanup-requested
, for instance, then rescheduling
the event is only a matter of updating event source configuration and neither
the corresponding project's event subscriptions nor script need to be modified.
Contributing
The Brigade project accepts contributions via GitHub pull requests. The Contributing document outlines the process to help get your contribution accepted.
Support & Feedback
We have a Slack channel! Visit slack.brigade.sh to join us. We welcome any support questions or feedback.
To report an issue or to request a feature, open an issue here.
Code of Conduct
Participation in the Brigade project is governed by the CNCF Code of Conduct.