knative
/
docs
mirror of https://github.com/knative/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

With 0.15 the MTChannelBasedBroker is the new default broker (#2533) 

Signed-off-by: Matthias Wessendorf <mwessend@redhat.com>
This commit is contained in:
Matthias Wessendorf 2020-06-02 19:10:18 +02:00 committed by GitHub
parent 416416b433
commit 8b6dc70ccd
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 62 additions and 254 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/eventing/broker/README.md
View File

@ -13,7 +13,7 @@ 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`
[MT Channel Based Broker](./mt-channel-based-broker.md). Simple example showing a `Broker`
where the configuration is specified in a `ConfigMap` config-br-default-channel,
which uses `InMemoryChannel`:
@ -112,7 +112,7 @@ have the extension `myextension` with the value `my-extension-value`.
### Broker setup
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).
yet, [install it from here](./mt-channel-based-broker.md).
### Subscriber

252
docs/eventing/broker/channel-based-broker.md
View File

@ -1,252 +0,0 @@
---
title: "Channel Based Broker"
weight: 30
type: "docs"
---
NOTE: This doc 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.
Knative provides a `Broker` implementation that uses [Channels](../channels/) for
event routing. You will need to have a Channel provider installed, for example
InMemoryChannel (for development purposes), Kafka, Nats, etc. You can choose from
list of [available channels](https://knative.dev/docs/eventing/channels/channels-crds/)
Once you have decided which Channel(s) you want to use and have installed them, you
can configure the Broker by controlling which Channel(s) are used. You can choose
this as a cluster level default, by namespace or by a specific Broker. These are
configured by a `config-br-defaults` `ConfigMap` in knative-eventing namespace.
Here's an example of a configuration that uses Kafka channel for all the
Brokers except namespace `test-broker-6` which uses InMemoryChannels. First
define the `ConfigMap`s to describe how the Channels of each type are created:
```yaml
# Define how InMemoryChannels are created
apiVersion: v1
kind: ConfigMap
metadata:
namespace: knative-eventing
name: imc-channel
data:
channelTemplateSpec: |
apiVersion: messaging.knative.dev/v1beta1
kind: InMemoryChannel
```
```yaml
# Define how Kafka channels are created. Note we specify
# extra parameters that are particular to Kakfa Channels, namely
# numPartitions as well as replicationFactor.
apiVersion: v1
kind: ConfigMap
metadata:
name: kafka-channel
namespace: knative-eventing
data:
channelTemplateSpec: |
apiVersion: messaging.knative.dev/v1alpha1
kind: KafkaChannel
spec:
numPartitions: 3
replicationFactor: 1
```
```yaml
kind: ConfigMap
apiVersion: v1
metadata:
name: config-br-defaults
namespace: knative-eventing
data:
default-br-config: |
clusterDefault:
brokerClass: ChannelBasedBroker
apiVersion: v1
kind: ConfigMap
name: imc-channel
namespace: knative-eventing
namespaceDefaults:
brokerClass: ChannelBasedBroker
test-broker-6:
apiVersion: v1
kind: ConfigMap
name: kafka-channel
namespace: knative-eventing
```
## Installing Broker by Annotation
The easiest way to get Broker installed, is to annotate your namespace
(replace `default` with the desired namespace):
```shell
kubectl label namespace default knative-eventing-injection=enabled
```
This will automatically create a `Broker` named `default` in the `default`
namespace. As per above configuration, it would be configured to use Kafka
channels.
```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
```
## Installing Broker by Trigger Annotation
Besides the annotation of the namespace, there is an alternative approach to annotate
one of the Triggers, with `knative-eventing-injection: enabled`:
```yaml
apiVersion: eventing.knative.dev/v1beta1
kind: Trigger
metadata:
annotations:
knative-eventing-injection: enabled
name: testevents-trigger0
namespace: default
spec:
broker: default
filter:
attributes:
type: dev.knative.sources.ping
subscriber:
ref:
apiVersion: serving.knative.dev/v1
kind: Service
name: broker-display
```
However, this approach only works _if_ the `Trigger` is coupled to the default `Broker`, and takes only effect
when there is no default `Broker` already present.
Deleting the `Trigger` does not delete the `Broker`. With this approach the same rules from the
[namespace annotation](./#installing-broker-by-annotation) apply here.
## Installing Broker Manually
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
```
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.
At the time of writing, the broker expects 3 configmaps to run properly: `eventing-config-{logging, observability, tracing}`.
You can manually copy the corresponding configmaps under [`eventing/config/`](https://github.com/knative/eventing/tree/release-0.13/config).
An easier way is to create a `ConfigMapPropagation` object and the configmaps will be automatically
propagated. To do so,
```shell
cat << EOF | kubectl apply -f -
apiVersion: configs.internal.knative.dev/v1alpha1
kind: ConfigMapPropagation
metadata:
namespace: default
name: eventing
spec:
originalNamespace: knative-eventing
selector:
# Only propagate configmaps with a specific label.
matchLabels:
knative.dev/config-category: eventing
EOF
```
Now we can create the `Broker`. Note that this example uses the name `default`,
but could be replaced by any other valid name. This example uses the defaults
for Channel that we configured above in our `config-br-defaults` `ConfigMap`,
and hence would use Kafka Channels.
```shell
cat << EOF | kubectl apply -f -
apiVersion: eventing.knative.dev/v1beta1
kind: Broker
metadata:
namespace: default
name: default
EOF
```
If you wanted to explicitly specify the Configuration of the Broker, you could do
so by using spec.config, like so (manually overriding it to use InMemoryChannels).
```shell
cat << EOF | kubectl apply -f -
apiVersion: eventing.knative.dev/v1beta1
kind: Broker
metadata:
namespace: default
name: broker-2
spec:
config:
apiVersion: v1
kind: ConfigMap
name: imc-channel
namespace: knative-eventing
EOF
```
## Handling failed event delivery
Broker allows you to specify what to do in the case if failed event delivery, say
you have a consumer (function for example) that's failing to process the event.
You can use `delivery` for it:
```yaml
apiVersion: eventing.knative.dev/v1beta1
kind: Broker
metadata:
name: default
spec:
config:
apiVersion: v1
kind: ConfigMap
namespace: knative-eventing
name: imc-channel
# Deliver failed events here
delivery:
deadLetterSink:
ref:
apiVersion: serving.knative.dev/v1
kind: Service
name: error-handler
```
You can find out more about delivery spec details [here](https://knative.dev/docs/eventing/event-delivery/).

60
docs/eventing/broker/mt-channel-based-broker.md
View File

@ -145,4 +145,64 @@ spec:
EOF
```
## Creating Broker by Annotation
The easiest way to get Broker installed, is to annotate your namespace
(replace `default` with the desired namespace):
```shell
kubectl label namespace default knative-eventing-injection=enabled
```
This will automatically create a `Broker` named `default` in the `default`
namespace. As per above configuration, it would be configured to use Kafka
channels.
```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
```
## Creating Broker by Trigger Annotation
Besides the annotation of the namespace, there is an alternative approach to annotate
one of the Triggers, with `knative-eventing-injection: enabled`:
```yaml
apiVersion: eventing.knative.dev/v1beta1
kind: Trigger
metadata:
annotations:
knative-eventing-injection: enabled
name: testevents-trigger0
namespace: default
spec:
broker: default
filter:
attributes:
type: dev.knative.sources.ping
subscriber:
ref:
apiVersion: serving.knative.dev/v1
kind: Service
name: broker-display
```
However, this approach only works _if_ the `Trigger` is coupled to the default `Broker`, and takes only effect
when there is no default `Broker` already present.
Deleting the `Trigger` does not delete the `Broker`. With this approach the same rules from the
[namespace annotation](./#installing-broker-by-annotation) apply here.
You can find out more about delivery spec details [here](https://knative.dev/docs/eventing/event-delivery/).