diff --git a/images/add-trigger-odc.png b/images/add-trigger-odc.png new file mode 100644 index 0000000000..b5c98cc4bd Binary files /dev/null and b/images/add-trigger-odc.png differ diff --git a/images/delete-trigger-odc.png b/images/delete-trigger-odc.png new file mode 100644 index 0000000000..abe9bc1d8a Binary files /dev/null and b/images/delete-trigger-odc.png differ diff --git a/images/odc-view-broker.png b/images/odc-view-broker.png new file mode 100644 index 0000000000..d8ed44717f Binary files /dev/null and b/images/odc-view-broker.png differ diff --git a/images/verify-trigger-odc.png b/images/verify-trigger-odc.png new file mode 100644 index 0000000000..be56d1a87b Binary files /dev/null and b/images/verify-trigger-odc.png differ diff --git a/modules/apiserversource-kn.adoc b/modules/apiserversource-kn.adoc index c8cf06244f..286cbe30f3 100644 --- a/modules/apiserversource-kn.adoc +++ b/modules/apiserversource-kn.adoc @@ -15,7 +15,6 @@ This section describes the steps required to create an ApiServerSource using `kn . Create an ApiServerSource that uses a broker as an event sink: + - [source,terminal] ---- $ kn source apiserver create --sink broker: --resource "event:v1" --service-account --mode Resource @@ -23,7 +22,6 @@ $ kn source apiserver create --sink broker: --r . To check that the ApiServerSource is set up correctly, create a Knative service that dumps incoming messages to its log: + - [source,terminal] ---- $ kn service create --image quay.io/openshift-knative/knative-eventing-sources-event-display:latest @@ -31,7 +29,6 @@ $ kn service create --image quay.io/openshift-knative/knative-eve . Create a trigger to filter events from the `default` broker to the service: + - [source,terminal] ---- $ kn trigger create --sink ksvc: @@ -40,7 +37,6 @@ $ kn trigger create --sink ksvc: . Create events by launching a Pod in the default namespace: + - [source,terminal] ---- $ oc create deployment hello-node --image quay.io/openshift-knative/knative-eventing-sources-event-display:latest @@ -48,16 +44,13 @@ $ oc create deployment hello-node --image quay.io/openshift-knative/knative-even . Check that the controller is mapped correctly by inspecting the output generated by the following command: + - [source,terminal] ---- $ kn source apiserver describe ---- - + .Example output + - [source,terminal] ---- Name: mysource @@ -69,7 +62,7 @@ Mode: Resource Sink: Name: default Namespace: default - Kind: Broker (eventing.knative.dev/v1alpha1) + Kind: Broker (eventing.knative.dev/v1) Resources: Kind: event (v1) Controller: false @@ -88,7 +81,6 @@ You can verify that the Kubernetes events were sent to Knative by looking at the . Get the pods: + - [source,terminal] ---- $ oc get pods @@ -96,14 +88,11 @@ $ oc get pods . View the message dumper function logs for the pods: + - [source,terminal] ---- $ oc logs $(oc get pod -o name | grep event-display) -c user-container ---- - + - .Example output [source,terminal] ---- diff --git a/modules/apiserversource-yaml.adoc b/modules/apiserversource-yaml.adoc index 93147da643..df2d28d487 100644 --- a/modules/apiserversource-yaml.adoc +++ b/modules/apiserversource-yaml.adoc @@ -16,7 +16,6 @@ This guide describes the steps required to create an ApiServerSource using YAML . To create a service account, role, and role binding for the ApiServerSource, create a file named `authentication.yaml` and copy the following sample code into it: + - [source,yaml] ---- apiVersion: v1 @@ -56,7 +55,6 @@ subjects: name: events-sa namespace: default <1> ---- - + <1> Change this namespace to the namespace that you have selected for installing ApiServerSource. + @@ -67,7 +65,6 @@ If you want to re-use an existing service account with the appropriate permissio + After you have created the `authentication.yaml` file, apply it: + - [source,terminal] ---- $ oc apply -f authentication.yaml @@ -75,7 +72,6 @@ $ oc apply -f authentication.yaml . To create an ApiServerSource event source, create a file named `k8s-events.yaml` and copy the following sample code into it: + - [source,yaml] ---- apiVersion: sources.knative.dev/v1alpha1 @@ -90,7 +86,7 @@ spec: kind: Event sink: ref: - apiVersion: eventing.knative.dev/v1beta1 + apiVersion: eventing.knative.dev/v1 kind: Broker name: default ---- @@ -98,7 +94,6 @@ spec: + After you have created the `k8s-events.yaml` file, apply it: + - [source,terminal] ---- $ oc apply -f k8s-events.yaml @@ -108,7 +103,6 @@ $ oc apply -f k8s-events.yaml + Copy the following sample YAML into a file named `service.yaml`: + - [source,yaml] ---- apiVersion: serving.knative.dev/v1 @@ -120,13 +114,11 @@ spec: template: spec: containers: - - image: quay.io/openshift-knative/knative-eventing-sources-event-display:v0.13.2 + - image: quay.io/openshift-knative/knative-eventing-sources-event-display:latest ---- - + After you have created the `service.yaml` file, apply it: + - [source,terminal] ---- $ oc apply -f service.yaml @@ -134,26 +126,24 @@ $ oc apply -f service.yaml . To create a trigger from the `default` broker that filters events to the service created in the previous step, create a file named `trigger.yaml` and copy the following sample code into it: + - [source,yaml] ---- -apiVersion: eventing.knative.dev/v1alpha1 +apiVersion: eventing.knative.dev/v1 kind: Trigger metadata: name: event-display-trigger namespace: default spec: + broker: default subscriber: ref: apiVersion: serving.knative.dev/v1 kind: Service name: event-display ---- - + After you have created the `trigger.yaml` file, apply it: + - [source,terminal] ---- $ oc apply -f trigger.yaml @@ -161,7 +151,6 @@ $ oc apply -f trigger.yaml . To create events, launch a Pod in the default namespace: + - [source,terminal] ---- $ oc create deployment hello-node --image=quay.io/openshift-knative/knative-eventing-sources-event-display @@ -169,16 +158,13 @@ $ oc create deployment hello-node --image=quay.io/openshift-knative/knative-even . To check that the controller is mapped correctly, enter the following command and inspect the output: + - [source,terminal] ---- $ oc get apiserversource.sources.knative.dev testevents -o yaml ---- - + .Example output + - [source,yaml] ---- apiVersion: sources.knative.dev/v1alpha1 @@ -207,7 +193,7 @@ spec: serviceAccountName: events-sa sink: ref: - apiVersion: eventing.knative.dev/v1beta1 + apiVersion: eventing.knative.dev/v1 kind: Broker name: default ---- @@ -218,7 +204,6 @@ To verify that the Kubernetes events were sent to Knative, you can look at the m . Get the pods: + - [source,terminal] ---- $ oc get pods @@ -226,16 +211,13 @@ $ oc get pods . View the message dumper function logs for the pods: + - [source,terminal] ---- $ oc logs $(oc get pod -o name | grep event-display) -c user-container ---- - + .Example output + - [source,terminal] ---- ☁️ cloudevents.Event diff --git a/modules/delete-kn-trigger.adoc b/modules/delete-kn-trigger.adoc index dd530ebafa..5744ca390c 100644 --- a/modules/delete-kn-trigger.adoc +++ b/modules/delete-kn-trigger.adoc @@ -1,12 +1,32 @@ +// Module included in the following assemblies: +// +// * /serverless/event_workflows/serverless-using-brokers.adoc + [id="delete-kn-trigger_{context}"] = Deleting a trigger using `kn` .Procedure -* Delete the trigger: +* Delete a trigger: + - [source,terminal] ---- $ kn trigger delete ---- + +.Verification steps + +. List existing triggers: ++ +[source,terminal] +---- +$ kn trigger list +---- + +. Verify that the trigger no longer exists: ++ +.Example output +[source,terminal] +---- +No triggers found. +---- diff --git a/modules/kn-trigger-describe.adoc b/modules/kn-trigger-describe.adoc index 205ca20d04..0c3b7bd024 100644 --- a/modules/kn-trigger-describe.adoc +++ b/modules/kn-trigger-describe.adoc @@ -1,22 +1,20 @@ // Module included in the following assemblies: // -// * serverless/event_workflows/serverless-kn-trigger.adoc +// * serverless/event_workflows/serverless-using-brokers.adoc [id="kn-trigger-describe_{context}"] = Describing a trigger using `kn` -The `kn trigger describe` command prints information about a trigger. +You can use the `kn trigger describe` command to print information about a trigger. .Procedure * Enter the command: + - [source,terminal] ---- $ kn trigger describe ---- - + .Example output [source,terminal] diff --git a/modules/kn-trigger-filtering.adoc b/modules/kn-trigger-filtering.adoc index 93f235287f..9cd323875c 100644 --- a/modules/kn-trigger-filtering.adoc +++ b/modules/kn-trigger-filtering.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// * serverless/knative_eventing/serverless-kn-trigger.adoc +// * /serverless/event_workflows/serverless-using-brokers.adoc [id="kn-trigger-filtering_{context}"] = Filtering events using triggers diff --git a/modules/kn-trigger-list.adoc b/modules/kn-trigger-list.adoc index 91c951d585..88f6c20d6c 100644 --- a/modules/kn-trigger-list.adoc +++ b/modules/kn-trigger-list.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// * serverless/event_workflows/serverless-kn-trigger.adoc +// * /serverless/event_workflows/serverless-using-brokers.adoc [id="kn-trigger-list_{context}"] = Listing triggers using `kn` @@ -10,12 +10,10 @@ The `kn trigger list` command prints a list of available triggers. .Procedure . Print a list of available triggers: + - [source,terminal] ---- $ kn trigger list ---- - + .Example output [source,terminal] @@ -25,16 +23,10 @@ email default ksvc:edisplay 4s 5 OK / 5 True ping default ksvc:edisplay 32s 5 OK / 5 True ---- -[id="kn-trigger-list-json_{context}"] -= Listing triggers using `kn` in JSON format - -.Procedure -. Print a list of triggers in JSON format: +. Optional: Print a list of triggers in JSON format: + - [source,terminal] ---- $ kn trigger list -o json ---- - //example output? diff --git a/modules/kn-trigger-update.adoc b/modules/kn-trigger-update.adoc index 315956b466..7626238802 100644 --- a/modules/kn-trigger-update.adoc +++ b/modules/kn-trigger-update.adoc @@ -1,43 +1,35 @@ // Module included in the following assemblies: // -// * serverless/event_workflows/serverless-kn-trigger.adoc +// * serverless/event_workflows/serverless-using-brokers.adoc [id="kn-trigger-update_{context}"] = Updating a trigger using `kn` You can use the `kn trigger update` command with certain flags to update attributes for a trigger. -.Example +.Procedure -. To update a trigger, enter the following command: +* Update a trigger: + - [source,terminal] ---- $ kn trigger update --filter --sink [flags] ---- - +** You can update a trigger to filter exact event attributes that match incoming events. For example, using the `type` attribute: + -You can update a trigger to filter exact event attributes that match incoming events, such as `type=knative.dev.event`. For example: -+ - [source,terminal] ---- $ kn trigger update --filter type=knative.dev.event ---- - -. You can also remove a filter attribute from a trigger. For example, you can remove the filter attribute with key `type`: +** You can remove a filter attribute from a trigger. For example, you can remove the filter attribute with key `type`: + - [source,terminal] ---- $ kn trigger update --filter type- ---- - -. Update the sink of a trigger to use a service named `event-display`: +** You can use the `--sink` parameter to change the event sink of a trigger: + - [source,terminal] ---- -$ kn trigger update --sink ksvc:event-display +$ kn trigger update --sink ksvc:my-event-sink ---- diff --git a/modules/serverless-create-broker-kn.adoc b/modules/serverless-create-broker-kn.adoc new file mode 100644 index 0000000000..c7fbab71c1 --- /dev/null +++ b/modules/serverless-create-broker-kn.adoc @@ -0,0 +1,38 @@ +// Module included in the following assemblies: +// +// * serverless/event_workflows/serverless-using-brokers.adoc + +[id="serverless-create-broker-kn_{context}"] += Creating a broker using the Knative CLI + +.Prerequisites +* The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. +* You have installed the `kn` CLI. + +.Procedure +* Create the `default` broker: ++ +[source,terminal] +---- +$ kn broker create default +---- + +.Verification steps + +. Use the `kn` command to list all existing brokers: ++ +[source,terminal] +---- +$ kn broker list +---- ++ +.Example output +[source,terminal] +---- +NAME URL AGE CONDITIONS READY REASON +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: ++ +image::odc-view-broker.png[View the broker in the web console Topology view] diff --git a/modules/serverless-create-kn-trigger.adoc b/modules/serverless-create-kn-trigger.adoc index aed725c1a1..6fe99dd6c9 100644 --- a/modules/serverless-create-kn-trigger.adoc +++ b/modules/serverless-create-kn-trigger.adoc @@ -1,7 +1,11 @@ +// Module included in the following assemblies: +// +// * serverless/event_workflows/serverless-using-brokers.adoc + [id="serverless-create-kn-trigger_{context}"] = Creating a trigger using `kn` -The Knative CLI provides a set of `kn trigger` commands that can be used to create and manage triggers. +You can create a trigger by using the `kn trigger create` command. .Procedure @@ -20,5 +24,4 @@ $ kn trigger create --inject-broker --filter --sink < ---- + By default, triggers forward all events sent to a broker to sinks that are subscribed to that broker. -+ Using the `--filter` attribute for triggers allows you to filter events from a broker, so that subscribers will only receive a subset of events based on your defined criteria. diff --git a/modules/serverless-create-trigger-odc.adoc b/modules/serverless-create-trigger-odc.adoc new file mode 100644 index 0000000000..1b85e0138d --- /dev/null +++ b/modules/serverless-create-trigger-odc.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * /serverless/event_workflows/serverless-using-brokers.adoc + +[id="serverless-create-trigger-odc_{context}"] += Creating a trigger using the Developer perspective + +After you have created a broker, you can create a trigger in the web console *Developer* perspective. + +.Prerequisites + +* The {ServerlessOperatorName}, Knative Serving, and Knative Eventing are installed on your {product-title} cluster. +* You have logged in to the web console. +* You are in the *Developer* perspective. +* 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}. +* You have created a broker and a Knative service or other event sink to connect to the trigger. + +.Procedure + +. In the *Developer* perspective, navigate to the *Topology* page. +. Hover over the broker that you want to create a trigger for, and drag the arrow. The *Add Trigger* option is displayed. ++ +image::add-trigger-odc.png[Create a trigger for the broker] +. Click *Add Trigger*. +. Select your sink as a *Subscriber* from the drop-down list. ++ +. Click *Add*. + +.Verification steps +* After the subscription has been created, it is represented as a line that connects the broker to the service in the *Topology* view: ++ +image::verify-trigger-odc.png[Trigger in the Topology view] diff --git a/modules/serverless-creating-broker-admin.adoc b/modules/serverless-creating-broker-admin.adoc index 03b76c62c4..37e8b32d00 100644 --- a/modules/serverless-creating-broker-admin.adoc +++ b/modules/serverless-creating-broker-admin.adoc @@ -3,22 +3,22 @@ // * serverless/event_workflows/serverless-using-brokers.adoc [id="serverless-creating-broker-admin_{context}"] -= Creating a broker as a cluster administrator using namespace annotation += Creating a broker by labeling a namespace -If you have cluster administrator permissions, you can create the `default` broker automatically by using namespace annotation. +If you have cluster administrator permissions, you can create the `default` broker automatically by labeling a namespace. [NOTE] ==== -Brokers created due to annotation will not be removed if you remove the annotation. You must manually delete them. +Brokers created using this method will not be removed if you remove the label. You must manually delete them. ==== .Prerequisites -* Knative Eventing installed. -* Cluster administrator permissions for {product-title}. +* The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. +* You have cluster administrator permissions for {product-title}. .Procedure -* Annotate a namespace: +* Label a namespace with `eventing.knative.dev/injection=enabled`: + [source,terminal] ---- @@ -27,9 +27,28 @@ $ oc label namespace eventing.knative.dev/injection=enabled .Verification steps -* Verify that the broker has been created successfully: +You can verify that the broker has been created successfully by using the `oc` CLI, or by observing it in the *Topology* view in the web console. + +. Use the `oc` command to get the broker: + [source,terminal] ---- $ oc -n get broker ---- ++ +.Example command +[source,terminal] +---- +$ oc -n default get broker default +---- ++ +.Example output +[source,terminal] +---- +NAME READY REASON URL AGE +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: ++ +image::odc-view-broker.png[View the broker in the web console Topology view] diff --git a/modules/serverless-creating-broker-annotation.adoc b/modules/serverless-creating-broker-annotation.adoc new file mode 100644 index 0000000000..82bec515d3 --- /dev/null +++ b/modules/serverless-creating-broker-annotation.adoc @@ -0,0 +1,67 @@ +// Module included in the following assemblies: +// +// * serverless/event_workflows/serverless-using-brokers.adoc + +[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. + +[IMPORTANT] +==== +If you create a broker by using the `eventing.knative.dev/injection: enabled` annotation, you cannot delete this broker without cluster administrator permissions. +If you delete the broker without having a cluster administrator remove this annotation first, the broker is created again after deletion. +==== + +.Prerequisites +* The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. + +.Procedure +. Create a `Trigger` object as a `.yaml` file that has the `eventing.knative.dev/injection: enabled` annotation: ++ +[source,yaml] +---- +apiVersion: eventing.knative.dev/v1 +kind: Trigger +metadata: + annotations: + eventing.knative.dev/injection: enabled + name: +spec: + broker: default + subscriber: <1> + ref: + apiVersion: serving.knative.dev/v1 + kind: Service + name: +---- ++ +<1> Specify details about the event sink, or _subscriber_, that the trigger sends events to. +. Apply the `.yaml` file: ++ +[source,terminal] +---- +$ oc apply -f +---- + +.Verification steps + +You can verify that the broker has been created successfully by using the `oc` CLI, or by observing it in the *Topology* view in the web console. + +. Use the `oc` command to get the broker: ++ +[source,terminal] +---- +$ oc -n get broker default +---- ++ +.Example output +[source,terminal] +---- +NAME READY REASON URL AGE +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: ++ +image::odc-view-broker.png[View the broker in the web console Topology view] diff --git a/modules/serverless-creating-broker.adoc b/modules/serverless-creating-broker.adoc deleted file mode 100644 index ce6a7be1bf..0000000000 --- a/modules/serverless-creating-broker.adoc +++ /dev/null @@ -1,149 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_workflows/serverless-using-brokers.adoc - -[id="serverless-creating-broker_{context}"] -= Creating a broker as a developer - -.Procedure - -. If you do not have an existing event sink created to consume events from the broker, create a simple Knative Service to use as an event sink. -.. Save the following YAML in a `.yaml` file: -+ - -[source,yaml] ----- -apiVersion: serving.knative.dev/v1 -kind: Service -metadata: - name: event-display - namespace: default -spec: - template: - spec: - containers: - - image: quay.io/openshift-knative/knative-eventing-sources-event-display ----- - -.. Create the Service by applying the file: -+ - -[source,terminal] ----- -$ oc apply -f ----- - -. If you do not have an existing event source, create an event source that emits events to the `default` broker. The following example shows how you can create a basic PingSource. -.. Save the following YAML in a `.yaml` file: -+ - -[source,yaml] ----- -apiVersion: sources.knative.dev/v1alpha2 -kind: PingSource -metadata: - name: ping-source -spec: - schedule: "*/1 * * * *" - jsonData: '{"message": "Hello serverless!"}' - sink: - ref: - apiVersion: eventing.knative.dev/v1beta1 - kind: Broker - name: default ----- - -+ -.. Create the event source by applying the file: -+ - -[source,terminal] ----- -$ oc apply -f ----- - -. Create the broker by creating a Trigger object that uses the `knative-eventing-injection: enabled` annotation. -+ -[IMPORTANT] -==== -If you create a broker that uses the `knative-eventing-injection: enabled` annotation, you cannot delete this broker without cluster administrator permissions. -If you delete the broker without having a cluster administrator remove this annotation first, the broker will be created again after deletion. -==== - -.. Save the following YAML in a `.yaml` file: -+ - -[source,yaml] ----- -apiVersion: eventing.knative.dev/v1beta1 -kind: Trigger -metadata: - annotations: - knative-eventing-injection: enabled - name: example-trigger -spec: - broker: default - subscriber: <1> - ref: - apiVersion: serving.knative.dev/v1 - kind: Service - name: event-display <1> ----- - -+ -<1> Specify the name of the event sink to use with the broker. - -+ -.. Create the broker by applying the file: -+ - -[source,terminal] ----- -$ oc apply -f ----- - -.Verification steps - -You can verify that events were sent to the event sink by looking at the sink Pod's logs. - -By default, Knative Services terminate their pods if no traffic is received within a 60 second period. -The example shown in this procedure creates a PingSource that sends a message every 2 minutes, so each message should be observed in a newly created pod. - -. Watch for a new Pod: -+ - -[source,terminal] ----- -$ watch oc get pods ----- - -. Cancel watching the pods by pressing Ctrl+C. -. Review the logs of the new Pod: -+ - -[source,terminal] ----- -$ oc logs $(oc get pod -o name | grep event-display) -c user-container ----- - -+ -The logs should contain lines similar to the following: -+ - -.Example output -[source,terminal] ----- -☁️ cloudevents.Event -Validation: valid -Context Attributes, - specversion: 1.0 - type: dev.knative.sources.ping - source: /apis/v1/namespaces/default/pingsources/test-ping-source - id: 042ff529-240e-45ee-b40c-3a908129853e - time: 2020-04-07T16:22:00.000791674Z - datacontenttype: application/json -Data, - { - "message": "Hello serverless!" - } ----- diff --git a/modules/serverless-delete-trigger-odc.adoc b/modules/serverless-delete-trigger-odc.adoc new file mode 100644 index 0000000000..ab396c8be3 --- /dev/null +++ b/modules/serverless-delete-trigger-odc.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * /serverless/event_workflows/serverless-using-brokers.adoc + +[id="serverless-delete-trigger-odc_{context}"] += Deleting a trigger using the Developer perspective + +You can delete triggers in the web console *Developer* perspective. + +.Prerequisites +* To delete a trigger using the *Developer* perspective, ensure that you have logged in to the web console. + +.Procedure + +. In the *Developer* perspective, navigate to the *Topology* page. +. Click on the trigger that you want to delete. +. In the *Actions* context menu, select *Delete Trigger*. ++ +image::delete-trigger-odc.png[Delete a trigger] diff --git a/modules/serverless-deleting-broker-admin.adoc b/modules/serverless-deleting-broker-admin.adoc index 3a706768a3..ada2d116ee 100644 --- a/modules/serverless-deleting-broker-admin.adoc +++ b/modules/serverless-deleting-broker-admin.adoc @@ -3,26 +3,47 @@ // * serverless/event_workflows/serverless-using-brokers.adoc [id="serverless-deleting-broker-admin_{context}"] -= Deleting a broker that was created by a cluster administrator using namespace annotation += Deleting a broker that was created by injection -Brokers created due to annotation will not be removed if you remove the annotation. You must manually delete them. +Brokers created by injection, by using a namespace label or trigger annotation, are not deleted permanently if a developer removes the label or annotation. +A user with cluster administrator permissions must manually delete these brokers. .Procedure -. Remove the injection annotation from the namespace: +. Remove the `eventing.knative.dev/injection=enabled` label from the namespace: + - [source,terminal] ---- $ oc label namespace eventing.knative.dev/injection- ---- + -Removing the annotation prevents the broker from being automatically recreated after you delete it. +Removing the annotation prevents Knative from recreating the broker after you delete it. -. Delete the injected broker from the selected namespace: +. Delete the broker from the selected namespace: + - [source,terminal] ---- $ oc -n delete broker ---- + +.Verification steps + +* Use the `oc` command to get the broker: ++ +[source,terminal] +---- +$ oc -n get broker +---- ++ +.Example command +[source,terminal] +---- +$ oc -n default get broker default +---- ++ +.Example output +[source,terminal] +---- +No resources found. +Error from server (NotFound): brokers.eventing.knative.dev "default" not found +---- diff --git a/modules/serverless-describe-broker-kn.adoc b/modules/serverless-describe-broker-kn.adoc new file mode 100644 index 0000000000..8df6cd4198 --- /dev/null +++ b/modules/serverless-describe-broker-kn.adoc @@ -0,0 +1,44 @@ +// Module included in the following assemblies: +// +// * serverless/event_workflows/serverless-using-brokers.adoc + +[id="serverless-describe-broker-kn_{context}"] += Describing an existing broker using the Knative CLI + +.Prerequisites +* The {ServerlessOperatorName}, Knative Serving and Knative Eventing are installed on your {product-title} cluster. +* You have installed the `kn` CLI. + +.Procedure +* Describe an existing broker: ++ +[source,terminal] +---- +$ kn broker describe +---- ++ +.Example command using default broker +[source,terminal] +---- +$ kn broker describe default +---- ++ +.Example output +[source,terminal] +---- +Name: default +Namespace: default +Annotations: eventing.knative.dev/broker.class=MTChannelBasedBroker, eventing.knative.dev/creato ... +Age: 22s + +Address: + URL: http://broker-ingress.knative-eventing.svc.cluster.local/default/default + +Conditions: + OK TYPE AGE REASON + ++ Ready 22s + ++ Addressable 22s + ++ FilterReady 22s + ++ IngressReady 22s + ++ TriggerChannelReady 22s +---- diff --git a/modules/serverless-list-broker-kn.adoc b/modules/serverless-list-broker-kn.adoc new file mode 100644 index 0000000000..614a5c56d2 --- /dev/null +++ b/modules/serverless-list-broker-kn.adoc @@ -0,0 +1,25 @@ +// Module included in the following assemblies: +// +// * serverless/event_workflows/serverless-using-brokers.adoc + +[id="serverless-list-broker-kn_{context}"] += Listing existing brokers using the Knative CLI + +.Prerequisites +* The {ServerlessOperatorName}, Knative Serving and Knative Eventing are installed on your {product-title} cluster. +* You have installed the `kn` CLI. + +.Procedure +* List all existing brokers: ++ +[source,terminal] +---- +$ kn broker list +---- ++ +.Example output +[source,terminal] +---- +NAME URL AGE CONDITIONS READY REASON +default http://broker-ingress.knative-eventing.svc.cluster.local/test/default 45s 5 OK / 5 True +---- diff --git a/modules/serverless-rn-1-10-0.adoc b/modules/serverless-rn-1-10-0.adoc index 88ef90ef00..298db13a63 100644 --- a/modules/serverless-rn-1-10-0.adoc +++ b/modules/serverless-rn-1-10-0.adoc @@ -12,7 +12,7 @@ * {ServerlessProductName} uses Knative Eventing 0.16.0. * {ServerlessProductName} now uses Kourier 0.16.0. * {ServerlessProductName} now uses Knative `kn` CLI 0.16.1. -* The annotation `knative-eventing-injection=enabled` that was previously used to annotate namespaces for broker creation is now deprecated. The new annotation is `eventing.knative.dev/injection=enabled`. For more information, see the documentation on _Creating a broker as a cluster administrator using namespace annotation_. +* The annotation `knative-eventing-injection=enabled` that was previously used to label namespaces for broker creation is now deprecated. The new annotation is `eventing.knative.dev/injection=enabled`. For more information, see the documentation on _Brokers and triggers_. * Multi-container support is now available on Knative as a Technology Preview feature. You can enable multi-container support in the `config-features` config map. For more information, see the https://knative.dev/docs/serving/feature-flags/#multi-containers[Knative documentation]. [id="fixed-issues-1-10-0_{context}"] diff --git a/serverless/event_sources/knative-event-sources.adoc b/serverless/event_sources/knative-event-sources.adoc index a9eb9117ab..ccd488ac9f 100644 --- a/serverless/event_sources/knative-event-sources.adoc +++ b/serverless/event_sources/knative-event-sources.adoc @@ -5,29 +5,23 @@ include::modules/common-attributes.adoc[] :context: knative-event-sources toc::[] -An _event source_ is an object that links an event producer with an event _sink_, or consumer. A sink can be a Knative Service, Channel, or Broker that receives events from an event source. +An _event source_ is an object that links an event producer with an event _sink_, or consumer. A sink can be a Knative service, channel, or broker that receives events from an event source. + +[id="knative-event-sources-creating"] +== Creating event sources Currently, {ServerlessProductName} supports the following event source types: ApiServerSource:: Connects a sink to the Kubernetes API server. PingSource:: Periodically sends ping events with a constant payload. It can be used as a timer. - -xref:../../serverless/event_workflows/serverless-sinkbinding.adoc#serverless-sinkbinding[SinkBinding] is also supported, which allows you to connect core Kubernetes resources such as Deployment, Job, or StatefulSet with a sink. +SinkBinding:: Allows you to connect core Kubernetes resource objects such as a `Deployment`, `Job`, or `StatefulSet` with a sink. You can create and manage Knative event sources using the **Developer** perspective in the {product-title} web console, the `kn` CLI, or by applying YAML files. -== Prerequisites - -* You must have a current installation of xref:../../serverless/installing_serverless/installing-openshift-serverless.adoc#serverless-install-web-console_installing-openshift-serverless[{ServerlessProductName}], including Knative Serving and Eventing, in your {product-title} cluster. This can be installed by a cluster administrator. -* Event sources need a service to use as an event _sink_. The sink is the service or application that events are sent to from the event source. -// TODO: Create a better section about adding serverless apps/Knative services, group kn + dev console etc as I am doing now for event sources. This content should be reusable in Serverless and Dev Console docs. - -[id="knative-event-sources-creating"] -== Creating event sources - * Create an xref:../../serverless/event_sources/serverless-apiserversource.adoc#serverless-apiserversource[ApiServerSource]. * Create an xref:../../serverless/event_sources/serverless-pingsource.adoc#serverless-pingsource[PingSource]. -// add others +* Create a xref:../../serverless/event_workflows/serverless-sinkbinding.adoc#serverless-sinkbinding[SinkBinding]. +// Add Kafka once docs available [id="knative-event-sources-additional-resources"] == Additional resources diff --git a/serverless/event_workflows/serverless-using-brokers.adoc b/serverless/event_workflows/serverless-using-brokers.adoc index 173b9f415c..184daa6bba 100644 --- a/serverless/event_workflows/serverless-using-brokers.adoc +++ b/serverless/event_workflows/serverless-using-brokers.adoc @@ -6,48 +6,43 @@ include::modules/serverless-document-attributes.adoc[] toc::[] -Events are sent from an event source to your broker as an HTTP POST request. -After events have entered the broker they can be filtered by event attributes, and sent as an HTTP POST request to an event sink by using triggers. +Brokers can be used in combination with xref:../../serverless/event_workflows/serverless-using-brokers.adoc#serverless-using-brokers-triggers[triggers] to deliver events from an xref:../../serverless/event_sources/knative-event-sources.adoc#knative-event-sources[event source] to an event sink. -image::serverless-event-broker-workflow.png[Broker workflow overview] +image::serverless-event-broker-workflow.png[Broker event delivery overview] -Developers can create the `default` broker by using the `knative-eventing-injection` annotation. +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. + +[id="serverless-using-brokers-creating-brokers"] +== Creating a broker + +{ServerlessProductName} provides a `default` Knative broker that can be created by using the Knative CLI. +You can also create the `default` broker by adding the `eventing.knative.dev/injection=enabled` label to a namespace if you are a cluster administrator, or by adding the `eventing.knative.dev/injection: enabled` annotation to a trigger if you are a developer. [IMPORTANT] ==== -Although both developers and cluster administrators can add the `knative-eventing-injection` annotation, only cluster administrators can remove brokers created using this annotation. +Although both developers and cluster administrators can add a broker by injection, only cluster administrators can permanently delete brokers that were created using this method. ==== -include::modules/serverless-creating-broker.adoc[leveloffset=+1] -include::modules/serverless-creating-broker-admin.adoc[leveloffset=+1] +include::modules/serverless-create-broker-kn.adoc[leveloffset=+2] +include::modules/serverless-creating-broker-annotation.adoc[leveloffset=+2] +include::modules/serverless-creating-broker-admin.adoc[leveloffset=+2] + +[id="serverless-using-brokers-managing-brokers"] +== Managing brokers + +The `kn` CLI provides commands that can be used to list, describe, update, and delete brokers. +Cluster administrators can also permanently delete a broker that was created using injection. + +include::modules/serverless-list-broker-kn.adoc[leveloffset=+2] +include::modules/serverless-describe-broker-kn.adoc[leveloffset=+2] include::modules/serverless-deleting-broker-admin.adoc[leveloffset=+2] [id="serverless-using-brokers-triggers"] -== Using triggers +== Filtering events using triggers -You can create triggers using YAML, as shown in the following example: - -.Example trigger YAML -[source,yaml] ----- -apiVersion: eventing.knative.dev/v1alpha1 -kind: Trigger -metadata: - name: trigger-example <1> -spec: - broker: default <2> - subscriber: - ref: - apiVersion: serving.knative.dev/v1 - kind: Service - name: my-service <3> ----- - -<1> The name of the trigger. -<2> The name of the broker where events will be filtered from. If the broker is not specified, the trigger will revert to using the `default` broker. -<3> The name of the service that will consumer filtered events. - -However, the Knative CLI (`kn`) provides the following commands to simplify creating and managing triggers. +Using triggers enables you to filter events from the broker for delivery to event sinks. .Prerequisites @@ -59,6 +54,11 @@ Before you can use triggers, you will need: You can create the `default` broker either by following the instructions on xref:../serverless-using-brokers.adoc#serverless-using-brokers[Using brokers with Knative Eventing], or by using the `--inject-broker` flag while creating a trigger. Use of this flag is described later in this section. * An available event consumer, such as a Knative service. +// ODC +include::modules/serverless-create-trigger-odc.adoc[leveloffset=+2] +include::modules/serverless-delete-trigger-odc.adoc[leveloffset=+2] + +// kn trigger include::modules/serverless-create-kn-trigger.adoc[leveloffset=+2] include::modules/kn-trigger-list.adoc[leveloffset=+2] include::modules/kn-trigger-describe.adoc[leveloffset=+2]