From 1c2a1b28f2d5ca6c86cb76d6c82fe762b7ae7db4 Mon Sep 17 00:00:00 2001 From: Grant Rodgers Date: Mon, 6 May 2019 16:10:28 -0700 Subject: [PATCH 1/3] Add Broker/Trigger docs from eventing repo Mostly a copy of github.com/knative/eventing/docs/broker/README.md, but with a new intro and without the Implementation section. --- docs/eventing/broker-trigger.md | 268 ++++++++++++++++++++++++++++++++ 1 file changed, 268 insertions(+) create mode 100644 docs/eventing/broker-trigger.md diff --git a/docs/eventing/broker-trigger.md b/docs/eventing/broker-trigger.md new file mode 100644 index 00000000000..6eb7f7383e4 --- /dev/null +++ b/docs/eventing/broker-trigger.md @@ -0,0 +1,268 @@ +# Broker and Trigger + +Broker and Trigger are CRDs providing an event delivery mechanism that hides the +details of event routing from the event producer and event consumer. + +## Broker + +Broker represents an 'event mesh'. Events are sent to the Broker's ingress and +are then sent to any subscribers that are interested in that event. Once inside +a Broker, all metadata other than the CloudEvent is stripped away (e.g. unless +set as a CloudEvent attribute, there is no concept of how this event entered the +Broker). + +Example: + +```yaml +apiVersion: eventing.knative.dev/v1alpha1 +kind: Broker +metadata: + name: default +spec: + channelTemplate: + provisioner: + apiVersion: eventing.knative.dev/v1alpha1 + kind: ClusterChannelProvisioner + name: gcp-pubsub +``` + +## Trigger + +Trigger represents a desire to subscribe to events from a specific Broker. Basic +filtering on the types of events is provided. + +Example: + +```yaml +apiVersion: eventing.knative.dev/v1alpha1 +kind: Trigger +metadata: + name: my-service-trigger +spec: + filter: + sourceAndType: + type: dev.knative.foo.bar + subscriber: + ref: + apiVersion: serving.knative.dev/v1alpha1 + kind: Service + name: my-service +``` + +## Usage + +### ClusterChannelProvisioner + +`Broker`'s use their `spec.channelTemplate` to create their internal `Channel`s, +which dictate the durability guarantees of events sent to that `Broker`. If +`spec.channelTemplate` is not specified, then the +[default provisioner](https://www.knative.dev/docs/eventing/channels/default-channels/) +for their namespace is used. + +#### Setup + +Have a `ClusterChannelProvisioner` installed and set as the +[default provisioner](https://www.knative.dev/docs/eventing/channels/default-channels/) +for the namespace you are interested in. For development, the +[`in-memory` `ClusterChannelProvisioner`](https://github.com/knative/eventing/tree/master/config/provisioners/in-memory-channel#deployment-steps) +is normally used. + +#### Changing + +**Note** changing the `ClusterChannelProvisioner` of a running `Broker` will +lose all in-flight events. + +If you want to change which `ClusterChannelProvisioner` is used by a given +`Broker`, then determine if the `spec.channelTemplate` is specified or not. + +If `spec.channelTemplate` is specified: + +1. Delete the `Broker`. +1. Create the `Broker` with the updated `spec.channelTemplate`. + +If `spec.channelTemplate` is not specified: + +1. Change the + [default provisioner](https://github.com/knative/docs/blob/master/docs/eventing/channels/default-channels.md#setting-the-default-channel-configuration) + for the namespace that `Broker` is in. +1. Delete and recreate the `Broker`. + +### Broker + +There are two ways to create a Broker, via [namespace annotation](#annotation) +or [manual setup](#manual-setup). + +Normally the [namespace annotation](#annotation) is used to do this setup. + +#### Annotation + +The easiest way to get started, is to annotate your namespace (replace `default` +with the desired namespace): + +```shell +kubectl label namespace default knative-eventing-injection=enabled +``` + +This should automatically create the `default` `Broker` in that namespace. + +```shell +kubectl -n default get broker default +``` + +#### Manual Setup + +In order to setup a `Broker` manually, we must first create the required +`ServiceAccount` and give it the proper RBAC permissions. This setup is required +once per namespace. These instructions will use the `default` namespace, but you +can replace it with any namespace you want to install a `Broker` into. + +Create the `ServiceAccount`. + +```shell +kubectl -n default create serviceaccount eventing-broker-filter +``` + +Then give it the needed RBAC permissions: + +```shell +kubectl -n default create rolebinding eventing-broker-filter \ + --clusterrole=eventing-broker-filter \ + --user=eventing-broker-filter +``` + +Note that the previous commands uses three different objects, all named +`eventing-broker-filter`. The `ClusterRole` is installed with Knative Eventing +[here](../../config/200-broker-clusterrole.yaml). The `ServiceAccount` was +created two commands prior. The `RoleBinding` is created with this command. + +Now we can create the `Broker`. Note that this example uses the name `default`, +but could be replaced by any other valid name. + +```shell +cat << EOF | kubectl apply -f - +apiVersion: eventing.knative.dev/v1alpha1 +kind: Broker +metadata: + namespace: default + name: default +EOF +``` + +### Subscriber + +Now create some function that wants to receive those events. This document will +assume the following, but it could be anything that is `Addressable`. + +```yaml +apiVersion: serving.knative.dev/v1alpha1 +kind: Service +metadata: + name: my-service + namespace: default +spec: + runLatest: + configuration: + revisionTemplate: + spec: + container: + # This corresponds to + # https://github.com/knative/eventing-sources/blob/v0.2.1/cmd/message_dumper/dumper.go. + image: gcr.io/knative-releases/github.com/knative/eventing-sources/cmd/message_dumper@sha256:ab5391755f11a5821e7263686564b3c3cd5348522f5b31509963afb269ddcd63 +``` + +### Trigger + +Create a `Trigger` that sends only events of a particular type to `my-service`: + +```yaml +apiVersion: eventing.knative.dev/v1alpha1 +kind: Trigger +metadata: + name: my-service-trigger + namespace: default +spec: + filter: + sourceAndType: + type: dev.knative.foo.bar + subscriber: + ref: + apiVersion: serving.knative.dev/v1alpha1 + kind: Service + name: my-service +``` + +#### Defaulting + +The Webhook will default certain unspecified fields. For example if +`spec.broker` is unspecified, it will default to `default`. If +`spec.filter.sourceAndType.type` or `spec.filter.sourceAndType.Source` are +unspecified, then they will default to the special value empty string, which +matches everything. + +The Webhook will default the YAML above to: + +```yaml +apiVersion: eventing.knative.dev/v1alpha1 +kind: Trigger +metadata: + name: my-service-trigger + namespace: default +spec: + broker: default # Defaulted by the Webhook. + filter: + sourceAndType: + type: dev.knative.foo.bar + source: "" # Defaulted by the Webhook. + subscriber: + ref: + apiVersion: serving.knative.dev/v1alpha1 + kind: Service + name: my-service +``` + +You can make multiple `Trigger`s on the same `Broker` corresponding to different +types, sources, and subscribers. + +### Source + +Now have something emit an event of the correct type (`dev.knative.foo.bar`) +into the `Broker`. We can either do this manually or with a normal Knative +Source. + +#### Manual + +The `Broker`'s address is well known, it will always be +`-broker..svc.`. In our case, it is +`default-broker.default.svc.cluster.local`. + +While SSHed into a `Pod` and run: + +```shell +curl -v "http://default-broker.default.svc.cluster.local/" \ + -X POST \ + -H "X-B3-Flags: 1" \ + -H "CE-CloudEventsVersion: 0.1" \ + -H "CE-EventType: dev.knative.foo.bar" \ + -H "CE-EventTime: 2018-04-05T03:56:24Z" \ + -H "CE-EventID: 45a8b444-3213-4758-be3f-540bf93f85ff" \ + -H "CE-Source: dev.knative.example" \ + -H 'Content-Type: application/json' \ + -d '{ "much": "wow" }' +``` + +#### Knative Source + +Provide the Knative Source the `default` `Broker` as its sink: + +```yaml +apiVersion: sources.eventing.knative.dev/v1alpha1 +kind: ContainerSource +metadata: + name: heartbeats-sender +spec: + image: github.com/knative/eventing-sources/cmd/heartbeats/ + sink: + apiVersion: eventing.knative.dev/v1alpha1 + kind: Broker + name: default +``` \ No newline at end of file From 77f76f65cb0f5869a83fe052f5d5929406f75449 Mon Sep 17 00:00:00 2001 From: Grant Rodgers Date: Wed, 15 May 2019 15:20:17 -0700 Subject: [PATCH 2/3] Update wording based on feedback --- docs/eventing/broker-trigger.md | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/docs/eventing/broker-trigger.md b/docs/eventing/broker-trigger.md index 6eb7f7383e4..1360f869136 100644 --- a/docs/eventing/broker-trigger.md +++ b/docs/eventing/broker-trigger.md @@ -5,7 +5,7 @@ details of event routing from the event producer and event consumer. ## Broker -Broker represents an 'event mesh'. Events are sent to the Broker's ingress and +A Broker represents an 'event mesh'. Events are sent to the Broker's ingress and are then sent to any subscribers that are interested in that event. Once inside a Broker, all metadata other than the CloudEvent is stripped away (e.g. unless set as a CloudEvent attribute, there is no concept of how this event entered the @@ -28,8 +28,8 @@ spec: ## Trigger -Trigger represents a desire to subscribe to events from a specific Broker. Basic -filtering on the types of events is provided. +A Trigger represents a desire to subscribe to events from a specific Broker. Basic +filtering on the type and source of events is provided. Example: @@ -89,8 +89,10 @@ If `spec.channelTemplate` is not specified: ### Broker -There are two ways to create a Broker, via [namespace annotation](#annotation) -or [manual setup](#manual-setup). +There are two ways to create a Broker: + +* [namespace annotation](#annotation) +* [manual setup](#manual-setup) Normally the [namespace annotation](#annotation) is used to do this setup. @@ -103,7 +105,8 @@ with the desired namespace): kubectl label namespace default knative-eventing-injection=enabled ``` -This should automatically create the `default` `Broker` in that namespace. +This should automatically create a `Broker` named `default` in the `default` +namespace. ```shell kubectl -n default get broker default @@ -150,8 +153,9 @@ EOF ### Subscriber -Now create some function that wants to receive those events. This document will -assume the following, but it could be anything that is `Addressable`. +Now create a function to receive those events. This document will +assume the following manifest describing a Knative Service is created, but it +could be anything that is `Addressable`. ```yaml apiVersion: serving.knative.dev/v1alpha1 @@ -172,7 +176,8 @@ spec: ### Trigger -Create a `Trigger` that sends only events of a particular type to `my-service`: +Create a `Trigger` using the following manifest that sends only events of a +particular type to `my-service`: ```yaml apiVersion: eventing.knative.dev/v1alpha1 From 9a9d9c22dd99f9e5b1207376fb0047edf2c40113 Mon Sep 17 00:00:00 2001 From: Grant Rodgers Date: Thu, 16 May 2019 10:40:30 -0700 Subject: [PATCH 3/3] Add title yaml and remove errant apostrophe --- docs/eventing/broker-trigger.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/eventing/broker-trigger.md b/docs/eventing/broker-trigger.md index 1360f869136..b35aa83435b 100644 --- a/docs/eventing/broker-trigger.md +++ b/docs/eventing/broker-trigger.md @@ -1,4 +1,8 @@ -# Broker and Trigger +--- +title: "Broker and Trigger" +weight: 20 +type: "docs" +--- Broker and Trigger are CRDs providing an event delivery mechanism that hides the details of event routing from the event producer and event consumer. @@ -53,7 +57,7 @@ spec: ### ClusterChannelProvisioner -`Broker`'s use their `spec.channelTemplate` to create their internal `Channel`s, +`Broker`s use their `spec.channelTemplate` to create their internal `Channel`s, which dictate the durability guarantees of events sent to that `Broker`. If `spec.channelTemplate` is not specified, then the [default provisioner](https://www.knative.dev/docs/eventing/channels/default-channels/)