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

clean up the broker docs, separate broker defaults (#2642)

This commit is contained in:
Ville Aikas 2020-07-06 09:30:43 -07:00 committed by GitHub
parent 88ee5c6f5d
commit 1b4beb4f0f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 330 additions and 167 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -23,6 +23,8 @@ Example:
apiVersion: eventing.knative.dev/v1
kind: Broker
metadata:
annotations:
eventing.knative.dev/broker.class: MTChannelBasedBroker
name: default
spec:
# Configuration specific to this broker.
@ -40,6 +42,8 @@ but with failed events being delivered to Knative Service called `dlq-service`
apiVersion: eventing.knative.dev/v1
kind: Broker
metadata:
annotations:
eventing.knative.dev/broker.class: MTChannelBasedBroker
name: default
spec:
# Configuration specific to this broker.
@ -57,55 +61,90 @@ spec:
name: dlq-service
```
### Creating a broker using annotation
### Creating a broker using defaults
You can create a broker annotate your namespace:
Knative Eventing provides a `ConfigMap` which by default lives in
`knative-eventing` namespace and is called `default-br-config`. Out of the box
it comes configured to create
[MT Channel Based Brokers](./mt-channel-based-broker.md). If you are using a
different Broker implementation, you should modify the `ConfigMap`
accordingly. You can read more details on how to use
[default-br-config config map ](./defaults-br-config.md)
```shell
kubectl label namespace <namespace> knative-eventing-injection=enabled
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: config-br-defaults
namespace: knative-eventing
labels:
eventing.knative.dev/release: v0.16.0
data:
# Configuration for defaulting channels that do not specify CRD implementations.
default-br-config: |
clusterDefault:
brokerClass: MTChannelBasedBroker
apiVersion: v1
kind: ConfigMap
name: config-br-default-channel
namespace: knative-eventing
```
This will automatically create a broker named `default`, which is configured to use
Kafka channels, in the specified namespace.
With this ConfigMap, any Broker created will be configured to use
MTChannelBasedBroker and the `Broker.Spec.Config` will be configured as
specified in the clusterDefault configuration. So, example below will create a
`Broker` called default in default namespace and uses MTChannelBasedBroker as
implementation.
```shell
kubectl -n default get broker default
kubectl create -f - <<EOF
apiVersion: eventing.knative.dev/v1
kind: Broker
metadata:
name: default
namespace: default
EOF
```
**NOTE:** Brokers created due by annotation will not be removed if you remove the
annotation. You must manually remove these brokers.
To delete the injected broker:
```shell
kubectl -n <namespace> delete broker default
```
### Creating a broker using trigger annotation
If you have a trigger that is coupled to the `default` broker, and there is no existing `default` broker, you can also annotate using triggers to create a broker:
The defaults specified in the `defaults-br-config` will result in a following
Broker being created.
```yaml
apiVersion: eventing.knative.dev/v1
kind: Trigger
kind: Broker
metadata:
annotations:
knative-eventing-injection: enabled
name: testevents-trigger0
eventing.knative.dev/broker.class: MTChannelBasedBroker
name: default
namespace: default
spec:
broker: default
filter:
attributes:
type: dev.knative.sources.ping
subscriber:
ref:
apiVersion: serving.knative.dev/v1
kind: Service
name: broker-display
config:
apiVersion: v1
kind: ConfigMap
name: config-br-default-channel
namespace: knative-eventing
```
**NOTE:** Deleting a trigger will not delete any brokers created using by annotating that trigger. You must delete these brokers manually.
To see the created `Broker`, you can get it like this:
```shell
kubectl get brokers default
```
```shell
kubectl get brokers default
NAME READY REASON URL AGE
default True http://broker-ingress.knative-eventing.svc.cluster.local/default/default 56m
```
Note the `URL` field where you can send `CloudEvent`s andthen use `Trigger`s to
route them to your functions.
To delete the `Broker`:
```shell
kubectl delete broker default
```
## Trigger
@ -114,7 +153,8 @@ A Trigger represents a desire to subscribe to events from a specific Broker.
Simple example which will receive all the events from the given (`default`) broker and
deliver them to Knative Serving service `my-service`:
```yaml
```shell
kubectl create -f - <<EOF
apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
@ -126,17 +166,20 @@ spec:
apiVersion: serving.knative.dev/v1
kind: Service
name: my-service
EOF
```
### Trigger Filtering
Exact match filtering on any number of CloudEvents attributes as well as extensions are
supported. If your filter sets multiple attributes, an event must have all of the attributes for the Trigger to filter it.
Note that we only support exact matching on string values.
Exact match filtering on any number of CloudEvents attributes as well as
extensions are supported. If your filter sets multiple attributes, an event must
have all of the attributes for the Trigger to filter it. Note that we only
support exact matching on string values.
Example:
```yaml
```shell
kubectl create -f - <<EOF
apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
@ -152,25 +195,29 @@ spec:
apiVersion: serving.knative.dev/v1
kind: Service
name: my-service
EOF
```
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`.
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`.
## Complete end-to-end example
<!-- TODO: review + clean this section up-->
### Broker setup
We assume that you have installed a Broker in namespace `default`. If you haven't done that
yet, [install it from here](./mt-channel-based-broker.md).
We assume that you have installed a Broker in namespace `default`. If you
haven't done that yet, [install it from here](./mt-channel-based-broker.md).
### Subscriber
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).
it could be anything that is
[Callable](https://github.com/knative/eventing/blob/master/docs/spec/interfaces.md).
```yaml
```shell
kubectl create -f - <<EOF
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
@ -183,6 +230,7 @@ spec:
- # This corresponds to
# https://github.com/knative/eventing-contrib/tree/master/cmd/event_display
image: gcr.io/knative-releases/knative.dev/eventing-contrib/cmd/event_display
EOF
```
### Trigger
@ -191,7 +239,8 @@ 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
```shell
kubectl create -f - <<EOF
apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
@ -207,43 +256,17 @@ spec:
apiVersion: serving.knative.dev/v1
kind: Service
name: my-service
EOF
```
#### Defaulting
The Webhook will default the `spec.broker` field to `default`, if left
unspecified.
The Webhook will default the YAML above to:
```yaml
apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
name: my-service-trigger
namespace: default
spec:
broker: default
filter:
attributes:
type: dev.knative.sources.ping
subscriber:
ref:
apiVersion: serving.knative.dev/v1
kind: Service
name: my-service
```
You can make multiple `Trigger`s on the same `Broker` corresponding to different
types, sources (or any other CloudEvents attribute), and subscribers.
### Emitting Events using Ping Source
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
```shell
kubectl create -f - <<EOF
apiVersion: sources.knative.dev/v1alpha2
kind: PingSource
metadata:
@ -257,4 +280,5 @@ spec:
apiVersion: eventing.knative.dev/v1
kind: Broker
name: default
EOF
```

186
docs/eventing/broker/defaults-br-config.md Normal file
View File

@ -0,0 +1,186 @@
---
title: "defaults-br-config"
weight: 30
type: "docs"
---
Knative provides a `ConfigMap` which makes it easier to create Brokers by
providing default values when Brokers are created. You can control which Broker
implementations are used and how they are configured by modifying this file. You
have the flexibility to control the defaults both at the cluster level (each
Broker created in the cluster) as well as at the namespace level (override the
behaviour for certain namespaces).
## Format of the file
Let's look at the `ConfigMap` that comes out of the box when you install a
release (v0.16.0 in this example):
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: config-br-defaults
namespace: knative-eventing
labels:
eventing.knative.dev/release: devel
data:
# Configuration for defaulting channels that do not specify CRD implementations.
default-br-config: |
clusterDefault:
brokerClass: MTChannelBasedBroker
apiVersion: v1
kind: ConfigMap
name: config-br-default-channel
namespace: knative-eventing
```
This means that any Broker created without a specific BrokerClass annotation or
`spec.config` will use a `MTChannelBasedBroker` implementation and the Broker
will have spec.config like so:
```
spec:
config:
apiVersion: v1
kind: ConfigMap
name: config-br-default-channel
namespace: knative-eventing
```
## Changing the default BrokerClass
### Changing the default BrokerClass for the cluster
If you have installed a different Broker, or multiple, you can change the
default Broker used at the cluster level and by namespace. If you for example
have installed MT Channel Based Broker as well as `YourBroker` and would prefer
that by default any Broker created uses `YourBroker` you could modify the
configmap to look like this:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: config-br-defaults
namespace: knative-eventing
labels:
eventing.knative.dev/release: devel
data:
# Configuration for defaulting channels that do not specify CRD implementations.
default-br-config: |
clusterDefault:
brokerClass: YourBroker
```
Now every Broker created in the cluster without the BrokerClass annotation will
be using `YourBroker` as the Broker implementation. Note that you can always use
a different implementation by explicity specifying the BrokerClass annotation
when you create a Broker.
### Changing the default BrokerClass for namespaces
As mentioned, you can also control the defaulting behaviour for some set of
namespaces. So, if for example, you wanted to use YourBroker for all the other
Brokers created, but wanted to use MTChannelBasedBroker for the following
namespaces: namespace1 and namespace2. You would modify the config map like
this:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: config-br-defaults
namespace: knative-eventing
labels:
eventing.knative.dev/release: devel
data:
# Configuration for defaulting channels that do not specify CRD implementations.
default-br-config: |
clusterDefault:
brokerClass: YourBroker
namespaceDefaults:
namespace1:
brokerClass: MTChannelBasedBroker
namespace2:
brokerClass: MTChannelBasedBroker
```
## Changing the default configuration of the Broker
### Changing the default configuration for the cluster
You can also control Broker configuration defaulting behaviour by specifying
what gets defaulted into a broker.spec.config if left empty when being created.
If you have installed a different Channel implementation (for example Kafka),
and by default would like to use that for any Broker created you could change
the ConfigMap to look like this:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: config-br-defaults
namespace: knative-eventing
labels:
eventing.knative.dev/release: devel
data:
# Configuration for defaulting channels that do not specify CRD implementations.
default-br-config: |
clusterDefault:
brokerClass: MTChannelBasedBroker
apiVersion: v1
kind: ConfigMap
name: config-kafka-channel
namespace: knative-eventing
```
Now every Broker created in the cluster without spec.config will be configured
to use `config-kafka-channel` ConfigMap. Note that you can always still
explicitly specify a different configuration for any given Broker by specifying
it in the `spec.config`.
### Changing the default configuration for namespaces
As mentioned, you can also control the defaulting behaviour for some set of
namespaces. So, if for example, you wanted to use config-kafka-channel for all
the other Brokers created, but wanted to use config-br-default-channel config the
following namespaces: namespace3 and namespace4. You would modify the config map like
this:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: config-br-defaults
namespace: knative-eventing
labels:
eventing.knative.dev/release: devel
data:
# Configuration for defaulting channels that do not specify CRD implementations.
default-br-config: |
clusterDefault:
brokerClass: MTChannelBasedBroker
apiVersion: v1
kind: ConfigMap
name: config-kafka-channel
namespace: knative-eventing
namespaceDefaults:
namespace3:
apiVersion: v1
kind: ConfigMap
name: config-br-default-channel
namespace: knative-eventing
namespace4:
apiVersion: v1
kind: ConfigMap
name: config-br-default-channel
namespace: knative-eventing
```
Note that we do not override the brokerClass for these namespaces. The
brokerClass and config are independently configurable.

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

@ -4,16 +4,21 @@ weight: 30
type: "docs"
---
Knative provides a Multi Tenant (MT) Broker implementation that uses [channels](../channels/) for
event routing.
Knative provides a Multi Tenant (MT) Broker implementation that uses
[channels](../channels/) for event routing.
## Before you begin
Before you can use the MT Broker, you will need to have a channel provider installed, for example, InMemoryChannel (for development purposes), Kafka or Nats.
Before you can use the MT Broker, you will need to have a channel provider
installed, for example, InMemoryChannel (for development purposes), Kafka or
Nats.
For more information on which channels are available, see the list of [available channels](https://knative.dev/docs/eventing/channels/channels-crds/).
For more information on which channels are available and how to install them,
see the list of [available channels](https://knative.dev/docs/eventing/channels/channels-crds/).
After you have installed the channel provider that you will use in your broker implementation, you must configure the ConfigMap for each channel type.
After you have installed the channel provider that will be used by MT Broker,
you must create a ConfigMap which specifies how to configure the channels that
the Broker creates for routing events.
**NOTE:** This guide assumes Knative Eventing is installed in the `knative-eventing`
namespace. If you have installed Knative Eventing in a different namespace, replace
@ -21,29 +26,54 @@ namespace. If you have installed Knative Eventing in a different namespace, repl
## Configure Channel ConfigMaps
You can define specifications for how each type of channel will be created, by modifying the ConfigMap for each channel type.
You can define specifications for how each type of channel will be created, by
modifying the ConfigMap for each channel type.
<!-- TODO: Split these configmaps out and document them properly in a section for each channel, then just link from here-->
### Example InMemoryChannel ConfigMap
When you install the InMemoryChannel Channel provider, the following YAML file is created automatically:
When you install the eventing release, the following YAML file is created automatically:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
namespace: knative-eventing
name: imc-channel
name: config-br-default-channel
data:
channelTemplateSpec: |
apiVersion: messaging.knative.dev/v1
kind: InMemoryChannel
```
To create a Broker that uses InMemoryChannel, you could create a Broker like
this:
```shell
kubectl create -f - <<EOF
apiVersion: eventing.knative.dev/v1
kind: Broker
metadata:
annotations:
eventing.knative.dev/broker.class: MTChannelBasedBroker
name: default
namespace: default
spec:
config:
apiVersion: v1
kind: ConfigMap
name: config-br-default-channel
namespace: knative-eventing
EOF
```
And the broker will use InMemoryChannel for routing events.
### Example Kafka Channel ConfigMap
To use Kafka channels, you must create a YAML file that specifies how these channels will be created.
To use Kafka channels, you must create a YAML file that specifies how these
channels will be created. **NOTE:** You must have Kafka Channel installed.
You can copy the following sample code into your Kafka channel ConfigMap:
@ -62,102 +92,25 @@ data:
replicationFactor: 1
```
**NOTE:** This example specifies two extra parameters that are specific to Kafka Channels; `numPartitions` and `replicationFactor`.
**NOTE:** This example specifies two extra parameters that are specific to Kafka
Channels; `numPartitions` and `replicationFactor`.
## Configuring the MT broker
After you have configured the ConfigMap for each Channel provider type, you can configure the MT Broker.
Channels can be configured as a cluster level default, by namespace, or for a specific broker.
The channels used by the MT broker can be configured in the `config-br-defaults` ConfigMap in the `knative-eventing` namespace.
The following example ConfigMap uses a Kafka channel for all brokers, except for the `example-ns` namespace, which uses InMemoryChannel.
### Example `config-br-defaults` ConfigMap
```yaml
kind: ConfigMap
apiVersion: v1
metadata:
name: config-br-defaults
namespace: knative-eventing
data:
default-br-config: |
clusterDefault:
brokerClass: MTChannelBasedBroker
apiVersion: v1
kind: ConfigMap
name: imc-channel
namespace: knative-eventing
namespaceDefaults:
brokerClass: MTChannelBasedBroker
example-ns:
apiVersion: v1
kind: ConfigMap
name: kafka-channel
namespace: knative-eventing
```
## Creating the MT broker using default configurations
To create the MT broker using the default configuration, use the command:
To create a Broker that uses Kafka underneath, you would do it like this:
```shell
kubectl apply -f - <<EOF
kubectl create -f - <<EOF
apiVersion: eventing.knative.dev/v1
kind: Broker
metadata:
name: mybroker
EOF
```
This creates a broker named `mybroker`, which is configured to use
InMemoryChannel, in the `default`
namespace.
```shell
kubectl -n default get broker mybroker
```
## Creating a custom MT broker using custom configurations
You can construct a custom broker object to suit your use case, without using the default configurations.
For example, to create a broker that has a different Kafka configuration, you can create a custom configuration as shown in the example.
In this example, the number of partitions has been increased to 10.
```shell
kubectl apply -f - <<EOF
apiVersion: v1
kind: ConfigMap
metadata:
name: my-kafka-channel
namespace: my-namespace
data:
channelTemplateSpec: |
apiVersion: messaging.knative.dev/v1alpha1
kind: KafkaChannel
spec:
numPartitions: 10
replicationFactor: 1
EOF
```
```shell
kubectl apply -f - <<EOF
apiVersion: eventing.knative.dev/v1
kind: Broker
metadata:
name: my-other-broker
namespace: my-namespace
annotations:
eventing.knative.dev/broker.class: MTChannelBasedBroker
name: kafka-backed-broker
namespace: default
spec:
config:
apiVersion: v1
kind: ConfigMap
name: my-kafka-channel
namespace: my-namespace
name: kafka-channel
namespace: knative-eventing
EOF
```