Update PingSource docs and examples to use v1beta2 (#3046)

* Update PingSource docs and examples to use v1beta2

* Apply suggestions from code review

Co-authored-by: Mike Petersen <mike.petersen@ibm.com>

Co-authored-by: Mike Petersen <mike.petersen@ibm.com>

docs/eventing/broker/README.md

@@ -148,13 +148,14 @@ events once a minute, saying, yes, you guessed it `Hello World!`.
 
 ```shell
 kubectl create -f - <<EOF
-apiVersion: sources.knative.dev/v1alpha2
+apiVersion: sources.knative.dev/v1beta2
 kind: PingSource
 metadata:
   name: test-ping-source
 spec:
   schedule: "*/1 * * * *"
-  jsonData: '{"message": "Hello world!"}'
+  contentType: "application/json"
+  data: '{"message": "Hello world!"}'
   sink:
     ref:
       # Deliver events to Broker.

docs/eventing/samples/parallel/multiple-branches/README.md

@@ -150,13 +150,14 @@ This will create a PingSource which will send a CloudEvent with
 `{"message": "Even or odd?"}` as the data payload every minute.
 
 ```yaml
-apiVersion: sources.knative.dev/v1beta1
+apiVersion: sources.knative.dev/v1beta2
 kind: PingSource
 metadata:
   name: ping-source
 spec:
   schedule: "*/1 * * * *"
-  jsonData: '{"message": "Even or odd?"}'
+  contentType: "application/json"
+  data: '{"message": "Even or odd?"}'
   sink:
     ref:
       apiVersion: flows.knative.dev/v1

docs/eventing/samples/parallel/multiple-branches/ping-source.yaml

@@ -1,10 +1,11 @@
-apiVersion: sources.knative.dev/v1beta1
+apiVersion: sources.knative.dev/v1beta2
 kind: PingSource
 metadata:
   name: ping-source
 spec:
   schedule: "*/1 * * * *"
-  jsonData: '{"message": "Even or odd?"}'
+  contentType: "application/json"
+  data: '{"message": "Even or odd?"}'
   sink:
     ref:
       apiVersion: flows.knative.dev/v1

docs/eventing/samples/parallel/mutual-exclusivity/README.md

@@ -133,13 +133,14 @@ This will create a PingSource which will send a CloudEvent with
 `{"message": "Even or odd?"}` as the data payload every minute.
 
 ```yaml
-apiVersion: sources.knative.dev/v1beta1
+apiVersion: sources.knative.dev/v1beta2
 kind: PingSource
 metadata:
   name: me-ping-source
 spec:
   schedule: "*/1 * * * *"
-  jsonData: '{"message": "Even or odd?"}'
+  contentType: "application/json"
+  data: '{"message": "Even or odd?"}'
   sink:
     ref:
       apiVersion: flows.knative.dev/v1

docs/eventing/samples/parallel/mutual-exclusivity/ping-source.yaml

@@ -1,10 +1,11 @@
-apiVersion: sources.knative.dev/v1beta1
+apiVersion: sources.knative.dev/v1beta2
 kind: PingSource
 metadata:
   name: me-ping-source
 spec:
   schedule: "*/1 * * * *"
-  jsonData: '{"message": "Even or odd?"}'
+  contentType: "application/json"
+  data: '{"message": "Even or odd?"}'
   sink:
     ref:
       apiVersion: flows.knative.dev/v1

docs/eventing/samples/ping-source/index.md

@@ -59,13 +59,14 @@ Use following command to create the event source from STDIN:
 
 ```shell
 cat <<EOF | kubectl create -f -
-apiVersion: sources.knative.dev/v1beta1
+apiVersion: sources.knative.dev/v1beta2
 kind: PingSource
 metadata:
   name: test-ping-source
 spec:
   schedule: "*/2 * * * *"
-  jsonData: '{"message": "Hello world!"}'
+  contentType: "application/json"
+  data: '{"message": "Hello world!"}'
   sink:
     ref:
       apiVersion: serving.knative.dev/v1
@@ -84,6 +85,44 @@ kubectl apply --filename ping-source.yaml
 {{< /tab >}}
 {{< /tabs >}}
 
+## (Optional) Create a PingSource with binary data
+
+Sometimes you may want to send binary data, which cannot be directly serialized in yaml, to downstream. This can be achieved by using `dataBase64` as the payload. As the name suggests, `dataBase64` should carry data that is base64 encoded.
+
+Please note that `data` and `dataBase64` cannot co-exist.
+
+{{< tabs name="create-source" default="By YAML" >}}
+{{% tab name="By YAML" %}}
+Use the following command to create the event source with binary data from STDIN:
+
+```shell
+cat <<EOF | kubectl create -f -
+apiVersion: sources.knative.dev/v1beta2
+kind: PingSource
+metadata:
+  name: test-ping-source-binary
+spec:
+  schedule: "*/2 * * * *"
+  contentType: "text/plain"
+  dataBase64: "ZGF0YQ=="
+  sink:
+    ref:
+      apiVersion: serving.knative.dev/v1
+      kind: Service
+      name: event-display
+EOF
+```
+{{< /tab >}}
+
+{{% tab name="By filename" %}}
+Use the following command to create the event source from the `ping-source-binary.yaml` file:
+
+```shell
+kubectl apply --filename ping-source-binary.yaml
+```
+{{< /tab >}}
+{{< /tabs >}}
+
 
 ## Verify
 
@@ -114,7 +153,7 @@ kail -l serving.knative.dev/service=event-display -c user-container --since=10m
 
 You should see log lines showing the request headers and body from the source:
 
-```
+```shell
 ☁️  cloudevents.Event
 Validation: valid
 Context Attributes,
@@ -130,6 +169,22 @@ Data,
   }
 ```
 
+If you created a PingSource with binary data, you should also see the following:
+
+```shell
+☁️  cloudevents.Event
+Validation: valid
+Context Attributes,
+  specversion: 1.0
+  type: dev.knative.sources.ping
+  source: /apis/v1/namespaces/default/pingsources/test-ping-source-binary
+  id: a195be33-ff65-49af-9045-0e0711d05e94
+  time: 2020-11-17T19:48:00.48334181Z
+  datacontenttype: text/plain
+Data,
+  ZGF0YQ==
+```
+
 ## Cleanup
 
 You can delete the PingSource instance by entering the following command:
@@ -138,12 +193,14 @@ You can delete the PingSource instance by entering the following command:
 {{% tab name="By name" %}}
 ```shell
 kubectl delete pingsources.sources.knative.dev test-ping-source
