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

Updating Broker docs (#2707) 

* Updating Broker docs

* fix broken links

* fix broken links

* renamed file for kafka configmap, mt broker info is moved to README now

* updates from peer review

* changes from peer review
This commit is contained in:
Ashleigh Brennan 2020-08-12 08:19:05 -05:00 committed by GitHub
parent ec79229f17
commit c3523dd1bb
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 137 additions and 249 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,113 +1,33 @@
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
Broker).
Knative provides a multi-tenant, channel-based broker implementation that uses channels for event routing.
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
[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`:
Before you can use the Knative Channel-based Broker, you must install a channel provider, such as InMemoryChannel, Kafka or Nats.
Example:
**NOTE:** InMemoryChannel channels are for development use only and must not be used in a production deployment.
```yaml
apiVersion: eventing.knative.dev/v1
kind: Broker
metadata:
annotations:
eventing.knative.dev/broker.class: MTChannelBasedBroker
name: default
spec:
# Configuration specific to this broker.
config:
apiVersion: v1
kind: ConfigMap
name: config-br-default-channel
namespace: knative-eventing
```
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/).
More complex example, showing the same `Broker` as above
but with failed events being delivered to Knative Service called `dlq-service`
## How it works
<!--TODO: Add a diagram that shows this-->
When an Event is sent to the Broker, all request metadata other than the CloudEvent data and context attributes is stripped away.
Unless the information existed as a `CloudEvent` attribute, no information is retained about how this Event entered the Broker.
```yaml
apiVersion: eventing.knative.dev/v1
kind: Broker
metadata:
annotations:
eventing.knative.dev/broker.class: MTChannelBasedBroker
name: default
spec:
# 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
```
Once an Event has entered the Broker, it can be forwarded to event Channels by using Triggers.
This event delivery mechanism hides details of event routing from the event producer and event consumer.
### Creating a broker using defaults
Triggers register a subscriber's interest in a particular class of events, so that the subscriber's event sink will receive events that match the Trigger's filter.
Knative Eventing provides a `ConfigMap` which by default lives in
`knative-eventing` namespace and is called `config-br-defaults`. Out of the box
it comes configured to create
[MT Channel Based Brokers](./mt-channel-based-broker.md) as well as In Memory
Channels. If you are using a different Broker implementation, or want to use
a different channel implementation, you should modify the `ConfigMap`
accordingly. You can read more details on how to use
[config-br-defaults `ConfigMap`](./config-br-defaults.md)
## Default Broker configuration
```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
```
Knative Eventing provides a `config-br-defaults` ConfigMap, which lives in the `knative-eventing` namespace, and provides default configuration settings to enable the creation of Brokers and Channels.
For more information, see the [`config-br-defaults`](./config-br-defaults.md) ConfigMap documentation.
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.
Create a Broker using the default settings:
```shell
kubectl create -f - <<EOF
apiVersion: eventing.knative.dev/v1
kind: Broker
metadata:
name: default
namespace: default
EOF
```
The defaults specified in the `defaults-br-config` will result in a following
Broker being created.
```yaml
apiVersion: eventing.knative.dev/v1
kind: Broker
metadata:
annotations:
eventing.knative.dev/broker.class: MTChannelBasedBroker
@ -119,36 +39,12 @@ spec:
kind: ConfigMap
name: config-br-default-channel
namespace: knative-eventing
EOF
```
To see the created `Broker`, you can get it like this:
## Next steps
```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
```
## 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).
After you have created a Broker, you can complete the following tasks to finish setting up event delivery.
### Subscriber
@ -222,3 +118,28 @@ spec:
name: default
EOF
```
The following example is more complex, and demonstrates the use of `deadLetterSink` configuration to send failed events to Knative Service called `dlq-service`:
```yaml
apiVersion: eventing.knative.dev/v1
kind: Broker
metadata:
annotations:
eventing.knative.dev/broker.class: MTChannelBasedBroker
name: default
spec:
# 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
```

2
docs/eventing/broker/_index.md
View File

@ -1,5 +1,5 @@
---
title: "Brokers"
title: "Broker"
weight: 60
type: "docs"
---

42
docs/eventing/broker/config-br-defaults.md
View File

@ -1,15 +1,43 @@
---
title: "Default config (config-br-defaults)"
title: "Default Broker ConfigMap"
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).
**NOTE:** This guide assumes Knative Eventing is installed in the `knative-eventing` namespace. If you have installed Knative Eventing in a different namespace, replace `default` with the name of that namespace.
Knative Eventing provides a `config-br-defaults` ConfigMap, which provides default configuration settings to enable the creation of Brokers and Channels.
If you are using the `config-br-defaults` ConfigMap default configuration, the example below will create a Broker called `default` in the default namespace, and uses `MTChannelBasedBroker` as the
implementation.
```shell
kubectl create -f - <<EOF
apiVersion: eventing.knative.dev/v1
kind: Broker
metadata:
name: default
namespace: default
EOF
```
The following example shows a Broker where the configuration is specified in a ConfigMap `config-br-default-channel`:
```yaml
apiVersion: eventing.knative.dev/v1
kind: Broker
metadata:
annotations:
eventing.knative.dev/broker.class: MTChannelBasedBroker
name: default
spec:
# Configuration specific to this broker.
config:
apiVersion: v1
kind: ConfigMap
name: config-br-default-channel
namespace: knative-eventing
```
## Format of the file

