Chapter 5. Eventing

Procedure

1. In the Administrator perspective of the OpenShift Container Platform web console, navigate to Serverless Eventing.
2. In the Create list, select Event Source. You will be directed to the Event Sources page.
3. Select the event source type that you want to create.

1. Create a service account, role, and role binding for the event source as a YAML file:

   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: events-sa
     namespace: default 1
   
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: Role
   metadata:
     name: event-watcher
     namespace: default 2
   rules:
     - apiGroups:
         - ""
       resources:
         - events
       verbs:
         - get
         - list
         - watch
   
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: RoleBinding
   metadata:
     name: k8s-ra-event-watcher
     namespace: default 3
   roleRef:
     apiGroup: rbac.authorization.k8s.io
     kind: Role
     name: event-watcher
   subjects:
     - kind: ServiceAccount
       name: events-sa
       namespace: default 4

   1 2 3 4

   Change this namespace to the namespace that you have selected for installing the event source.

2. Apply the YAML file:

   $ oc apply -f <filename>

3. In the Developer perspective, navigate to +Add Event Source. The Event Sources page is displayed.
4. Optional: If you have multiple providers for your event sources, select the required provider from the Providers list to filter the available event sources from the provider.
5. Select ApiServerSource and then click Create Event Source. The Create Event Source page is displayed.

6. Configure the ApiServerSource settings by using the Form view or YAML view:

   Note

   You can switch between the Form view and YAML view. The data is persisted when switching between the views.

   1. Enter v1 as the APIVERSION and Event as the KIND.
   2. Select the Service Account Name for the service account that you created.
   3. Select the Sink for the event source. A Sink can be either a Resource, such as a channel, broker, or service, or a URI.
7. Click Create.

Deleting the API server source

1. Navigate to the Topology view.

2. Right-click the API server source and select Delete ApiServerSource.

   

1. Create a service account, role, and role binding for the event source as a YAML file:

   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: events-sa
     namespace: default 1
   
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: Role
   metadata:
     name: event-watcher
     namespace: default 2
   rules:
     - apiGroups:
         - ""
       resources:
         - events
       verbs:
         - get
         - list
         - watch
   
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: RoleBinding
   metadata:
     name: k8s-ra-event-watcher
     namespace: default 3
   roleRef:
     apiGroup: rbac.authorization.k8s.io
     kind: Role
     name: event-watcher
   subjects:
     - kind: ServiceAccount
       name: events-sa
       namespace: default 4

   1 2 3 4

   Change this namespace to the namespace that you have selected for installing the event source.

2. Apply the YAML file:

   $ oc apply -f <filename>

3. Create an API server source that has an event sink. In the following example, the sink is a broker:

   $ kn source apiserver create <event_source_name> --sink broker:<broker_name> --resource "event:v1" --service-account <service_account_name> --mode Resource

4. To check that the API server source is set up correctly, create a Knative service that dumps incoming messages to its log:

   $ kn service create <service_name> --image quay.io/openshift-knative/knative-eventing-sources-event-display:latest

5. If you used a broker as an event sink, create a trigger to filter events from the default broker to the service:

   $ kn trigger create <trigger_name> --sink ksvc:<service_name>

6. Create events by launching a pod in the default namespace:

   $ oc create deployment hello-node --image quay.io/openshift-knative/knative-eventing-sources-event-display:latest

7. Check that the controller is mapped correctly by inspecting the output generated by the following command:

   $ kn source apiserver describe <source_name>

   Example output

   Name:                mysource
   Namespace:           default
   Annotations:         sources.knative.dev/creator=developer, sources.knative.dev/lastModifier=developer
   Age:                 3m
   ServiceAccountName:  events-sa
   Mode:                Resource
   Sink:
     Name:       default
     Namespace:  default
     Kind:       Broker (eventing.knative.dev/v1)
   Resources:
     Kind:        event (v1)
     Controller:  false
   Conditions:
     OK TYPE                     AGE REASON
     ++ Ready                     3m
     ++ Deployed                  3m
     ++ SinkProvided              3m
     ++ SufficientPermissions     3m
     ++ EventTypesProvided        3m

1. Get the pods:

   $ oc get pods

2. View the message dumper function logs for the pods:

   $ oc logs $(oc get pod -o name | grep event-display) -c user-container

   Example output

   ☁️  cloudevents.Event
   Validation: valid
   Context Attributes,
     specversion: 1.0
     type: dev.knative.apiserver.resource.update
     datacontenttype: application/json
     ...
   Data,
     {
       "apiVersion": "v1",
       "involvedObject": {
         "apiVersion": "v1",
         "fieldPath": "spec.containers{hello-node}",
         "kind": "Pod",
         "name": "hello-node",
         "namespace": "default",
          .....
       },
       "kind": "Event",
       "message": "Started container",
       "metadata": {
         "name": "hello-node.159d7608e3a3572c",
         "namespace": "default",
         ....
       },
       "reason": "Started",
       ...
     }

