From b4067ca46fd145b1bfdd632ea29bc692e41af654 Mon Sep 17 00:00:00 2001 From: Ashleigh Brennan Date: Mon, 11 Apr 2022 11:20:14 -0500 Subject: [PATCH] SRVCOM-1728: Updating broker and trigger abstracts for Jupiter guidelines --- modules/delete-kn-trigger.adoc | 4 ++-- modules/kn-trigger-describe.adoc | 4 ++-- modules/kn-trigger-filtering.adoc | 3 +++ modules/kn-trigger-list.adoc | 4 ++-- modules/kn-trigger-update.adoc | 4 ++-- modules/serverless-broker-types.adoc | 3 +++ modules/serverless-create-broker-kn.adoc | 7 +++++-- modules/serverless-create-kn-trigger.adoc | 4 ++-- modules/serverless-create-trigger-odc.adoc | 3 ++- modules/serverless-creating-broker-annotation.adoc | 7 ++++--- modules/serverless-creating-broker-labeling.adoc | 7 ++++--- modules/serverless-deleting-broker-injection.adoc | 2 +- modules/serverless-describe-broker-kn.adoc | 4 +++- modules/serverless-list-broker-kn.adoc | 4 +++- serverless/develop/serverless-triggers.adoc | 2 +- serverless/develop/serverless-using-brokers.adoc | 11 +++-------- snippets/serverless-brokers-intro.adoc | 10 ++++++++++ 17 files changed, 52 insertions(+), 31 deletions(-) create mode 100644 snippets/serverless-brokers-intro.adoc diff --git a/modules/delete-kn-trigger.adoc b/modules/delete-kn-trigger.adoc index f5fc80a76d..d9556128f4 100644 --- a/modules/delete-kn-trigger.adoc +++ b/modules/delete-kn-trigger.adoc @@ -6,12 +6,12 @@ [id="delete-kn-trigger_{context}"] = Deleting a trigger by using the Knative CLI -You can use the `kn trigger delete` command to delete a trigger. +Using the `kn` CLI to delete a trigger provides a streamlined and intuitive user interface. You can use the `kn trigger delete` command to delete a trigger. .Prerequisites * The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. -* You have installed the `kn` CLI. +* You have installed the Knative (`kn`) CLI. * You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}. .Procedure diff --git a/modules/kn-trigger-describe.adoc b/modules/kn-trigger-describe.adoc index 87da6bfe88..6bcafe02f9 100644 --- a/modules/kn-trigger-describe.adoc +++ b/modules/kn-trigger-describe.adoc @@ -6,12 +6,12 @@ [id="kn-trigger-describe_{context}"] = Describing a trigger by using the Knative CLI -You can use the `kn trigger describe` command to print information about a trigger. +Using the `kn` CLI to describe triggers provides a streamlined and intuitive user interface. You can use the `kn trigger describe` command to print information about existing triggers in your cluster by using the `kn` CLI. .Prerequisites * The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. -* You have installed the `kn` CLI. +* You have installed the Knative (`kn`) CLI. * You have created a trigger. .Procedure diff --git a/modules/kn-trigger-filtering.adoc b/modules/kn-trigger-filtering.adoc index 1c0cc3136b..cb3f5d5392 100644 --- a/modules/kn-trigger-filtering.adoc +++ b/modules/kn-trigger-filtering.adoc @@ -5,6 +5,9 @@ :_content-type: REFERENCE [id="kn-trigger-filtering_{context}"] = Filtering events with triggers by using the Knative CLI +// should be a procedure module but out of scope for this PR + +Using the `kn` CLI to filter events by using triggers provides a streamlined and intuitive user interface. You can use the `kn trigger create` command, along with the appropriate flags, to filter events by using triggers. In the following trigger example, only events with the attribute `type: dev.knative.samples.helloworld` are sent to the event sink: diff --git a/modules/kn-trigger-list.adoc b/modules/kn-trigger-list.adoc index ffee2de252..d8b2d65dd0 100644 --- a/modules/kn-trigger-list.adoc +++ b/modules/kn-trigger-list.adoc @@ -6,12 +6,12 @@ [id="kn-trigger-list_{context}"] = Listing triggers by using the Knative CLI -The `kn trigger list` command prints a list of available triggers. +Using the `kn` CLI to list triggers provides a streamlined and intuitive user interface. You can use the `kn trigger list` command to list existing triggers in your cluster. .Prerequisites * The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. -* You have installed the `kn` CLI. +* You have installed the Knative (`kn`) CLI. .Procedure diff --git a/modules/kn-trigger-update.adoc b/modules/kn-trigger-update.adoc index 8b934bff82..83b9d8bb5f 100644 --- a/modules/kn-trigger-update.adoc +++ b/modules/kn-trigger-update.adoc @@ -6,12 +6,12 @@ [id="kn-trigger-update_{context}"] = Updating a trigger by using the Knative CLI -You can use the `kn trigger update` command with certain flags to update attributes for a trigger. +Using the `kn` CLI to update triggers provides a streamlined and intuitive user interface. You can use the `kn trigger update` command with certain flags to update attributes for a trigger. .Prerequisites * The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. -* You have installed the `kn` CLI. +* You have installed the Knative (`kn`) CLI. * You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}. .Procedure diff --git a/modules/serverless-broker-types.adoc b/modules/serverless-broker-types.adoc index 8e10790393..31338d1dc2 100644 --- a/modules/serverless-broker-types.adoc +++ b/modules/serverless-broker-types.adoc @@ -21,4 +21,7 @@ The channel-based broker implementation internally uses channels for event deliv [id="serverless-using-brokers-kafka"] == Kafka broker +:FeatureName: Kafka broker +include::snippets/technology-preview.adoc[leveloffset=+2] + The Kafka broker is a broker implementation that uses Kafka internally to provide at-least once delivery guarantees. It supports multiple Kafka versions, and has a native integration with Kafka for storing and routing events. diff --git a/modules/serverless-create-broker-kn.adoc b/modules/serverless-create-broker-kn.adoc index ca33c044e1..25ed1150c2 100644 --- a/modules/serverless-create-broker-kn.adoc +++ b/modules/serverless-create-broker-kn.adoc @@ -6,10 +6,12 @@ [id="serverless-create-broker-kn_{context}"] = Creating a broker by using the Knative CLI +Brokers can be used in combination with triggers to deliver events from an event source to an event sink. Using the `kn` CLI to create brokers provides a more streamlined and intuitive user interface over modifying YAML files directly. You can use the `kn broker create` command to create a broker by using the `kn` CLI. + .Prerequisites * The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. -* You have installed the `kn` CLI. +* You have installed the Knative (`kn`) CLI. * You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}. .Procedure @@ -37,6 +39,7 @@ NAME URL default http://broker-ingress.knative-eventing.svc.cluster.local/test/default 45s 5 OK / 5 True ---- -. Optional: If you are using the {product-title} web console, you can navigate to the **Topology** view in the **Developer** perspective, and observe that the broker exists: +. Optional: If you are using the {product-title} web console, you can navigate to the *Topology* view in the *Developer* perspective, and observe that the broker exists: + image::odc-view-broker.png[View the broker in the web console Topology view] +// need to add separate docs for broker in ODC - out of scope for this PR diff --git a/modules/serverless-create-kn-trigger.adoc b/modules/serverless-create-kn-trigger.adoc index ac1af95ee3..f341b6aa0c 100644 --- a/modules/serverless-create-kn-trigger.adoc +++ b/modules/serverless-create-kn-trigger.adoc @@ -6,12 +6,12 @@ [id="serverless-create-kn-trigger_{context}"] = Creating a trigger by using the Knative CLI -You can create a trigger by using the `kn trigger create` command. +Using the `kn` CLI to create triggers provides a more streamlined and intuitive user interface over modifying YAML files directly. You can use the `kn trigger create` command to create a trigger by using the `kn` CLI. .Prerequisites * The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. -* You have installed the `kn` CLI. +* You have installed the Knative (`kn`) CLI. * You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}. .Procedure diff --git a/modules/serverless-create-trigger-odc.adoc b/modules/serverless-create-trigger-odc.adoc index 87be752388..dd211bf946 100644 --- a/modules/serverless-create-trigger-odc.adoc +++ b/modules/serverless-create-trigger-odc.adoc @@ -6,7 +6,7 @@ [id="serverless-create-trigger-odc_{context}"] = Creating a trigger by using the web console -After you have created a broker, you can create a trigger by using the web console. +Using the {product-title} web console provides a streamlined and intuitive user interface to create a trigger. After Knative Eventing is installed on your cluster and you have created a broker, you can create a trigger by using the web console. .Prerequisites @@ -28,6 +28,7 @@ After you have created a broker, you can create a trigger by using the web conso * After the subscription has been created, you can view it in the *Topology* page, where it is represented as a line that connects the broker to the event sink. .Deleting a trigger +// should be a separate module; out of scope for this PR . In the *Developer* perspective, navigate to the *Topology* page. . Click on the trigger that you want to delete. diff --git a/modules/serverless-creating-broker-annotation.adoc b/modules/serverless-creating-broker-annotation.adoc index bca76f4453..cc51c150ca 100644 --- a/modules/serverless-creating-broker-annotation.adoc +++ b/modules/serverless-creating-broker-annotation.adoc @@ -6,7 +6,7 @@ [id="serverless-creating-broker-annotation_{context}"] = Creating a broker by annotating a trigger -You can create a broker by adding the `eventing.knative.dev/injection: enabled` annotation to a `Trigger` object. +Brokers can be used in combination with triggers to deliver events from an event source to an event sink. You can create a broker by adding the `eventing.knative.dev/injection: enabled` annotation to a `Trigger` object. [IMPORTANT] ==== @@ -17,7 +17,7 @@ If you delete the broker without having a cluster administrator remove this anno .Prerequisites * The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. -* Install the OpenShift CLI (`oc`). +* Install the OpenShift (`oc`) CLI. * You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}. .Procedure @@ -68,6 +68,7 @@ NAME READY REASON URL default True http://broker-ingress.knative-eventing.svc.cluster.local/test/default 3m56s ---- -. Navigate to the *Topology* view in the web console, and observe that the broker exists: +. Optional: If you are using the {product-title} web console, you can navigate to the *Topology* view in the *Developer* perspective, and observe that the broker exists: + image::odc-view-broker.png[View the broker in the web console Topology view] +// need to add separate docs for broker in ODC - out of scope for this PR diff --git a/modules/serverless-creating-broker-labeling.adoc b/modules/serverless-creating-broker-labeling.adoc index 483a30a45c..01915f661d 100644 --- a/modules/serverless-creating-broker-labeling.adoc +++ b/modules/serverless-creating-broker-labeling.adoc @@ -6,7 +6,7 @@ [id="serverless-creating-broker-labeling_{context}"] = Creating a broker by labeling a namespace -You can create the `default` broker automatically by labeling a namespace that you own or have write permissions for. +Brokers can be used in combination with triggers to deliver events from an event source to an event sink. You can create the `default` broker automatically by labelling a namespace that you own or have write permissions for. [NOTE] ==== @@ -16,7 +16,7 @@ Brokers created using this method are not removed if you remove the label. You m .Prerequisites * The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. -* Install the OpenShift CLI (`oc`). +* Install the OpenShift (`oc`) CLI. * You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}. ifdef::openshift-dedicated[] @@ -56,6 +56,7 @@ NAME READY REASON URL default True http://broker-ingress.knative-eventing.svc.cluster.local/test/default 3m56s ---- -. Navigate to the *Topology* view in the web console, and observe that the broker exists: +. Optional: If you are using the {product-title} web console, you can navigate to the *Topology* view in the *Developer* perspective, and observe that the broker exists: + image::odc-view-broker.png[View the broker in the web console Topology view] +// need to add separate docs for broker in ODC - out of scope for this PR diff --git a/modules/serverless-deleting-broker-injection.adoc b/modules/serverless-deleting-broker-injection.adoc index 1d89ed4301..33f598726b 100644 --- a/modules/serverless-deleting-broker-injection.adoc +++ b/modules/serverless-deleting-broker-injection.adoc @@ -10,7 +10,7 @@ If you create a broker by injection and later want to delete it, you must delete .Prerequisites -* Install the OpenShift CLI (`oc`). +* Install the OpenShift (`oc`) CLI. .Procedure diff --git a/modules/serverless-describe-broker-kn.adoc b/modules/serverless-describe-broker-kn.adoc index dfcc13144a..b46b5bf46c 100644 --- a/modules/serverless-describe-broker-kn.adoc +++ b/modules/serverless-describe-broker-kn.adoc @@ -6,10 +6,12 @@ [id="serverless-describe-broker-kn_{context}"] = Describing an existing broker by using the Knative CLI +Using the `kn` CLI to describe brokers provides a streamlined and intuitive user interface. You can use the `kn broker describe` command to print information about existing brokers in your cluster by using the `kn` CLI. + .Prerequisites * The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. -* You have installed the `kn` CLI. +* You have installed the Knative (`kn`) CLI. .Procedure diff --git a/modules/serverless-list-broker-kn.adoc b/modules/serverless-list-broker-kn.adoc index 65b52f1027..13d659e3c4 100644 --- a/modules/serverless-list-broker-kn.adoc +++ b/modules/serverless-list-broker-kn.adoc @@ -6,10 +6,12 @@ [id="serverless-list-broker-kn_{context}"] = Listing existing brokers by using the Knative CLI +Using the `kn` CLI to list brokers provides a streamlined and intuitive user interface. You can use the `kn broker list` command to list existing brokers in your cluster by using the `kn` CLI. + .Prerequisites * The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. -* You have installed the `kn` CLI. +* You have installed the Knative (`kn`) CLI. .Procedure diff --git a/serverless/develop/serverless-triggers.adoc b/serverless/develop/serverless-triggers.adoc index 868a10eb23..295006eff7 100644 --- a/serverless/develop/serverless-triggers.adoc +++ b/serverless/develop/serverless-triggers.adoc @@ -6,7 +6,7 @@ include::_attributes/common-attributes.adoc[] toc::[] -Using triggers enables you to filter events from the broker for delivery to event sinks. +include::snippets/serverless-brokers-intro.adoc[] // ODC include::modules/serverless-create-trigger-odc.adoc[leveloffset=+1] diff --git a/serverless/develop/serverless-using-brokers.adoc b/serverless/develop/serverless-using-brokers.adoc index 63d49d0eb4..63eb97fe7e 100644 --- a/serverless/develop/serverless-using-brokers.adoc +++ b/serverless/develop/serverless-using-brokers.adoc @@ -6,17 +6,10 @@ include::_attributes/common-attributes.adoc[] toc::[] -Brokers can be used in combination with xref:../../serverless/develop/serverless-triggers.adoc#serverless-triggers[triggers] to deliver events from an xref:../../serverless/discover/knative-event-sources.adoc#knative-event-sources[event source] to an event sink. - -image::serverless-event-broker-workflow.png[Broker event delivery overview] - -Events can be sent from an event source to a broker as an HTTP `POST` request. After events have entered the broker, they can be filtered by https://github.com/cloudevents/spec/blob/v1.0/spec.md#context-attributes[CloudEvent attributes] using triggers, and sent as an HTTP `POST` request to an event sink. +include::snippets/serverless-brokers-intro.adoc[] include::modules/serverless-broker-types.adoc[leveloffset=+1] -:FeatureName: Kafka broker -include::snippets/technology-preview.adoc[leveloffset=+2] - [id="serverless-using-brokers-creating-brokers"] == Creating a broker that uses default settings @@ -38,5 +31,7 @@ include::modules/serverless-describe-broker-kn.adoc[leveloffset=+2] [id="additional-resources_serverless-using-brokers"] [role="_additional-resources"] == Additional resources +* xref:../../serverless/develop/serverless-triggers.adoc#serverless-triggers[Triggers] +xref:../../serverless/discover/knative-event-sources.adoc#knative-event-sources[Event sources] * xref:../../serverless/develop/serverless-event-delivery.adoc#serverless-event-delivery[Event delivery] * xref:../../serverless/develop/serverless-kafka-developer.adoc#serverless-kafka-developer-broker[Kafka broker] diff --git a/snippets/serverless-brokers-intro.adoc b/snippets/serverless-brokers-intro.adoc new file mode 100644 index 0000000000..88fe487419 --- /dev/null +++ b/snippets/serverless-brokers-intro.adoc @@ -0,0 +1,10 @@ +// Text snippet included in the following modules: +// +// * /serverless/develop/serverless-using-brokers.adoc +// * /serverless/develop/serverless-triggers.adoc + +:_content-type: SNIPPET + +Brokers can be used in combination with triggers to deliver events from an event source to an event sink. Events are sent from an event source to a broker as an HTTP `POST` request. After events have entered the broker, they can be filtered by https://github.com/cloudevents/spec/blob/v1.0/spec.md#context-attributes[CloudEvent attributes] using triggers, and sent as an HTTP `POST` request to an event sink. + +image::serverless-event-broker-workflow.png[Broker event delivery overview]