mirror of https://github.com/knative/docs.git
Edit PingSource docs (#4116)
* Edit PingSource docs * fix trailing whitespace * Link to sink topic * Add status fields * Remove kn command
This commit is contained in:
Samia Nneji
GitHub
parent
46995b865e
commit
66b0be98b7
|
|
@ -102,7 +102,9 @@ nav:
|
|||
- Creating a ContainerSource object: developer/eventing/sources/containersource/README.md
|
||||
- ContainerSource Reference: developer/eventing/sources/containersource/reference.md
|
||||
- Kafka source: developer/eventing/sources/kafka-source/README.md
|
||||
- PingSource: developer/eventing/sources/ping-source/README.md
|
||||
- PingSource:
|
||||
- Creating a PingSource object: developer/eventing/sources/ping-source/README.md
|
||||
- PingSource reference: developer/eventing/sources/ping-source/reference.md
|
||||
- SinkBinding:
|
||||
- Overview: developer/eventing/sources/sinkbinding/README.md
|
||||
- Creating a SinkBinding object: developer/eventing/sources/sinkbinding/getting-started.md
|
||||
|
|
|
|||
|
|
@ -1,143 +1,80 @@
|
|||
---
|
||||
title: "PingSource"
|
||||
weight: 31
|
||||
type: "docs"
|
||||
aliases:
|
||||
- /docs/eventing/sources/pingsource
|
||||
- ../cronjob-source
|
||||
- /docs/eventing/samples/ping-source
|
||||
---
|
||||
# Creating a PingSource object
|
||||
|
||||
# PingSource
|
||||
|
||||
|
||||
|
||||
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](https://en.wikipedia.org/wiki/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.
|
||||
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
|
||||
|
||||
1. To create a PingSource, you must install [Knative Eventing](../../../../eventing/README.md). The PingSource event source type is enabled by default when you install Knative Eventing.
|
||||
1. Optional: You can use either `kubectl` or `kn` commands to create components such as a sink and PingSource. To install `kn`, see [Installing kn](../../../../client/install-kn.md).
|
||||
1. Optional: You can use either `kubectl` or `kail` for logging during the verification step in this procedure. For more information about `kail`, see [kail](https://github.com/boz/kail) in GitHub.
|
||||
To create a PingSource:
|
||||
|
||||
## Procedure
|
||||
- You must install [Knative Eventing](../../../../admin/install/eventing/install-eventing-with-yaml.md).
|
||||
The PingSource event source type is enabled by default when you install Knative Eventing.
|
||||
- You can use either `kubectl` or [`kn`](../../../../client/install-kn.md) commands
|
||||
to create components such as a sink and PingSource.
|
||||
- You can use either `kubectl` or [`kail`](https://github.com/boz/kail) for logging
|
||||
during the verification step in this procedure.
|
||||
|
||||
1. Optional: Create a new namespace called `pingsource-example` by entering the following command:
|
||||
## Create a PingSource object
|
||||
|
||||
1. Optional: Create a namespace for your PingSource by running the command:
|
||||
|
||||
```bash
|
||||
kubectl create namespace pingsource-example
|
||||
kubectl create namespace <namespace>
|
||||
```
|
||||
|
||||
Creating a namespace for the PingSource example allows you to isolate the components created by this demo, so that it is easier for you to view changes and remove components when you are finished.
|
||||
Where `<namespace>` is the namespace that you want your PingSource to use.
|
||||
For example, `pingsource-example`.
|
||||
|
||||
1. To verify that the PingSource is working correctly, create an example sink in the
|
||||
`pingsource-example` namespace that dumps incoming messages to a log:
|
||||
!!! 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.<br><br>
|
||||
It also makes removing the source easier, because you can delete the
|
||||
namespace to remove all of the resources.
|
||||
|
||||
```yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: event-display
|
||||
spec:
|
||||
replicas: 1
|
||||
selector:
|
||||
matchLabels: &labels
|
||||
app: event-display
|
||||
template:
|
||||
metadata:
|
||||
labels: *labels
|
||||
spec:
|
||||
containers:
|
||||
- name: event-display
|
||||
image: gcr.io/knative-releases/knative.dev/eventing-contrib/cmd/event_display
|
||||
1. Create a sink. If you do not have your own sink, you can use the following example Knative Service that dumps incoming messages to a log:
|
||||
|
||||
---
|
||||
|
||||
kind: Service
|
||||
apiVersion: v1
|
||||
metadata:
|
||||
name: event-display
|
||||
spec:
|
||||
selector:
|
||||
app: event-display
|
||||
ports:
|
||||
- protocol: TCP
|
||||
port: 80
|
||||
targetPort: 8080
|
||||
```
|
||||
|
||||
1. Apply the YAML file by running the command:
|
||||
|
||||
```bash
|
||||
kubectl apply -f <filename>.yaml
|
||||
```
|
||||
Where `<filename>` is the name of the file you created in the previous step.
|
||||
|
||||
1. Create a PingSource that sends an event containing `{"message": "Hello world!"}` every minute:
|
||||
|
||||
=== "YAML"
|
||||
|
||||
1. Copy the following YAML into a file:
|
||||
|
||||
```yaml
|
||||
apiVersion: sources.knative.dev/v1
|
||||
kind: PingSource
|
||||
metadata:
|
||||
name: test-ping-source
|
||||
spec:
|
||||
schedule: "*/1 * * * *"
|
||||
contentType: "application/json"
|
||||
data: '{"message": "Hello world!"}'
|
||||
sink:
|
||||
ref:
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
name: event-display
|
||||
```
|
||||
|
||||
1. Apply the YAML file by running the command:
|
||||
|
||||
```bash
|
||||
kubectl apply -f <filename>.yaml
|
||||
```
|
||||
Where `<filename>` is the name of the file you created in the previous step.
|
||||
|
||||
=== "kn"
|
||||
|
||||
- To create the PingSource, run the command:
|
||||
|
||||
```bash
|
||||
kn source ping create test-ping-source \
|
||||
--namespace pingsource-example \
|
||||
--schedule "*/1 * * * *" \
|
||||
--data '{"message": "Hello world!"}' \
|
||||
--sink http://event-display.pingsource-example.svc.cluster.local
|
||||
```
|
||||
|
||||
1. Optional: Create a PingSource that sends binary data.
|
||||
|
||||
If you want to send binary data in an event, this cannot be directly serialized in YAML. However, you can use `dataBase64` in place of `data` in the PingSource spec to carry a data payload that is base64 encoded.
|
||||
|
||||
To create a PingSource that uses base64 encoded data:
|
||||
|
||||
1. Create a YAML file using the following template:
|
||||
1. Copy the YAML below into a file:
|
||||
|
||||
```yaml
|
||||
apiVersion: sources.knative.dev/v1
|
||||
kind: PingSource
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: test-ping-source-binary
|
||||
name: event-display
|
||||
spec:
|
||||
schedule: "*/1 * * * *"
|
||||
contentType: "text/plain"
|
||||
dataBase64: "ZGF0YQ=="
|
||||
sink:
|
||||
ref:
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
name: event-display
|
||||
replicas: 1
|
||||
selector:
|
||||
matchLabels: &labels
|
||||
app: event-display
|
||||
template:
|
||||
metadata:
|
||||
labels: *labels
|
||||
spec:
|
||||
containers:
|
||||
- name: event-display
|
||||
image: gcr.io/knative-releases/knative.dev/eventing-contrib/cmd/event_display
|
||||
|
||||
---
|
||||
|
||||
kind: Service
|
||||
apiVersion: v1
|
||||
metadata:
|
||||
name: event-display
|
||||
spec:
|
||||
selector:
|
||||
app: event-display
|
||||
ports:
|
||||
- protocol: TCP
|
||||
port: 80
|
||||
targetPort: 8080
|
||||
```
|
||||
|
||||
1. Apply the YAML file by running the command:
|
||||
|
|
@ -147,8 +84,121 @@ The following example shows how you can configure a PingSource as an event sourc
|
|||
```
|
||||
Where `<filename>` is the name of the file you created in the previous step.
|
||||
|
||||
1. View the logs for the `event-display` event consumer by
|
||||
entering the following command:
|
||||
1. 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:
|
||||
|
||||
=== "kn"
|
||||
|
||||
- To create a PingSource that sends data that can be represented as
|
||||
plain text, such as text, JSON, or XML, run the command:
|
||||
|
||||
```bash
|
||||
kn source ping create <pingsource-name> \
|
||||
--namespace <namespace> \
|
||||
--schedule "<cron-schedule>" \
|
||||
--data '<data>' \
|
||||
--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.
|
||||
- `<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](https://github.com/knative/client/blob/main/docs/cmd/kn_source_ping_create.md).
|
||||
|
||||
=== "YAML"
|
||||
|
||||
- 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:
|
||||
|
||||
```yaml
|
||||
apiVersion: sources.knative.dev/v1
|
||||
kind: PingSource
|
||||
metadata:
|
||||
name: <pingsource-name>
|
||||
spec:
|
||||
schedule: "<cron-schedule>"
|
||||
contentType: "<content-type>"
|
||||
data: '<data>'
|
||||
sink:
|
||||
ref:
|
||||
apiVersion: v1
|
||||
kind: <sink-kind>
|
||||
name: <sink-name>
|
||||
```
|
||||
Where:
|
||||
|
||||
- `<pingsource-name>` is the name of the PingSource that you want to create, for example, `test-ping-source`.
|
||||
- `<cron-schedule>` is a cron expression for the schedule for the PingSource to send events, for example, `*/1 * * * *` sends an event every minute.
|
||||
- `<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 PodSpecable object that you want to use as a sink, for example, `Service` or `Deployment`. A PodSpecable is an object that describes a PodSpec.
|
||||
- `<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](reference.md).
|
||||
|
||||
1. Apply the YAML file by running the command:
|
||||
|
||||
```bash
|
||||
kubectl apply -f <filename>.yaml
|
||||
```
|
||||
Where `<filename>` is the name of the file you created in the previous step.
|
||||
|
||||
=== "YAML: binary data"
|
||||
|
||||
- To create a PingSource that sends binary data:
|
||||
|
||||
1. Create a YAML file using the template below:
|
||||
|
||||
```yaml
|
||||
apiVersion: sources.knative.dev/v1
|
||||
kind: PingSource
|
||||
metadata:
|
||||
name: <pingsource-name>
|
||||
spec:
|
||||
schedule: "<cron-schedule>"
|
||||
contentType: "<content-type>"
|
||||
dataBase64: "<base64-data>"
|
||||
sink:
|
||||
ref:
|
||||
apiVersion: v1
|
||||
kind: <sink-kind>
|
||||
name: <sink-name>
|
||||
```
|
||||
Where:
|
||||
|
||||
- `<pingsource-name>` is the name of the PingSource that you want to create, for example, `test-ping-source-binary`.
|
||||
- `<cron-schedule>` is a cron expression for the schedule for the PingSource to send events, for example, `*/1 * * * *` sends an event every minute.
|
||||
- `<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 PodSpecable object that you want to use as a sink, for example, `Service` or `Deployment`. A PodSpecable is an object that describes a PodSpec.
|
||||
- `<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](reference.md).
|
||||
|
||||
1. Apply the YAML file by running the command:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
=== "kubectl"
|
||||
|
||||
|
|
@ -163,7 +213,10 @@ entering the following command:
|
|||
kail -l serving.knative.dev/service=event-display -c user-container --since=10m
|
||||
```
|
||||
|
||||
This returns the `Attributes` and `Data` of the events that the PingSource sent to the `event-display` service:
|
||||
1. 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:
|
||||
|
||||
```{ .bash .no-copy }
|
||||
☁️ cloudevents.Event
|
||||
|
|
@ -181,69 +234,47 @@ entering the following command:
|
|||
}
|
||||
```
|
||||
|
||||
If you created a PingSource that sends binary data, you will also see output similar to the following:
|
||||
|
||||
```{ .bash .no-copy }
|
||||
☁️ cloudevents.Event
|
||||
Validation: valid
|
||||
Context Attributes,
|
||||
specversion: 1.0
|
||||
type: dev.knative.sources.ping
|
||||
source: /apis/v1/namespaces/pingsource-example/pingsources/test-ping-source-binary
|
||||
id: ddd7bad2-9b6a-42a7-8f9b-b64494a6ce43
|
||||
time: 2021-03-25T19:38:00.455013472Z
|
||||
datacontenttype: text/plain
|
||||
Data,
|
||||
data
|
||||
```
|
||||
## Delete the PingSource object
|
||||
|
||||
1. Optional: You can delete the `pingsource-example` namespace and all related resources from your cluster by entering the following command:
|
||||
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:
|
||||
|
||||
```bash
|
||||
kubectl delete namespace pingsource-example
|
||||
kubectl delete namespace <namespace>
|
||||
```
|
||||
Where `<namespace>` is the namespace that contains the PingSource object.
|
||||
|
||||
1. Optional: You can also delete the PingSource instance only by entering the following command:
|
||||
|
||||
=== "kubectl"
|
||||
|
||||
```bash
|
||||
kubectl delete pingsources.sources.knative.dev test-ping-source
|
||||
```
|
||||
|
||||
- To delete the PingSource instance only, run the command:
|
||||
|
||||
=== "kn"
|
||||
|
||||
```bash
|
||||
kn source ping delete test-ping-source
|
||||
kn source ping delete <pingsource-name>
|
||||
```
|
||||
|
||||
|
||||
=== "kubectl: binary data PingSource"
|
||||
|
||||
```bash
|
||||
kubectl delete pingsources.sources.knative.dev test-ping-source-binary
|
||||
```
|
||||
|
||||
|
||||
=== "kn: binary data PingSource"
|
||||
|
||||
```bash
|
||||
kn source ping delete test-ping-source-binary
|
||||
```
|
||||
|
||||
1. Optional: Delete the `event-display` service:
|
||||
Where `<pingsource-name>` is the name of the PingSource you want to delete, for example, `test-ping-source`.
|
||||
|
||||
=== "kubectl"
|
||||
|
||||
```bash
|
||||
kubectl delete service.serving.knative.dev event-display
|
||||
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:
|
||||
|
||||
=== "kn"
|
||||
|
||||
```bash
|
||||
kn service delete event-display
|
||||
kn service delete <sink-name>
|
||||
```
|
||||
Where `<sink-name>` is the name of your sink, for example, `event-display`.
|
||||
|
||||
=== "kubectl"
|
||||
|
||||
```bash
|
||||
kubectl delete service.serving.knative.dev <sink-name>
|
||||
```
|
||||
Where `<sink-name>` is the name of your sink, for example, `event-display`.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,78 @@
|
|||
# PingSource reference
|
||||
|
||||
This topic provides reference information about the configurable fields for the
|
||||
PingSource object.
|
||||
|
||||
|
||||
## PingSource
|
||||
|
||||
A PingSource definition supports the following fields:
|
||||
|
||||
| Field | Description | Required or optional |
|
||||
|-------|-------------|----------------------|
|
||||
| [`apiVersion`][kubernetes-overview] | Specifies the API version, for example `sources.knative.dev/v1`. | Required |
|
||||
| [`kind`][kubernetes-overview] | Identifies this resource object as a PingSource object. | Required |
|
||||
| [`metadata`][kubernetes-overview] | Specifies metadata that uniquely identifies the PingSource object. For example, a `name`. | Required |
|
||||
| [`spec`][kubernetes-overview] | Specifies the configuration information for this PingSource object. | Required |
|
||||
| `spec.contentType`| The media type of `data` or `dataBase64`. Default is empty. | Optional |
|
||||
| `spec.data` | The data used as the body of the event posted to the sink. Default is empty. Mutually exclusive with `dataBase64`. | Required if not sending base64 encoded data |
|
||||
| `spec.dataBase64` | A base64-encoded string of the actual event's body posted to the sink. Default is empty. Mutually exclusive with `data`. | Required if sending base64 encoded data |
|
||||
| `spec.schedule` | Specifies the cron schedule. Defaults to `* * * * *`. | Optional |
|
||||
| [`spec.sink`](../../sinks/README.md) | A reference to an object that resolves to a URI to use as the sink. | Required |
|
||||
| `spec.timezone` | Modifies the actual time relative to the specified timezone. Defaults to the system time zone. <br><br> See the [list of valid tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) on Wikipedia. For general information about time zones, see the [IANA](https://www.iana.org/time-zones) website. | Optional |
|
||||
| [`spec.ceOverrides`](#cloudevent-overrides) | Defines overrides to control the output format and modifications to the event sent to the sink. | Optional |
|
||||
| `status`| Defines the observed state of PingSource. | Optional |
|
||||
| `status.observedGeneration` | The 'Generation' of the Service that was last processed by the controller. | Optional |
|
||||
| `status.conditions` | The latest available observations of a resource's current state. | Optional |
|
||||
| `status.sinkUri` | The current active sink URI that has been configured for the Source. | Optional |
|
||||
|
||||
### CloudEvent Overrides
|
||||
|
||||
CloudEvent Overrides defines overrides to control the output format and
|
||||
modifications of the event sent to the sink.
|
||||
|
||||
A `ceOverrides` definition supports the following fields:
|
||||
|
||||
| Field | Description | Required or optional |
|
||||
|-------|-------------|----------------------|
|
||||
| `extensions` | Specifies which attributes are added or overridden on the outbound event. Each `extensions` key-value pair is set independently on the event as an attribute extension. | Optional |
|
||||
|
||||
!!! note
|
||||
Only valid [CloudEvent attribute names][cloudevents-attribute-naming]
|
||||
are allowed as extensions. You cannot set the spec defined attributes from
|
||||
the extensions override configuration. For example, you can not modify the
|
||||
`type` attribute.
|
||||
|
||||
#### Example: CloudEvent Overrides
|
||||
|
||||
```yaml
|
||||
apiVersion: sources.knative.dev/v1
|
||||
kind: PingSource
|
||||
metadata:
|
||||
name: test-heartbeats
|
||||
spec:
|
||||
...
|
||||
ceOverrides:
|
||||
extensions:
|
||||
extra: this is an extra attribute
|
||||
additional: 42
|
||||
```
|
||||
|
||||
!!! contract
|
||||
This results in the `K_CE_OVERRIDES` environment variable being set on the
|
||||
`subject` as follows: <!-- unsure about this -->
|
||||
```{ .json .no-copy }
|
||||
{ "extensions": { "extra": "this is an extra attribute", "additional": "42" } }
|
||||
```
|
||||
|
||||
|
||||
[kubernetes-overview]:
|
||||
https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields
|
||||
[kubernetes-kinds]:
|
||||
https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
|
||||
[kubernetes-names]:
|
||||
https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
|
||||
[kubernetes-namespaces]:
|
||||
https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/
|
||||
[cloudevents-attribute-naming]:
|
||||
https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#attribute-naming-convention
|
||||
Loading…
Reference in New Issue