Deleting the API server source

1. Delete the trigger:

   $ kn trigger delete <trigger_name>

2. Delete the event source:

   $ kn source apiserver delete <source_name>

3. Delete the service account, cluster role, and cluster binding:

   $ oc delete -f authentication.yaml

1. Create a service account, role, and role binding for the event source as a YAML file:

   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: events-sa
     namespace: default 1
   
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: Role
   metadata:
     name: event-watcher
     namespace: default 2
   rules:
     - apiGroups:
         - ""
       resources:
         - events
       verbs:
         - get
         - list
         - watch
   
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: RoleBinding
   metadata:
     name: k8s-ra-event-watcher
     namespace: default 3
   roleRef:
     apiGroup: rbac.authorization.k8s.io
     kind: Role
     name: event-watcher
   subjects:
     - kind: ServiceAccount
       name: events-sa
       namespace: default 4

   1 2 3 4

   Change this namespace to the namespace that you have selected for installing the event source.

2. Apply the YAML file:

   $ oc apply -f <filename>

3. Create an API server source as a YAML file:

   apiVersion: sources.knative.dev/v1alpha1
   kind: ApiServerSource
   metadata:
     name: testevents
   spec:
     serviceAccountName: events-sa
     mode: Resource
     resources:
       - apiVersion: v1
         kind: Event
     sink:
       ref:
         apiVersion: eventing.knative.dev/v1
         kind: Broker
         name: default

4. Apply the ApiServerSource YAML file:

   $ oc apply -f <filename>

5. To check that the API server source is set up correctly, create a Knative service as a YAML file that dumps incoming messages to its log:

   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:latest

6. Apply the Service YAML file:

   $ oc apply -f <filename>

7. Create a Trigger object as a YAML file that filters events from the default broker to the service created in the previous step:

   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

8. Apply the Trigger YAML file:

   $ oc apply -f <filename>

9. Create events by launching a pod in the default namespace:

   $ oc create deployment hello-node --image=quay.io/openshift-knative/knative-eventing-sources-event-display

10. Check that the controller is mapped correctly, by entering the following command and inspecting the output:

    $ oc get apiserversource.sources.knative.dev testevents -o yaml

    Example output

    apiVersion: sources.knative.dev/v1alpha1
    kind: ApiServerSource
    metadata:
      annotations:
      creationTimestamp: "2020-04-07T17:24:54Z"
      generation: 1
      name: testevents
      namespace: default
      resourceVersion: "62868"
      selfLink: /apis/sources.knative.dev/v1alpha1/namespaces/default/apiserversources/testevents2
      uid: 1603d863-bb06-4d1c-b371-f580b4db99fa
    spec:
      mode: Resource
      resources:
      - apiVersion: v1
        controller: false
        controllerSelector:
          apiVersion: ""
          kind: ""
          name: ""
          uid: ""
        kind: Event
        labelSelector: {}
      serviceAccountName: events-sa
      sink:
        ref:
          apiVersion: eventing.knative.dev/v1
          kind: Broker
          name: default

1. Get the pods by entering the following command:

   $ oc get pods

2. View the message dumper function logs for the pods by entering the following command:

   $ oc logs $(oc get pod -o name | grep event-display) -c user-container

   Example output

   ☁️  cloudevents.Event
   Validation: valid
   Context Attributes,
     specversion: 1.0
     type: dev.knative.apiserver.resource.update
     datacontenttype: application/json
     ...
   Data,
     {
       "apiVersion": "v1",
       "involvedObject": {
         "apiVersion": "v1",
         "fieldPath": "spec.containers{hello-node}",
         "kind": "Pod",
         "name": "hello-node",
         "namespace": "default",
          .....
       },
       "kind": "Event",
       "message": "Started container",
       "metadata": {
         "name": "hello-node.159d7608e3a3572c",
         "namespace": "default",
         ....
       },
       "reason": "Started",
       ...
     }

Deleting the API server source

1. Delete the trigger:

   $ oc delete -f trigger.yaml

2. Delete the event source:

   $ oc delete -f k8s-events.yaml

3. Delete the service account, cluster role, and cluster binding:

   $ oc delete -f authentication.yaml

Procedure

1. To verify that the ping source is working, create a simple Knative service that dumps incoming messages to the logs of the service.

   1. In the Developer perspective, navigate to +Add YAML.

   2. Copy the example YAML:

      apiVersion: serving.knative.dev/v1
      kind: Service
      metadata:
        name: event-display
      spec:
        template:
          spec:
            containers:
              - image: quay.io/openshift-knative/knative-eventing-sources-event-display:latest

   3. Click Create.

