## 1. Project Overview & Quickstart (sameersbn/Changelog) ## 1. Project Overview & Quickstart (sameersbn/Changelog) # Changelog Open-source repository sameersbn/Changelog ### Repository Details - **Repository:** [sameersbn/Changelog](https://github.com/sameersbn/Changelog) - **Primary Language:** Code *Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.* ## 2. Official Technical Reference & Guides (sameersbn/docs) ## File: README.md # Documentation Site for TriggerMesh This uses [`mkdocs`](https://www.mkdocs.org/) Install it with: ``` pip install mkdocs-material mkdocs-redirects ``` If you have Python3, you may need to run ``` pip3 install mkdocs-material mkdocs-redirects ``` ## Serve the site locally ``` mkdocs serve ``` ## Changes Commit your changes and CI will automatically build the new site and deploy it ## Docker Instructions From the `docs` directory, build the image with the `docs` name. ``` docker build -t docs . ``` After a few minutes ``` docker images REPOSITORY TAG IMAGE ID CREATED SIZE docs latest 1e704c7ab807 About a minute ago 155MB ``` Start up the container ``` docker run -p 8081:80 docs:latest ``` and open http://localhost:8081 to view the content. ## Support We would love your feedback and help on this documentation, so don't hesitate to let us know what is wrong and how we could improve them, just file an [issue](https://github.com/triggermesh/docs/issues/new) or join those of us who are maintaining them and submit a [PR](https://github.com/triggermesh/docs/compare) ## Commercial Support TriggerMesh Inc offers commercial support, email info@triggermesh.com to get more details. ## Code of Conduct This plugin is by no means part of [CNCF](https://www.cncf.io/) but we abide by its [code of conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md) --- ## File: docs/index.md # TriggerMesh documentation TriggerMesh is free open-source software that lets you easily build event-driven applications. - :material-clock-fast:{ .lg .middle } __Your first events in 5 minutes__ --- Install the TriggerMesh command line interface [`tmctl`](reference/tmctl/tmctl.md) and get up and running in minutes on a standard laptop. [:octicons-arrow-right-24: Getting started](get-started/quickstart.md) - :material-kubernetes:{ .lg .middle } __Deploy natively on Kubernetes__ --- TriggerMesh runs natively on Kubernetes with its [`custom resource definitions`](reference/index.md) and controllers. [:octicons-arrow-right-24: K8s install](installation/kubernetes-helm.md) - :material-shuffle-variant:{ .lg .middle } __What is TriggerMesh__ --- Learn why TriggerMesh is part of a new generation of EDA solutions native to the cloud and built for developers. [:octicons-arrow-right-24: Concepts](get-started/concepts) - :material-github:{ .lg .middle } __Open Source, Apache 2.0__ --- TriggerMesh :material-heart: open source. Issues, pull requests, and thoughtful discussion are always welcome. [:octicons-arrow-right-24: GitHub](#) ## 2. Official Technical Reference & Guides (sameersbn/docs) ## File: README.md # Documentation Site for TriggerMesh This uses [`mkdocs`](https://www.mkdocs.org/) Install it with: ``` pip install mkdocs-material mkdocs-redirects ``` If you have Python3, you may need to run ``` pip3 install mkdocs-material mkdocs-redirects ``` ## Serve the site locally ``` mkdocs serve ``` ## Changes Commit your changes and CI will automatically build the new site and deploy it ## Docker Instructions From the `docs` directory, build the image with the `docs` name. ``` docker build -t docs . ``` After a few minutes ``` docker images REPOSITORY TAG IMAGE ID CREATED SIZE docs latest 1e704c7ab807 About a minute ago 155MB ``` Start up the container ``` docker run -p 8081:80 docs:latest ``` and open http://localhost:8081 to view the content. ## Support We would love your feedback and help on this documentation, so don't hesitate to let us know what is wrong and how we could improve them, just file an [issue](https://github.com/triggermesh/docs/issues/new) or join those of us who are maintaining them and submit a [PR](https://github.com/triggermesh/docs/compare) ## Commercial Support TriggerMesh Inc offers commercial support, email info@triggermesh.com to get more details. ## Code of Conduct This plugin is by no means part of [CNCF](https://www.cncf.io/) but we abide by its [code of conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md) --- ## File: docs/brokers/eventdelivery.md # Handling failed delivery of events The Broker is the component responsible for guaranteeing delivery of events, and provides what is commonly referred to as at-least-once delivery guarantees. Read more about at-least-once in the [dedicated guide](../get-started/reliabledelivery.md). This guide talks about the configuration options available on Triggers that let you define how the system should behave in the case of failed delivery. You can configure how events are delivered for each Trigger by adding a `delivery` spec to the `Trigger` object, as shown at the end of the following example: ```yaml apiVersion: eventing.triggermesh.io/v1alpha1 kind: Trigger metadata: name: mytrigger spec: broker: group: eventing.triggermesh.io kind: RedisBroker name: mybroker filters: - exact: type: mytype1 target: ref: apiVersion: targets.triggermesh.io/v1alpha1 kind: cloudeventstarget name: cloudeventstarget delivery: retry: 5 backoffDelay: PT5S backoffPolicy: constant deadLetterSink: uri: https://mycompany.com/deadletter ``` Where - `retry` specifies the number of times that event delivery is retried before the event is sent to the dead letter sink. - The `backoffDelay` delivery parameter specifies the time delay before an event delivery retry is attempted after a failure. The duration of the `backoffDelay` parameter is specified using the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Durations) duration format. For example, `PT1S` specifies a 1 second delay. - The `backoffPolicy` delivery parameter can be used to specify the retry back off policy. The policy can be specified as either `linear` or `exponential`. When using the `linear` back off policy, the back off delay is the time interval specified between retries. When using the `exponential` back off policy, the back off delay is equal to `backoffDelay*2^`. - The `deadLetterSink` spec contains configuration settings to enable using a dead letter sink. This tells the Subscription what happens to events that cannot be delivered to the subscriber. When this is configured, events that fail to be delivered are sent to the dead letter sink destination. The destination can be a reference to any TriggerMesh target, meaning anything could potentially be used to store dead lettered events. The destatination can also be URI. In the example above a URI is used. --- ## File: docs/brokers/index.md # Brokers and Triggers # What are Brokers? TriggerMesh provides components called Brokers that act as intermediaries that route events from event producers to consumers. Brokers are responsible for guaranteeing that events are delivered to their destinations, and enable the publish-subscribe model in which multiple consumers can be notified of the same events. Different Broker types will provide different guarantees and tradeoffs: * [`Memory Broker`](memorybroker.md) uses ephemeral memory to store events, and is best used for development and non-mission-critical use cases where event loss is acceptable in the case of crashes or restarts * [`Redis Broker`](redisbroker.md) uses a backing Redis instance to store events, thereby providing durability that is suitable for production uses cases where event loss in not acceptable during crashes or restarts # What are Triggers? The TriggerMesh Brokers run [Triggers](triggers.md) which listen for events, and evaluate them against the [Trigger's filters](triggerfilters.md), and if they match deliver the events to their defined targets. --- ## File: docs/brokers/memorybroker.md # Memory Broker Memory Broker is the simplest Broker implementation provided by TriggerMesh and is used by default by `tmctl`. The [Redis Broker](redisbroker.md) provides event durability and is used by default with TriggerMesh on Kubernetes. With `tmctl`: ``` tmctl create broker ``` On Kubernetes: ```yaml apiVersion: eventing.triggermesh.io/v1alpha1 kind: MemoryBroker metadata: name: spec: memory: bufferSize: broker: port: observability: valueFromConfigMap: ``` The only `MemoryBroker` specific parameter is `spec.memory.bufferSize` which indicates the available size of the internal queue that the broker manages. When the maximum number of items is reached, new ingest requests will block and might eventually time out. This parameter is optional and defaults to 10000. The `spec.broker` section contains generic Broker parameters: - `spec.broker.port` that the Broker service will be listening at. Optional, defaults to port 80. - `spec.broker.observability` can be set to the name of a ConfigMap at the same namespace that contains observability settings (documentation coming soon). This parameter is optional. ## Getting Started guide with the Memory Broker on Kubernetes In this introduction tutorial we are going to setup a MemoryBroker with a Trigger that sends events to a Target endpoint, and if the delivery faisl to a Dead Letter Sink endpoint. ### Instructions This guide uses 2 TriggerMesh components: * MemoryBroker, which uses ephemeral memory to store events and routes them via Triggers. * Trigger, which subscribes to events and push them to your targets. Events must conform to [CloudEvents spec](https://github.com/cloudevents/spec) using the [HTTP binding](https://github.com/cloudevents/spec/blob/main/cloudevents/bindings/http-protocol-binding.md). Create a MemoryBroker named `demo`. ```console kubectl apply -f https://raw.githubusercontent.com/triggermesh/triggermesh-core/main/docs/assets/manifests/getting-started-memory/broker.yaml ``` Wait until the MemoryBroker is ready. It will inform in its status of the URL where events can be ingested. ```console kubectl get memorybroker demo NAME URL AGE READY REASON demo http://demo-mb-broker.default.svc.cluster.local 10s True ``` To be able to use the broker we will create a Pod that allow us to send events inside the Kubernetes cluster. ```console kubectl apply -f https://raw.githubusercontent.com/triggermesh/triggermesh-core/main/docs/assets/manifests/common/curl.yaml ``` It is possible now to send events to the broker address by issuing curl commands. The response for ingested events must be an `HTTP 200` which means that the broker has received it and will try to deliver them to configured triggers. ```console kubectl exec -ti curl -- curl -v http://demo-mb-broker.default.svc.cluster.local/ \ -X POST \ -H "Ce-Id: 1234-abcd" \ -H "Ce-Specversion: 1.0" \ -H "Ce-Type: demo.type1" \ -H "Ce-Source: curl" \ -H "Content-Type: application/json" \ -d '{"test1":"no trigger configured yet"}' ``` Unfortunately we haven't configured any trigger yet, which means any ingested event will not be delivered. `event_display` is a CloudEvents consumer that logs to console the list of events received. We will be creating 2 instances of `event_display`, one as the target for consumed events and another one for the Dead Letter Sink. A Dead Letter Sink, abbreviated DLS is a destination that consumes events that a subscription was not able to deliver to the intended target. ```console # Target service kubectl apply -f https://raw.githubusercontent.com/triggermesh/triggermesh-core/main/docs/assets/manifests/common/display-target.yaml # DLS service kubectl apply -f https://raw.githubusercontent.com/triggermesh/triggermesh-core/main/docs/assets/manifests/common/display-deadlettersink.yaml ``` The Trigger object configures the broker to consume events and send them to a target. The Trigger object can include filters that select which events should be forwarded to the target, and delivery options to configure retries and fallback targets when the event cannot be delivered. ```console kubectl apply -f https://raw.githubusercontent.com/triggermesh/triggermesh-core/main/docs/assets/manifests/getting-started-memory/trigger.yaml ``` The Trigger created above filters by CloudEvents containing `type: demo.type1` attribute and delivers them to `display-target` service, if delivery fails it will issue 3 retries and then forward the CloudEvent to the `display-deadlettersink` service. Using the `curl` Pod again we can send this CloudEvent to the broker. ```console kubectl exec -ti curl -- curl -v http://demo-mb-broker.default.svc.cluster.local/ \ -X POST \ -H "Ce-Id: 1234-abcd" \ -H "Ce-Specversion: 1.0" \ -H "Ce-Type: demo.type1" \ -H "Ce-Source: curl" \ -H "Content-Type: application/json" \ -d '{"test 2":"message for display target"}' ``` The target display Pod will show the delivered event. ```console kubectl logs -l app=display-target --tail 100 ☁️ cloudevents.Event Validation: valid Context Attributes, specversion: 1.0 type: demo.type1 source: curl id: 1234-abcd datacontenttype: application/json Extensions, triggermeshbackendid: 1666613846441-0 Data, { "test": "value2" } ``` To simulate a target failure we will reconfigure the target display service to make it point to a non existing Pod set: ```console kubectl delete -f https://raw.githubusercontent.com/triggermesh/triggermesh-core/main/docs/assets/manifests/common/display-target.yaml ``` Any event that pass the filter will try to be sent to the target, and upon failing will be delivered to the DLS. ```console kubectl exec -ti curl -- curl -v http://demo-mb-broker.default.svc.cluster.local/ \ -X POST \ -H "Ce-Id: 1234-abcd" \ -H "Ce-Specversion: 1.0" \ -H "Ce-Type: demo.type1" \ -H "Ce-Source: curl" \ -H "Content-Type: application/json" \ -d '{"test 3":"not delivered, will be sent to DLS"}' ``` ```console kubectl logs -l app=display-deadlettersink --tail 100 ☁️ cloudevents.Event Validation: valid Context Attributes, specversion: 1.0 type: demo.type1 source: curl id: 1234-abcd datacontenttype: application/json Extensions, triggermeshbackendid: 1666613846441-0 Data, { "test": "value3" } ``` ### Clean Up To clean up the getting started guide, delete each of the created assets: ```console # Removal of display-target not in this list, since it was deleted previously. kubectl delete -f \ https://raw.githubusercontent.com/triggermesh/triggermesh-core/main/docs/assets/manifests/getting-started-memory/trigger.yaml,\ https://raw.githubusercontent.com/triggermesh/triggermesh-core/main/docs/assets/manifests/common/display-deadlettersink.yaml,\ https://raw.githubusercontent.com/triggermesh/triggermesh-core/main/docs/assets/manifests/getting-started-memory/broker.yaml,\ https://raw.githubusercontent.com/triggermesh/triggermesh-core/main/docs/assets/manifests/common/curl.yaml ``` --- ## File: docs/brokers/redisbroker.md # Redis Broker The Redis Broker uses a backing Redis instance to store events, thereby providing durability that is suitable for production uses cases where event loss in not acceptable during crashes or restarts. The management of the Redis instance is greatly simplified by TriggerMesh. It is also possible to point the Broker to any Redis instance, such as a managed instance from a cloud provider. With `tmctl`: !!! warning "Work in progress" This component is not yet available with `tmctl`. By default, Brokers created with `tmctl` are [Memory Brokers](memorybroker.md). However, when you export your configuration to Kubernetes manifests using `tmctl dump`, TriggerMesh will export a `Redis Broker`, thereby providing message durability by default. You can switch to a Memory Broker if you prefer by updating the exported manifest. TriggerMesh will add support for Redis Broker in `tmctl` in the future. On Kubernetes: ```yaml apiVersion: eventing.triggermesh.io/v1alpha1 kind: RedisBroker metadata: name: spec: redis: connection: url: username: secretKeyRef: name: key: password: secretKeyRef: name: key: tlsEnabled: tlsSkipVerify: stream: streamMaxLen: broker: port: observability: valueFromConfigMap: ``` The only `RedisBroker` specific parameters are: - `spec.redis.connection`. When not used the broker will spin up a managed Redis Deployment. However for production scenarios that require HA and hardened security it is recommended to provide the connection to a user managed Redis instance. - `spec.stream` is the Redis stream name to be used by the broker. If it doesn't exists the Broker will create it. - `spec.streamMaxLen` is the maximum number of elements that the stream will contain. The `spec.broker` section contains generic Broker parameters: - `spec.broker.port` that the Broker service will be listening at. Optional, defaults to port 80. - `spec.broker.observability` can be set to the name of a ConfigMap at the same namespace that contains observability settings (documentation coming soon). This parameter is optional. ## Getting Started with the Redis Broker on Kubernetes In this introduction tutorial we are going to setup a RedisBroker with a Trigger that sends events to a Target endpoint, and if the delivery faisl to a Dead Letter Sink endpoint. ### Instructions TriggerMesh Core includes 2 components: * RedisBroker, which uses a backing Redis instance to store events and routes them via Triggers. * Trigger, which subscribes to events and push them to your targets. Events must conform to [CloudEvents spec](https://github.com/cloudevents/spec) using the [HTTP binding](https://github.com/cloudevents/spec/blob/main/cloudevents/bindings/http-protocol-binding.md). Create a RedisBroker named `demo`. ```console kubectl apply -f https://raw.githubusercontent.com/triggermesh/triggermesh-core/main/docs/assets/manifests/getting-started-redis/broker.yaml ``` Wait until the RedisBroker is ready. It will inform in its status of the URL where events can be ingested. ```console kubectl get redisbroker demo NAME URL AGE READY REASON demo http://demo-rb-broker.default.svc.cluster.local 10s True ``` To be able to use the broker we will create a Pod that allow us to send events inside the Kubernetes cluster. ```console kubectl apply -f https://raw.githubusercontent.com/triggermesh/triggermesh-core/main/docs/assets/manifests/common/curl.yaml ``` It is possible now to send events to the broker address by issuing curl commands. The response for ingested events must be an `HTTP 200` which means that the broker has received it and will try to deliver them to configured triggers. ```console kubectl exec -ti curl -- curl -v http://demo-rb-broker.default.svc.cluster.local/ \ -X POST \ -H "Ce-Id: 1234-abcd" \ -H "Ce-Specversion: 1.0" \ -H "Ce-Type: demo.type1" \ -H "Ce-Source: curl" \ -H "Content-Type: application/json" \ -d '{"test1":"no trigger configured yet"}' ``` Unfortunately we haven't configured any trigger yet, which means any ingested event will not be delivered. `event_display` is a CloudEvents consumer that logs to console the list of events received. We will be creating 2 instances of `event_display`, one as the target for consumed events and another one for the Dead Letter Sink. A Dead Letter Sink, abbreviated DLS is a destination that consumes events that a subscription was not able to deliver to the intended target. ```console # Target service kubectl apply -f https://raw.githubusercontent.com/triggermesh/triggermesh-core/main/docs/assets/manifests/common/display-target.yaml # DLS service kubectl apply -f https://raw.githubusercontent.com/triggermesh/triggermesh-core/main/docs/assets/manifests/common/display-deadlettersink.yaml ``` The Trigger object configures the broker to consume events and send them to a target. The Trigger object can include filters that select which events should be forwarded to the target, and delivery options to configure retries and fallback targets when the event cannot be delivered. ```console kubectl apply -f https://raw.githubusercontent.com/triggermesh/triggermesh-core/main/docs/assets/manifests/getting-started-redis/trigger.yaml ``` The Trigger created above filters by CloudEvents containing `type: demo.type1` attribute and delivers them to `display-target` service, if delivery fails it will issue 3 retries and then forward the CloudEvent to the `display-deadlettersink` service. Using the `curl` Pod again we can send this CloudEvent to the broker. ```console kubectl exec -ti curl -- curl -v http://demo-rb-broker.default.svc.cluster.local/ \ -X POST \ -H "Ce-Id: 1234-abcd" \ -H "Ce-Specversion: 1.0" \ -H "Ce-Type: demo.type1" \ -H "Ce-Source: curl" \ -H "Content-Type: application/json" \ -d '{"test 2":"message for display target"}' ``` The target display Pod will show the delivered event. ```console kubectl logs -l app=display-target --tail 100 ☁️ cloudevents.Event Validation: valid Context Attributes, specversion: 1.0 type: demo.type1 source: curl id: 1234-abcd datacontenttype: application/json Extensions, triggermeshbackendid: 1666613846441-0 Data, { "test": "value2" } ``` To simulate a target failure we will reconfigure the target display service to make it point to a non existing Pod set: ```console kubectl delete -f https://raw.githubusercontent.com/triggermesh/triggermesh-core/main/docs/assets/manifests/common/display-target.yaml ``` Any event that pass the filter will try to be sent to the target, and upon failing will be delivered to the DLS. ```console kubectl exec -ti curl -- curl -v http://demo-rb-broker.default.svc.cluster.local/ \ -X POST \ -H "Ce-Id: 1234-abcd" \ -H "Ce-Specversion: 1.0" \ -H "Ce-Type: demo.type1" \ -H "Ce-Source: curl" \ -H "Content-Type: application/json" \ -d '{"test 3":"not delivered, will be sent to DLS"}' ``` ```console kubectl logs -l app=display-deadlettersink --tail 100 ☁️ cloudevents.Event Validation: valid Context Attributes, specversion: 1.0 type: demo.type1 source: curl id: 1234-abcd datacontenttype: application/json Extensions, triggermeshbackendid: 1666613846441-0 Data, { "test": "value3" } ``` ### Clean Up To clean up the getting started guide, delete each of the created assets: ```console # Removal of display-target not in this list, since it was deleted previously. kubectl delete -f \ https://raw.githubusercontent.com/triggermesh/triggermesh-core/main/docs/assets/manifests/getting-started-redis/trigger.yaml,\ https://raw.githubusercontent.com/triggermesh/triggermesh-core/main/docs/assets/manifests/common/display-deadlettersink.yaml,\ https://raw.githubusercontent.com/triggermesh/triggermesh-core/main/docs/assets/manifests/getting-started-redis/broker.yaml,\ https://raw.githubusercontent.com/triggermesh/triggermesh-core/main/docs/assets/manifests/common/curl.yaml ``` --- ## File: docs/brokers/triggerfilters.md # Trigger filters Events flowing through a Broker can be filtered before being sent to targets by means of Trigger filters. TriggerMesh filters are based on the [CloudEvents Subscriptions API filters](https://github.com/cloudevents/spec/blob/main/subscriptions/spec.md#324-filters), which allow for fairly complex filtering against event metadata, known as [CloudEvent context attributes](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#context-attributes). Filters are not supported for the event payload (i.e. the `data` attribute of an event). Content-based filtering of entire payload will be added in the future. As described below, TriggerMesh on Kubernetes provides full control over Trigger filters through its Kubernetes CRD. On the other hand, `tmctl` provides a simpler abstraction over filters as described in the [Trigger documentation](triggers.md). ## Filter operators Filter operators fall under two categories: string matching functions `exact`, `prefix` and `suffix`, and logical operators `all`, `any` and `not` to combine them. The string matching functions can be used at the root of the `filters` attribute without requiring a logical operator. - `exact`: the key must exist and exactly match the provided value - `prefix` the key must exist and the value include the provided value as a prefix - `suffix` the key must exist and the value include the provided value as a suffix - `all` all operators must evaluate to `true` - `any` at least one operator must evaluate to `true` - `not` all operators must evaluate to `false` ## Examples Filter for events whose `type` attribute is set to `io.triggermesh.demo` ```yaml filters: - exact: type: my.demo.type ``` Filter for events whose `type` attribute is set to `io.triggermesh.demo` and `category` is set to `test` ```yaml filters: - all: - exact: type: io.triggermesh.demo - exact: category: test ``` Filter for events whose `type` attribute starts with `io.triggermesh.` or `type` is set to `io.tm.demo` ```yaml filters: - any: - prefix: type: io.triggermesh. - exact: type: io.tm.demo ``` Filter for events whose `type` attribute does not ends with `.avoid.me` or `.avoid.me.too`. ```yaml filters: - not: - any: - suffix: type: .avoid.me - suffix: type: .avoid.me.too ``` --- ## File: docs/brokers/triggers.md # Triggers A Trigger belongs to a broker, and is used to route events from a Broker to a Target. A Broker can have multiple Triggers, and each Trigger has its own filters which are used to determine if an event should fire the trigger. When an event lands on a Broker, it is evaluated against all that Broker's Triggers and will fire every Trigger whose filters are a match. This allows for publish-subscribe style communication. ## `tmctl` ```sh tmctl create trigger --eventTypes --target ``` `tmctl` provides easy definition of Triggers. Just like any other TriggerMesh component, `tmctl` assumes that the Trigger should be assigned to the current Broker, but a different Broker can be specified with the `--broker` parameter. The only required parameter for a Trigger with `tmctl` is `--target` which specifies the name of the target that should be used to deliver the event to an external consumer. The `--eventTypes` parameter is used to specify which event types should match this Trigger's filter. If an array of types is provided, for example `--eventTypes mytype1, mytype2` then events matching either type will fire the Trigger (`OR` logic). If no `--eventTypes` are provided, a catch-all Trigger will be created, that fires against every event that lands on the Broker. :material-alert: Warning: catch-all Triggers can create event loops when used incorrectly and are generally best avoided. As a shortcut, you can also use `--source` to specify the name of the source component that you want to use to fire the Trigger. Under the hood, `tmctl` will figure our the right filter to create based on the types of events emitted by that source. ## Kubernetes The Trigger custom resource definition lets you create Trigger objects on Kubernetes. Below is an example of a Trigger object definition: ```yaml apiVersion: eventing.triggermesh.io/v1alpha1 kind: Trigger metadata: name: mytrigger spec: broker: group: eventing.triggermesh.io kind: RedisBroker name: mybroker target: targets.triggermesh.io/v1alpha1 ref: apiVersion: targets.triggermesh.io/v1alpha1 kind: cloudeventstarget name: cloudeventstarget filters: ``` The key elements of a Trigger object are: - The Broker on which the Trigger will run - The Target to which events will be delivered. It must be set to either a Kubernetes object that can be resolved to an URL, or simply a URL. - The filters which contain a set of filter expressions that evaluate which events should fire the Trigger. The absence of a filter results in a catch-all Trigger. See [Trigger filters](triggerfilters.md) for details. - The optional Delivery section to configure retries and dead-lettering. See [delivery](eventdelivery.md) for details on configuring event delivery. --- ## File: docs/get-started/architecture.md # TriggerMesh's architecture ## TriggerMesh components TriggerMesh's main functionality is provided by individual components such as Brokers, Sources, Targets, and Transformations. Each component is a provided as container which can be configured declaratively to customise its behaviour. For example, the SQS Source takes the SQS queue ARN as a configuration. Brokers are the most complex of these containers: they include Triggers, and have the option of being backed by Redis for event durability. ## Working with TriggerMesh components There are two "user interfaces" that you can use to configure and run TriggerMesh components. `tmctl` is a command line interface that both lets you easily configure the components in a developer-friendly way, and also runs the containers on your machine using Docker. TriggerMesh components can also run natively on Kubernetes. This is made possible by the TriggerMesh custom resource definitions (CRDs) and controllers. Each TriggerMesh component has its own CRD. Sources, targets, transformations, and others all share one controller, and the Broker has its own controller. This means you can configure and operate TriggerMesh just like any other Kubernetes-native application and reap the associated benefits. ## How do events flow through TriggerMesh? TriggerMesh components communicate over the network according to the CloudEvents standard. CloudEvents provide a standard envelope for events which means they can be manipulated in a uniform way: routing, transformations, etc... become possible regardless of where the event comes from. CloudEvents also comes with protocol bindings which govern how components can exchange events over the network. Inside TriggerMesh, events are exchanged using the CloudEvents HTTP protocol binding. ## GitHub repos - Brokers and Triggers: these are the TriggerMesh eventing components. The source code for the Kubernetes controller can be found at [TriggerMesh Core](https://github.com/triggermesh/triggermesh-core). - Sources, Targets, Transformations, and other components: these let you connect to external systems and process events. Their source code can be found at [TriggerMesh](https://github.com/triggermesh/triggermesh). - `tmctl`: the command line interface, which makes the components from `triggermesh-core` and `triggermesh` easy to configure and run on Docker. The source code can be found [tmctl](https://github.com/triggermesh/tmctl). - The TriggerMesh documentation can be found at [docs](https://github.com/triggermesh/docs). ## Dependency on Knative Serving TriggerMesh relies on [Knative Serving](https://github.com/knative/serving) to run on Kubernetes. TriggerMesh sources and targets use Knative Serving to run as addressable services and to scale. We plan on relaxing this dependency in the future. --- ## File: docs/get-started/autocompletion.md # Configure autocompletion for `tmctl` !!! warning "Work in progress" We are still working to stabilise these instructions for various configurations. [Please let us know](https://github.com/triggermesh/tmctl/issues/new) if you encounter difficulties. With autocompletion with `tmctl`, you'll be able to hit the Tab key to get contextual recommendations for CLI commands and their parameters. If you used `brew install` to install `tmctl` then autocompletion should already be configured. For other methods, please follow the instructions below. === "Bash (Linux, Windows WSL)" ``` echo 'source <(tmctl completion bash)' >>~/.bash_profile ``` === "ZSH (MacOS, Linux)" If shell completion is not already enabled in your environment you will need to enable it by adding the following two commands to your `.zshrc`: ```sh autoload -Uz compinit compinit ``` With autocomplete for ZSH configured, you can proceed to configure autocomplete for `tmctl` with the following commands: ``` source <(tmctl completion zsh) compdef _tmctl tmctl ``` For autocomplete to load automatically in a new terminal, you should also add the two previous commands to your `.zshrc`. For other shells than those shown above, please try: ```sh tmctl completion --help ``` And then for example: ```sh tmctl completion fish --help ``` --- ## File: docs/get-started/concepts.md # TriggerMesh Concepts TriggerMesh lets you capture events with Sources, route and transform them using Transformations, Brokers, and Triggers, and deliver them to consumers using Targets. TriggerMesh provides a unified eventing experience meaning all events can be centralised to a single Broker with a common format called CloudEvents. ## Events In TriggerMesh, an Event is described using a common format that defines the structure and metadata description of events. The format is based on a subset of the [CloudEvents specification](https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md). TriggerMesh supports the JSON format of CloudEvents and uses the [HTTP protocol binding](https://github.com/cloudevents/spec/blob/main/cloudevents/bindings/http-protocol-binding.md) to transport CloudEvents over HTTP. A TriggerMesh Event is composed of the following elements: * `id`: Identifies the event * `specversion`: The version of the CloudEvents specification which the event uses. This enables the interpretation of the context * `type`: This attribute contains a value describing the type of event related to the originating occurrence. Often this attribute is used for routing, observability, policy enforcement, etc. * (optional) `dataschema`: Identifies the schema that data adheres to. When using the Registry, this can be an explicit reference to a schema version in the Registry. * (optional) `subject`: This describes the subject of the event, for example a filename if the event is “S3 object created” * (optional) `time`: timestamp of when the occurrence happened * (optional) `datacontenttype`: Content type of data value. For now TriggerMesh only supports JSON for Transformations and Advanced filters. Events may include any number of additional attributes with distinct names, known as extension attributes. The `data` attribute carries the event payload encoded into a media format specified by datacontenttype (e.g. application/json). It and adheres to the dataschema format if present. Example event: ```json { "specversion" : "1.0", "type" : "com.aws.s3.objectcreated", "source" : "aws.s3", "subject" : "mynewfile.jpg", "id" : "A234-1234-1234", "time" : "2018-04-05T17:31:00Z", "extension1" : "value", "datacontenttype" : "application/json", "dataschema": "http://schemas.myorg.com/schemagroups/awsS3/schemas/com.aws.s3.objectcreated@aws.s3/versions/2", "data" : "{\"hello\":\"world\"}" } ``` ## Sources Sources are the origin of data and events. These may be on-premises or cloud-based. Examples include databases, message queues, logs, and events from applications or services. All sources are listed and documented in the [sources documentation](../sources/awscloudwatch.md) and in the [API Reference](../reference/sources.md). ## Brokers, Triggers and Filters TriggerMesh provides a Broker that acts as an intermediary between event producers and consumers, decoupling them from each other and providing delivery guarantees to ensure that no events are lost along the way. Brokers behave like an event bus, meaning all events are buffered together as a group. Triggers are used to determine which events go to which targets. A Trigger is attached to a Broker, and contains a Filter which specifies which events should cause the Trigger to fire. These filters are based on event metadata or payload contents. If a Trigger fires, it sends the event to the Target defined in the Trigger. There are two flavours of the TriggerMesh Broker: MemoryBroker and RedisBroker. The former has no persistence, whereas the later is able to recover from failure scenarios without losing events. ## Targets Targets are the destination for the processed events or data. Examples include databases, message queues, monitoring systems, and cloud services. In some cases, a Target may in turn reply with another event (acknowledgment, error, ...). These response events can be handled with additional Triggers. Typically, the event `type`of a response event is the same as the original event type with `.response` appended to the end. All targets are listed and documented in the [targets documentation](../targets/awss3.md) and in the [API Reference](../reference/targets.md) ## Transformations Transformations are a set of modifications to incoming events. Examples include annotating incoming events with timestamps, dropping fields, or rearranging data to fit an expected format. TriggerMesh provides a few ways to transform events: * using the low-code TriggerMesh transformation language called Bumblebee * using functions written Python, NodeJS, and Ruby