54
docs/eventing/broker/kafka-configmap.md Normal file
View File

@ -0,0 +1,54 @@
---
title: "Kafka Channel ConfigMap"
weight: 30
type: "docs"
---
**NOTE:** This guide assumes Knative Eventing is installed in the `knative-eventing`
namespace. If you have installed Knative Eventing in a different namespace, replace
`knative-eventing` with the name of that namespace.
To use Kafka channels, you must create a YAML file that specifies how these
channels will be created.
**NOTE:** You must install the Kafka Channel first.
You can copy the following sample code into your `kafka-channel` ConfigMap:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: kafka-channel
namespace: knative-eventing
data:
channelTemplateSpec: |
apiVersion: messaging.knative.dev/v1beta1
kind: KafkaChannel
spec:
numPartitions: 3
replicationFactor: 1
```
**NOTE:** This example specifies two extra parameters that are specific to Kafka
Channels; `numPartitions` and `replicationFactor`.
To create a Broker that uses the KafkaChannel, specify the `kafka-channel` ConfigMap:
```shell
kubectl create -f - <<EOF
apiVersion: eventing.knative.dev/v1
kind: Broker
metadata:
annotations:
eventing.knative.dev/broker.class: MTChannelBasedBroker
name: kafka-backed-broker
namespace: default
spec:
config:
apiVersion: v1
kind: ConfigMap
name: kafka-channel
namespace: knative-eventing
EOF
```

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

@ -1,116 +0,0 @@
---
title: "MT Channel Based Broker"
weight: 30
type: "docs"
---
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.
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 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
`knative-eventing` with the name of that namespace.
## Configure Channel ConfigMaps
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 eventing release, the following YAML file is created automatically:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
namespace: knative-eventing
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. **NOTE:** You must have Kafka Channel installed.
You can copy the following sample code into your Kafka channel ConfigMap:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: kafka-channel
namespace: knative-eventing
data:
channelTemplateSpec: |
apiVersion: messaging.knative.dev/v1beta1
kind: KafkaChannel
spec:
numPartitions: 3
replicationFactor: 1
```
**NOTE:** This example specifies two extra parameters that are specific to Kafka
Channels; `numPartitions` and `replicationFactor`.
To create a Broker that uses Kafka underneath, you would do it like this:
```shell
kubectl create -f - <<EOF
apiVersion: eventing.knative.dev/v1
kind: Broker
metadata:
annotations:
eventing.knative.dev/broker.class: MTChannelBasedBroker
name: kafka-backed-broker
namespace: default
spec:
config:
apiVersion: v1
kind: ConfigMap
name: kafka-channel
namespace: knative-eventing
EOF
```

5
docs/eventing/samples/helloworld/helloworld-python/README.md
View File

@ -184,7 +184,8 @@ folder) you're ready to build and deploy the sample app.
Once you have deployed the application and verified that the namespace, sample application and trigger are ready, let's send a CloudEvent.
### Send CloudEvent to the Broker
We can send an http request directly to the [Broker](../../../broker/README.md) with correct CloudEvent headers set.
We can send an http request directly to the Broker with correct CloudEvent headers set.
1. Deploy a curl pod and SSH into it
```shell
@ -234,7 +235,7 @@ Helloworld-python app logs the context and the msg of the above event, and repli
{"msg":"Hi from Knative!"}
```
Play around with the CloudEvent attributes in the curl command and the trigger specification to understand how [Triggers work](../../../broker/README.md#trigger).
Play around with the CloudEvent attributes in the curl command and the trigger specification to understand how Triggers work.
## Verify reply from helloworld-python app
`helloworld-python` app replies back with an event of `type= dev.knative.samples.hifromknative`, and `source=knative/eventing/samples/hello-world`. This event enters the eventing mesh via the Broker and can be delivered to other services using a Trigger