2. Create a ping source in the same namespace as the service created in the previous step, or any other sink that you want to send events to.

   1. In the Developer perspective, navigate to +Add Event Source. The Event Sources page is displayed.
   2. Optional: If you have multiple providers for your event sources, select the required provider from the Providers list to filter the available event sources from the provider.

   3. Select Ping Source and then click Create Event Source. The Create Event Source page is displayed.

      Note

      You can configure the PingSource settings by using the Form view or YAML view and can switch between the views. The data is persisted when switching between the views.

   4. Enter a value for Schedule. In this example, the value is */2 * * * *, which creates a PingSource that sends a message every two minutes.
   5. Optional: You can enter a value for Data, which is the message payload.
   6. Select a Sink. This can be either a Resource or a URI. In this example, the event-display service created in the previous step is used as the Resource sink.
   7. Click Create.

1. In the Developer perspective, navigate to Topology.

2. View the ping source and sink.

   

Deleting the ping source

1. Navigate to the Topology view.
2. Right-click the API server source and select Delete Ping Source.

Procedure

1. To verify that the ping source is working, create a simple Knative service that dumps incoming messages to the service logs:

   $ kn service create event-display \
       --image quay.io/openshift-knative/knative-eventing-sources-event-display:latest

2. For each set of ping events that you want to request, create a ping source in the same namespace as the event consumer:

   $ kn source ping create test-ping-source \
       --schedule "*/2 * * * *" \
       --data '{"message": "Hello world!"}' \
       --sink ksvc:event-display

3. Check that the controller is mapped correctly by entering the following command and inspecting the output:

   $ kn source ping describe test-ping-source

   Example output

   Name:         test-ping-source
   Namespace:    default
   Annotations:  sources.knative.dev/creator=developer, sources.knative.dev/lastModifier=developer
   Age:          15s
   Schedule:     */2 * * * *
   Data:         {"message": "Hello world!"}
   
   Sink:
     Name:       event-display
     Namespace:  default
     Resource:   Service (serving.knative.dev/v1)
   
   Conditions:
     OK TYPE                 AGE REASON
     ++ Ready                 8s
     ++ Deployed              8s
     ++ SinkProvided         15s
     ++ ValidSchedule        15s
     ++ EventTypeProvided    15s
     ++ ResourcesCorrect     15s

1. Watch for new pods created:

   $ watch oc get pods

2. Cancel watching the pods using Ctrl+C, then look at the logs of the created pod:

   $ oc logs $(oc get pod -o name | grep event-display) -c user-container

   Example output

   ☁️  cloudevents.Event
   Validation: valid
   Context Attributes,
     specversion: 1.0
     type: dev.knative.sources.ping
     source: /apis/v1/namespaces/default/pingsources/test-ping-source
     id: 99e4f4f6-08ff-4bff-acf1-47f61ded68c9
     time: 2020-04-07T16:16:00.000601161Z
     datacontenttype: application/json
   Data,
     {
       "message": "Hello world!"
     }

Procedure

1. To verify that the ping source is working, create a simple Knative service that dumps incoming messages to the service’s logs.

   1. Create a service YAML file:

      apiVersion: serving.knative.dev/v1
      kind: Service
      metadata:
        name: event-display
      spec:
        template:
          spec:
            containers:
              - image: quay.io/openshift-knative/knative-eventing-sources-event-display:latest

   2. Create the service:

      $ oc apply -f <filename>

2. For each set of ping events that you want to request, create a ping source in the same namespace as the event consumer.

   1. Create a YAML file for the ping source:

      apiVersion: sources.knative.dev/v1
      kind: PingSource
      metadata:
        name: test-ping-source
      spec:
        schedule: "*/2 * * * *"
        data: '{"message": "Hello world!"}'
        sink:
          ref:
            apiVersion: serving.knative.dev/v1
            kind: Service
            name: event-display

   2. Create the ping source:

      $ oc apply -f <filename>

3. Check that the controller is mapped correctly by entering the following command:

   $ oc get pingsource.sources.knative.dev <ping_source_name> -oyaml

   Example output

   apiVersion: sources.knative.dev/v1
   kind: PingSource
   metadata:
     annotations:
       sources.knative.dev/creator: developer
       sources.knative.dev/lastModifier: developer
     creationTimestamp: "2020-04-07T16:11:14Z"
     generation: 1
     name: test-ping-source
     namespace: default
     resourceVersion: "55257"
     selfLink: /apis/sources.knative.dev/v1/namespaces/default/pingsources/test-ping-source
     uid: 3d80d50b-f8c7-4c1b-99f7-3ec00e0a8164
   spec:
     data: '{ value: "hello" }'
     schedule: '*/2 * * * *'
     sink:
       ref:
         apiVersion: serving.knative.dev/v1
         kind: Service
         name: event-display
         namespace: default

1. Watch for new pods created:

   $ watch oc get pods

2. Cancel watching the pods using Ctrl+C, then look at the logs of the created pod:

   $ oc logs $(oc get pod -o name | grep event-display) -c user-container

   Example output

   ☁️  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 world!"
     }

Procedure

1. In the Developer perspective, navigate to the +Add page and select Event Source.
2. In the Event Sources page, select Kafka Source in the Type section.

3. Configure the Kafka Source settings:

   1. Add a comma-separated list of Bootstrap Servers.
   2. Add a comma-separated list of Topics.
   3. Add a Consumer Group.
   4. Select the Service Account Name for the service account that you created.
   5. Select the Sink for the event source. A Sink can be either a Resource, such as a channel, broker, or service, or a URI.
   6. Enter a Name for the Kafka event source.
4. Click Create.

1. In the Developer perspective, navigate to Topology.

2. View the Kafka event source and sink.

   

Procedure

1. To verify that the Kafka event source is working, create a Knative service that dumps incoming events into the service logs:

   $ kn service create event-display \
       --image quay.io/openshift-knative/knative-eventing-sources-event-display

2. Create a KafkaSource CR:

   $ kn source kafka create <kafka_source_name> \
       --servers <cluster_kafka_bootstrap>.kafka.svc:9092 \
       --topics <topic_name> --consumergroup my-consumer-group \
       --sink event-display

   Note

   Replace the placeholder values in this command with values for your source name, bootstrap servers, and topics.

   The --servers, --topics, and --consumergroup options specify the connection parameters to the Kafka cluster. The --consumergroup option is optional.

3. Optional: View details about the KafkaSource CR you created:

   $ kn source kafka describe <kafka_source_name>

   Example output

   Name:              example-kafka-source
   Namespace:         kafka
   Age:               1h
   BootstrapServers:  example-cluster-kafka-bootstrap.kafka.svc:9092
   Topics:            example-topic
   ConsumerGroup:     example-consumer-group
   
   Sink:
     Name:       event-display
     Namespace:  default
     Resource:   Service (serving.knative.dev/v1)
   
   Conditions:
     OK TYPE            AGE REASON
     ++ Ready            1h
     ++ Deployed         1h
     ++ SinkProvided     1h

Verification steps

1. Trigger the Kafka instance to send a message to the topic:

   $ oc -n kafka run kafka-producer \
       -ti --image=quay.io/strimzi/kafka:latest-kafka-2.7.0 --rm=true \
       --restart=Never -- bin/kafka-console-producer.sh \
       --broker-list <cluster_kafka_bootstrap>:9092 --topic my-topic

   Enter the message in the prompt. This command assumes that:

   • The Kafka cluster is installed in the kafka namespace.
   • The KafkaSource object has been configured to use the my-topic topic.

2. Verify that the message arrived by viewing the logs:

   $ oc logs $(oc get pod -o name | grep event-display) -c user-container

   Example output

   ☁️  cloudevents.Event
   Validation: valid
   Context Attributes,
     specversion: 1.0
     type: dev.knative.kafka.event
     source: /apis/v1/namespaces/default/kafkasources/example-kafka-source#example-topic
     subject: partition:46#0
     id: partition:46/offset:0
     time: 2021-03-10T11:21:49.4Z
   Extensions,
     traceparent: 00-161ff3815727d8755848ec01c866d1cd-7ff3916c44334678-00
   Data,
     Hello!

Procedure

1. Create a KafkaSource object as a YAML file:

   apiVersion: sources.knative.dev/v1beta1
   kind: KafkaSource
   metadata:
     name: <source_name>
   spec:
     consumerGroup: <group_name> 1
     bootstrapServers:
     - <list_of_bootstrap_servers>
     topics:
     - <list_of_topics> 2
     sink:
     - <list_of_sinks> 3

   1

   A consumer group is a group of consumers that use the same group ID, and consume data from a topic.

   2

   A topic provides a destination for the storage of data. Each topic is split into one or more partitions.

   3

   A sink specifies where events are sent to from a source.

   Important

   Only the v1beta1 version of the API for KafkaSource objects on OpenShift Serverless is supported. Do not use the v1alpha1 version of this API, as this version is now deprecated.

   Example KafkaSource object

   apiVersion: sources.knative.dev/v1beta1
   kind: KafkaSource
   metadata:
     name: kafka-source
   spec:
     consumerGroup: knative-group
     bootstrapServers:
     - my-cluster-kafka-bootstrap.kafka:9092
     topics:
     - knative-demo-topic
     sink:
       ref:
         apiVersion: serving.knative.dev/v1
         kind: Service
         name: event-display

2. Apply the KafkaSource YAML file:

   $ oc apply -f <filename>

Procedure

1. Create the certificate files as secrets in your chosen namespace:

   $ oc create secret -n <namespace> generic <kafka_auth_secret> \
     --from-file=ca.crt=caroot.pem \
     --from-literal=password="SecretPassword" \
     --from-literal=saslType="SCRAM-SHA-512" \ 1
     --from-literal=user="my-sasl-user"

   1

   The SASL type can be PLAIN, SCRAM-SHA-256, or SCRAM-SHA-512.

