Getting Started with Knative Eventing

After you install Knative Eventing, you can create, send, and verify events. This guide shows how you can use a basic workflow for managing events.

Before you start to manage events, you must create the objects needed to transport the events.

Creating a Knative Eventing namespace

Namespaces are used to group together and organize your Knative resources.

Create a new namespace called event-example by entering the following command:

  1. kubectl create namespace event-example

Adding a broker to the namespace

The broker allows you to route events to different event sinks or consumers.

  1. Add a broker named default to your namespace by copying the following YAML into a file:

    1. apiVersion: eventing.knative.dev/v1
    2. kind: Broker
    3. metadata:
    4.  name: default
    5.  namespace: event-example

  2. Apply the YAML file by running the command:

    1. kubectl apply -f <filename>.yaml

    Where <filename> is the name of the file you created in the previous step.

  3. Verify that the broker is working correctly, by entering the following command:

    1. kubectl -n event-example get broker default

    This shows information about your broker. If the broker is working correctly, it shows a READY status of True:

    1. NAME      READY   REASON   URL                                                                                 AGE
    2. default   True             http://broker-ingress.knative-eventing.svc.cluster.local/event-example/default      1m

    If READY is False, wait a few moments and then run the command again. If you continue to receive the False status, see the Debugging Guide to troubleshoot the issue.

Creating event consumers

In this step, you create two event consumers, hello-display and goodbye-display, to demonstrate how you can configure your event producers to target a specific consumer.

  1. To deploy the hello-display consumer to your cluster, copy the following YAML into a file:

    1. apiVersion: apps/v1
    2. kind: Deployment
    3. metadata:
    4.   name: hello-display
    5.   namespace: event-example
    6. spec:
    7.   replicas: 1
    8.   selector:
    9.     matchLabels: &labels
    10.       app: hello-display
    11.   template:
    12.     metadata:
    13.       labels: *labels
    14.     spec:
    15.       containers:
    16.         - name: event-display
    17.           image: gcr.io/knative-releases/knative.dev/eventing/cmd/event_display
    19. ---
    21. kind: Service
    22. apiVersion: v1
    23. metadata:
    24.   name: hello-display
    25.   namespace: event-example
    26. spec:
    27.   selector:
    28.     app: hello-display
    29.   ports:
    30.   - protocol: TCP
    31.     port: 80
    32.     targetPort: 8080

  2. Apply the YAML file by running the command:

    1. kubectl apply -f <filename>.yaml

    Where <filename> is the name of the file you created in the previous step.

  3. To deploy the goodbye-display consumer to your cluster, copy the following YAML into a file:

    1. apiVersion: apps/v1
    2. kind: Deployment
    3. metadata:
    4.   name: goodbye-display
    5.   namespace: event-example
    6. spec:
    7.   replicas: 1
    8.   selector:
    9.     matchLabels: &labels
    10.       app: goodbye-display
    11.   template:
    12.     metadata:
    13.       labels: *labels
    14.     spec:
    15.       containers:
    16.         - name: event-display
    17.           # Source code: https://github.com/knative/eventing/tree/main/cmd/event_display
    18.           image: gcr.io/knative-releases/knative.dev/eventing/cmd/event_display
    20. ---
    22. kind: Service
    23. apiVersion: v1
    24. metadata:
    25.   name: goodbye-display
    26.   namespace: event-example
    27. spec:
    28.   selector:
    29.     app: goodbye-display
    30.   ports:
    31.   - protocol: TCP
    32.     port: 80
    33.     targetPort: 8080

    1. Apply the YAML file by running the command:

    1. kubectl apply -f <filename>.yaml

    Where <filename> is the name of the file you created in the previous step.

  4. Verify that the event consumers are working by entering the following command:

    1. kubectl -n event-example get deployments hello-display goodbye-display

    This lists the hello-display and goodbye-display consumers that you deployed:

    1. NAME              READY   UP-TO-DATE   AVAILABLE   AGE
    2. hello-display     1/1     1            1           26s
    3. goodbye-display   1/1     1            1           16s

    The number of replicas in the READY column should match the number of replicas in the AVAILABLE column. If the numbers do not match, see the Debugging Guide to troubleshoot the issue.

Creating triggers

