From 37a53de0f79a4cf7558da70f7a3860a08ec8f3a1 Mon Sep 17 00:00:00 2001 From: Adam Harwayne Date: Tue, 21 May 2019 09:38:07 -0700 Subject: [PATCH] Remove the redundant Broker and Trigger documentation. Instead point to the docs repo. --- docs/broker/README.md | 273 +----------------------------------------- 1 file changed, 2 insertions(+), 271 deletions(-) diff --git a/docs/broker/README.md b/docs/broker/README.md index f14cb026fda..1b9dea02aed 100644 --- a/docs/broker/README.md +++ b/docs/broker/README.md @@ -1,277 +1,8 @@ # Broker and Trigger CRDs -The Broker and Trigger CRDs, both in `eventing.knative.dev/v1alpha1`, are -interdependent. +The `Broker` and `Trigger` CRDs are documented in the +[docs repo](https://github.com/knative/docs/blob/master/docs/eventing/broker-trigger.md). -## 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`s and give them 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-ingress -kubectl -n default create serviceaccount eventing-broker-filter -``` - -Then give it the needed RBAC permissions: - -```shell -kubectl -n default create rolebinding eventing-broker-ingress \ - --clusterrole=eventing-broker-ingress \ - --user=eventing-broker-ingress -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-ingress` or `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 -``` ## Implementation