2. Create or modify your Kafka source so that it contains the following spec configuration:

   apiVersion: sources.knative.dev/v1beta1
   kind: KafkaSource
   metadata:
     name: example-source
   spec:
   ...
     net:
       sasl:
         enable: true
         user:
           secretKeyRef:
             name: <kafka_auth_secret>
             key: user
         password:
           secretKeyRef:
             name: <kafka_auth_secret>
             key: password
         type:
           secretKeyRef:
             name: <kafka_auth_secret>
             key: saslType
       tls:
         enable: true
         caCert: 1
           secretKeyRef:
             name: <kafka_auth_secret>
             key: ca.crt
   ...

   1

   The caCert spec is not required if you are using a public cloud Kafka service, such as Red Hat OpenShift Streams for Apache Kafka.

Procedure

1. Create an event source of any type, by navigating to +Add Event Source and selecting the event source type that you want to create.
2. In the Sink section of the Create Event Source form view, select your sink in the Resource list.
3. Click Create.

1. In the Developer perspective, navigate to Topology.
2. View the event source and click the connected sink to see the sink details in the right panel.

Procedure

1. Create a KafkaSink object definition as a YAML file:

   Kafka sink YAML

   apiVersion: eventing.knative.dev/v1alpha1
   kind: KafkaSink
   metadata:
     name: <sink-name>
     namespace: <namespace>
   spec:
     topic: <topic-name>
     bootstrapServers:
      - <bootstrap-server>

2. To create the Kafka sink, apply the KafkaSink YAML file:

   $ oc apply -f <filename>

3. Configure an event source so that the sink is specified in its spec:

   Example of a Kafka sink connected to an API server source

   apiVersion: sources.knative.dev/v1alpha2
   kind: ApiServerSource
   metadata:
     name: <source-name> 1
     namespace: <namespace> 2
   spec:
     serviceAccountName: <service-account-name> 3
     mode: Resource
     resources:
     - apiVersion: v1
       kind: Event
     sink:
       ref:
         apiVersion: eventing.knative.dev/v1alpha1
         kind: KafkaSink
         name: <sink-name> 4

   1

   The name of the event source.

   2

   The namespace of the event source.

   3

   The service account for the event source.

   4

   The Kafka sink name.

Procedure

1. Create the certificate files as a secret in the same namespace as your KafkaSink object:

   Important

   Certificates and keys must be in PEM format.

   • For authentication using SASL without encryption:

     $ oc create secret -n <namespace> generic <secret_name> \
       --from-literal=protocol=SASL_PLAINTEXT \
       --from-literal=sasl.mechanism=<sasl_mechanism> \
       --from-literal=user=<username> \
       --from-literal=password=<password>

   • For authentication using SASL and encryption using TLS:

     $ oc create secret -n <namespace> generic <secret_name> \
       --from-literal=protocol=SASL_SSL \
       --from-literal=sasl.mechanism=<sasl_mechanism> \
       --from-file=ca.crt=<my_caroot.pem_file_path> \ 1
       --from-literal=user=<username> \
       --from-literal=password=<password>

     1

     The ca.crt can be omitted to use the system’s root CA set if you are using a public cloud managed Kafka service, such as Red Hat OpenShift Streams for Apache Kafka.

   • For authentication and encryption using TLS:

     $ oc create secret -n <namespace> generic <secret_name> \
       --from-literal=protocol=SSL \
       --from-file=ca.crt=<my_caroot.pem_file_path> \ 1
       --from-file=user.crt=<my_cert.pem_file_path> \
       --from-file=user.key=<my_key.pem_file_path>

     1

     The ca.crt can be omitted to use the system’s root CA set if you are using a public cloud managed Kafka service, such as Red Hat OpenShift Streams for Apache Kafka.

2. Create or modify a KafkaSink object and add a reference to your secret in the auth spec:

   apiVersion: eventing.knative.dev/v1alpha1
   kind: KafkaSink
   metadata:
      name: <sink_name>
      namespace: <namespace>
   spec:
   ...
      auth:
        secret:
          ref:
            name: <secret_name>
   ...

3. Apply the KafkaSink object:

   $ oc apply -f <filename>

Verification

1. Use the kn command to list all existing brokers:

   $ kn broker list

   Example output

   NAME      URL                                                                     AGE   CONDITIONS   READY   REASON
   default   http://broker-ingress.knative-eventing.svc.cluster.local/test/default   45s   5 OK / 5     True

2. Optional: If you are using the OpenShift Container Platform web console, you can navigate to the Topology view in the Developer perspective, and observe that the broker exists:

   

Procedure

1. Create a Trigger object as a YAML file that has the eventing.knative.dev/injection: enabled annotation:

   apiVersion: eventing.knative.dev/v1
   kind: Trigger
   metadata:
     annotations:
       eventing.knative.dev/injection: enabled
     name: <trigger_name>
   spec:
     broker: default
     subscriber: 1
       ref:
         apiVersion: serving.knative.dev/v1
         kind: Service
         name: <service_name>

   1

   Specify details about the event sink, or subscriber, that the trigger sends events to.

