Skip to content

Update docs to v1beta1 + add more details about channel based broker #2259

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Mar 3, 2020
Merged

Update docs to v1beta1 + add more details about channel based broker #2259

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7e157af
Update docs to v1beta1 + add more details about channel based broker
vaikas Feb 27, 2020
a862da9
fix yaml indentation + break broker into simple and simple with dlq
vaikas Feb 27, 2020
666e5bb
address PR feedback
vaikas Feb 28, 2020
a6afdea
Updated for eventing pr 2670
vaikas Mar 3, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
274 changes: 72 additions & 202 deletions docs/eventing/broker-trigger.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,27 +15,63 @@ 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).

There can be different classes of Brokers providing different kinds
of semantics around durability of events, performance, etc. The Broker that is
part of the Knative Eventing repo is used for these examples, it uses Knative
[Channels](./channels/) for delivering events. You can read more details about
[Channel Based Broker](./channel-based-broker.md). Simple example showing a `Broker`
where the configuration is specified in a `ConfigMap` config-br-default-channel,
which uses `InMemoryChannel`:

Example:

```yaml
apiVersion: eventing.knative.dev/v1alpha1
apiVersion: eventing.knative.dev/v1beta1
kind: Broker
metadata:
name: default
spec:
# Configuration specific to this broker.
config:
apiVersion: v1
kind: ConfigMap
name: config-br-default-channel
namespace: knative-eventing
```

More complex example, showing the same `Broker` as above
but with failed events being delivered to Knative Service called `dlq-service`

```yaml
apiVersion: eventing.knative.dev/v1beta1
kind: Broker
metadata:
name: default
spec:
channelTemplateSpec:
apiVersion: messaging.knative.dev/v1alpha1
kind: InMemoryChannel
# Configuration specific to this broker.
config:
apiVersion: v1
kind: ConfigMap
name: config-br-default-channel
namespace: knative-eventing
# Where to deliver Events that failed to be processed.
delivery:
deadLetterSink:
ref:
apiVersion: serving.knative.dev/v1
kind: Service
name: dlq-service
```

## Trigger

A Trigger represents a desire to subscribe to events from a specific Broker.

Example:
Simple example which will receive all the events from the given (`default`) broker and
deliver them to Knative Serving service `my-service`:

```yaml
apiVersion: eventing.knative.dev/v1alpha1
apiVersion: eventing.knative.dev/v1beta1
kind: Trigger
metadata:
name: my-service-trigger
Expand All @@ -57,7 +93,7 @@ Note that we only support exact matching on string values.
Example:

```yaml
apiVersion: eventing.knative.dev/v1alpha1
apiVersion: eventing.knative.dev/v1beta1
kind: Trigger
metadata:
name: my-service-trigger
Expand All @@ -77,146 +113,17 @@ spec:
The example above filters events from the `default` Broker that are of type `dev.knative.foo.bar` AND
have the extension `myextension` with the value `my-extension-value`.

## Usage

### Channel

`Broker`s use their `spec.channelTemplateSpec` to create their internal
[Channels](./channels/), which dictate the durability guarantees of events sent
to that `Broker`. If `spec.channelTemplateSpec` is not specified, then the
[default channel](./channels/default-channels.md) for their namespace is used.

#### Setup

