brokers doc

Author: odacremolbap

README.md

@@ -14,6 +14,18 @@ Devevlopment version might be unstable.
 ko apply -f ./config
 ```
 
+## Concepts
+
+TriggerMesh core contains Kubernetes objects for Brokers and Triggers:
+
+- [RedisBroker](docs/redis-broker.md)
+- [MemoryBroker](docs/memory-broker.md)
+- [Trigger](docs/trigger.md)
+
+The brokers are used to ingest events and route them to targets. To ingest events, they must conform to the [CloudEvents specification][ce-spec] using the HTTP binding, and must use the HTTP address exposed by the Broker.
+
+Events consumption is done asynchronously by configuring Triggers that reference a Broker object. A Trigger must also include information about the consumer address, either a Kubernetes object or an HTTP address, and optionally can include an event filter.
+
 ## Usage
 
 - [Getting Started (Redis Broker)](docs/getting-started-redis.md).
@@ -37,3 +49,4 @@ Additionally, the End User License Agreement included in the [`EULA.pdf`](EULA.p
 executables and container images released by TriggerMesh Inc.
 
 [asl2]: https://www.apache.org/licenses/LICENSE-2.0
+[ce-spec]: https://github.com/cloudevents/spec

docs/memory-broker.md

@@ -0,0 +1,29 @@
+# Memory Broker
+
+## Spec
+
+```yaml
+apiVersion: eventing.triggermesh.io/v1alpha1
+kind: MemoryBroker
+metadata:
+  name: <broker instance name>
+spec:
+  memory:
+    bufferSize: <maximum number of events>
+  broker:
+    port: <HTTP port for ingesting events>
+    observability:
+      valueFromConfigMap: <kubernetes ConfigMap that contains observability configuration>
+```
+
+The only `MemoryBroker` specific parameter is `spec.memory.bufferSize` which indicates the availible 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 Borker 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](observability.md). This parameter is optional.
+
+## Example
+
+- See [MemoryBroker example](https://github.com/triggermesh/triggermesh-core/blob/main/docs/assets/manifests/getting-started-memory/broker.yaml)
+- See [MemoryBroker getting started guide](getting-started-memory.md)

docs/observability.md

@@ -0,0 +1,3 @@
+## Broker Observability
+
+TODO

docs/redis-broker.md

@@ -0,0 +1,46 @@
+# Redis Broker
+
+## Spec
+
+```yaml
+apiVersion: eventing.triggermesh.io/v1alpha1
+kind: RedisBroker
+metadata:
+  name: <broker instance name>
+spec:
+  redis:
+    connection: <Provides a connection to an external Redis instance. Optional>
+        url: <redis URL. Required>
+        username: <redis username, referenced using a Kubernetes secret>
+          secretKeyRef:
+            name: <Kubernetes secret name>
+            key: <Kubernetes secret key>
+        password: <redis password, referenced using a Kubernetes secret>
+          secretKeyRef:
+            name: <Kubernetes secret name>
+            key: <Kubernetes secret key>
+        tlsEnabled: <boolean that indicates if the Redis server is TLS protected. Optional, defaults to false>
+        tlsSkipVerify: <boolean that skips verifying TLS certificates. Optional, defaults to false>
+    stream: <Redis stream name. Optional, defaults to a combination of namespace and broker name>
+    streamMaxLen: <maximum number of items the Redis stream can host. Optional, defaults to unlimited>
+  broker:
+    port: <HTTP port for ingesting events>
+    observability:
+      valueFromConfigMap: <kubernetes ConfigMap that contains observability configuration>
+```
+
+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 Borker 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](observability.md). This parameter is optional.
+
+## Example
+
+- See [RedisBroker example](https://github.com/triggermesh/triggermesh-core/blob/main/docs/assets/manifests/getting-started-redis/broker.yaml)
+- See [RedisBroker getting started guide](getting-started-redis.md)

docs/trigger.md

@@ -0,0 +1,3 @@
+# Trigger
+
+TODO