openshift-docs/modules/serverless-pingsource-yaml.adoc

// Module included in the following assemblies:
//
// * /serverless/eventing/event-sources/serverless-pingsource.adoc

:_mod-docs-content-type: PROCEDURE
[id="serverless-pingsource-yaml_{context}"]
= Creating a ping source by using YAML

Creating Knative resources by using YAML files uses a declarative API, which enables you to describe event sources declaratively and in a reproducible manner. To create a serverless ping source by using YAML, you must create a YAML file that defines a `PingSource` object, then apply it by using `oc apply`.

.Example `PingSource` object
[source,yaml]
----
apiVersion: sources.knative.dev/v1
kind: PingSource
metadata:
  name: test-ping-source
spec:
  schedule: "*/2 * * * *" <1>
  data: '{"message": "Hello world!"}' <2>
  sink: <3>
    ref:
      apiVersion: serving.knative.dev/v1
      kind: Service
      name: event-display
----

<1> The schedule of the event specified using https://kubernetes.io/docs/tasks/job/automated-tasks-with-cron-jobs/#schedule[CRON expression].
<2> The event message body expressed as a JSON encoded data string.
<3> These are the details of the event consumer. In this example, we are using a Knative service named `event-display`.

.Prerequisites

* The {ServerlessOperatorName}, Knative Serving and Knative Eventing are installed on the cluster.
* Install the OpenShift CLI (`oc`).
* 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}.

.Procedure

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

.. Create a service YAML file:
+
[source,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
----
.. Create the service:
+
[source,terminal]
----
$ oc apply -f <filename>
----

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

.. Create a YAML file for the ping source:
+
[source,yaml]
----
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
----
.. Create the ping source:
+
[source,terminal]
----
$ oc apply -f <filename>
----

. Check that the controller is mapped correctly by entering the following command:
+
[source,terminal]
----
$ oc get pingsource.sources.knative.dev <ping_source_name> -oyaml
----
+
.Example output
[source,terminal]
----
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
----

.Verification

You can verify that the Kubernetes events were sent to the Knative 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 guide creates a PingSource that sends a message every 2 minutes, so each message should be observed in a newly created pod.

. Watch for new pods created:
+
[source,terminal]
----
$ watch oc get pods
----

. Cancel watching the pods using Ctrl+C, then look at the logs of the created pod:
+
[source,terminal]
----
$ oc logs $(oc get pod -o name | grep event-display) -c user-container
----
+
.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 world!"
  }
----

.Deleting the ping source
// move to separate procedure; out of scope for this PR

* Delete the ping source:
+
[source,terminal]
----
$ oc delete -f <filename>
----
+
.Example command
[source,terminal]
----
$ oc delete -f ping-source.yaml
----