Have a `Channel` CRD installed and set as the default channel for the namespace
you are interested in. For development, the
[InMemoryChannel](https://github.com/knative/eventing/tree/{{< branch >}}/config/channels/in-memory-channel)
is normally used.

#### Changing

**Note** changing the `Channel` of a running `Broker` will lose all in-flight
events.

If you want to change which `Channel` is used by a given `Broker`, then
determine if the `spec.channelTemplateSpec` is specified or not.

If `spec.channelTemplateSpec` is specified:

1. Delete the `Broker`.
1. Create the `Broker` with the updated `spec.channelTemplateSpec`.

If `spec.channelTemplateSpec` is not specified:

1. Change the
[default channel](./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:

- [namespace annotation](#annotation)
- [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 a `Broker` named `default` in the `default`
namespace.

```shell
kubectl -n default get broker default
```

_NOTE_ `Broker`s created due to annotation will not be removed if you remove the
annotation. For example, if you annotate the namespace, which will then create
the `Broker` as described above. If you now remove the annotation, the `Broker`
will not be removed, you have to manually delete it.

For example, to delete the injected Broker from the foo namespace:

```shell
kubectl -n foo delete 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` objects.

```shell
kubectl -n default create serviceaccount eventing-broker-ingress
kubectl -n default create serviceaccount eventing-broker-filter
```

Then give them the needed RBAC permissions:

```shell
kubectl -n default create rolebinding eventing-broker-ingress \
--clusterrole=eventing-broker-ingress \
--serviceaccount=default:eventing-broker-ingress
kubectl -n default create rolebinding eventing-broker-filter \
--clusterrole=eventing-broker-filter \
--serviceaccount=default:eventing-broker-filter
```
## Complete end-to-end example

Note that these commands each use three different objects, all named
`eventing-broker-ingress` or `eventing-broker-filter`. The `ClusterRole` is
installed with Knative Eventing
[here](https://github.com/knative/eventing/blob/master/config/200-broker-clusterrole.yaml).
The `ServiceAccount` was created two commands prior. The `RoleBinding` is
created with this command.

Create RBAC permissions granting access to shared configmaps for logging,
tracing, and metrics configuration.

_These commands assume the shared Knative Eventing components are installed in
the `knative-eventing` namespace. If you installed the shared Knative Eventing
components in a different namespace, replace `knative-eventing` with the name of
that namespace._

```shell
kubectl -n knative-eventing create rolebinding eventing-config-reader-default-eventing-broker-ingress \
--clusterrole=eventing-config-reader \
--serviceaccount=default:eventing-broker-ingress
kubectl -n knative-eventing create rolebinding eventing-config-reader-default-eventing-broker-filter \
--clusterrole=eventing-config-reader \
--serviceaccount=default:eventing-broker-filter
```

Now we can create the `Broker`. Note that this example uses the name `default`,
but could be replaced by any other valid name.
### Broker setup

```shell
cat << EOF | kubectl apply -f -
apiVersion: eventing.knative.dev/v1alpha1
kind: Broker
metadata:
namespace: default
name: default
EOF
```
We assume that you have installed a Broker in namespace `default`. If you haven't done that
yet, [install it from here](./channel-based-broker.md).

### Subscriber

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`.
Create a function to receive events. This document uses a Knative Service, but
it could be anything that is [Callable](https://github.com/knative/eventing/blob/master/docs/spec/interfaces.md).

```yaml
apiVersion: serving.knative.dev/v1
Expand All @@ -229,25 +136,26 @@ spec:
spec:
containers:
- # This corresponds to
# https://github.com/knative/eventing-contrib/blob/v0.2.1/cmd/message_dumper/dumper.go.
image: gcr.io/knative-releases/github.com/knative/eventing-sources/cmd/message_dumper@sha256:ab5391755f11a5821e7263686564b3c3cd5348522f5b31509963afb269ddcd63
# https://github.com/knative/eventing-contrib/tree/master/cmd/event_display
- image: gcr.io/knative-releases/knative.dev/eventing-contrib/cmd/event_display@sha256:a214514d6ba674d7393ec8448dd272472b2956207acb3f83152d3071f0ab1911
Copy link
Contributor

@grantr grantr Feb 28, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if we can use the latest tag here?

```

### Trigger

Create a `Trigger` using the following manifest that sends only events of a
particular type to `my-service`:
Create a `Trigger` that sends only events of a particular type to the subscriber
created above (`my-service`). For this example, we use Ping Source, and it
emits events types `dev.knative.sources.ping`.

```yaml
apiVersion: eventing.knative.dev/v1alpha1
apiVersion: eventing.knative.dev/v1beta1
kind: Trigger
metadata:
name: my-service-trigger
namespace: default
spec:
filter:
attributes:
type: dev.knative.foo.bar
type: dev.knative.sources.ping
subscriber:
ref:
apiVersion: serving.knative.dev/v1
Expand All @@ -263,7 +171,7 @@ unspecified.
The Webhook will default the YAML above to:

```yaml
apiVersion: eventing.knative.dev/v1alpha1
apiVersion: eventing.knative.dev/v1beta1
kind: Trigger
metadata:
name: my-service-trigger
Expand All @@ -272,7 +180,7 @@ spec:
broker: default # Defaulted by the Webhook.
filter:
attributes:
type: dev.knative.foo.bar
type: dev.knative.sources.ping
subscriber:
ref:
apiVersion: serving.knative.dev/v1
Expand All @@ -283,62 +191,24 @@ spec:
You can make multiple `Trigger`s on the same `Broker` corresponding to different
types, sources (or any other CloudEvents attribute), 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
`<name>-broker.<namespace>.svc.<ending>`. In our case, it is
`default-broker.default.svc.cluster.local`.
### Emitting Events using Ping Source

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-SpecVersion: 0.2" \
-H "CE-Type: dev.knative.foo.bar" \
-H "CE-Time: 2018-04-05T03:56:24Z" \
-H "CE-ID: 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 (note you'll need
to use ko apply -f <source_file>.yaml to create it):
Knative Eventing comes with a [Ping Source](./samples/ping-source/README.md) which
emits an event on a configured schedule. For this we'll configure it to emit
events once a minute, saying, yes, you guessed it `Hello World!`.

```yaml
apiVersion: sources.eventing.knative.dev/v1alpha1
kind: ContainerSource
apiVersion: sources.knative.dev/v1alpha1
kind: PingSource
metadata:
name: heartbeats-sender
name: test-ping-source
spec:
template:
spec:
containers:
- image: github.com/knative/eventing-contrib/cmd/heartbeats/
name: heartbeats-sender
args:
- --eventType=dev.knative.foo.bar
env:
- name: POD_NAME
valueFrom:
fieldRef:
fieldPath: metadata.name
- name: POD_NAMESPACE
valueFrom:
fieldRef:
fieldPath: metadata.namespace
schedule: "*/1 * * * *"
Copy link
Contributor

@grantr grantr Feb 28, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the /1 here isn't needed, it can just be * * * * *

data: '{"message": "Hello world!"}'
sink:
apiVersion: eventing.knative.dev/v1alpha1
kind: Broker
name: default
ref:
# Deliver events to Broker.
apiVersion: eventing.knative.dev/v1alpha1
Copy link
Contributor

@grantr grantr Feb 28, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

v1beta1 here right?

kind: Broker
name: default
```
Loading