{"id":13588576,"url":"https://github.com/brigadecore/brigade-cron-event-source","last_synced_at":"2025-04-26T17:30:49.545Z","repository":{"id":37796467,"uuid":"431397563","full_name":"brigadecore/brigade-cron-event-source","owner":"brigadecore","description":"Emit user-defined events to Brigade 2's event bus on a user-defined schedule!","archived":false,"fork":false,"pushed_at":"2024-06-24T22:06:04.000Z","size":161,"stargazers_count":4,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-25T05:02:53.914Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brigadecore.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-11-24T08:07:06.000Z","updated_at":"2022-07-19T21:15:52.000Z","dependencies_parsed_at":"2024-11-06T08:33:28.509Z","dependency_job_id":"cae2acd1-762f-448a-875f-bf5affebb479","html_url":"https://github.com/brigadecore/brigade-cron-event-source","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brigadecore%2Fbrigade-cron-event-source","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brigadecore%2Fbrigade-cron-event-source/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brigadecore%2Fbrigade-cron-event-source/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brigadecore%2Fbrigade-cron-event-source/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brigadecore","download_url":"https://codeload.github.com/brigadecore/brigade-cron-event-source/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251025586,"owners_count":21524829,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T15:06:47.921Z","updated_at":"2025-04-26T17:30:49.273Z","avatar_url":"https://github.com/brigadecore.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# Brigade Cron Event Source\n\n![build](https://badgr.brigade2.io/v1/github/checks/brigadecore/brigade-cron-event-source/badge.svg?appID=99005)\n[![codecov](https://codecov.io/gh/brigadecore/brigade-cron-event-source/branch/main/graph/badge.svg?token=ZSac3nWz6M)](https://codecov.io/gh/brigadecore/brigade-cron-event-source)\n[![Go Report Card](https://goreportcard.com/badge/github.com/brigadecore/brigade-cron-event-source)](https://goreportcard.com/report/github.com/brigadecore/brigade-cron-event-source)\n[![slack](https://img.shields.io/badge/slack-brigade-brightgreen.svg?logo=slack)](https://kubernetes.slack.com/messages/C87MF1RFD)\n\n\u003cimg width=\"100\" align=\"left\" src=\"logo.png\"\u003e\n\nThe Brigade Cron Event Source offers an easy, low-overhead method of emitting\nuser-defined events into Brigade's event bus on a user-defined schedule. It will\ncreate a Kubernetes `CronJob` resource for each such event. A small program will\nwake on the specified schedule to emit its event. _That's it._\n\n\u003cbr clear=\"left\"/\u003e\n\n## Why a Cron Event Source?\n\nBefore getting started with this event source, do ask yourself if you truly need\nit. If your only interest is in executing a _simple_ task on a particular\nschedule, Kubernetes, by itself, gives you everything you need. In such a case,\nwe don't recommend over-complicating things by involving Brigade!\n\nIf, however, you wish to execute a more complex workflow on a particular\nschedule or if your use case is well-served by other Brigade features, _do_\nconsider utilizing this event source.\n\nA non-exhaustive set of reasons you might wish to use this event source\nincludes:\n\n* Your workflow is complex and involves multiple containers that need to execute\n  concurrently or in serial.\n* You also have _other_ events you need to handle.\n* You care about capturing and saving logs from your automated task.\n\n## Installation\n\nPrerequisites:\n\n* A Kubernetes cluster:\n    * For which you have the `admin` cluster role\n    * That is already running Brigade 2\n\n* `kubectl`, `helm` (commands below require Helm 3.7.0+), and `brig` (the\n  Brigade 2 CLI)\n\n### 1. Create a Service Account for the Event Source\n\n\u003e ⚠️\u0026nbsp;\u0026nbsp;To proceed beyond this point, you'll need to be logged into Brigade 2\nas the \"root\" user (not recommended) or (preferably) as a user with the `ADMIN`\nrole. Further discussion of this is beyond the scope of this documentation.\nPlease refer to Brigade's own documentation.\n\nUsing Brigade 2's `brig` CLI, create a service account for the event source to\nuse:\n\n```shell\n$ brig service-account create \\\n    --id brigade-cron-event-source \\\n    --description brigade-cron-event-source\n```\n\nMake note of the __token__ returned. This value will be used in another step.\n_It is your only opportunity to access this value, as Brigade does not save it._\n\nAuthorize this service account to create new events:\n\n```shell\n$ brig role grant EVENT_CREATOR \\\n    --service-account brigade-cron-event-source \\\n    --source brigade.sh/cron\n```\n\n\u003e ⚠️\u0026nbsp;\u0026nbsp;The `--source brigade.sh/cron` option specifies that this service\naccount can be used _only_ to create events having a value of `brigade.sh/cron`\nin the event's `source` field. _This is a security measure that prevents the\nevent source from using this token for impersonating other sources._\n\n### 2. Install the Cron Event Source\n\n\u003e ⚠️\u0026nbsp;\u0026nbsp;Be sure you are using\n\u003e [Helm 3.7.0](https://github.com/helm/helm/releases/tag/v3.7.0) or greater and\n\u003e enable experimental OCI support:\n\u003e\n\u003e ```shell\n\u003e $ export HELM_EXPERIMENTAL_OCI=1\n\u003e ```\n\nAs this chart requires custom configuration to function properly, we'll need to\ncreate a chart values file with said config.\n\nUse the following command to extract the full set of configuration options into\na file you can modify:\n\n```shell\n$ helm inspect values oci://ghcr.io/brigadecore/brigade-cron-event-source \\\n    --version v1.1.1 \u003e ~/brigade-cron-event-source-values.yaml\n```\n\nEdit `~/brigade-cron-event-source-values.yaml`, making the following changes:\n\n* `brigade.apiAddress`: Address of the Brigade API server, beginning with\n  `https://`\n\n* `brigade.apiToken`: Service account token from step 2\n\n* `events`: By default, this field contains an empty array. It can be modified\n  to enumerate events that should each be emitted to Brigade's event bus on a\n  schedule of your choosing. The file contains extensive comments on how to do\n  this, but some highlights are covered here:\n\n  * `name`: Give your event a name. It must be unique to this installation of\n    the cron event source. The name may contain only lower case alphanumeric\n    characters and dashes.\n\n  * `schedule`: The schedule for emitting the event to Brigade. It should follow\n    the syntax described \n    [here](https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/#schedule).\n\n  * `brigadeEvent`: YAML representation of a Brigade event. It must conform to\n    the [v2 event schema](https://schemas.brigade.sh/schemas-v2/event.json) and\n    has the following _additional_ restrictions:\n\n      * `projectID`: MUST be specified\n\n      * `source`: MUST be `brigade.sh/cron`\n\nSave your changes to `~/brigade-cron-event-source-values.yaml` and use the\nfollowing command to install the event source using the above customizations:\n\n```shell\n$ helm install brigade-cron-event-source \\\n    oci://ghcr.io/brigadecore/brigade-cron-event-source \\\n    --version v1.1.1 \\\n    --create-namespace \\\n    --namespace brigade-cron-event-source \\\n    --values ~/brigade-cron-event-source-values.yaml \\\n    --wait \\\n    --timeout 300s\n```\n\n### 3. Subscribe a Brigade Project\n\nAs noted in the previous section, events emitted by this event source MUST\nspecify a Brigade project by ID. For each event emitted by this event source,\ncreate or modify the corresponding project.\n\nIn the example (new) project definition below, we subscribe to an event of type\n`cleanup-requested` emitted by this event source:\n\n```yaml\napiVersion: brigade.sh/v2\nkind: Project\nmetadata:\n  id: cron-demo\ndescription: A project that demonstrates integration with the cron event source\nspec:\n  eventSubscriptions:\n  - source: brigade.sh/cron\n    types:\n    - cleanup-requested\n  workerTemplate:\n    defaultConfigFiles:\n      brigade.js: |-\n        const { events } = require(\"@brigadecore/brigadier\");\n\n        events.on(\"brigade.sh/cron\", \"cleanup-requested\", () =\u003e {\n          console.log(\"Performing nightly cleanup...\");\n          // ...\n        });\n\n        events.process();\n```\n\nAssuming this file were named `project.yaml`, you can create the project like\nso:\n\n```shell\n$ brig project create --file project.yaml\n```\n\n## General Guidance\n\nThis event source is different than most others in that it has the flexibility\nto generate user-defined events on a user-defined schedule. With this being the\ncase, this event source's creators wish to offer some guidance on how best to\nleverage that flexibility without becoming encumbered by it.\n\nIn general, what we do _not_ recommend is emitting events with `type` values\nthat reflect times or intervals. `midnight` or `top-of-the-hour`, are in our\nopinion, poor event types. While these might accurately convey real world\nevents, such as \"the stroke of midnight,\" such events can be problematic for\ntheir corresponding projects. Supposing, for instance, that some project\nexecutes a nightly cleanup process in response to the `midnight` event and one\nwished to move nightly cleanup to 1:00 AM. Not only would the event source need\nto be reconfiguration to emit events with a `type` value like (for instance)\n`one-am`, but the project's subscriptions and script would _likewise_ require\nupdating.\n\nIn contrast, what we _do_ recommend is emitting events with `type` values that\nreflect some _desired effect_. If the event source were configured to emit\nevents with `type` value `cleanup-requested`, for instance, then rescheduling\nthe event is only a matter of updating event source configuration and neither\nthe corresponding project's event subscriptions nor script need to be modified.\n\n## Contributing\n\nThe Brigade project accepts contributions via GitHub pull requests. The\n[Contributing](CONTRIBUTING.md) document outlines the process to help get your\ncontribution accepted.\n\n## Support \u0026 Feedback\n\nWe have a Slack channel! Visit [slack.brigade.sh](https://slack.brigade.sh) to\njoin us. We welcome any support questions or feedback.\n\nTo report an issue or to request a feature, open an issue\n[here](https://github.com/brigadecore/brigade-cron-event-source/issues).\n\n## Code of Conduct\n\nParticipation in the Brigade project is governed by the\n[CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrigadecore%2Fbrigade-cron-event-source","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrigadecore%2Fbrigade-cron-event-source","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrigadecore%2Fbrigade-cron-event-source/lists"}