+kubectl delete pingsources.sources.knative.dev test-ping-source-binary
 ```
 {{< /tab >}}
 
 {{% tab name="By filename" %}}
 ```shell
 kubectl delete --filename ping-source.yaml
+kubectl delete --filename ping-source-binary.yaml
 ```
 {{< /tab >}}
 {{< /tabs >}}

docs/eventing/samples/ping-source/ping-source-binary.yaml

@@ -0,0 +1,13 @@
+apiVersion: sources.knative.dev/v1beta2
+kind: PingSource
+metadata:
+  name: test-ping-source-binary
+spec:
+  schedule: "*/2 * * * *"
+  contentType: "text/plain"
+  dataBase64: "ZGF0YQ=="
+  sink:
+    ref:
+      apiVersion: serving.knative.dev/v1
+      kind: Service
+      name: event-display

docs/eventing/samples/ping-source/ping-source.yaml

@@ -1,10 +1,11 @@
-apiVersion: sources.knative.dev/v1beta1
+apiVersion: sources.knative.dev/v1beta2
 kind: PingSource
 metadata:
   name: test-ping-source
 spec:
   schedule: "*/2 * * * *"
-  jsonData: '{"message": "Hello world!"}'
+  contentType: "application/json"
+  data: '{"message": "Hello world!"}'
   sink:
     ref:
       apiVersion: serving.knative.dev/v1

docs/eventing/samples/sequence/sequence-reply-to-event-display/README.md

@@ -141,13 +141,14 @@ This will create a PingSource which will send a CloudEvent with {"message":
 "Hello world!"} as the data payload every 2 minutes.
 
 ```yaml
-apiVersion: sources.knative.dev/v1beta1
+apiVersion: sources.knative.dev/v1beta2
 kind: PingSource
 metadata:
   name: ping-source
 spec:
   schedule: "*/2 * * * *"
-  jsonData: '{"message": "Hello world!"}'
+  contentType: "application/json"
+  data: '{"message": "Hello world!"}'
   sink:
     ref:
       apiVersion: flows.knative.dev/v1

docs/eventing/samples/sequence/sequence-reply-to-event-display/ping-source.yaml

@@ -1,10 +1,11 @@
-apiVersion: sources.knative.dev/v1alpha2
+apiVersion: sources.knative.dev/v1beta2
 kind: PingSource
 metadata:
   name: ping-source
 spec:
   schedule: "*/2 * * * *"
-  jsonData: '{"message": "Hello world!"}'
+  contentType: "application/json"
+  data: '{"message": "Hello world!"}'
   sink:
     ref:
       apiVersion: flows.knative.dev/v1

