From 2498912cd14669b25bb37dc848fab2644c612f19 Mon Sep 17 00:00:00 2001 From: Ashleigh Brennan Date: Wed, 31 Aug 2022 13:05:18 -0500 Subject: [PATCH] Cleanup broker docs and snippets (#5193) * Cleanup broker docs and snippets * fixing redirects * more snippets, broker types docs * updates, fixing links * fix errors * updated nav --- config/nav.yml | 37 ++++++++----- config/redirects.yml | 15 +++-- docs/concepts/eventing-resources/brokers.md | 21 +++++++ .../revisions.md | 2 +- docs/eventing/README.md | 4 -- docs/eventing/broker/README.md | 55 ------------------- .../broker/images/broker-workflow.svg | 1 - docs/eventing/brokers/README.md | 27 +++++++++ .../brokers/broker-admin-config-options.md | 3 + .../broker-developer-config-options.md} | 6 +- docs/eventing/brokers/broker-types/README.md | 28 ++++++++++ .../broker-types}/kafka-broker/README.md | 7 ++- .../broker-types}/rabbitmq-broker/README.md | 2 +- .../{broker => brokers}/create-mtbroker.md | 3 +- docs/eventing/event-registry.md | 13 +---- docs/eventing/{broker => }/triggers/README.md | 4 +- docs/getting-started/first-broker.md | 47 ++-------------- .../eventing/install-eventing-with-yaml.md | 4 +- docs/serving/revisions/README.md | 4 +- docs/snippets/about-brokers.md | 8 +++ docs/snippets/about-revisions.md | 2 +- docs/snippets/about-subscribers.md | 5 ++ docs/snippets/about-triggers.md | 5 ++ 23 files changed, 155 insertions(+), 148 deletions(-) create mode 100644 docs/concepts/eventing-resources/brokers.md rename docs/concepts/{resources => serving-resources}/revisions.md (98%) delete mode 100644 docs/eventing/broker/README.md delete mode 100644 docs/eventing/broker/images/broker-workflow.svg create mode 100644 docs/eventing/brokers/README.md create mode 100644 docs/eventing/brokers/broker-admin-config-options.md rename docs/eventing/{broker/example-mtbroker.md => brokers/broker-developer-config-options.md} (91%) create mode 100644 docs/eventing/brokers/broker-types/README.md rename docs/eventing/{broker => brokers/broker-types}/kafka-broker/README.md (98%) rename docs/eventing/{broker => brokers/broker-types}/rabbitmq-broker/README.md (97%) rename docs/eventing/{broker => brokers}/create-mtbroker.md (93%) rename docs/eventing/{broker => }/triggers/README.md (97%) create mode 100644 docs/snippets/about-brokers.md create mode 100644 docs/snippets/about-subscribers.md create mode 100644 docs/snippets/about-triggers.md diff --git a/config/nav.yml b/config/nav.yml index 51cb8c5e5..6fd667711 100644 --- a/config/nav.yml +++ b/config/nav.yml @@ -11,7 +11,10 @@ nav: - Concepts: - Overview: concepts/README.md - Resources: - - Revisions: concepts/resources/revisions.md + - Serving resources: + - Revisions: concepts/serving-resources/revisions.md + - Eventing resources: + - Brokers: concepts/eventing-resources/brokers.md - Duck types: concepts/duck-typing.md ############################################################################### # Getting started @@ -25,7 +28,7 @@ nav: - Traffic splitting: getting-started/first-traffic-split.md - Using Knative Eventing: - Introducing Knative Eventing: getting-started/getting-started-eventing.md - - Sources, Brokers, Triggers, Sinks: getting-started/first-broker.md + - Sources, Brokers, and Triggers: getting-started/first-broker.md - Using a Knative Service as a source: getting-started/first-source.md - Using Triggers and sinks: getting-started/first-trigger.md - What's Next?: getting-started/next-steps.md @@ -151,6 +154,22 @@ nav: ############################################################################### - Eventing: - Knative Eventing overview: eventing/README.md + - Resources: + - Brokers: + - About Brokers: eventing/brokers/README.md + - Broker types: + - Available Broker types: eventing/brokers/broker-types/README.md + # add default IMC broker page, page explaining broker types + - Knative Kafka Broker: 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 + - Developer configuration options: eventing/brokers/broker-developer-config-options.md + - Triggers: + - Using Triggers: eventing/triggers/README.md + # about triggers docs + # - Administrator configuration options: eventing/triggers/trigger-admin-config-options.md + # - Developer configuration options: eventing/triggers/trigger-developer-config-options.md # Eventing - developer docs - Developer topics: - Event sources: @@ -201,17 +220,8 @@ nav: - Creating a Channel using cluster or namespace defaults: eventing/channels/create-default-channel.md - Available Channels: eventing/channels/channels-crds.md - Subscriptions: eventing/channels/subscriptions.md - - Sugar Controller: eventing/sugar/README.md - - Brokers: - - About Brokers: eventing/broker/README.md - - Using the Event registry: eventing/event-registry.md # does this make sense here since it mentions being used with brokers and triggers? - - Creating a Broker: eventing/broker/create-mtbroker.md - - Triggers: eventing/broker/triggers/README.md - - Broker configuration example: eventing/broker/example-mtbroker.md - - Knative Kafka Broker: eventing/broker/kafka-broker/README.md - - RabbitMQ Broker: eventing/broker/rabbitmq-broker/README.md - - Accessing CloudEvent traces: eventing/accessing-traces.md - # Eventing - admin docs + - Event registry: eventing/event-registry.md + - Sugar controller: eventing/sugar/README.md - Administrator topics: # Eventing config - Eventing configuration: @@ -222,6 +232,7 @@ nav: - Configure Sugar Controller: eventing/configuration/sugar-configuration.md # Eventing - observability - Observability: + - Accessing CloudEvent traces: eventing/accessing-traces.md - Collecting logs: eventing/observability/logging/collecting-logs.md - Configuring logging: eventing/observability/logging/config-logging.md - Collecting metrics: eventing/observability/metrics/collecting-metrics.md diff --git a/config/redirects.yml b/config/redirects.yml index 796e4fd78..db4385fe5 100644 --- a/config/redirects.yml +++ b/config/redirects.yml @@ -1,6 +1,13 @@ plugins: redirects: redirect_maps: + 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/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 + eventing/broker/README.md: eventing/brokers/README.md + concepts/resources/revisions.md: concepts/serving-resources/revisions.md serving/revision-gc.md: serving/revisions/revision-developer-config-options.md serving/configuration/revision-gc.md: serving/revisions/revision-admin-config-options.md reference/concepts/duck-typing.md: concepts/duck-typing.md @@ -15,7 +22,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/configuration/broker-configuration.md + admin/eventing/broker-configuration.md: eventing/brokers/broker-admin-config-options.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 @@ -109,10 +116,9 @@ plugins: developer/serving/tag-resolution.md: serving/tag-resolution.md developer/serving/traffic-management.md: serving/traffic-management.md developer/serving/troubleshooting/debugging-application-issues.md: serving/troubleshooting/debugging-application-issues.md - eventing/broker/alternate/index.md: eventing/broker/README.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/configuration/broker-configuration.md - eventing/broker/kafka-broker/kafka-configmap.md: eventing/configuration/kafka-channel-configuration.md + eventing/broker/configmaps/README.md: eventing/brokers/broker-admin-config-options.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 @@ -148,7 +154,6 @@ plugins: eventing/sink/kafka-sink.md: eventing/sinks/kafka-sink.md eventing/sources/containersource.md: eventing/custom-event-source/containersource/README.md eventing/sources/pingsource/index.md: eventing/sources/ping-source/README.md - eventing/triggers/index.md: eventing/broker/triggers/README.md install/collecting-logs/index.md: serving/observability/logging/collecting-logs.md install/collecting-metrics/index.md: serving/observability/metrics/collecting-metrics.md install/eventing/eventing-installation-files.md: install/yaml-install/eventing/eventing-installation-files.md diff --git a/docs/concepts/eventing-resources/brokers.md b/docs/concepts/eventing-resources/brokers.md new file mode 100644 index 000000000..742d26bad --- /dev/null +++ b/docs/concepts/eventing-resources/brokers.md @@ -0,0 +1,21 @@ +# Brokers + +--8<-- "about-brokers.md" + +## Related concepts + +### Triggers + +--8<-- "about-triggers.md" + +### Subscribers + +--8<-- "about-subscribers.md" + + diff --git a/docs/concepts/resources/revisions.md b/docs/concepts/serving-resources/revisions.md similarity index 98% rename from docs/concepts/resources/revisions.md rename to docs/concepts/serving-resources/revisions.md index 8e3b50281..52e83b09a 100644 --- a/docs/concepts/resources/revisions.md +++ b/docs/concepts/serving-resources/revisions.md @@ -1,4 +1,4 @@ -# About Revisions +# Revisions --8<-- "about-revisions.md" diff --git a/docs/eventing/README.md b/docs/eventing/README.md index da6cdcdf9..e32b1e63a 100644 --- a/docs/eventing/README.md +++ b/docs/eventing/README.md @@ -2,10 +2,6 @@ --8<-- "about-eventing.md" -In a Knative Eventing deployment, event [Sources](../eventing/sources/README.md){target=_blank} are the primary event producers. Examples of [sinks](../eventing/sinks/README.md){target=_blank} include [Brokers](../eventing/broker/README.md){target=_blank}, [Channels](../eventing/channels/README.md){target=_blank}, and [Services](../serving/services/README.md){target=_blank}. - -## Common use cases - Examples of supported Knative Eventing use cases: - Publish an event without creating a consumer. You can send events to a broker as an HTTP POST, and use binding to decouple the destination configuration from your application that produces events. diff --git a/docs/eventing/broker/README.md b/docs/eventing/broker/README.md deleted file mode 100644 index 03e30df97..000000000 --- a/docs/eventing/broker/README.md +++ /dev/null @@ -1,55 +0,0 @@ -# Brokers - -Brokers are Kubernetes [custom resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) that define an event mesh for collecting a pool of [CloudEvents](https://cloudevents.io/). Brokers provide a discoverable endpoint, `status.address`, for event ingress, and triggers for event delivery. Event producers can send events to a broker by POSTing the event to the `status.address.url` of the broker. - -Event delivery mechanics are an implementation detail that depend on the configured -[broker class](../configuration/broker-configuration.md#broker-class-options). -Using brokers and triggers abstracts the details of event routing from the event producer and event consumer. - -![An event enters a Broker. The Broker uses Triggers to forward the event to the appropriate Subscriber.](images/broker-workflow.svg) - -After an event has entered a broker, it can be forwarded to subscribers by using triggers. Triggers allow events to be filtered by attributes, so that events with particular attributes can be sent to subscribers that have registered interest in events with those attributes. - -A subscriber can be any URL or _Addressable_ resource. Subscribers can also reply to an active request from the broker, and can respond with a new CloudEvent that will be sent back into the broker. - -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. - -## Broker types - -The following broker types are available for use with Knative Eventing. - -### Multi-tenant channel-based broker - -Knative Eventing provides a multi-tenant (MT) channel-based broker implementation that uses channels for event routing. - -Before you can use the MT channel-based broker, you must install a -[channel implementation](../channels/channel-types-defaults.md). - -### 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). - -The following is a list of brokers provided by the community or vendors: - -#### GCP broker - -The GCP broker is optimized for running in GCP. For more details, refer to the [documentation](https://github.com/google/knative-gcp/blob/master/docs/install/install-gcp-broker.md). - -#### Apache Kafka broker - -For more information, see [Apache Kafka Broker](kafka-broker/README.md). - -#### 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). - -## Next steps - -- Create an [MT channel-based broker](create-mtbroker.md). -- Configure [default broker ConfigMap settings](../configuration/broker-configuration.md). -- View the [broker specifications](https://github.com/knative/specs/blob/main/specs/eventing/overview.md#broker). diff --git a/docs/eventing/broker/images/broker-workflow.svg b/docs/eventing/broker/images/broker-workflow.svg deleted file mode 100644 index 0688473c8..000000000 --- a/docs/eventing/broker/images/broker-workflow.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/eventing/brokers/README.md b/docs/eventing/brokers/README.md new file mode 100644 index 000000000..9efab93cf --- /dev/null +++ b/docs/eventing/brokers/README.md @@ -0,0 +1,27 @@ +# About Brokers + +--8<-- "about-brokers.md" + +## Event delivery + +Event delivery mechanics are an implementation detail that depend on the configured +[broker class](../configuration/broker-configuration.md#broker-class-options). +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 +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](../configuration/broker-configuration.md). + +## Additional resources + +- [Brokers concept documentation](../../concepts/eventing-resources/brokers.md) +- [Broker specifications](https://github.com/knative/specs/blob/main/specs/eventing/overview.md#broker){target=_blank} diff --git a/docs/eventing/brokers/broker-admin-config-options.md b/docs/eventing/brokers/broker-admin-config-options.md new file mode 100644 index 000000000..3675d9739 --- /dev/null +++ b/docs/eventing/brokers/broker-admin-config-options.md @@ -0,0 +1,3 @@ +# Administrator configuration options + +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. diff --git a/docs/eventing/broker/example-mtbroker.md b/docs/eventing/brokers/broker-developer-config-options.md similarity index 91% rename from docs/eventing/broker/example-mtbroker.md rename to docs/eventing/brokers/broker-developer-config-options.md index 181131cdb..e85ca7dc8 100644 --- a/docs/eventing/broker/example-mtbroker.md +++ b/docs/eventing/brokers/broker-developer-config-options.md @@ -1,4 +1,6 @@ -# Broker configuration example +# Developer configuration options + +## 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: @@ -31,6 +33,6 @@ metadata: - 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 current 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` broker class. For more information about Kafka brokers, see the [Apache Kafka Broker](kafka-broker/README.md) documentation. +- 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` broker class. For more information about Kafka brokers, see the [Apache Kafka Broker](../brokers/broker-types/kafka-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](../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 new file mode 100644 index 000000000..ee635f838 --- /dev/null +++ b/docs/eventing/brokers/broker-types/README.md @@ -0,0 +1,28 @@ +# Available Broker types + +The following broker types are available for use with Knative Eventing. + +## Multi-tenant channel-based broker + +Knative Eventing provides a multi-tenant (MT) channel-based broker implementation that uses channels for event routing. + +Before you can use the MT 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). + +The following is a list of brokers provided by the community or vendors: + +### GCP broker + +The GCP broker is optimized for running in GCP. For more details, refer to the [documentation](https://github.com/google/knative-gcp/blob/master/docs/install/install-gcp-broker.md). + +### Apache Kafka broker + +For more information, see [Apache Kafka Broker](kafka-broker/README.md). + +### 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). diff --git a/docs/eventing/broker/kafka-broker/README.md b/docs/eventing/brokers/broker-types/kafka-broker/README.md similarity index 98% rename from docs/eventing/broker/kafka-broker/README.md rename to docs/eventing/brokers/broker-types/kafka-broker/README.md index b480e2ac4..fca68b4b9 100644 --- a/docs/eventing/broker/kafka-broker/README.md +++ b/docs/eventing/brokers/broker-types/kafka-broker/README.md @@ -15,8 +15,11 @@ The Knative Kafka Broker stores incoming CloudEvents as Kafka records, using the ## Prerequisites -1. [Installing Eventing using YAML files](../../../install/yaml-install/eventing/install-eventing-with-yaml.md). -2. An Apache Kafka cluster (if you're just getting started you can follow [Strimzi Quickstart page](https://strimzi.io/quickstarts/)). +1. You have installed Knative Eventing. +2. You have access to an Apache Kafka cluster. + +!!! tip + If you need to set up a Kafka cluster, you can do this by following the instructions on the [Strimzi Quickstart page](https://strimzi.io/quickstarts/). ## Installation diff --git a/docs/eventing/broker/rabbitmq-broker/README.md b/docs/eventing/brokers/broker-types/rabbitmq-broker/README.md similarity index 97% rename from docs/eventing/broker/rabbitmq-broker/README.md rename to docs/eventing/brokers/broker-types/rabbitmq-broker/README.md index 28957a3db..683ed2e41 100644 --- a/docs/eventing/broker/rabbitmq-broker/README.md +++ b/docs/eventing/brokers/broker-types/rabbitmq-broker/README.md @@ -4,7 +4,7 @@ This topic describes how to create a RabbitMQ Broker. ## Prerequisites -1. You have installed [Knative Eventing](../../../install/yaml-install/eventing/install-eventing-with-yaml.md) +1. You have installed Knative Eventing. 1. You have installed [CertManager v1.5.4](https://github.com/jetstack/cert-manager/releases/tag/v1.5.4) - easiest integration with RabbitMQ Messaging Topology Operator 1. You have installed [RabbitMQ Messaging Topology Operator](https://github.com/rabbitmq/messaging-topology-operator) - our recommendation is [latest release](https://github.com/rabbitmq/messaging-topology-operator/releases/latest) with CertManager 1. You have access to a working RabbitMQ instance. You can create a RabbitMQ instance by using the [RabbitMQ Cluster Kubernetes Operator](https://github.com/rabbitmq/cluster-operator). For more information see the [RabbitMQ website](https://www.rabbitmq.com/kubernetes/operator/using-operator.html). diff --git a/docs/eventing/broker/create-mtbroker.md b/docs/eventing/brokers/create-mtbroker.md similarity index 93% rename from docs/eventing/broker/create-mtbroker.md rename to docs/eventing/brokers/create-mtbroker.md index b8c318408..b8674ccf3 100644 --- a/docs/eventing/broker/create-mtbroker.md +++ b/docs/eventing/brokers/create-mtbroker.md @@ -4,7 +4,6 @@ Once you have installed Knative Eventing, you can create an instance of the mult 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: @@ -31,7 +30,7 @@ You can create a broker by using the `kn` CLI or by applying YAML files using `k === "kubectl" - The YAML in the following example creates a broker named `default` in the current namespace. For more information about configuring broker options using YAML, see the full [broker configuration example](example-mtbroker.md). + 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: diff --git a/docs/eventing/event-registry.md b/docs/eventing/event-registry.md index c04b735e4..bc33179e9 100644 --- a/docs/eventing/event-registry.md +++ b/docs/eventing/event-registry.md @@ -6,17 +6,8 @@ The event registry maintains a catalog of event types that each Broker can consu This topic provides information about how you can populate the event registry, how to discover events using the registry, and how to leverage that information to subscribe to events of interest. -## Before you begin - -It's recommended that you have a basic understanding of the following: - -- [Brokers](broker/README.md) -- [Triggers](broker/triggers/README.md) -- The [CloudEvents spec](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md), - particularly the - [Context Attributes](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#context-attributes) - section -- [Event sources](sources/README.md) +!!! note + Before using the event registry, it is recommended that you have a basic understanding of Brokers, Triggers, Event Sources, and the [CloudEvents spec](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md) (particularly the [Context Attributes](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#context-attributes) section). ## About EventType objects diff --git a/docs/eventing/broker/triggers/README.md b/docs/eventing/triggers/README.md similarity index 97% rename from docs/eventing/broker/triggers/README.md rename to docs/eventing/triggers/README.md index be84a9f4c..e8efd7795 100644 --- a/docs/eventing/broker/triggers/README.md +++ b/docs/eventing/triggers/README.md @@ -1,4 +1,4 @@ -# Triggers +# Using Triggers A trigger represents a desire to subscribe to events from a specific broker. @@ -104,7 +104,7 @@ This example filters events from the `default` broker that are of type You can modify a Trigger's behavior by setting the following two annotations: -- `eventing.knative.dev/injection`: if set to `enabled`, Eventing automatically creates a Broker for a Trigger if it doesn't exist. The Broker is created in the namespace where the Trigger is created. This annotation only works if you have the [Sugar Controller](../../sugar/README.md) enabled, which is optional and not enabled by default. +- `eventing.knative.dev/injection`: if set to `enabled`, Eventing automatically creates a Broker for a Trigger if it doesn't exist. The Broker is created in the namespace where the Trigger is created. This annotation only works if you have the [Sugar Controller](../sugar/README.md) enabled, which is optional and not enabled by default. - `knative.dev/dependency`: this annotation is used to mark the sources that the Trigger depends on. If one of the dependencies is not ready, the Trigger will not be ready. The following YAML is an example of a Trigger with a dependency: diff --git a/docs/getting-started/first-broker.md b/docs/getting-started/first-broker.md index c7f10e3c3..d62ac0fd3 100644 --- a/docs/getting-started/first-broker.md +++ b/docs/getting-started/first-broker.md @@ -1,41 +1,8 @@ -# Sources, Brokers, Triggers, Sinks, oh my! +# Sources, Brokers, and Triggers -For the purposes of this tutorial, let's keep it simple. You will focus on four powerful Eventing components: **Source**, **Trigger**, **Broker**, and **Sink**. +As part of the `kn quickstart` install, an InMemoryChannel-backed Broker is installed on your kind cluster. -Let's take a look at how these components interact: - -![Source 1 and Source 2 are transmitting some data -- ones and twos -- to the Broker, which then gets filtered by Triggers to the desired Sink.](https://user-images.githubusercontent.com/16281246/116248768-1fe56080-a73a-11eb-9a85-8bdccb82d16c.png){draggable=false} - -| Component | Basic Definition | -| :---------: | :----------------------------------: | -|:material-information: **Source** |A Kubernetes Custom Resource which emits events to the Broker. | -|:material-relation-many-to-many: **Broker** | A "hub" for events in your infrastructure; a central location to send events for delivery. | -|:material-magnet: **Trigger** |Acts as a filter for events entering the broker, can be configured with desired event attributes. | -|:material-download: **Sink** | A destination for events. | - -!!! note "A note on Sources and Sinks" - A Knative Service can act as both a Source and a Sink for events, and for good reason. You may want to consume events from the Broker and send modified events back to the Broker, as you would in any pipeline use-case. - -## CloudEvents - -Knative Eventing uses -[CloudEvents](https://github.com/cloudevents/spec/blob/v1.0.1/primer.md){target=blank_} to send -information back and forth between your Services and these components. - -??? question "What are CloudEvents?" - For our purposes, the only thing you need to know about CloudEvents are: - - 1. CloudEvents can carry some attributes (like id, Source, type, etc) as well as data payloads (JSON, plaintext, reference to data that lives elsewhere, etc). - 1. CloudEvents can be "emitted" by almost anything and can be transported to anywhere in your deployment. - 1. CloudEvents follow the [CloudEvents 1.0 Specification](https://github.com/cloudevents/spec){target=_blank}, with required and optional attributes. - - - To find out more about CloudEvents, check out the [CloudEvents website](https://cloudevents.io/)! - - -## Examining the Broker - -As part of the `kn quickstart` install, an In-Memory Broker should already be installed in your Cluster. Check to see that it is installed by running the command: +Verify that the Broker is installed by running the following command: ```bash kn broker list @@ -47,12 +14,6 @@ kn broker list example-broker http://broker-ingress.knative-eventing.svc.cluster.local/default/example-broker 5m 5 OK / 5 True ``` !!! warning - In-Memory Brokers are for development use only and must not be used in a production deployment. - - -??? question "Are there any other components of Knative Eventing?" - Though it is out of scope for this tutorial, Knative Eventing has many components which can be used in many ways to suit your needs. - - If you want to find out more about the different components of Knative Eventing, such as Channels, Sequences and Parallel flows, check out the [Knative Eventing documentation](../eventing/README.md){target=_blank}. + InMemoryChannel-backed Brokers are for development use only and must not be used in a production deployment. **Next, you'll take a look at a simple implementation** of Sources, Brokers, Triggers and Sinks using an app called the CloudEvents Player. diff --git a/docs/install/yaml-install/eventing/install-eventing-with-yaml.md b/docs/install/yaml-install/eventing/install-eventing-with-yaml.md index 551105d5c..80d957c05 100644 --- a/docs/install/yaml-install/eventing/install-eventing-with-yaml.md +++ b/docs/install/yaml-install/eventing/install-eventing-with-yaml.md @@ -72,7 +72,6 @@ Follow the procedure for the Channel of your choice: kubectl apply -f {{ artifact(org="knative-sandbox",repo="eventing-kafka-broker",file="eventing-kafka-post-install.yaml")}} ``` - === "Google Cloud Pub/Sub Channel" * Install the Google Cloud Pub/Sub Channel by running the command: @@ -141,8 +140,7 @@ Follow the procedure for the Broker of your choice: kubectl apply -f {{ artifact(org="knative-sandbox",repo="eventing-kafka-broker",file="eventing-kafka-post-install.yaml")}} ``` - - For more information, see the [Kafka Broker](../../../eventing/broker/kafka-broker/README.md) documentation. + For more information, see the [Kafka Broker](../../../eventing/brokers/broker-types/kafka-broker/README.md) documentation. === "MT-Channel-based" diff --git a/docs/serving/revisions/README.md b/docs/serving/revisions/README.md index fbb662c9f..9e2a62a32 100644 --- a/docs/serving/revisions/README.md +++ b/docs/serving/revisions/README.md @@ -1,7 +1,7 @@ -# Revisions +# About Revisions --8<-- "about-revisions.md" ## Additional resources -- [Revisions concept documentation](../../concepts/resources/revisions.md){target=_blank} +- [Revisions concept documentation](../../concepts/serving-resources/revisions.md){target=_blank} diff --git a/docs/snippets/about-brokers.md b/docs/snippets/about-brokers.md new file mode 100644 index 000000000..10db07311 --- /dev/null +++ b/docs/snippets/about-brokers.md @@ -0,0 +1,8 @@ + + +Brokers are Kubernetes custom resources that define an event mesh for collecting a pool of events. Brokers provide a discoverable endpoint for event ingress, and use Triggers for event delivery. Event producers can send events to a broker by POSTing the event. + +![Source 1 and Source 2 are transmitting some data -- ones and twos -- to the Broker, which then gets filtered by Triggers to the desired Sink.](https://user-images.githubusercontent.com/16281246/116248768-1fe56080-a73a-11eb-9a85-8bdccb82d16c.png){draggable=false} diff --git a/docs/snippets/about-revisions.md b/docs/snippets/about-revisions.md index f47b19df2..9d6af9775 100644 --- a/docs/snippets/about-revisions.md +++ b/docs/snippets/about-revisions.md @@ -1,5 +1,5 @@ Revisions are Knative Serving resources that contain point-in-time snapshots of the application code and configuration for each change made to a Knative Service. diff --git a/docs/snippets/about-subscribers.md b/docs/snippets/about-subscribers.md new file mode 100644 index 000000000..b5eefad6e --- /dev/null +++ b/docs/snippets/about-subscribers.md @@ -0,0 +1,5 @@ + + +A Subscriber can be any URL or Addressable resource. Subscribers can also reply to an active request from the Broker, and can respond with a new event that is sent back into the Broker. diff --git a/docs/snippets/about-triggers.md b/docs/snippets/about-triggers.md new file mode 100644 index 000000000..0f589507e --- /dev/null +++ b/docs/snippets/about-triggers.md @@ -0,0 +1,5 @@ + + +After an event has entered a broker, it can be forwarded to subscribers by using Triggers. Triggers allow events to be filtered by attributes, so that events with particular attributes can be sent to Subscribers that have registered interest in events with those attributes.