2. Apply the Trigger YAML file:

   $ oc apply -f <filename>

1. Enter the following oc command to get the broker:

   $ oc -n <namespace> get broker default

   Example output

   NAME      READY     REASON    URL                                                                     AGE
   default   True                http://broker-ingress.knative-eventing.svc.cluster.local/test/default   3m56s

2. Optional: If you are using the OpenShift Container Platform web console, you can navigate to the Topology view in the Developer perspective, and observe that the broker exists:

   

1. Use the oc command to get the broker:

   $ oc -n <namespace> get broker <broker_name>

   Example command

   $ oc -n default get broker default

   Example output

   NAME      READY     REASON    URL                                                                     AGE
   default   True                http://broker-ingress.knative-eventing.svc.cluster.local/test/default   3m56s

2. Optional: If you are using the OpenShift Container Platform web console, you can navigate to the Topology view in the Developer perspective, and observe that the broker exists:

   

Procedure

1. Remove the eventing.knative.dev/injection=enabled label from the namespace:

   $ oc label namespace <namespace> eventing.knative.dev/injection-

   Removing the annotation prevents Knative from recreating the broker after you delete it.

2. Delete the broker from the selected namespace:

   $ oc -n <namespace> delete broker <broker_name>

Procedure

1. In the Developer perspective, navigate to +Add Broker. The Broker page is displayed.
2. Optional. Update the Name of the broker. If you do not update the name, the generated broker is named default.
3. Click Create.

1. In the Developer perspective, navigate to Topology.

2. View the mt-broker-ingress, mt-broker-filter, and mt-broker-controller components.

   

Procedure

1. In the Administrator perspective of the OpenShift Container Platform web console, navigate to Serverless Eventing.
2. In the Create list, select Broker. You will be directed to the Create Broker page.
3. Optional: Modify the YAML configuration for the broker.
4. Click Create.

Procedure

1. Modify the kafka-broker-config config map, or create your own config map that contains the following configuration:

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: <config_map_name> 1
     namespace: <namespace> 2
   data:
     default.topic.partitions: <integer> 3
     default.topic.replication.factor: <integer> 4
     bootstrap.servers: <list_of_servers> 5

   1

   The config map name.

   2

   The namespace where the config map exists.

   3

   The number of topic partitions for the Kafka broker. This controls how quickly events can be sent to the broker. A higher number of partitions requires greater compute resources.

   4

   The replication factor of topic messages. This prevents against data loss. A higher replication factor requires greater compute resources and more storage.

   5

   A comma separated list of bootstrap servers. This can be inside or outside of the OpenShift Container Platform cluster, and is a list of Kafka clusters that the broker receives events from and sends events to.

   Important

   The default.topic.replication.factor value must be less than or equal to the number of Kafka broker instances in your cluster. For example, if you only have one Kafka broker, the default.topic.replication.factor value should not be more than "1".

   Example Kafka broker config map

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: kafka-broker-config
     namespace: knative-eventing
   data:
     default.topic.partitions: "10"
     default.topic.replication.factor: "3"
     bootstrap.servers: "my-cluster-kafka-bootstrap.kafka:9092"

2. Apply the config map:

   $ oc apply -f <config_map_filename>

3. Specify the config map for the Kafka Broker object:

   Example Broker object

   apiVersion: eventing.knative.dev/v1
   kind: Broker
   metadata:
     name: <broker_name> 1
     namespace: <namespace> 2
     annotations:
       eventing.knative.dev/broker.class: Kafka 3
   spec:
     config:
       apiVersion: v1
       kind: ConfigMap
       name: <config_map_name> 4
       namespace: <namespace> 5
   ...

   1

   The broker name.

   2

   The namespace where the broker exists.

   3

   The broker class annotation. In this example, the broker is a Kafka broker that uses the class value Kafka.

   4

   The config map name.

   5

   The namespace where the config map exists.

4. Apply the broker:

   $ oc apply -f <broker_filename>

Procedure

1. Create or modify a Trigger object and set the kafka.eventing.knative.dev/delivery.order annotation:

   apiVersion: eventing.knative.dev/v1
   kind: Trigger
   metadata:
     name: <trigger_name>
     annotations:
        kafka.eventing.knative.dev/delivery.order: ordered
   ...

   The supported consumer delivery guarantees are:

   unordered

   An unordered consumer is a non-blocking consumer that delivers messages unordered, while preserving proper offset management.

   ordered

   An ordered consumer is a per-partition blocking consumer that waits for a successful response from the CloudEvent subscriber before it delivers the next message of the partition.

   The default ordering guarantee is unordered.

2. Apply the Trigger object:

   $ oc apply -f <filename>

Procedure