A trigger defines the events that each event consumer receives. Brokers use triggers to forward events to the correct consumers. Each trigger can specify a filter that enables selection of relevant events based on the Cloud Event context attributes.

  1. Create a trigger by copying the following YAML into a file:

    1. apiVersion: eventing.knative.dev/v1
    2. kind: Trigger
    3. metadata:
    4.   name: hello-display
    5.   namespace: event-example
    6. spec:
    7.   broker: default
    8.   filter:
    9.     attributes:
    10.       type: greeting
    11.   subscriber:
    12.     ref:
    13.      apiVersion: v1
    14.      kind: Service
    15.      name: hello-display

    The command creates a trigger that sends all events of type greeting to your event consumer named hello-display.

  2. Apply the YAML file by running the command:

    1. kubectl apply -f <filename>.yaml

    Where <filename> is the name of the file you created in the previous step.

  3. To add a second trigger, copy the following YAML into a file:

    1. apiVersion: eventing.knative.dev/v1
    2. kind: Trigger
    3. metadata:
    4.   name: goodbye-display
    5.   namespace: event-example
    6. spec:
    7.   broker: default
    8.   filter:
    9.     attributes:
    10.       source: sendoff
    11.   subscriber:
    12.     ref:
    13.      apiVersion: v1
    14.      kind: Service
    15.      name: goodbye-display

    The command creates a trigger that sends all events of source sendoff to your event consumer named goodbye-display.

  4. Apply the YAML file by running the command:

    1. kubectl apply -f <filename>.yaml

    Where <filename> is the name of the file you created in the previous step.

  5. Verify that the triggers are working correctly by running the following command:

    1. kubectl -n event-example get triggers

    This returns the hello-display and goodbye-display triggers that you created:

    1. NAME                   READY   REASON   BROKER    SUBSCRIBER_URI                                                                 AGE
    2. goodbye-display        True             default   http://goodbye-display.event-example.svc.cluster.local/                        9s
    3. hello-display          True             default   http://hello-display.event-example.svc.cluster.local/                          16s

    If the triggers are correctly configured, they will be ready and pointing to the correct broker (default) and SUBSCRIBER_URI.

    The SUBSCRIBER_URI has a value similar to triggerName.namespaceName.svc.cluster.local. The exact value depends on the broker implementation. If this value looks incorrect, see the Debugging Guide to troubleshoot the issue.

Creating a pod as an event producer

This guide uses curl commands to manually send individual events as HTTP requests to the broker, and demonstrate how these events are received by the correct event consumer.

The broker can only be accessed from within the cluster where Knative Eventing is installed. You must create a pod within that cluster to act as an event producer that will execute the curl commands.

  1. To create a pod, copy the following YAML into a file:

    1. apiVersion: v1
    2. kind: Pod
    3. metadata:
    4.   labels:
    5.     run: curl
    6.   name: curl
    7.   namespace: event-example
    8. spec:
    9.   containers:
    10.     # This could be any image that we can SSH into and has curl.
    11.   - image: radial/busyboxplus:curl
    12.     imagePullPolicy: IfNotPresent
    13.     name: curl
    14.     resources: {}
    15.     stdin: true
    16.     terminationMessagePath: /dev/termination-log
    17.     terminationMessagePolicy: File
    18.     tty: true

  2. Apply the YAML file by running the command:

    1. kubectl apply -f <filename>.yaml

    Where <filename> is the name of the file you created in the previous step.

Sending events to the broker

  1. SSH into the pod by running the following command:

    1. kubectl -n event-example attach curl -it

    You will see a prompt similar to the following:

    1. Defaulting container name to curl.
    2. Use 'kubectl describe pod/ -n event-example' to see all of the containers in this pod.
    3. If you don't see a command prompt, try pressing enter.
    4. [ root@curl:/ ]$

  2. Make a HTTP request to the broker. To show the various types of events you can send, you will make three requests:

    • To make the first request, which creates an event that has the type greeting, run the following in the SSH terminal:

      1. curl -v "http://broker-ingress.knative-eventing.svc.cluster.local/event-example/default" \
      2.   -X POST \
      3.   -H "Ce-Id: say-hello" \
      4.   -H "Ce-Specversion: 1.0" \
      5.   -H "Ce-Type: greeting" \
      6.   -H "Ce-Source: not-sendoff" \
      7.   -H "Content-Type: application/json" \
      8.   -d '{"msg":"Hello Knative!"}'

      When the broker receives your event, hello-display will activate and send it to the event consumer of the same name. If the event has been received, you will receive a 202 Accepted response similar to the following example:

    1. < HTTP/1.1 202 Accepted
    2. < Content-Length: 0
    3. < Date: Mon, 12 Aug 2019 19:48:18 GMT

    - To make the second request, which creates an event that has the source sendoff, run the following in the SSH terminal:

    1. curl -v "http://broker-ingress.knative-eventing.svc.cluster.local/event-example/default" \
    2.   -X POST \
    3.   -H "Ce-Id: say-goodbye" \
    4.   -H "Ce-Specversion: 1.0" \
    5.   -H "Ce-Type: not-greeting" \
    6.   -H "Ce-Source: sendoff" \
    7.   -H "Content-Type: application/json" \
    8.   -d '{"msg":"Goodbye Knative!"}'

    When the broker receives your event, goodbye-display will activate and send the event to the event consumer of the same name. If the event has been received, you will receive a 202 Accepted response similar to the following example:

    1. < HTTP/1.1 202 Accepted
    2. < Content-Length: 0
    3. < Date: Mon, 12 Aug 2019 19:48:18 GMT

    - To make the third request, which creates an event that has the type greeting and the source sendoff, run the following in the SSH terminal:

    1. curl -v "http://broker-ingress.knative-eventing.svc.cluster.local/event-example/default" \
    2.   -X POST \
    3.   -H "Ce-Id: say-hello-goodbye" \
    4.   -H "Ce-Specversion: 1.0" \
    5.   -H "Ce-Type: greeting" \
    6.   -H "Ce-Source: sendoff" \
    7.   -H "Content-Type: application/json" \
    8.   -d '{"msg":"Hello Knative! Goodbye Knative!"}'

    When the broker receives your event, hello-display and goodbye-display will activate and send the event to the event consumers of the same name. If the event has been received, you will receive a 202 Accepted response similar to the following example:

    1. < HTTP/1.1 202 Accepted
    2. < Content-Length: 0
    3. < Date: Mon, 12 Aug 2019 19:48:18 GMT

  3. Exit SSH by typing exit into the command prompt.

