diff --git a/config/nav.yml b/config/nav.yml index 9b4b3b729..732f8e41e 100644 --- a/config/nav.yml +++ b/config/nav.yml @@ -184,10 +184,10 @@ nav: - Broker types: - Available Broker types: eventing/brokers/broker-types/README.md # add default IMC broker page, page explaining broker types + - Channel based Broker: eventing/brokers/broker-types/channel-based-broker/README.md - Apache Kafka: eventing/brokers/broker-types/kafka-broker/README.md - RabbitMQ Broker: eventing/brokers/broker-types/rabbitmq-broker/README.md - - Creating a Broker: eventing/brokers/create-mtbroker.md - - Administrator configuration options: eventing/brokers/broker-admin-config-options.md + - Creating a Broker: eventing/brokers/create-broker.md - Developer configuration options: eventing/brokers/broker-developer-config-options.md - Triggers: - Using Triggers: eventing/triggers/README.md @@ -251,6 +251,7 @@ nav: - Administrator topics: # Eventing config - Eventing configuration: + - Configure Broker defaults: eventing/configuration/broker-configuration.md - Configure Channel defaults: eventing/configuration/channel-configuration.md - Configure Apache Kafka Channel defaults: eventing/configuration/kafka-channel-configuration.md - Configure event source defaults: eventing/configuration/sources-configuration.md diff --git a/config/redirects.yml b/config/redirects.yml index 03b7602f7..cdff8b887 100644 --- a/config/redirects.yml +++ b/config/redirects.yml @@ -3,7 +3,7 @@ plugins: redirect_maps: contributing/about.md: contributing/README.md eventing/broker/kafka-broker/kafka-configmap.md: eventing/configuration/kafka-channel-configuration.md - eventing/broker/create-mtbroker.md: eventing/brokers/create-mtbroker.md + eventing/broker/create-mtbroker.md: eventing/brokers/create-broker.md eventing/broker/example-mtbroker.md: eventing/brokers/broker-developer-config-options.md eventing/broker/kafka-broker/README.md: eventing/brokers/broker-types/kafka-broker/README.md eventing/broker/rabbitmq-broker/README.md: eventing/brokers/broker-types/rabbitmq-broker/README.md @@ -24,7 +24,7 @@ plugins: admin/collecting-metrics/README.md: serving/observability/metrics/collecting-metrics.md admin/collecting-metrics/eventing-metrics/metrics.md: eventing/observability/metrics/eventing-metrics.md admin/collecting-metrics/serving-metrics/metrics.md: serving/observability/metrics/serving-metrics.md - admin/eventing/broker-configuration.md: eventing/brokers/broker-admin-config-options.md + admin/eventing/broker-configuration.md: eventing/configuration/broker-configuration.md admin/eventing/channel-configuration.md: eventing/configuration/channel-configuration.md admin/eventing/kafka-channel-configuration.md: eventing/configuration/kafka-channel-configuration.md admin/eventing/sources-configuration.md: eventing/configuration/sources-configuration.md @@ -119,7 +119,7 @@ plugins: developer/serving/troubleshooting/debugging-application-issues.md: serving/troubleshooting/debugging-application-issues.md eventing/broker/alternate/index.md: eventing/brokers/README.md eventing/broker/broker-event-delivery.md: eventing/event-delivery.md - eventing/broker/configmaps/README.md: eventing/brokers/broker-admin-config-options.md + eventing/broker/configmaps/README.md: eventing/configuration/broker-configuration.md eventing/channels/default-channels/index.md: eventing/channels/README.md eventing/debugging/README.md: eventing/troubleshooting/README.md eventing/metrics.md: eventing/observability/metrics/eventing-metrics.md @@ -212,3 +212,5 @@ plugins: serving/using-an-ssl-cert/index.md: serving/using-a-tls-cert.md serving/using-subroutes.md: serving/traffic-management.md about/case-studies/README.md: about/case-studies/deepc.md + eventing/brokers/create-mtbroker.md: eventing/brokers/create-broker.md + eventing/brokers/broker-admin-config-options.md: eventing/configuration/broker-configuration.md diff --git a/docs/eventing/brokers/README.md b/docs/eventing/brokers/README.md index f794c3879..e570cd41c 100644 --- a/docs/eventing/brokers/README.md +++ b/docs/eventing/brokers/README.md @@ -4,20 +4,20 @@ ## Event delivery -Event delivery mechanics are an implementation detail that depend on the configured broker class. Using brokers and triggers abstracts the details of event routing from the event producer and event consumer. +Event delivery mechanics are an implementation detail that depend on the configured Broker class. Using Brokers and Triggers abstracts the details of event routing from the event producer and event consumer. ## Advanced use cases -For most use cases, a single broker per namespace is sufficient, but -there are several use cases where multiple brokers can simplify -architecture. For example, separate brokers for events containing Personally +For most use cases, a single Broker per namespace is sufficient, but +there are several use cases where multiple Brokers can simplify +architecture. For example, separate Brokers for events containing Personally Identifiable Information (PII) and non-PII events can simplify audit and access control rules. ## Next steps -- Create an [MT channel-based broker](create-mtbroker.md). -- Configure [default broker ConfigMap settings](broker-admin-config-options.md). +- Create a [Broker](create-broker.md). +- Configure [default Broker ConfigMap settings](../configuration/broker-configuration.md). ## Additional resources diff --git a/docs/eventing/brokers/broker-developer-config-options.md b/docs/eventing/brokers/broker-developer-config-options.md index a41b7111e..20fa11921 100644 --- a/docs/eventing/brokers/broker-developer-config-options.md +++ b/docs/eventing/brokers/broker-developer-config-options.md @@ -2,7 +2,7 @@ ## Broker configuration example -The following is a full example of a multi-tenant (MT) channel-based Broker object which shows the possible configuration options that you can modify: +The following is a full example of a Channel based Broker object which shows the possible configuration options that you can modify: ```yaml apiVersion: eventing.knative.dev/v1 @@ -34,5 +34,5 @@ spec: - You can specify any valid `name` for your broker. Using `default` will create a broker named `default`. - The `namespace` must be an existing namespace in your cluster. Using `default` will create the broker in the `default` namespace. - You can set the `eventing.knative.dev/broker.class` annotation to change the class of the broker. The default broker class is `MTChannelBasedBroker`, but Knative also supports use of the `Kafka` and `RabbitMQBroker` broker class. For more information see the [Apache Kafka Broker](../brokers/broker-types/kafka-broker/README.md) or [RabbitMQ Broker](../brokers/broker-types/rabbitmq-broker/README.md) documentation. -- `spec.config` is used to specify the default backing channel configuration for MT channel-based broker implementations. For more information on configuring the default channel type, see the documentation on [Configure Broker defaults](../brokers/broker-admin-config-options.md). +- `spec.config` is used to specify the default backing channel configuration for Channel based Broker implementations. For more information on configuring the default channel type, see the documentation on [Configure Broker defaults](../configuration/broker-configuration.md). - `spec.delivery` is used to configure event delivery options. Event delivery options specify what happens to an event that fails to be delivered to an event sink. For more information, see the documentation on [Event delivery](../event-delivery.md). diff --git a/docs/eventing/brokers/broker-types/README.md b/docs/eventing/brokers/broker-types/README.md index aa2fedf2d..72468591a 100644 --- a/docs/eventing/brokers/broker-types/README.md +++ b/docs/eventing/brokers/broker-types/README.md @@ -2,23 +2,23 @@ The following broker types are available for use with Knative Eventing. -## Multi-tenant channel-based broker +## Channel-based broker -Knative Eventing provides a multi-tenant (MT) channel-based broker implementation that uses channels for event routing. +Knative Eventing provides a [Channel based Broker](./channel-based-broker/README.md) implementation that uses Channels for event routing. -Before you can use the MT channel-based broker, you must install a channel implementation. +Before you can use the Channel based Broker, you must install a Channel implementation. ## Alternative broker implementations -In the Knative Eventing ecosystem, alternative broker implementations are welcome as long as they respect the [broker specifications](https://github.com/knative/specs/blob/main/specs/eventing/control-plane.md#broker-lifecycle). +In the Knative Eventing ecosystem, alternative Broker implementations are welcome as long as they respect the [Broker specifications](https://github.com/knative/specs/blob/main/specs/eventing/control-plane.md#broker-lifecycle). -The following is a list of brokers provided by the community or vendors: +The following is a list of Brokers provided by the community or vendors: ### Knative Broker for Apache Kafka -This broker implementation uses [Apache Kafka](https://kafka.apache.org/) as its backing technology. For more information, see [here](kafka-broker/README.md). +This Broker implementation uses [Apache Kafka](https://kafka.apache.org/) as its backing technology. For more information, see the [Knative Broker for Apache Kafka](./kafka-broker/README.md) documentation. ### RabbitMQ broker The RabbitMQ Broker uses [RabbitMQ](https://www.rabbitmq.com/) for its underlying implementation. -For more information, see [RabbitMQ Broker](rabbitmq-broker/README.md) or [the docs available on GitHub](https://github.com/knative-sandbox/eventing-rabbitmq). +For more information, see [RabbitMQ Broker](./rabbitmq-broker/README.md) or [the docs available on GitHub](https://github.com/knative-sandbox/eventing-rabbitmq). diff --git a/docs/eventing/brokers/broker-types/channel-based-broker/README.md b/docs/eventing/brokers/broker-types/channel-based-broker/README.md new file mode 100644 index 000000000..c26d03022 --- /dev/null +++ b/docs/eventing/brokers/broker-types/channel-based-broker/README.md @@ -0,0 +1,118 @@ +# Channel based Broker + +The Channel based Broker (`MTChannelBasedBroker`) uses [Channels](../../../channels) for event routing. It is shipped by default with Knative Eventing. +Users should prefer native Broker implementations (like [Knative Broker for Apache Kafka](../kafka-broker/README.md) or [RabbitMQ Broker](../rabbitmq-broker/README.md)) over the MTChannelBasedBroker and Channel combination because it is usually more efficient as they reduce network hops for example. +## Prerequisites + +* You have Knative Eventing installed. +* You have a Channel implementation installed. + + As the MTChannelBasedBroker is based on Channels, you need to install a Channel implementation. Check out the [available Channels](../../../channels/channels-crds.md) for a (non-exhaustive) list of the available Channels for Knative Eventing. + + You can install for example the InMemory Channel by running the following command: + + ```bash + kubectl apply -f {{ artifact(repo="eventing",file="in-memory-channel.yaml")}} + ``` + +## Create a MTChannelBasedBroker + +You can create a MTChannelBasedBroker by using the `kn` CLI or by applying YAML files using `kubectl`. + +=== "kn" + + You can create a MTChannelBasedBroker by entering the following command: + + ```bash + kn broker create --class MTChannelBasedBroker + ``` + Where `` is the name of your Broker. + +=== "kubectl" + + The YAML in the following example creates a Broker. + + 1. Create a MTChannelBasedBroker by creating a YAML file using the following template: + + ```yaml + apiVersion: eventing.knative.dev/v1 + kind: Broker + metadata: + annotations: + eventing.knative.dev/broker.class: MTChannelBasedBroker + name: + ``` + Where `` is the name of your Broker. + + !!! note + Note, that the Broker class is specified via the `eventing.knative.dev/broker.class` annotation. + + 1. Apply the YAML file: + + ```bash + kubectl apply -f .yaml + ``` + Where `` is the name of the file you created in the previous step. + +## Configuration + +You configure the Broker object itself, or you can define cluster or namespace default values. + +### Broker specific configuration + +It is possible to configure each Broker individually by referencing a ConfigMap in the `spec.config`: + +```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: my-broker-specific-configuration + namespace: default +``` + +The referenced ConfigMap must contain a `channel-template-spec` that defines the underlining Channel implementation for this Broker, as well as some Channel specific configurations. For example: + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: my-broker-specific-configuration + namespace: default +data: + channel-template-spec: | + apiVersion: messaging.knative.dev/v1 + kind: InMemoryChannel +``` + +[Kafka Channel](../../../configuration/kafka-channel-configuration.md) configuration example: + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: kafka-channel + namespace: knative-eventing +data: + channel-template-spec: | + apiVersion: messaging.knative.dev/v1beta1 + kind: KafkaChannel + spec: + numPartitions: 3 + replicationFactor: 1 +``` + +### Broker default configuration + +The `config-br-defaults` ConfigMap defines default values for any Broker that does not specify a `spec.config` or a Broker class. It is possible to define these defaults cluser wide or on a per namespace basis. Check the [Administrator configuration options](../../../configuration/broker-configuration.md) on how to set Broker defaults cluster wide or on a namespace basis. + +## Developer documentation + +For more information about `MTChannelBasedBroker`, see the [MTChannelBasedBroker developer documentation](https://github.com/knative/eventing/blob/main/docs/mt-channel-based-broker/README.md). diff --git a/docs/eventing/brokers/create-broker.md b/docs/eventing/brokers/create-broker.md new file mode 100644 index 000000000..af7f89824 --- /dev/null +++ b/docs/eventing/brokers/create-broker.md @@ -0,0 +1,116 @@ +# Creating a Broker + +Once you have installed Knative Eventing and a Broker implementation, you can create an instance of a Broker. + +!!! note + Knative Eventing provides by default the [MTChannelBasedBroker](./broker-types/channel-based-broker/README.md). Its default backing channel is the [`InMemoryChannel`](https://github.com/knative/eventing/blob/main/config/channels/in-memory-channel/README.md). `InMemoryChannel` should not be used in production. Other Broker types and their configuration options can be found under [Available Broker types](./broker-types/README.md). + +You can create a Broker by using the `kn` CLI or by applying YAML files using `kubectl`. + +=== "kn" + + 1. You can create a Broker by entering the following command: + + ```bash + kn broker create -n + ``` + + This will create a new Broker of your default Broker class and default Broker configuration (both defined in the `config-br-defaults` ConfigMap). + + !!! note + If you choose not to specify a namespace, the Broker will be created in the current namespace. + + !!! note + If you have multiple Broker classes installed in your cluster, you can specify the Broker class via the `--class` parameter, e.g.: + + ```bash + kn broker create -n --class MTChannelBasedBroker + ``` + + 1. Optional: Verify that the Broker was created by listing existing Brokers: + + ```bash + kn broker list + ``` + + 1. Optional: You can also verify the Broker exists by describing the Broker you have created: + + ```bash + kn broker describe + ``` + +=== "kubectl" + + The YAML in the following example creates a Broker named `default`. + + 1. Create a Broker by creating a YAML file using the following template: + + ```yaml + apiVersion: eventing.knative.dev/v1 + kind: Broker + metadata: + name: + namespace: + ``` + + This creates a new Broker using the default Broker class and default Broker configuration, both of which are defined in the `config-br-defaults` ConfigMap. + + 1. Apply the YAML file: + + ```bash + kubectl apply -f .yaml + ``` + Where `` is the name of the file you created in the previous step. + + 1. Optional: Verify that the Broker is working correctly: + + ```bash + kubectl -n get broker + ``` + + This shows information about your Broker. If the Broker is working correctly, it shows a `READY` status of `True`: + + ```bash + NAME READY REASON URL AGE + default True http://broker-ingress.knative-eventing.svc.cluster.local/default/default 1m + ``` + + If the `READY` status is `False`, wait a few moments and then run the command again. + +## Broker class options + +When a Broker is created without a specified `eventing.knative.dev/broker.class` annotation, the default `MTChannelBasedBroker` Broker class is used, as specified by default in the `config-br-defaults` ConfigMap. + +In case you have multiple Broker classes installed in your cluster and want to use a non-default Broker class for a Broker, you can modify the `eventing.knative.dev/broker.class` annotation and `spec.config` for the Broker object. + +1. Set the `eventing.knative.dev/broker.class` annotation. Replace `MTChannelBasedBroker` in the following example with the class type you want to use. Be aware that the Broker class annoation is immutable and thus can't be updated after the Broker got created: + + ```yaml + apiVersion: eventing.knative.dev/v1 + kind: Broker + metadata: + annotations: + eventing.knative.dev/broker.class: MTChannelBasedBroker + name: default + namespace: default + ``` + +1. Configure the `spec.config` with the details of the ConfigMap that defines the required configuration for the Broker class (e.g. with some Channel configurations in case of the `MTChannelBasedBroker`): + + ```yaml + 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 + ``` + +For further information about configuring a default Broker class cluster wide or on a per namespace basis, check the [Administrator configuration options](../configuration/broker-configuration.md#configuring-the-broker-class). diff --git a/docs/eventing/brokers/create-mtbroker.md b/docs/eventing/brokers/create-mtbroker.md deleted file mode 100644 index b8674ccf3..000000000 --- a/docs/eventing/brokers/create-mtbroker.md +++ /dev/null @@ -1,65 +0,0 @@ -# Creating a broker - -Once you have installed Knative Eventing, you can create an instance of the multi-tenant (MT) channel-based broker that is provided by default. The default backing channel type for an MT channel-based broker is InMemoryChannel. - -You can create a broker by using the `kn` CLI or by applying YAML files using `kubectl`. - -=== "kn" - - 1. You can create a broker in current namespace by entering the following command: - - ```bash - kn broker create -n - ``` - - !!! note - If you choose not to specify a namespace, the broker will be created in the current namespace. - - 1. Optional: Verify that the broker was created by listing existing brokers. Enter the following command: - - ```bash - kn broker list - ``` - - 1. Optional: You can also verify the broker exists by describing the broker you have created. Enter the following command: - - ```bash - kn broker describe - ``` - - -=== "kubectl" - - The YAML in the following example creates a broker named `default` in the current namespace. - - 1. Create a broker in the current namespace by creating a YAML file using the - following template: - - ```yaml - apiVersion: eventing.knative.dev/v1 - kind: Broker - metadata: - name: - ``` - - 1. Apply the YAML file by running the command: - - ```bash - kubectl apply -f .yaml - ``` - Where `` is the name of the file you created in the previous step. - - 1. Optional: Verify that the broker is working correctly, by entering the following command: - - ```bash - kubectl -n get broker - ``` - - This shows information about your broker. If the broker is working correctly, it shows a `READY` status of `True`: - - ```{ .bash .no-copy } - NAME READY REASON URL AGE - default True http://broker-ingress.knative-eventing.svc.cluster.local/event-example/default 1m - ``` - - If the `READY` status is `False`, wait a few moments and then run the command again. diff --git a/docs/eventing/brokers/broker-admin-config-options.md b/docs/eventing/configuration/broker-configuration.md similarity index 67% rename from docs/eventing/brokers/broker-admin-config-options.md rename to docs/eventing/configuration/broker-configuration.md index 256bb6778..5fcf21952 100644 --- a/docs/eventing/brokers/broker-admin-config-options.md +++ b/docs/eventing/configuration/broker-configuration.md @@ -1,4 +1,4 @@ -# Administrator configuration options +# Configure Broker defaults If you have cluster administrator permissions for your Knative installation, you can modify ConfigMaps to change the global default configuration options for Brokers on the cluster. @@ -12,8 +12,6 @@ kind: ConfigMap metadata: name: config-br-defaults namespace: knative-eventing - labels: - eventing.knative.dev/release: devel data: # Configures the default for any Broker that does not specify a spec.config or Broker class. default-br-config: | @@ -25,29 +23,9 @@ data: namespace: knative-eventing ``` -## Channel implementation options +In this case, each new Broker created in the cluster would use by default the `MTChannelBasedBroker` Broker class and the `config-br-default-channel` ConfigMap from the `knative-eventing` namespace for its configuration if not other specified in the Brokers `eventing.knative.dev/broker.class` annotation and/or `.spec.config` (see [Developer configuration options](../brokers/broker-developer-config-options.md)). -The following example shows a Broker object where the `spec.config` configuration is specified in a `config-br-default-channel` ConfigMap: - -```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 -``` - -A Broker object that does not have a `spec.config` specified uses the `config-br-default-channel` ConfigMap by default because this is specified in the `config-br-defaults` ConfigMap. - -However, if you have installed a different Channel implementation, for example, Kafka, and would like this to be used as the default Channel implementation for any Broker that is created, you can change the `config-br-defaults` ConfigMap to look as follows: +However, if you would like like for example a Kafka Channel to be used as the default Channel implementation for any Broker that is created, you can change the `config-br-defaults` ConfigMap to look as follows: ```yaml apiVersion: v1 @@ -55,8 +33,6 @@ kind: ConfigMap metadata: name: config-br-defaults namespace: knative-eventing - labels: - eventing.knative.dev/release: devel data: # Configures the default for any Broker that does not specify a spec.config or Broker class. default-br-config: | @@ -68,16 +44,9 @@ data: namespace: knative-eventing ``` -Now every Broker created in the cluster that does not have a `spec.config` will be configured to use the `kafka-channel` ConfigMap. +Now every Broker created in the cluster that does not have a `spec.config` will be configured to use the `kafka-channel` ConfigMap. For more information about creating a `kafka-channel` ConfigMap to use with your Broker, see the [Kafka Channel ConfigMap](./kafka-channel-configuration.md#create-a-kafka-channel-configmap) documentation. -For more information about creating a `kafka-channel` ConfigMap to use with your Broker, see the -[Kafka Channel ConfigMap](../configuration/kafka-channel-configuration.md#create-a-kafka-channel-configmap) documentation. - -### Changing the default Channel implementation for a namespace - -You can modify the default Broker creation behavior for one or more namespaces. - -For example, if you wanted to use the `kafka-channel` ConfigMap for all other Brokers created, but wanted to use `config-br-default-channel` ConfigMap for `namespace-1` and `namespace-2`, you would use the following ConfigMap settings: +You can also modify the default Broker configuration for one or more dedicated namespaces, by defining it in the `namespaceDefaults` section. For example, if you want to use the `config-br-default-channel` ConfigMap for all Brokers by default, but want to use `kafka-channel` ConfigMap for `namespace-1` and `namespace-2`, you would use the following ConfigMap: ```yaml apiVersion: v1 @@ -85,30 +54,76 @@ kind: ConfigMap metadata: name: config-br-defaults namespace: knative-eventing - labels: - eventing.knative.dev/release: devel data: - # Configures the default for any Broker that does not specify a spec.config or Broker class. default-br-config: | clusterDefault: brokerClass: MTChannelBasedBroker apiVersion: v1 kind: ConfigMap - name: config-kafka-channel + name: config-br-default-channel namespace: knative-eventing namespaceDefaults: namespace-1: apiVersion: v1 kind: ConfigMap - name: config-br-default-channel + name: kafka-channel namespace: knative-eventing namespace-2: apiVersion: v1 kind: ConfigMap - name: config-br-default-channel + name: kafka-channel namespace: knative-eventing ``` + +## Configuring the Broker class + +Besides configuring the Broker class for each broker [individually](../brokers/create-broker.md#broker-class-options), it is possible to define the default Broker class cluster wide or on a per namespace basis: + +### Configuring the default Broker class for the cluster + +You can configure the `clusterDefault` Broker class so that any Broker created in the cluster that does not have a `eventing.knative.dev/broker.class` annotation uses this default Broker class: + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: config-br-defaults + namespace: knative-eventing +data: + # Configures the default for any Broker that does not specify a spec.config or Broker class. + default-br-config: | + clusterDefault: + brokerClass: MTChannelBasedBroker +``` + +### Configuring the default Broker class for namespaces + +You can modify the default Broker class for one or more namespaces. + +For example, if you want to use a `KafkaBroker` Broker class for all other Brokers created on the cluster, but you want to use the `MTChannelBasedBroker` Broker class for Brokers created in `namespace-1` and `namespace-2`, you would use the following ConfigMap settings: + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: config-br-defaults + namespace: knative-eventing +data: + # Configures the default for any Broker that does not specify a spec.config or Broker class. + default-br-config: | + clusterDefault: + brokerClass: KafkaBroker + namespaceDefaults: + namespace1: + brokerClass: MTChannelBasedBroker + namespace2: + brokerClass: MTChannelBasedBroker +``` + + !!! note + Be aware that different Broker classes usually require different configuration ConfigMaps. See the configuration options of the different [Broker implementations](../brokers/broker-types/README.md) on how their referenced ConfigMaps have to look like (e.g. for [MTChannelBasedBroker](../brokers/broker-types/channel-based-broker/README.md#configuration-configmap) or [Knative Broker for Apache Kafka](../brokers/broker-types/kafka-broker/README.md#configure-a-kafka-broker)). + ## Configuring delivery spec defaults You can configure default event delivery parameters for Brokers that are applied in cases where an event fails to be delivered: @@ -119,8 +134,6 @@ kind: ConfigMap metadata: name: config-br-defaults namespace: knative-eventing - labels: - eventing.knative.dev/release: devel data: # Configures the default for any Broker that does not specify a spec.config or Broker class. default-br-config: | @@ -128,7 +141,7 @@ data: brokerClass: MTChannelBasedBroker apiVersion: v1 kind: ConfigMap - name: config-kafka-channel + name: kafka-channel namespace: knative-eventing delivery: retry: 10 @@ -169,115 +182,6 @@ You can set the `backoffDelay` delivery parameter to specify the time delay befo The `backoffPolicy` delivery parameter can be used to specify the retry back off policy. The policy can be specified as either linear or exponential. When using the linear back off policy, the back off delay is the time interval specified between retries. When using the exponential backoff policy, the back off delay is equal to `backoffDelay*2^`. -## Broker class options - -When a Broker is created without a specified `BrokerClass` annotation, the default `MTChannelBasedBroker` Broker class is used, as specified in the `config-br-defaults` ConfigMap. - -The following example creates a Broker called `default` in the default namespace, and uses `MTChannelBasedBroker` as the implementation: - -1. Create a YAML file for your Broker using the following example: - - ```yaml - apiVersion: eventing.knative.dev/v1 - kind: Broker - metadata: - name: default - namespace: default - ``` - -1. Apply the YAML file by running the command: - - ```bash - kubectl apply -f .yaml - ``` - Where `` is the name of the file you created in the previous step. - - -### Configuring the Broker class - -To configure a Broker class, you can modify the -`eventing.knative.dev/broker.class` annotation and `spec.config` for the Broker -object. `MTChannelBasedBroker` is the Broker class default. - -1. Modify the `eventing.knative.dev/broker.class` annotation. Replace -`MTChannelBasedBroker` with the class type you want to use: - - ```yaml - apiVersion: eventing.knative.dev/v1 - kind: Broker - metadata: - annotations: - eventing.knative.dev/broker.class: MTChannelBasedBroker - name: default - namespace: default - ``` - -1. Configure the `spec.config` with the details of the ConfigMap that defines -the backing Channel for the Broker class: - - ```yaml - 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 - ``` - -### Configuring the default BrokerClass for the cluster - -You can configure the `clusterDefault` Broker class so that any Broker created in the cluster that does not have a `BrokerClass` annotation uses this default class. - -#### Example - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: config-br-defaults - namespace: knative-eventing - labels: - eventing.knative.dev/release: devel -data: - # Configures the default for any Broker that does not specify a spec.config or Broker class. - default-br-config: | - clusterDefault: - brokerClass: MTChannelBasedBroker -``` - -### Configuring the default BrokerClass for namespaces - -You can modify the default Broker class for one or more namespaces. - -For example, if you want to use a `KafkaBroker` class for all other Brokers created on the cluster, but you want to use the `MTChannelBasedBroker` class for Brokers created in `namespace-1` and `namespace-2`, you would use the following ConfigMap settings: - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: config-br-defaults - namespace: knative-eventing - labels: - eventing.knative.dev/release: devel -data: - # Configures the default for any Broker that does not specify a spec.config or Broker class. - default-br-config: | - clusterDefault: - brokerClass: KafkaBroker - namespaceDefaults: - namespace1: - brokerClass: MTChannelBasedBroker - namespace2: - brokerClass: MTChannelBasedBroker -``` - ## Integrating Istio with Knative Brokers ### Protect a Knative Broker by using JSON Web Token (JWT) and Istio @@ -301,7 +205,7 @@ data: kubectl delete pod -n knative-eventing ``` - Where `` is the name of your broker ingress pod. + Where `` is the name of your Broker ingress pod. The pod now has two containers: @@ -309,12 +213,14 @@ data: knative-eventing 2/2 Running 1 175m ``` -1. Create a broker, then use get the URL of your broker by running the command: +1. Create a broker, then use get the URL of your Broker by running the command: ```bash kubectl get broker ``` + Where `` is the name of your Broker. + Example output: ```{ .bash .no-copy } @@ -322,13 +228,13 @@ data: default my-broker http://broker-ingress.knative-eventing.svc.cluster.local/default/my-broker 6s True ``` -1. Start a `curl` pod: +1. Start a `curl` pod by running the following command: ```bash kubectl -n default run curl --image=radial/busyboxplus:curl -i --tty ``` -1. Send a CloudEvent with an HTTP POST against the broker URL: +1. Send a CloudEvent with an HTTP POST against the Broker URL by running the following command: ```bash curl -X POST -v \ @@ -341,7 +247,7 @@ data: ``` - Where `` is the URL of your broker. For example: + Where `` is the URL of your Broker. For example: ```{ .bash .no-copy } curl -X POST -v \ diff --git a/docs/install/operator/configuring-eventing-cr.md b/docs/install/operator/configuring-eventing-cr.md index c322c77f5..977b35847 100644 --- a/docs/install/operator/configuring-eventing-cr.md +++ b/docs/install/operator/configuring-eventing-cr.md @@ -40,7 +40,7 @@ spec: ## Setting the default channel for the broker -If you are using a channel-based broker, you can change the default channel type for the broker from InMemoryChannel to KafkaChannel, by updating the `config-br-default-channel` ConfigMap. +If you are using a Channel based Broker, you can change the default Channel type for the Broker from InMemoryChannel to KafkaChannel, by updating the `config-br-default-channel` ConfigMap. You can do this by modifying the KnativeEventing CR: