Creating a PingSource object

stage version

This topic describes how to create a PingSource object.

A PingSource is an event source that produces events with a fixed payload on a specified cron schedule.

The following example shows how you can configure a PingSource as an event source that sends events every minute to a Knative service named event-display that is used as a sink. If you have an existing sink, you can replace the examples with your own values.

Before you begin

To create a PingSource:

  • You must install Knative Eventing. The PingSource event source type is enabled by default when you install Knative Eventing.
  • You can use either kubectl or kn commands to create components such as a sink and PingSource.
  • You can use either kubectl or kail for logging during the verification step in this procedure.

Create a PingSource object

  1. Optional: Create a namespace for your PingSource by running the command:

    1. kubectl create namespace <namespace>

    Where <namespace> is the namespace that you want your PingSource to use. For example, pingsource-example.

    Note

    Creating a namespace for your PingSource and related components allows you to view changes and events for this workflow more easily, because these are isolated from the other components that might exist in your default namespace.

    It also makes removing the source easier, because you can delete the namespace to remove all of the resources.

  2. Create a sink. If you do not have your own sink, you can use the following example Service that dumps incoming messages to a log:

    1. Copy the YAML below into a file:

      1. apiVersion: apps/v1
      2. kind: Deployment
      3. metadata:
      4.   name: event-display
      5.   namespace: <namespace>
      6. spec:
      7.   replicas: 1
      8.   selector:
      9.     matchLabels: &labels
      10.       app: event-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: event-display
      25.   namespace: <namespace>
      26. spec:
      27.   selector:
      28.     app: event-display
      29.   ports:
      30.   - protocol: TCP
      31.     port: 80
      32.     targetPort: 8080

      Where <namespace> is the name of the namespace that you created in step 1 above.

    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. Create the PingSource object.

    Note

    The data you want to send must be represented as text in the PingSource YAML file. Events that send binary data cannot be directly serialized in YAML. However, you can send binary data that is base64 encoded by using dataBase64 in place of data in the PingSource spec.

    Use one of the following options:

    knkn: binary dataYAMLYAML: binary data

    • To create a PingSource that sends data that can be represented as plain text, such as text, JSON, or XML, run the command:

      1. kn source ping create <pingsource-name> \
      2.   --namespace <namespace> \
      3.   --schedule "<cron-schedule>" \
      4.   --data '<data>' \
      5.   --sink <sink-name>

      Where:

      • <pingsource-name> is the name of the PingSource that you want to create, for example, test-ping-source.
      • <namespace> is the name of the namespace that you created in step 1 above.
      • <cron-schedule> is a cron expression for the schedule for the PingSource to send events, for example, */1 * * * * sends an event every minute. Both standard and Quartz Scheduler cron formats are supported, with the latter supporting a seconds field.
      • <data> is the data you want to send. This data must be represented as text, not binary. For example, a JSON object such as {"message": "Hello world!"}.
      • <sink-name> is the name of your sink, for example, http://event-display.pingsource-example.svc.cluster.local.

      For a list of available options, see the Knative client documentation.

    • To create a PingSource that sends binary data, run the command:

      1. kn source ping create <pingsource-name> \
      2.   --namespace <namespace> \
      3.   --schedule "<cron-schedule>" \
      4.   --data '<base64-data>' \
      5.   --encoding 'base64' \
      6.   --sink <sink-name>

      Where:

      • <pingsource-name> is the name of the PingSource that you want to create, for example, test-ping-source.
      • <namespace> is the name of the namespace that you created in step 1 above.
      • <cron-schedule> is a cron expression for the schedule for the PingSource to send events, for example, */1 * * * * sends an event every minute. Both standard and Quartz Scheduler cron formats are supported, with the latter supporting a seconds field.
      • <base64-data> is the base64 encoded binary data that you want to send, for example, ZGF0YQ==.
      • <sink-name> is the name of your sink, for example, http://event-display.pingsource-example.svc.cluster.local.

      For a list of available options, see the Knative client documentation.

    • To create a PingSource that sends data that can be represented as plain text, such as text, JSON, or XML:

      1. Create a YAML file using the template below:

        1. apiVersion: sources.knative.dev/v1
        2. kind: PingSource
        3. metadata:
        4.   name: <pingsource-name>
        5.   namespace: <namespace>
        6. spec:
        7.   schedule: "<cron-schedule>"
        8.   contentType: "<content-type>"
        9.   data: '<data>'
        10.   sink:
        11.     ref:
        12.       apiVersion: v1
        13.       kind: <sink-kind>
        14.       name: <sink-name>

        Where:

        • <pingsource-name> is the name of the PingSource that you want to create, for example, test-ping-source.
        • <namespace> is the name of the namespace that you created in step 1 above.
        • <cron-schedule> is a cron expression for the schedule for the PingSource to send events, for example, */1 * * * * sends an event every minute. Both standard and Quartz Scheduler cron formats are supported, with the latter supporting a seconds field.
        • <content-type> is the media type of the data you want to send, for example, application/json.
        • <data> is the data you want to send. This data must be represented as text, not binary. For example, a JSON object such as {"message": "Hello world!"}.
        • <sink-kind> is any supported Addressable object that you want to use as a sink, for example, a Service or Deployment.
        • <sink-name> is the name of your sink, for example, event-display.

        For more information about the fields you can configure for the PingSource object, see PingSource reference.

      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.

    • To create a PingSource that sends binary data:

      1. Create a YAML file using the template below:

        1. apiVersion: sources.knative.dev/v1
        2. kind: PingSource
        3. metadata:
        4.   name: <pingsource-name>
        5.   namespace: <namespace>
        6. spec:
        7.   schedule: "<cron-schedule>"
        8.   contentType: "<content-type>"
        9.   dataBase64: "<base64-data>"
        10.   sink:
        11.     ref:
        12.       apiVersion: v1
        13.       kind: <sink-kind>
        14.       name: <sink-name>

        Where:

        • <pingsource-name> is the name of the PingSource that you want to create, for example, test-ping-source-binary.
        • <namespace> is the name of the namespace that you created in step 1 above.
        • <cron-schedule> is a cron expression for the schedule for the PingSource to send events, for example, */1 * * * * sends an event every minute. Both standard and Quartz Scheduler cron formats are supported, with the latter supporting a seconds field.
        • <content-type> is the media type of the data you want to send, for example, application/json.
        • <base64-data> is the base64 encoded binary data that you want to send, for example, ZGF0YQ==.
        • <sink-kind> is any supported Addressable object that you want to use as a sink, for example, a Kubernetes Service.
        • <sink-name> is the name of your sink, for example, event-display.

        For more information about the fields you can configure for the PingSource object, see PingSource reference.

      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.