1. Create or modify a Trigger object and set the kafka.eventing.knative.dev/delivery.order annotation:

   apiVersion: eventing.knative.dev/v1
   kind: Trigger
   metadata:
     name: <trigger_name>
     annotations:
        kafka.eventing.knative.dev/delivery.order: ordered
   ...

   The supported consumer delivery guarantees are:

   unordered

   An unordered consumer is a non-blocking consumer that delivers messages unordered, while preserving proper offset management.

   ordered

   An ordered consumer is a per-partition blocking consumer that waits for a successful response from the CloudEvent subscriber before it delivers the next message of the partition.

   The default ordering guarantee is unordered.

2. Apply the Trigger object:

   $ oc apply -f <filename>

Procedure

1. In the Administrator perspective of the OpenShift Container Platform web console, navigate to Serverless Eventing.
2. In the Broker tab, select the Options menu for the broker that you want to add a trigger to.
3. Click Add Trigger in the list.
4. In the Add Trigger dialogue box, select a Subscriber for the trigger. The subscriber is the Knative service that will receive events from the broker.
5. Click Add.

Procedure

1. In the Developer perspective, navigate to the Topology page.
2. Hover over the broker that you want to create a trigger for, and drag the arrow. The Add Trigger option is displayed.
3. Click Add Trigger.
4. Select your sink in the Subscriber list.
5. Click Add.

Deleting a trigger

1. In the Developer perspective, navigate to the Topology page.
2. Click on the trigger that you want to delete.
3. In the Actions context menu, select Delete Trigger.

Procedure

1. Print a list of available triggers:

   $ kn trigger list

   Example output

   NAME    BROKER    SINK           AGE   CONDITIONS   READY   REASON
   email   default   ksvc:edisplay   4s    5 OK / 5     True
   ping    default   ksvc:edisplay   32s   5 OK / 5     True

2. Optional: Print a list of triggers in JSON format:

   $ kn trigger list -o json

Verification

1. List existing triggers:

   $ kn trigger list

2. Verify that the trigger no longer exists:

   Example output

   No triggers found.

Procedure

1. In the Administrator perspective of the OpenShift Container Platform web console, navigate to Serverless Eventing.
2. In the Create list, select Channel. You will be directed to the Channel page.

3. Select the type of Channel object that you want to create in the Type list.

   Note

   Currently only InMemoryChannel channel objects are supported by default. Kafka channels are available if you have installed Knative Kafka on OpenShift Serverless.

4. Click Create.

Procedure

1. In the Developer perspective, navigate to +Add Channel.
2. Select the type of Channel object that you want to create in the Type list.
3. Click Create.

Procedure

1. Create a Channel object as a YAML file:

   apiVersion: messaging.knative.dev/v1
   kind: Channel
   metadata:
     name: example-channel
     namespace: default

2. Apply the YAML file:

   $ oc apply -f <filename>

Procedure

1. Create a KafkaChannel object as a YAML file:

   apiVersion: messaging.knative.dev/v1beta1
   kind: KafkaChannel
   metadata:
     name: example-channel
     namespace: default
   spec:
     numPartitions: 3
     replicationFactor: 1

   Important

   Only the v1beta1 version of the API for KafkaChannel objects on OpenShift Serverless is supported. Do not use the v1alpha1 version of this API, as this version is now deprecated.

2. Apply the KafkaChannel YAML file:

   $ oc apply -f <filename>

Procedure

1. Create the certificate files as secrets in your chosen namespace:

   $ oc create secret -n <namespace> generic <kafka_auth_secret> \
     --from-file=ca.crt=caroot.pem \
     --from-file=user.crt=certificate.pem \
     --from-file=user.key=key.pem

   Important

   Use the key names ca.crt, user.crt, and user.key. Do not change them.

2. Start editing the KnativeKafka custom resource:

   $ oc edit knativekafka

3. Reference your secret and the namespace of the secret:

   apiVersion: operator.serverless.openshift.io/v1alpha1
   kind: KnativeKafka
   metadata:
     namespace: knative-eventing
     name: knative-kafka
   spec:
     channel:
       authSecretName: <kafka_auth_secret>
       authSecretNamespace: <kafka_auth_secret_namespace>
       bootstrapServers: <bootstrap_servers>
       enabled: true
     source:
       enabled: true

   Note

   Make sure to specify the matching port in the bootstrap server.

   For example:

   apiVersion: operator.serverless.openshift.io/v1alpha1
   kind: KnativeKafka
   metadata:
     namespace: knative-eventing
     name: knative-kafka
   spec:
     channel:
       authSecretName: tls-user
       authSecretNamespace: kafka
       bootstrapServers: eventing-kafka-bootstrap.kafka.svc:9094
       enabled: true
     source:
       enabled: true

Procedure

1. Create the certificate files as secrets in your chosen namespace:

   $ oc create secret -n <namespace> generic <kafka_auth_secret> \
     --from-file=ca.crt=caroot.pem \
     --from-literal=password="SecretPassword" \
     --from-literal=saslType="SCRAM-SHA-512" \
     --from-literal=user="my-sasl-user"

   • Use the key names ca.crt, password, and sasl.mechanism. Do not change them.

   • If you want to use SASL with public CA certificates, you must use the tls.enabled=true flag, rather than the ca.crt argument, when creating the secret. For example:

     $ oc create secret -n <namespace> generic <kafka_auth_secret> \
       --from-literal=tls.enabled=true \
       --from-literal=password="SecretPassword" \
       --from-literal=saslType="SCRAM-SHA-512" \
       --from-literal=user="my-sasl-user"

