Chapter 2. Event sources

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. In the Target section, select your event sink. This can be either a Resource or a URI:

      1. Select Resource to use a channel, broker, or service as an event sink for the event source.
      2. Select URI to specify a Uniform Resource Identifier (URI) where the events are routed to.
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 event-display --image quay.io/openshift-knative/showcase

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:event-display

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

   $ oc create deployment event-origin --image quay.io/openshift-knative/showcase

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

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/showcase

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 event-origin --image=quay.io/openshift-knative/showcase

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

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/showcase

   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. In the Target section, select your event sink. This can be either a Resource or a URI:

      1. Select Resource to use a channel, broker, or service as an event sink for the event source. In this example, the event-display service created in the previous step is used as the target Resource.
      2. Select URI to specify a Uniform Resource Identifier (URI) where the events are routed to.
   7. Click Create.

1. In the Developer perspective, navigate to Topology.

2. View the ping source and sink.

   

3. View the event-display service in the web browser. You should see the ping source events in the web UI.

   

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/showcase

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/showcase

   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. In the Target section, select your event sink. This can be either a Resource or a URI:

      1. Select Resource to use a channel, broker, or service as an event sink for the event source.
      2. Select URI to specify a Uniform Resource Identifier (URI) where the events are routed to.
   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/showcase

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.

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 Target section of the Create Event Source form view, select your event sink. This can be either a Resource or a URI:

   1. Select Resource to use a channel, broker, or service as an event sink for the event source.
   2. Select URI to specify a Uniform Resource Identifier (URI) where the events are routed to.
3. Click Create.

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