docs/eventing/samples/sequence/sequence-reply-to-sequence/README.md

@@ -221,16 +221,17 @@ This will create a PingSource which will send a CloudEvent with
 `{"message": "Hello world!"}` as the data payload every 2 minutes.
 
 ```yaml
-apiVersion: sources.knative.dev/v1beta1
+apiVersion: sources.knative.dev/v1beta2
 kind: PingSource
 metadata:
   name: ping-source
 spec:
   schedule: "*/2 * * * *"
-  jsonData: '{"message": "Hello world!"}'
+  contentType: "application/json"
+  data: '{"message": "Hello world!"}'
   sink:
     ref:
-      apiVersion: flows.knative.dev/v1beta1
+      apiVersion: flows.knative.dev/v1
       kind: Sequence
       name: first-sequence
 ```

docs/eventing/samples/sequence/sequence-reply-to-sequence/ping-source.yaml

@@ -1,10 +1,11 @@
-apiVersion: sources.knative.dev/v1beta1
+apiVersion: sources.knative.dev/v1beta2
 kind: PingSource
 metadata:
   name: ping-source
 spec:
   schedule: "*/2 * * * *"
-  jsonData: '{"message": "Hello world!"}'
+  contentType: "application/json"
+  data: '{"message": "Hello world!"}'
   sink:
     ref:
       apiVersion: flows.knative.dev/v1

docs/eventing/samples/sequence/sequence-terminal/README.md

@@ -115,13 +115,14 @@ This will create a PingSource which will send a CloudEvent with
 `{"message": "Hello world!"}` as the data payload every 2 minutes.
 
 ```yaml
-apiVersion: sources.knative.dev/v1beta1
+apiVersion: sources.knative.dev/v1beta2
 kind: PingSource
 metadata:
   name: ping-source
 spec:
   schedule: "*/2 * * * *"
-  jsonData: '{"message": "Hello world!"}'
+  contentType: "application/json"
+  data: '{"message": "Hello world!"}'
   sink:
     ref:
       apiVersion: flows.knative.dev/v1

docs/eventing/samples/sequence/sequence-terminal/ping-source.yaml

@@ -1,10 +1,11 @@
-apiVersion: sources.knative.dev/v1beta1
+apiVersion: sources.knative.dev/v1beta2
 kind: PingSource
 metadata:
   name: ping-source
 spec:
   schedule: "*/2 * * * *"
-  jsonData: '{"message": "Hello world!"}'
+  contentType: "application/json"
+  data: '{"message": "Hello world!"}'
   sink:
     ref:
       apiVersion: flows.knative.dev/v1

docs/eventing/samples/sequence/sequence-with-broker-trigger/README.md

@@ -139,13 +139,14 @@ This will create a PingSource which will send a CloudEvent with {"message":
 "Hello world!"} as the data payload every 2 minutes.
 
 ```yaml
-apiVersion: sources.knative.dev/v1beta1
+apiVersion: sources.knative.dev/v1beta2
 kind: PingSource
 metadata:
   name: ping-source
 spec:
   schedule: "*/2 * * * *"
-  jsonData: '{"message": "Hello world!"}'
+  contentType: "application/json"
+  data: '{"message": "Hello world!"}'
   sink:
     ref:
       apiVersion: eventing.knative.dev/v1

docs/eventing/samples/sequence/sequence-with-broker-trigger/ping-source.yaml

@@ -1,10 +1,11 @@
-apiVersion: sources.knative.dev/v1beta1
+apiVersion: sources.knative.dev/v1beta2
 kind: PingSource
 metadata:
   name: ping-source
 spec:
   schedule: "*/2 * * * *"
-  jsonData: '{"message": "Hello world!"}'
+  contentType: "application/json"
+  data: '{"message": "Hello world!"}'
   sink:
     ref:
       apiVersion: eventing.knative.dev/v1

docs/eventing/sources/_index.md