2. Start editing the KnativeKafka custom resource:

   $ oc edit knativekafka

3. Reference your secret and the namespace of the secret:

   apiVersion: operator.serverless.openshift.io/v1alpha1
   kind: KnativeKafka
   metadata:
     namespace: knative-eventing
     name: knative-kafka
   spec:
     channel:
       authSecretName: <kafka_auth_secret>
       authSecretNamespace: <kafka_auth_secret_namespace>
       bootstrapServers: <bootstrap_servers>
       enabled: true
     source:
       enabled: true

   Note

   Make sure to specify the matching port in the bootstrap server.

   For example:

   apiVersion: operator.serverless.openshift.io/v1alpha1
   kind: KnativeKafka
   metadata:
     namespace: knative-eventing
     name: knative-kafka
   spec:
     channel:
       authSecretName: scram-user
       authSecretNamespace: kafka
       bootstrapServers: eventing-kafka-bootstrap.kafka.svc:9093
       enabled: true
     source:
       enabled: true

Procedure

1. In the Administrator perspective of the OpenShift Container Platform web console, navigate to Serverless Eventing.
2. In the Channel tab, select the Options menu for the channel that you want to add a subscription to.
3. Click Add Subscription in the list.
4. In the Add Subscription dialogue box, select a Subscriber for the subscription. The subscriber is the Knative service that receives events from the channel.
5. Click Add.

Procedure

1. In the Developer perspective, navigate to the Topology page.

2. Create a subscription using one of the following methods:

   1. Hover over the channel that you want to create a subscription for, and drag the arrow. The Add Subscription option is displayed.

      
      1. Select your sink in the Subscriber list.
      2. Click Add.
   2. If the service is available in the Topology view under the same namespace or project as the channel, click on the channel that you want to create a subscription for, and drag the arrow directly to a service to immediately create a subscription from the channel to that service.

Procedure

1. List the available event source types in the terminal:

   $ kn source list-types

   Example output

   TYPE              NAME                                            DESCRIPTION
   ApiServerSource   apiserversources.sources.knative.dev            Watch and send Kubernetes API events to a sink
   PingSource        pingsources.sources.knative.dev                 Periodically send ping events to a sink
   SinkBinding       sinkbindings.sources.knative.dev                Binding for connecting a PodSpecable to a sink

2. Optional: You can also list the available event source types in YAML format:

   $ kn source list-types -o yaml

Procedure

1. Access the Developer perspective.
2. Click +Add.
3. Click Event Source.
4. View the available event source types.

Procedure

1. List the existing event sources in the terminal:

   $ kn source list

   Example output

   NAME   TYPE              RESOURCE                               SINK         READY
   a1     ApiServerSource   apiserversources.sources.knative.dev   ksvc:eshow2   True
   b1     SinkBinding       sinkbindings.sources.knative.dev       ksvc:eshow3   False
   p1     PingSource        pingsources.sources.knative.dev        ksvc:eshow1   True

2. Optional: You can list event sources of a specific type only, by using the --type flag:

   $ kn source list --type <event_source_type>

   Example command

   $ kn source list --type PingSource

   Example output

   NAME   TYPE              RESOURCE                               SINK         READY
   p1     PingSource        pingsources.sources.knative.dev        ksvc:eshow1   True

Procedure

1. In the OpenShift Container Platform web console Administrator perspective, navigate to OperatorHub Installed Operators.
2. Select the knative-eventing namespace.
3. Click Knative Eventing in the list of Provided APIs for the OpenShift Serverless Operator to go to the Knative Eventing tab.

4. Click knative-eventing, then go to the YAML tab in the knative-eventing page.

   

5. Modify the number of replicas in the KnativeEventing CR:

   Example YAML

   apiVersion: operator.knative.dev/v1beta1
   kind: KnativeEventing
   metadata:
     name: knative-eventing
     namespace: knative-eventing
   spec:
     high-availability:
       replicas: 3

Procedure

1. In the OpenShift Container Platform web console Administrator perspective, navigate to OperatorHub Installed Operators.
2. Select the knative-eventing namespace.
3. Click Knative Kafka in the list of Provided APIs for the OpenShift Serverless Operator to go to the Knative Kafka tab.

4. Click knative-kafka, then go to the YAML tab in the knative-kafka page.

   

5. Modify the number of replicas in the KnativeKafka CR:

   Example YAML

   apiVersion: operator.serverless.openshift.io/v1alpha1
   kind: KnativeKafka
   metadata:
     name: knative-kafka
     namespace: knative-eventing
   spec:
     high-availability:
       replicas: 3