You have sent two events to the hello-display event consumer and two events to the goodbye-display event consumer (note that say-hello-goodbye activates the trigger conditions for both hello-display and goodbye-display). You will verify that these events were received correctly in the next section.

Verifying that events were received

After you send the events, verify that the events were received by the correct subscribers.

  1. Look at the logs for the hello-display event consumer by entering the following command:

    1. kubectl -n event-example logs -l app=hello-display --tail=100

    This returns the Attributes and Data of the events you sent to hello-display:

    1. ☁️  cloudevents.Event
    2. Validation: valid
    3. Context Attributes,
    4.   specversion: 1.0
    5.   type: greeting
    6.   source: not-sendoff
    7.   id: say-hello
    8.   time: 2019-05-20T17:59:43.81718488Z
    9.   contenttype: application/json
    10. Extensions,
    11.   knativehistory: default-broker-srk54-channel-24gls.event-example.svc.cluster.local
    12. Data,
    13.   {
    14.     "msg": "Hello Knative!"
    15.   }
    16. ☁️  cloudevents.Event
    17. Validation: valid
    18. Context Attributes,
    19.   specversion: 1.0
    20.   type: greeting
    21.   source: sendoff
    22.   id: say-hello-goodbye
    23.   time: 2019-05-20T17:59:54.211866425Z
    24.   contenttype: application/json
    25. Extensions,
    26.   knativehistory: default-broker-srk54-channel-24gls.event-example.svc.cluster.local
    27. Data,
    28.  {
    29.    "msg": "Hello Knative! Goodbye Knative!"
    30.  }

  2. Look at the logs for the goodbye-display event consumer by entering the following command:

    1. kubectl -n event-example logs -l app=goodbye-display --tail=100

    This returns the Attributes and Data of the events you sent to goodbye-display:

    1. ☁️  cloudevents.Event
    2. Validation: valid
    3. Context Attributes,
    4.    specversion: 1.0
    5.    type: not-greeting
    6.    source: sendoff
    7.    id: say-goodbye
    8.    time: 2019-05-20T17:59:49.044926148Z
    9.    contenttype: application/json
    10.  Extensions,
    11.    knativehistory: default-broker-srk54-channel-24gls.event-example.svc.cluster.local
    12. Data,
    13.    {
    14.      "msg": "Goodbye Knative!"
    15.    }
    16.  ☁️  cloudevents.Event
    17.  Validation: valid
    18.  Context Attributes,
    19.    specversion: 1.0
    20.    type: greeting
    21.    source: sendoff
    22.    id: say-hello-goodbye
    23.    time: 2019-05-20T17:59:54.211866425Z
    24.    contenttype: application/json
    25.  Extensions,
    26.    knativehistory: default-broker-srk54-channel-24gls.event-example.svc.cluster.local
    27.  Data,
    28.   {
    29.     "msg": "Hello Knative! Goodbye Knative!"
    30.   }

Cleaning up example resources

You can delete the event-example namespace and its associated resources from your cluster if you do not plan to use it again in the future.

Delete the event-example namespace and all of its resources from your cluster by entering the following command:

  1. kubectl delete namespace event-example