@@ -43,7 +43,7 @@ kn source list
 | [GitHub](https://github.com/knative-sandbox/eventing-github/blob/master/pkg/apis/sources/v1alpha1/githubsource_types.go)            | v1alpha1 | Knative    | Registers for events of the specified types on the specified GitHub organization or repository, and brings those events into Knative. The GitHubSource fires a new event for selected [GitHub event types](https://developer.github.com/v3/activity/events/types/). See the [GitHub Source](../samples/github-source) example for more details.  |
 | [GitLab](https://github.com/knative-sandbox/eventing-gitlab/blob/master/pkg/apis/sources/v1alpha1/gitlabsource_types.go) | v1alpha1 | Knative    | Registers for events of the specified types on the specified GitLab repository, and brings those events into Knative. The GitLabSource creates a webhooks for specified [event types](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html#events), listens for incoming events, and passes them to a consumer. See the [GitLab Source](../samples/gitlab-source) example for more details.  |
 | [Heartbeats](https://github.com/knative/eventing-contrib/tree/master/cmd/heartbeats) |  N/A | Knative    | Uses an in-memory timer to produce events at the specified interval. |
-| [PingSource](./pingsource) |  	v1beta1  | Knative    | Produces events with a fixed payload on a specified [Cron](https://en.wikipedia.org/wiki/Cron) schedule. See the [Ping Source](../samples/ping-source) example for more details. |
+| [PingSource](./pingsource) |  	v1beta2  | Knative    | Produces events with a fixed payload on a specified [Cron](https://en.wikipedia.org/wiki/Cron) schedule. See the [Ping Source](../samples/ping-source) example for more details. |
 | [RabbitMQ](https://github.com/knative-sandbox/eventing-rabbitmq) | Active development | None | Brings [RabbitMQ](https://www.rabbitmq.com/) messages into Knative.
 | [SinkBinding](https://knative.dev/docs/eventing/samples/sinkbinding/)                                                               |  	v1           | Knative    | The SinkBinding can be used to author new event sources using any of the familiar compute abstractions that Kubernetes makes available (e.g. Deployment, Job, DaemonSet, StatefulSet), or Knative abstractions (e.g. Service, Configuration). SinkBinding provides a framework for injecting `K_SINK` (destination address) and `K_CE_OVERRIDES` (JSON cloudevents attributes) environment variables into any Kubernetes resource which has a `spec.template` that looks like a Pod (aka PodSpecable). See the [SinkBinding](../samples/container-source) example for more details. |
 | [WebSocket](https://github.com/knative/eventing-contrib/tree/master/cmd/websocketsource)                                            | N/A | Knative    | Opens a WebSocket to the specified source and packages each received message as a Knative event.  |

docs/eventing/sources/pingsource.md

@@ -79,13 +79,14 @@ You can now create the `PingSource` sending an event containing
 
 ```shell
 kubectl create -n pingsource-example -f - <<EOF
-apiVersion: sources.knative.dev/v1beta1
+apiVersion: sources.knative.dev/v1beta2
 kind: PingSource
 metadata:
   name: test-ping-source
 spec:
   schedule: "*/1 * * * *"
-  jsonData: '{"message": "Hello world!"}'
+  contentType: "application/json"
+  data: '{"message": "Hello world!"}'
   sink:
     ref:
       apiVersion: v1
@@ -109,6 +110,30 @@ kn source ping create test-ping-source \
 {{< /tab >}}
 {{< /tabs >}}
 
+## (Optional) Create a PingSource with binary data
+
+Sometimes you may want to send binary data, which cannot be directly serialized in yaml, to downstream. This can be achieved by using `dataBase64` as the payload. As the name suggests, `dataBase64` should carry data that is base64 encoded.
+
+Please note that `data` and `dataBase64` cannot co-exist.
+
+```shell
+cat <<EOF | kubectl create -f -
+apiVersion: sources.knative.dev/v1beta2
+kind: PingSource
+metadata:
+  name: test-ping-source-binary
+spec:
+  schedule: "*/2 * * * *"
+  contentType: "text/plain"
+  dataBase64: "ZGF0YQ=="
+  sink:
+    ref:
+      apiVersion: serving.knative.dev/v1
+      kind: Service
+      name: event-display
+EOF
+```
+
 ### Verify
 
 View the logs for the `event-display` event consumer by
@@ -136,6 +161,22 @@ Data,
   }
 ```
 
+If you created a PingSource with binary data, you should also see the following:
+
+```shell
+☁️  cloudevents.Event
+Validation: valid
+Context Attributes,
+  specversion: 1.0
+  type: dev.knative.sources.ping
+  source: /apis/v1/namespaces/default/pingsources/test-ping-source-binary
+  id: a195be33-ff65-49af-9045-0e0711d05e94
+  time: 2020-11-17T19:48:00.48334181Z
+  datacontenttype: text/plain
+Data,
+  ZGF0YQ==
+```
+
 ### Cleanup
 
 Delete the `pingsource-example` namespace and all of its resources from your
@@ -147,7 +188,7 @@ kubectl delete namespace pingsource-example
 
 ## Reference Documentation
 
-See the [PingSource specification](../../reference/api/eventing/#sources.knative.dev/v1beta1.PingSource).
+See the [PingSource specification](../../reference/api/eventing/#sources.knative.dev/v1beta2.PingSource).
 
 ## Contact