Verify the PingSource object

  1. View the logs for the event-display event consumer by running the command:

    kubectlkail

    1. kubectl -n pingsource-example logs -l app=event-display --tail=100
    1. kail -l serving.knative.dev/service=event-display -c user-container --since=10m

  2. Verify that the output returns the properties of the events that your PingSource sent to your sink. In the example below, the command has returned the Attributes and Data properties of the events that the PingSource sent to the event-display Service:

    1. ☁️  cloudevents.Event
    2. Validation: valid
    3. Context Attributes,
    4.   specversion: 1.0
    5.   type: dev.knative.sources.ping
    6.   source: /apis/v1/namespaces/pingsource-example/pingsources/test-ping-source
    7.   id: 49f04fe2-7708-453d-ae0a-5fbaca9586a8
    8.   time: 2021-03-25T19:41:00.444508332Z
    9.   datacontenttype: application/json
    10. Data,
    11.   {
    12.     "message": "Hello world!"
    13.   }

Delete the PingSource object

You can either delete the PingSource and all related resources, or delete the resources individually:

  • To remove the PingSource object and all of the related resources, delete the namespace by running the command:

    1. kubectl delete namespace <namespace>

    Where <namespace> is the namespace that contains the PingSource object.

  • To delete the PingSource instance only, run the command:

    knkubectl

    1. kn source ping delete <pingsource-name>

    Where <pingsource-name> is the name of the PingSource you want to delete, for example, test-ping-source.

    1. kubectl delete pingsources.sources.knative.dev <pingsource-name>

    Where <pingsource-name> is the name of the PingSource you want to delete, for example, test-ping-source.

  • To delete the sink only, run the command:

    knkubectl

    1. kn service delete <sink-name>

    Where <sink-name> is the name of your sink, for example, event-display.

    1. kubectl delete service.serving.knative.dev <sink-name>

    Where <sink-name> is the name of your sink, for example, event-display.