{"id":18853099,"url":"https://github.com/kubevela/kube-trigger","last_synced_at":"2025-07-18T05:40:23.102Z","repository":{"id":49833005,"uuid":"516281758","full_name":"kubevela/kube-trigger","owner":"kubevela","description":"kube-trigger watches events and triggers actions in a programmable way.","archived":false,"fork":false,"pushed_at":"2025-07-11T20:19:29.000Z","size":666,"stargazers_count":52,"open_issues_count":8,"forks_count":20,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-07-11T22:18:08.335Z","etag":null,"topics":["controller","crd","kubernetes","trigger"],"latest_commit_sha":null,"homepage":"","language":"Go","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/kubevela.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-07-21T08:08:58.000Z","updated_at":"2025-07-11T20:19:34.000Z","dependencies_parsed_at":"2024-06-18T21:31:25.632Z","dependency_job_id":"ba99cb3d-ad5f-400d-8d9e-87851d113715","html_url":"https://github.com/kubevela/kube-trigger","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/kubevela/kube-trigger","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubevela%2Fkube-trigger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubevela%2Fkube-trigger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubevela%2Fkube-trigger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubevela%2Fkube-trigger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kubevela","download_url":"https://codeload.github.com/kubevela/kube-trigger/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubevela%2Fkube-trigger/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265705729,"owners_count":23814495,"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":["controller","crd","kubernetes","trigger"],"created_at":"2024-11-08T03:42:55.925Z","updated_at":"2025-07-18T05:40:23.071Z","avatar_url":"https://github.com/kubevela.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kube-trigger\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/kubevela/kube-trigger)](https://goreportcard.com/report/github.com/kubevela/kube-trigger)\n[![LICENSE](https://img.shields.io/github/license/kubevela/kube-trigger.svg?style=flat-square)](/LICENSE)\n[![Releases](https://img.shields.io/github/release/kubevela/kube-trigger/all.svg?style=flat-square)](https://github.com/kubevela/kube-trigger/releases)\n[![codecov](https://codecov.io/gh/kubevela/kube-trigger/branch/main/graph/badge.svg)](https://codecov.io/gh/kubevela/kube-trigger)\n![Docker Pulls](https://img.shields.io/docker/pulls/oamdev/kube-trigger)\n[![TODOs](https://img.shields.io/endpoint?url=https://api.tickgit.com/badge?repo=github.com/kubevela/kube-trigger)](https://www.tickgit.com/browse?repo=github.com/kubevela/kube-trigger)\n[![Go Checks](https://github.com/kubevela/kube-trigger/actions/workflows/go-checks.yaml/badge.svg?branch=main)](https://github.com/kubevela/kube-trigger/actions/workflows/go-checks.yaml)\n[![Unit Tests](https://github.com/kubevela/kube-trigger/actions/workflows/unit-test.yaml/badge.svg)](https://github.com/kubevela/kube-trigger/actions/workflows/unit-test.yaml)\n\nkube-trigger is a workflow based trigger that combines listeners, filter events and action triggers in a programmable way with CUElang.\n\n![kube-trigger overview](docs/img/overview.svg)\n\n## Overview\n\nAlthough there is `kube` in the name, it is actually not limited to Kubernetes and can do much more than that. It has an\nextensible architecture that can extend its capabilities fairly easily. We have docs (not yet) on how to\nextend [Source](#Source), [Filter](#Filter), and [Action](#Action). All users are welcomed to contribute their own\nextensions.\n\n### Source\n\nA Source is what listens to events (event source). For example, a `resource-watcher` source can watch Kubernetes\nresources from multi-clusters. Once a Kubernetes resource (e.g. Deployment) is changed, it will raise an event that will be passed\nto [Filter](#Filter) for further processing.\n\n```yaml\nsource:\n  type: resource-watcher\n  properties:\n    apiVersion: apps/v1\n    kind: Deployment\n    events:\n      - update\n```\n\n### Filters\n\nA Filter will filter the events that are raised by [Source](#Source), i.e, drop events that do not satisfy a certain\ncriteria. For example, users can check the status of the Deployment to decide whether to filter out events. All the\nevents that passed the Filter will then trigger an [Action](#Action).\n\n```yaml\nfilter: context.data.status.readyReplicas == context.data.status.replicas\n```\n\n### Actions\n\nAn Action is a job that does what the user specified when an event happens. For example, the user can send\nnotifications, log events, execute a command, or patch some Kubernetes objects when an event happens.\n\nFor example, you can use the built-in action `patch-resource` to patch resources in Kubernetes like:\n\n```yaml\naction:\n  type: patch-resource\n  properties:\n    resource:\n      apiVersion: v1\n      kind: ConfigMap\n      name: my-cm\n      namespace: default\n    patch:\n      type: merge\n      data:\n        data: \n          foo: bar\n```\n\nThe underlying mechanism of action is using [CUE](https://github.com/cue-lang/cue) to render the template and execute it with your parameters. For example, the above action can be written in CUE as:\n\n```cue\nimport (\n\t\"vela/kube\"\n)\n\npatchObject: kube.#Patch \u0026 {\n\t$params: {\n\t\tresource: {\n\t\t\tapiVersion: parameter.resource.apiVersion\n\t\t\tkind:       parameter.resource.kind\n\t\t\tmetadata: {\n\t\t\t\tname:      parameter.resource.name\n\t\t\t\tnamespace: parameter.resource.namespace\n\t\t\t}\n\t\t}\n\t\tpatch: parameter.patch\n\t}\n}\n\n// users' parameters to be passed to the action\nparameter: {\n\t// +usage=The resource to patch\n\tresource: {\n\t\t// +usage=The api version of the resource\n\t\tapiVersion: string\n\t\t// +usage=The kind of the resource\n\t\tkind: string\n\t\t// +usage=The metadata of the resource\n\t\tmetadata: {\n\t\t\t// +usage=The name of the resource\n\t\t\tname: string\n\t\t\t// +usage=The namespace of the resource\n\t\t\tnamespace: *\"default\" | string\n\t\t}\n\t}\n\t// +usage=The patch to be applied to the resource with kubernetes patch\n\tpatch: *{\n\t\t// +usage=The type of patch being provided\n\t\ttype: \"merge\"\n\t\tdata: {...}\n\t} | {\n\t\t// +usage=The type of patch being provided\n\t\ttype: \"json\"\n\t\tdata: [{...}]\n\t} | {\n\t\t// +usage=The type of patch being provided\n\t\ttype: \"strategic\"\n\t\tdata: {...}\n\t}\n}\n\n```\n\n## Quick Start\n\nTo quickly know the concepts of kube-trigger, let's use a real use-case as an exmaple (\nsee [#4418](https://github.com/kubevela/kubevela/issues/4418)). TL;DR, the user want the Application to be automatically\nupdated whenever the ConfigMaps that are referenced by `ref-objects` are updated.\n\nTo accomplish this, we will:\n\n- use a `resource-watcher` Source to listen to update events of ConfigMaps\n- filter the events to only keep the ConfigMaps that we are interested in\n- trigger an `bump-application-revision` Action to update Application.\n\nAnd the trigger config file will look like:\n\n```yaml\ntriggers:\n  - source:\n      type: resource-watcher\n      properties:\n        # We are interested in ConfigMap events.\n        apiVersion: \"v1\"\n        kind: ConfigMap\n        namespace: default\n        # Only watch update event.\n        events:\n          - update\n    filter: |\n      context: data: metadata: name: =~\"this-will-trigger-update-.*\"\n    action:\n      # Bump Application Revision to update Application.\n      type: bump-application-revision\n      properties:\n        namespace: default\n        # Select Applications to bump using labels.\n        nameSelector:\n          fromLabel: \"watch-this\"\n```\n\nSee [examples](https://github.com/kubevela/kube-trigger/tree/main/examples) directory for more instructions.\n\n## Usage\n\nYou can run kube-trigger in two modes: standalone and in-cluster.\n\n### Configuration File\n\nA config file instructs kube-trigger to use what [Source](#Source), [Filter](#Filter), and [Action](#Action), and\nhow they are configured.\n\nNo matter you are running kube-trigger as standalone or in-cluster, the config format is similar, so it is beneficial to\nknow the format first. We will use yaml format as an example (json and cue are also supported).\n\n```yaml\n# A trigger is a group of Source, Filter, and Action.\n# You can add multiple triggers.\ntriggers:\n  - source:\n      type: \u003cyour-source-type\u003e\n      properties: ...\n      # ... properties\n    filter: \u003cyour-filter\u003e\n    action:\n      type: \u003cyour-action-type\u003e\n      properties: ...\n```\n\n### Standalone\n\nWhen running in standalone mode, you will need to provide a config file to kube-trigger binary.\n\nkube-trigger can accept `cue`, `yaml`, and `json` config files. You can also specify a directory to load all the\nsupported files inside that directory. `-c`/`--config` cli flag and `CONFIG` environment variable can be used to specify\nconfig file.\n\nAn example config file looks like this:\n\n```yaml\n# A trigger is a group of Source, Filters, and Actions.\n# You can add multiple triggers.\ntriggers:\n  - source:\n      type: resource-watcher\n      properties:\n        # We are interested in ConfigMap events.\n        apiVersion: \"v1\"\n        kind: ConfigMap\n        namespace: default\n        # Only watch update event.\n        events:\n          - update\n    # Filter the events above.\n    filter: |\n      context: data: metadata: name: =~\"this-will-trigger-update-.*\"\n    action:\n      # Bump Application Revision to update Application.\n      type: bump-application-revision\n      properties:\n        namespace: default\n        # Select Applications to bump using labels.\n        nameSelector:\n          fromLabel: \"watch-this\"\n```\n\nLet's assume your config file is `config.yaml`, to run kube-trigger:\n\n- `./kube-trigger -c=config.yaml`\n- `CONFIG=config.yaml ./kube-trigger`\n\n### In-Cluster\n\nWe have one CRD called *TriggerService*. *TriggerInstance* is what creates a kube-trigger instance (similar to running `./kube-trigger` in-cluster but no config with config specified in its spec.\n\n```yaml\n# You can find this file in config/samples/standard_v1alpha1_triggerservice.yaml\napiVersion: standard.oam.dev/v1alpha1\nkind: TriggerService\nmetadata:\n  name: kubetrigger-sample-config\n  namespace: default\nspec:\n  selector:\n    instance: kubetrigger-sample\n  triggers:\n    - source:\n        type: resource-watcher\n        properties:\n          apiVersion: \"v1\"\n          kind: ConfigMap\n          namespace: default\n          events:\n            - update\n      filter: |\n        context: data: metadata: name: =~\"this-will-trigger-update-.*\"\n      action:\n        type: bump-application-revision\n        properties:\n          namespace: default\n          # Select Applications to bump using labels.\n          nameSelector:\n            fromLabel: \"watch-this\"\n```\n\n## Advanced kube-trigger Configuration\n\nIn addition to config files, you can also do advanced configurations. Advanced kube-trigger Configurations are\ninternal configurations to fine-tune your kube-trigger instance. In\nmost cases, you probably don't need to fiddle with these settings.\n\n### Log Level\n\nFrequently-used values: `debug`, `info`, `error`\n\nDefault: `info`\n\n| CLI           | ENV         | KubeTrigger CRD |\n|---------------|-------------|-----------------|\n| `--log-level` | `LOG_LEVEL` | `TODO`          |\n\n### Action Retry\n\nRe-run Action if it fails.\n\nDefault: `false`\n\n| CLI              | ENV            | KubeTrigger CRD |\n|------------------|----------------|-----------------|\n| `--action-retry` | `ACTION_RETRY` | `TODO`          |\n\n### Max Retry\n\nMax retry count if an Action fails, valid only when action retrying is enabled.\n\nDefault: `5`\n\n| CLI           | ENV         | KubeTrigger CRD               |\n|---------------|-------------|-------------------------------|\n| `--max-retry` | `MAX_RETRY` | `.spec.workerConfig.maxRetry` |\n\n### Retry Delay\n\nFirst delay to retry actions in seconds, subsequent delay will grow exponentially, valid only when action retrying is\nenabled.\n\nDefault: `2`\n\n| CLI             | ENV           | KubeTrigger CRD                 |\n|-----------------|---------------|---------------------------------|\n| `--retry-delay` | `RETRY_DELAY` | `.spec.workerConfig.retryDelay` |\n\n### Per-Worker QPS\n\nLong-term QPS limiting per Action worker, this is shared between all watchers.\n\nDefault: `2`\n\n| CLI                | ENV              | KubeTrigger CRD                   |\n|--------------------|------------------|-----------------------------------|\n| `--per-worker-qps` | `PER_WORKER_QPS` | `.spec.workerConfig.perWorkerQPS` |\n\n### Queue Size\n\nQueue size for running actions, this is shared between all watchers\n\nDefault: `50`\n\n| CLI            | ENV          | KubeTrigger CRD                |\n|----------------|--------------|--------------------------------|\n| `--queue-size` | `QUEUE_SIZE` | `.spec.workerConfig.queueSize` |\n\n### Job Timeout\n\nTimeout for running each action in seconds.\n\nDefault: `10`\n\n| CLI         | ENV       | KubeTrigger CRD              |\n|-------------|-----------|------------------------------|\n| `--timeout` | `TIMEOUT` | `.spec.workerConfig.timeout` |\n\n### Worker Count\n\nNumber of workers for running actions, this is shared between all watchers.\n\nDefault: `4`\n\n| CLI         | ENV       | KubeTrigger CRD                  |\n|-------------|-----------|----------------------------------|\n| `--workers` | `WORKERS` | `.spec.workerConfig.workerCount` |\n\n### Registry Size\n\nCache size for filters and actions.\n\nDefault: `100`\n\n| CLI               | ENV             | KubeTrigger CRD      |\n|-------------------|-----------------|----------------------|\n| `--registry-size` | `REGISTRY_SIZE` | `.spec.registrySize` |\n\n## Roadmap\n\n### v0.0.1-alpha.x\n\n- [x] Basic build infrastructure\n- [x] Complete a basic proof-of-concept sample\n- [x] linters, license checker\n- [x] GitHub Actions\n- [x] Rate-limited worker\n- [x] Make the configuration as CRD, launch new process/pod for new watcher\n- [x] Notification for more than one app: selector from compose of Namespace; Labels; Name\n- [x] Refine README, quick starts\n- [x] Refactor CRD according to [#2](https://github.com/kubevela/kube-trigger/issues/2)\n\n### v0.0.1-beta.x\n\nCode enhancements\n\n- [ ] Add missing unit tests\n- [ ] Add missing integration tests\n\n### v0.0.x\n\nUser experience\n\n- [ ] Refine health status of CRs\n- [ ] Make it run as Addon, build component definition, and examples\n- [ ] Kubernetes dynamic admission control with validation webhook\n- [ ] Auto-generate usage docs of Sources, Filters, and Actions from CUE markers\n- [ ] Show available Sources, Filters, and Actions in cli\n\n### v0.1.x\n\nWebhook support\n\n- [ ] Contribution Guide\n- [ ] New Action: webhook\n- [ ] New Source: webhook\n\n### v0.2.x\n\nObservability\n\n- [ ] New Action: execute VelaQL(CUE and K8s operations)\n- [ ] New Source: cron\n- [ ] New Action: notifications(email, dingtalk, slack, telegram)\n- [ ] New Action: log (loki, clickhouse)\n\n### Planned for later releases\n\n- [ ] Allow user set custom RBAC for each TriggerInstance\n- [ ] New Action: workflow-run\n- [ ] New Action: execute-command\n- [ ] New Action: metric (prometheus)\n- [ ] Refine controller logic\n- [ ] Remove cache informer, make it with no catch but list watch events with unique queue.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubevela%2Fkube-trigger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkubevela%2Fkube-trigger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubevela%2Fkube-trigger/lists"}