mirror of https://github.com/knative/docs.git
Updating ContainerSource, Sources list, and migration example (#2342)
* updates to sources. * update * Update docs/eventing/README.md Co-Authored-By: Matt Moore <mattmoor@vmware.com> * Update docs/eventing/README.md Co-Authored-By: Matt Moore <mattmoor@vmware.com> * Update docs/eventing/README.md Co-Authored-By: Matt Moore <mattmoor@vmware.com> * Update docs/eventing/migration/sinkbinding.md Co-Authored-By: Matt Moore <mattmoor@vmware.com> * Update docs/eventing/README.md Co-Authored-By: Matt Moore <mattmoor@vmware.com> * Update docs/eventing/README.md Co-Authored-By: Matt Moore <mattmoor@vmware.com> * updates * Update docs/eventing/migration/sinkbinding.md Co-Authored-By: Matt Moore <mattmoor@vmware.com> * added Co-authored-by: Matt Moore <mattmoor@vmware.com>
This commit is contained in:
Ignacio (Nacho) Cano
GitHub
parent
6b5971327e
commit
3c5fa60c75
|
|
@ -137,17 +137,13 @@ messaging protocols.
|
||||||
|
|
||||||
Each source is a separate Kubernetes custom resource. This allows each type of
|
Each source is a separate Kubernetes custom resource. This allows each type of
|
||||||
Source to define the arguments and parameters needed to instantiate a source.
|
Source to define the arguments and parameters needed to instantiate a source.
|
||||||
Knative Eventing defines the following Sources in the
|
All Sources should be part of the `sources` category, so you can list all existing Sources with
|
||||||
`sources.eventing.knative.dev` API group. Types below are declared in golang
|
`kubectl get sources`.
|
||||||
format, but may be expressed as simple lists, etc in YAML. All Sources should be
|
|
||||||
part of the `sources` category, so you can list all existing Sources with
|
|
||||||
`kubectl get sources`. The currently-implemented Sources are described below.
|
|
||||||
|
|
||||||
In addition to the core sources (explained below), there are
|
In addition to the sources explained below, there are
|
||||||
[other sources](./sources/README.md) that you can install.
|
[other sources](./sources/README.md) that you can install.
|
||||||
|
If you need a Source not covered by the ones mentioned below nor by the other
|
||||||
If you need a Source not covered by the
|
[available implementations](./sources/README.md), there is a
|
||||||
[available Source implementations](./sources/README.md), there is a
|
|
||||||
[tutorial on writing your own Source with kubebuilder](./samples/writing-a-source/README.md) as
|
[tutorial on writing your own Source with kubebuilder](./samples/writing-a-source/README.md) as
|
||||||
well as an
|
well as an
|
||||||
[extended tutorial on writing a Source with Receive Adapter](./samples/writing-receive-adapter-source).
|
[extended tutorial on writing a Source with Receive Adapter](./samples/writing-receive-adapter-source).
|
||||||
|
|
@ -156,216 +152,67 @@ If your code needs to send events as part of its business logic and doesn't fit
|
||||||
the model of a Source, consider
|
the model of a Source, consider
|
||||||
[feeding events directly to a Broker](https://knative.dev/docs/eventing/broker-trigger/#manual).
|
[feeding events directly to a Broker](https://knative.dev/docs/eventing/broker-trigger/#manual).
|
||||||
|
|
||||||
### APIServerSource
|
### Core Sources
|
||||||
|
|
||||||
|
These are the core sources that come out-of-the-box when installing Knative Eventing.
|
||||||
|
|
||||||
|
#### APIServerSource
|
||||||
|
|
||||||
The APIServerSource fires a new event each time a Kubernetes resource is created, updated or deleted.
|
The APIServerSource fires a new event each time a Kubernetes resource is created, updated or deleted.
|
||||||
|
|
||||||
See the [Kubernetes API Server Source](samples/kubernetes-event-source) example.
|
See the [Kubernetes API Server Source](samples/kubernetes-event-source) example for more details.
|
||||||
|
|
||||||
### GitHubSource
|
#### PingSource
|
||||||
|
|
||||||
|
The PingSource fires events based on given
|
||||||
|
[Cron](https://en.wikipedia.org/wiki/Cron) schedule.
|
||||||
|
|
||||||
|
See the [Ping Source](samples/ping-source) example for more details.
|
||||||
|
|
||||||
|
#### ContainerSource
|
||||||
|
|
||||||
|
The ContainerSource will instantiate container image(s) that can generate events
|
||||||
|
until the ContainerSource is deleted. This may be used (for example) to poll an
|
||||||
|
FTP server for new files or generate events at a set time interval.
|
||||||
|
|
||||||
|
Refer to the [Container Source](samples/container-source) example for more details.
|
||||||
|
|
||||||
|
#### SinkBinding
|
||||||
|
|
||||||
|
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).
|
||||||
|
|
||||||
|
See the [SinkBinding](samples/container-source) example for more details.
|
||||||
|
|
||||||
|
### Eventing Contrib Sources
|
||||||
|
|
||||||
|
This is a non-exhaustive list of Sources supported by our community and maintained
|
||||||
|
in the [Knative Eventing-Contrib](https://github.com/knative/eventing-contrib) Github repo.
|
||||||
|
|
||||||
|
#### GitHubSource
|
||||||
|
|
||||||
The GitHubSource fires a new event for selected
|
The GitHubSource fires a new event for selected
|
||||||
[GitHub event types](https://developer.github.com/v3/activity/events/types/).
|
[GitHub event types](https://developer.github.com/v3/activity/events/types/).
|
||||||
|
|
||||||
**Spec fields**:
|
See the [GitHub Source](samples/github-source) example for more details.
|
||||||
|
|
||||||
- `ownerAndRepository`: `string` The GitHub owner/org and repository to receive
|
#### AwsSqsSource
|
||||||
events from. The repository may be left off to receive events from an entire
|
|
||||||
organization.
|
|
||||||
- `eventTypes`: `[]string` A list of
|
|
||||||
[event types](https://developer.github.com/v3/activity/events/types/) in
|
|
||||||
"Webhook event name" format (lower_case).
|
|
||||||
- `accessToken.secretKeyRef`:
|
|
||||||
[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#secretkeyselector-v1-core)
|
|
||||||
containing a GitHub access token for configuring a GitHub webhook. One of this
|
|
||||||
or `secretToken` must be set.
|
|
||||||
- `secretToken.secretKeyRef`:
|
|
||||||
[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#secretkeyselector-v1-core)
|
|
||||||
containing a GitHub secret token for configuring a GitHub webhook. One of this
|
|
||||||
or `accessToken` must be set.
|
|
||||||
- `serviceAccountName`: `string` The name of the ServiceAccount to run the
|
|
||||||
container as.
|
|
||||||
- `sink`:
|
|
||||||
[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#objectreference-v1-core)
|
|
||||||
A reference to the object that should receive events.
|
|
||||||
- `githubAPIURL`: `string` Optional field to specify the base URL for API
|
|
||||||
requests. Defaults to the public GitHub API if not specified, but can be set
|
|
||||||
to a domain endpoint to use with GitHub Enterprise, for example,
|
|
||||||
`https://github.mycompany.com/api/v3/`. This base URL should always be
|
|
||||||
specified with a trailing slash.
|
|
||||||
|
|
||||||
See the [GitHub Source](samples/github-source) example.
|
|
||||||
|
|
||||||
### CloudPubSubSource
|
|
||||||
|
|
||||||
The CloudPubSubSource fires a new event each time a message is published on a
|
|
||||||
[Google Cloud Platform PubSub topic](https://cloud.google.com/pubsub/).
|
|
||||||
|
|
||||||
**Spec fields**:
|
|
||||||
|
|
||||||
- `topic`: `string` The name of the PubSub topic.
|
|
||||||
- `sink`:
|
|
||||||
[Destination](https://github.com/knative/pkg/blob/master/apis/duck/v1/destination.go)
|
|
||||||
A reference to the target that should receive events.
|
|
||||||
- `secret`:
|
|
||||||
[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#secretkeyselector-v1-core)
|
|
||||||
Credential to use to poll the Cloud Pub/Sub Subscription. It is not used to create or delete the Subscription, only to poll it.
|
|
||||||
The value of the secret entry must be a service account key in the JSON format (see https://cloud.google.com/iam/docs/creating-managing-service-account-keys). Defaults to secret.name of 'google-cloud-key' and secret.key of 'key.json'.
|
|
||||||
- `project`: `string` ID of the Google Cloud Project that the Pub/Sub Topic exists in. If omitted uses the Project ID from the GKE cluster metadata service.
|
|
||||||
|
|
||||||
See the [CloudPubSubSource](samples/cloud-pubsub-source) example.
|
|
||||||
|
|
||||||
### CloudStorageSource
|
|
||||||
|
|
||||||
Registers for events of the specified types on the specified
|
|
||||||
[Google Cloud Storage](https://cloud.google.com/storage/) bucket and optional object prefix.
|
|
||||||
Brings those events into Knative.
|
|
||||||
|
|
||||||
**Spec fields**:
|
|
||||||
|
|
||||||
- `bucket`: `string` GCS bucket to subscribe to. For example my-test-bucket.
|
|
||||||
- `sink`:
|
|
||||||
[Destination](https://github.com/knative/pkg/blob/master/apis/duck/v1/destination.go)
|
|
||||||
A reference to the target that should receive events.
|
|
||||||
- `secret`:
|
|
||||||
[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#secretkeyselector-v1-core)
|
|
||||||
Credential to use for managing GCS notifications.
|
|
||||||
The value of the secret entry must be a service account key in the JSON format (see https://cloud.google.com/iam/docs/creating-managing-service-account-keys). Defaults to secret.name of 'google-cloud-key' and secret.key of 'key.json'.
|
|
||||||
- `project`: `string` ID of the Google Cloud Project that the Pub/Sub Topic exists in. If omitted uses the Project ID from the GKE cluster metadata service.
|
|
||||||
|
|
||||||
See the [CloudStorageSource](samples/cloud-storage-source) example.
|
|
||||||
|
|
||||||
### CloudSchedulerSource
|
|
||||||
|
|
||||||
Create, update, and delete [Google Cloud Scheduler](https://cloud.google.com/scheduler/) Jobs.
|
|
||||||
When those jobs are triggered, receive the event inside Knative.
|
|
||||||
|
|
||||||
**Spec fields**:
|
|
||||||
|
|
||||||
- `location`: `string` Location to create the Scheduler job in.
|
|
||||||
- `data`: `string` Data to send in the payload of the Event.
|
|
||||||
- `schedule`: `string` Frequency using the unix-cron format. Or App Engine Cron format.
|
|
||||||
- `sink`:
|
|
||||||
[Destination](https://github.com/knative/pkg/blob/master/apis/duck/v1/destination.go)
|
|
||||||
A reference to the target that should receive events.
|
|
||||||
- `secret`:
|
|
||||||
[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#secretkeyselector-v1-core)
|
|
||||||
Credential to use for managing Scheduler Jobs.
|
|
||||||
The value of the secret entry must be a service account key in the JSON format (see https://cloud.google.com/iam/docs/creating-managing-service-account-keys). Defaults to secret.name of 'google-cloud-key' and secret.key of 'key.json'.
|
|
||||||
- `project`: `string` ID of the Google Cloud Project that the Pub/Sub Topic exists in. If omitted uses the Project ID from the GKE cluster metadata service.
|
|
||||||
|
|
||||||
See the [CloudSchedulerSource](samples/cloud-scheduler-source) example.
|
|
||||||
|
|
||||||
### CloudAuditLogsSource
|
|
||||||
|
|
||||||
Registers for events of the specified types on the specified [Google Cloud Audit Logs](https://cloud.google.com/logging/docs/audit/). Brings those events into Knative.
|
|
||||||
|
|
||||||
**Spec fields**:
|
|
||||||
|
|
||||||
- `serviceName`: `string` The GCP service providing audit logs.
|
|
||||||
- `methodName`: `string` The name of the service method or operation. For API calls, this should be the name of the API method.
|
|
||||||
- `resourceName`: `string` The resource or collection that is the target of the operation. The name is a scheme-less URI, not including the API service name. If omitted, audit log events matching service and method will be pulled for all resources.
|
|
||||||
- `sink`:
|
|
||||||
[Destination](https://github.com/knative/pkg/blob/master/apis/duck/v1/destination.go)
|
|
||||||
A reference to the target that should receive events.
|
|
||||||
- `secret`:
|
|
||||||
[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#secretkeyselector-v1-core)
|
|
||||||
Credential used to pull Stackdriver audit log pubsub messages.
|
|
||||||
The value of the secret entry must be a service account key in the JSON format (see https://cloud.google.com/iam/docs/creating-managing-service-account-keys). Defaults to secret.name of 'google-cloud-key' and secret.key of 'key.json'.
|
|
||||||
- `project`: `string` ID of the Google Cloud Project that the Pub/Sub Topic exists in. If omitted uses the Project ID from the GKE cluster metadata service.
|
|
||||||
|
|
||||||
See the [CloudAuditLogsSource](samples/cloud-audit-logs-source) example.
|
|
||||||
|
|
||||||
### AwsSqsSource
|
|
||||||
|
|
||||||
The AwsSqsSource fires a new event each time an event is published on an
|
The AwsSqsSource fires a new event each time an event is published on an
|
||||||
[AWS SQS topic](https://aws.amazon.com/sqs/).
|
[AWS SQS topic](https://aws.amazon.com/sqs/).
|
||||||
|
|
||||||
**Spec fields**:
|
#### KafkaSource
|
||||||
|
|
||||||
- `queueURL`: URL of the SQS queue to pull events from.
|
|
||||||
- `awsCredsSecret`: credential to use to poll the AWS SQS queue.
|
|
||||||
- `sink`:
|
|
||||||
[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#objectreference-v1-core)
|
|
||||||
A reference to the object that should receive events.
|
|
||||||
- `serviceAccountName`: `string` The name of the ServiceAccount used to access
|
|
||||||
the `awsCredsSecret`.
|
|
||||||
|
|
||||||
### ContainerSource
|
|
||||||
|
|
||||||
The ContainerSource will instantiate a container image which can generate events
|
|
||||||
until the ContainerSource is deleted. This may be used (for example) to poll an
|
|
||||||
FTP server for new files or generate events at a set time interval.
|
|
||||||
|
|
||||||
**Spec fields**:
|
|
||||||
|
|
||||||
- `image` (**required**): `string` A docker image of the container to be run.
|
|
||||||
- `args`: `[]string` Command-line arguments. If no `--sink` flag is provided,
|
|
||||||
one will be added and filled in with the DNS address of the `sink` object.
|
|
||||||
- `env`: `map[string]string` Environment variables to be set in the container.
|
|
||||||
- `serviceAccountName`: `string` The name of the ServiceAccount to run the
|
|
||||||
container as.
|
|
||||||
- `sink`:
|
|
||||||
[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#objectreference-v1-core)
|
|
||||||
A reference to the object that should receive events.
|
|
||||||
|
|
||||||
### CronJobSource
|
|
||||||
|
|
||||||
The CronJobSource fires events based on given
|
|
||||||
[Cron](https://en.wikipedia.org/wiki/Cron) schedule.
|
|
||||||
|
|
||||||
**Spec fields**:
|
|
||||||
|
|
||||||
- `schedule` (**required**): `string` A
|
|
||||||
[Cron](https://en.wikipedia.org/wiki/Cron) format string, such as `0 * * * *`
|
|
||||||
or `@hourly`.
|
|
||||||
- `data`: `string` Optional data sent to downstream receiver.
|
|
||||||
- `serviceAccountName`: `string` The name of the ServiceAccount to run the
|
|
||||||
container as.
|
|
||||||
- `sink`:
|
|
||||||
[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#objectreference-v1-core)
|
|
||||||
A reference to the object that should receive events.
|
|
||||||
|
|
||||||
See the [Cronjob Source](samples/cronjob-source) example.
|
|
||||||
|
|
||||||
### KafkaSource
|
|
||||||
|
|
||||||
The KafkaSource reads events from an Apache Kafka Cluster, and passes these to a
|
The KafkaSource reads events from an Apache Kafka Cluster, and passes these to a
|
||||||
Knative Serving application so that they can be consumed.
|
Knative Serving application so that they can be consumed.
|
||||||
|
|
||||||
**Spec fields**:
|
|
||||||
|
|
||||||
- `consumerGroup`: `string` Name of a Kafka consumer group.
|
|
||||||
- `bootstrapServers`: `string` Comma separated list of `hostname:port` pairs for
|
|
||||||
the Kafka Broker.
|
|
||||||
- `topics`: `string` Name of the Kafka topic to consume messages from.
|
|
||||||
- `net`: Optional network configuration.
|
|
||||||
- `sasl`: Optional SASL authentication configuration.
|
|
||||||
- `enable`: `boolean` If true, use SASL for authentication.
|
|
||||||
- `user.secretKeyRef`:
|
|
||||||
[`SecretKeySelector`](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#secretkeyselector-v1-core)
|
|
||||||
containing the SASL username to use.
|
|
||||||
- `password.secretKeyRef`:
|
|
||||||
[`SecretKeySelector`](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#secretkeyselector-v1-core)
|
|
||||||
containing the SASL password to use.
|
|
||||||
- `tls`: Optional TLS configuration.
|
|
||||||
- `enable`: `boolean` If true, use TLS when connecting.
|
|
||||||
- `cert.secretKeyRef`:
|
|
||||||
[`SecretKeySelector`](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#secretkeyselector-v1-core)
|
|
||||||
containing the client certificate to use.
|
|
||||||
- `key.secretKeyRef`:
|
|
||||||
[`SecretKeySelector`](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#secretkeyselector-v1-core)
|
|
||||||
containing the client key to use.
|
|
||||||
- `caCert.secretKeyRef`:
|
|
||||||
[`SecretKeySelector`](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#secretkeyselector-v1-core)
|
|
||||||
containing a server CA certificate to use when verifying the server
|
|
||||||
certificate.
|
|
||||||
|
|
||||||
See the
|
See the
|
||||||
[Kafka Source](https://github.com/knative/eventing-contrib/tree/master/kafka/source)
|
[Kafka Source](https://github.com/knative/eventing-contrib/tree/master/kafka/source)
|
||||||
example.
|
example for more details.
|
||||||
|
|
||||||
### CamelSource
|
#### CamelSource
|
||||||
|
|
||||||
A CamelSource is an event source that can represent any existing
|
A CamelSource is an event source that can represent any existing
|
||||||
[Apache Camel component](https://github.com/apache/camel/tree/master/components)
|
[Apache Camel component](https://github.com/apache/camel/tree/master/components)
|
||||||
|
|
@ -374,34 +221,49 @@ endpoint. Each Camel endpoint has the form of a URI where the scheme is the ID
|
||||||
of the component to use.
|
of the component to use.
|
||||||
|
|
||||||
CamelSource requires [Camel-K](https://github.com/apache/camel-k#installation)
|
CamelSource requires [Camel-K](https://github.com/apache/camel-k#installation)
|
||||||
to be installed into the current namespace.
|
to be installed into the current namespace. See the
|
||||||
|
|
||||||
**Spec fields**:
|
|
||||||
|
|
||||||
- source: information on the kind of Camel source that should be created.
|
|
||||||
- component: the default kind of source, enables creating an EventSource by
|
|
||||||
configuring a single Camel component.
|
|
||||||
- uri: `string` contains the Camel URI that should be used to push events
|
|
||||||
into the target sink.
|
|
||||||
- properties: `key/value map` contains Camel global options or component
|
|
||||||
specific configuration. Options are available in the documentation of each
|
|
||||||
existing Apache Camel component.
|
|
||||||
- serviceAccountName: `string` an optional service account that can be used to
|
|
||||||
run the source pod.
|
|
||||||
- image: `string` an optional base image to use for the source pod, mainly for
|
|
||||||
development purposes.
|
|
||||||
|
|
||||||
See the
|
|
||||||
[CamelSource](https://github.com/knative/eventing-contrib/tree/master/camel/source/samples)
|
[CamelSource](https://github.com/knative/eventing-contrib/tree/master/camel/source/samples)
|
||||||
example.
|
example.
|
||||||
|
|
||||||
|
### Google Cloud Sources
|
||||||
|
|
||||||
|
In order to consume events from different GCP services, [Knative-GCP](https://github.com/google/knative-gcp) supports
|
||||||
|
different GCP Sources.
|
||||||
|
|
||||||
|
#### CloudPubSubSource
|
||||||
|
|
||||||
|
The CloudPubSubSource fires a new event each time a message is published on a
|
||||||
|
[Google Cloud Platform PubSub topic](https://cloud.google.com/pubsub/).
|
||||||
|
|
||||||
|
See the [CloudPubSubSource](samples/cloud-pubsub-source) example for more details.
|
||||||
|
|
||||||
|
#### CloudStorageSource
|
||||||
|
|
||||||
|
Registers for events of specific types on the specified
|
||||||
|
[Google Cloud Storage](https://cloud.google.com/storage/) bucket and optional object prefix.
|
||||||
|
Brings those events into Knative.
|
||||||
|
|
||||||
|
See the [CloudStorageSource](samples/cloud-storage-source) example.
|
||||||
|
|
||||||
|
#### CloudSchedulerSource
|
||||||
|
|
||||||
|
Creates, updates, and deletes [Google Cloud Scheduler](https://cloud.google.com/scheduler/) Jobs.
|
||||||
|
When those jobs are triggered, receive the event inside Knative.
|
||||||
|
|
||||||
|
See the [CloudSchedulerSource](samples/cloud-scheduler-source) example for further details.
|
||||||
|
|
||||||
|
#### CloudAuditLogsSource
|
||||||
|
|
||||||
|
Registers for events of specific types on the specified [Google Cloud Audit Logs](https://cloud.google.com/logging/docs/audit/).
|
||||||
|
Brings those events into Knative.
|
||||||
|
|
||||||
|
Refer to the [CloudAuditLogsSource](samples/cloud-audit-logs-source) example for more details.
|
||||||
|
|
||||||
|
|
||||||
## Getting Started
|
## Getting Started
|
||||||
|
|
||||||
- [Setup Knative Serving](../install/README.md)
|
|
||||||
- [Install the Eventing component](#installation)
|
- [Install the Eventing component](#installation)
|
||||||
|
- [Setup Knative Serving](../install/README.md)
|
||||||
- [Run samples](./samples/)
|
- [Run samples](./samples/)
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
- [Default Channels](./channels/default-channels.md) provide a way to choose the
|
- [Default Channels](./channels/default-channels.md) provide a way to choose the
|
||||||
persistence strategy for Channels across the cluster.
|
persistence strategy for Channels across the cluster.
|
||||||
|
|
|
||||||
|
|
@ -1,3 +1,6 @@
|
||||||
Knative Eventing in version 0.13 does deprecate a few resources. This document provides a collection of migration examples:
|
Knative Eventing in version 0.13 does deprecate a few resources and
|
||||||
|
introduces new constructs for fine-grained control
|
||||||
|
over underlying resources.
|
||||||
|
This document provides a collection of such examples:
|
||||||
* [PingSource](./ping.md) migration from `CronJobSource`.
|
* [PingSource](./ping.md) migration from `CronJobSource`.
|
||||||
* [SinkBinding](./sinkbinding.md) migration from `ContainerSource`.
|
* [SinkBinding](./sinkbinding.md) alternative to `ContainerSource`.
|
||||||
|
|
|
||||||
|
|
@ -1,88 +1,101 @@
|
||||||
---
|
---
|
||||||
title: "Migrating from ContainerSource to SinkBinding"
|
title: "SinkBinding alternative to ContainerSource"
|
||||||
weight: 20
|
weight: 20
|
||||||
type: "docs"
|
type: "docs"
|
||||||
aliases:
|
aliases:
|
||||||
- /docs/eventing/ping.md
|
- /docs/eventing/sinkbinding.md
|
||||||
---
|
---
|
||||||
|
|
||||||
The deprecated `ContainerSource` should be converted to a `SinkBinding`.
|
`ContainerSource` can be seen as the combination of
|
||||||
|
`SinkBinding`+`Deployment`. In fact, that
|
||||||
|
is exactly how it's implemented!
|
||||||
|
|
||||||
The YAML file for a `ContainerSource` that emits events to a Knative Serving service will look similar to this:
|
In YAML, these two options are equivalent:
|
||||||
|
|
||||||
```yaml
|
1. `ContainerSource` that emits events to a `Knative Service`:
|
||||||
apiVersion: sources.eventing.knative.dev/v1alpha1
|
|
||||||
kind: ContainerSource
|
|
||||||
metadata:
|
|
||||||
name: urbanobservatory-event-source
|
|
||||||
spec:
|
|
||||||
image: quay.io/openshift-knative/knative-eventing-sources-websocketsource:latest
|
|
||||||
args:
|
|
||||||
- '--source=wss://api.usb.urbanobservatory.ac.uk/stream'
|
|
||||||
- '--eventType=my.custom.event'
|
|
||||||
sink:
|
|
||||||
apiVersion: serving.knative.dev/v1
|
|
||||||
kind: Service
|
|
||||||
name: wss-event-display
|
|
||||||
```
|
|
||||||
|
|
||||||
The referenced image of the `ContainerSource` needed an "sink" argument, [see](https://knative.dev/docs/eventing/#containersource) for details.
|
```yaml
|
||||||
|
apiVersion: sources.knative.dev/v1alpha2
|
||||||
|
kind: ContainerSource
|
||||||
|
metadata:
|
||||||
|
name: urbanobservatory-event-source
|
||||||
|
spec:
|
||||||
|
template:
|
||||||
|
spec:
|
||||||
|
containers:
|
||||||
|
- image: quay.io/openshift-knative/knative-eventing-sources-websocketsource:latest
|
||||||
|
args:
|
||||||
|
- '--source=wss://api.usb.urbanobservatory.ac.uk/stream'
|
||||||
|
- '--eventType=my.custom.event'
|
||||||
|
sink:
|
||||||
|
ref:
|
||||||
|
apiVersion: serving.knative.dev/v1
|
||||||
|
kind: Service
|
||||||
|
name: wss-event-display
|
||||||
|
```
|
||||||
|
|
||||||
To migrate this source to a `SinkBinding`, a few steps are required. Instead of using a `ContainerSource`,
|
2. `SinkBinding` + `Deployment`. Something like the following:
|
||||||
you need to create a `SinkBinding`, like:
|
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
apiVersion: sources.knative.dev/v1alpha2
|
apiVersion: sources.knative.dev/v1alpha2
|
||||||
kind: SinkBinding
|
kind: SinkBinding
|
||||||
metadata:
|
metadata:
|
||||||
name: bind-wss
|
name: bind-wss
|
||||||
spec:
|
spec:
|
||||||
subject:
|
subject:
|
||||||
|
apiVersion: apps/v1
|
||||||
|
kind: Deployment
|
||||||
|
selector:
|
||||||
|
matchLabels:
|
||||||
|
app: wss
|
||||||
|
sink:
|
||||||
|
ref:
|
||||||
|
apiVersion: serving.knative.dev/v1
|
||||||
|
kind: Service
|
||||||
|
name: wss-event-display
|
||||||
|
```
|
||||||
|
|
||||||
|
Here the `SinkBinding`'s `subject` references to a Kubernetes
|
||||||
|
`Deployment`, that is labeled with `app: wss`. This is done with
|
||||||
|
the `subject.selector` field, which is a standard Kubernetes
|
||||||
|
Label Selector object. Note that you could explicitly set a
|
||||||
|
`Deployment` name and namespace in `subject` (i.e., `subject.name`
|
||||||
|
and `subject.namespace`) instead of using `subject.selector`.
|
||||||
|
The YAML for the `Deployment` looks like:
|
||||||
|
|
||||||
|
```yaml
|
||||||
apiVersion: apps/v1
|
apiVersion: apps/v1
|
||||||
kind: Deployment
|
kind: Deployment
|
||||||
selector:
|
|
||||||
matchLabels:
|
|
||||||
app: wss
|
|
||||||
sink:
|
|
||||||
ref:
|
|
||||||
apiVersion: serving.knative.dev/v1
|
|
||||||
kind: Service
|
|
||||||
name: wss-event-display
|
|
||||||
```
|
|
||||||
|
|
||||||
Here the `SinkBinding`'s `subject` references to a Kubernetes `Deployment`, that is labeled with `app: wss`. The YAML for the `Deployment`
|
|
||||||
looks like:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
apiVersion: apps/v1
|
|
||||||
kind: Deployment
|
|
||||||
metadata:
|
|
||||||
name: wss
|
|
||||||
labels:
|
|
||||||
app: wss
|
|
||||||
spec:
|
|
||||||
selector:
|
|
||||||
matchLabels:
|
|
||||||
app: wss
|
|
||||||
template:
|
|
||||||
metadata:
|
metadata:
|
||||||
|
name: wss
|
||||||
labels:
|
labels:
|
||||||
app: wss
|
app: wss
|
||||||
spec:
|
spec:
|
||||||
containers:
|
selector:
|
||||||
- image: quay.io/openshift-knative/knative-eventing-sources-websocketsource:latest
|
matchLabels:
|
||||||
name: wss
|
app: wss
|
||||||
args:
|
template:
|
||||||
- '--source=wss://api.usb.urbanobservatory.ac.uk/stream'
|
metadata:
|
||||||
- '--eventType=my.custom.event'
|
labels:
|
||||||
```
|
app: wss
|
||||||
|
spec:
|
||||||
|
containers:
|
||||||
|
- image: quay.io/openshift-knative/knative-eventing-sources-websocketsource:latest
|
||||||
|
name: wss
|
||||||
|
args:
|
||||||
|
- '--source=wss://api.usb.urbanobservatory.ac.uk/stream'
|
||||||
|
- '--eventType=my.custom.event'
|
||||||
|
```
|
||||||
|
|
||||||
The `Deployment` is a standard Kubernetes Deployment, like you might have used before. However, the important part here is that it has the `app: wss`
|
The `Deployment` is a standard Kubernetes Deployment, like you might have used before. However, the important part
|
||||||
label, which is needed by the above `SinkBinding` in order to _bind_ the two components together.
|
here is that it has the `app: wss` label, which is needed by the above `SinkBinding` in order to _bind_ the
|
||||||
|
two components together.
|
||||||
|
|
||||||
The `image` that is used by the `Deployment` is required to understands the semantics of the `K_SINK` environment variable, holding the endpoint to which to send cloud events. The `K_SINK` environment variable is part of the `SinkBinding`'s runtime contract of the [referenced container image](https://knative.dev/docs/reference/eventing/#sources.knative.dev/v1alpha2.SinkBinding).
|
In both cases, the `image` is required to understand
|
||||||
|
the semantics of the `K_SINK` environment variable, which holds
|
||||||
|
the destination endpoint for sending CloudEvents.
|
||||||
|
|
||||||
Running the above example will give a log like:
|
Running any of the above examples will give a log similar to:
|
||||||
|
|
||||||
```
|
```
|
||||||
☁️ cloudevents.Event
|
☁️ cloudevents.Event
|
||||||
|
|
@ -96,3 +109,13 @@ Context Attributes,
|
||||||
Data,
|
Data,
|
||||||
{"signal":2,"data":{"brokerage":{"broker":{"id":"BMS-USB-5-JACE","meta":{"protocol":"BACNET","building":"Urban Sciences Building","buildingFloor":"5"}},"id":"Drivers.L6_C3_Electric_Meters.C3_Mechcanical_Plant.points.C3_HP_Current_L1","meta":{}},"entity":{"name":"Urban Sciences Building: Floor 5","meta":{"building":"Urban Sciences Building","buildingFloor":"5"}},"feed":{"metric":"C3 HP Current L1","meta":{}},"timeseries":{"unit":"no units","value":{"time":"2020-03-05T13:45:51.468Z","timeAccuracy":8.754,"data":0.47110211849212646,"type":"Real"}}},"recipients":0}
|
{"signal":2,"data":{"brokerage":{"broker":{"id":"BMS-USB-5-JACE","meta":{"protocol":"BACNET","building":"Urban Sciences Building","buildingFloor":"5"}},"id":"Drivers.L6_C3_Electric_Meters.C3_Mechcanical_Plant.points.C3_HP_Current_L1","meta":{}},"entity":{"name":"Urban Sciences Building: Floor 5","meta":{"building":"Urban Sciences Building","buildingFloor":"5"}},"feed":{"metric":"C3 HP Current L1","meta":{}},"timeseries":{"unit":"no units","value":{"time":"2020-03-05T13:45:51.468Z","timeAccuracy":8.754,"data":0.47110211849212646,"type":"Real"}}},"recipients":0}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## When to use SinkBinding?
|
||||||
|
|
||||||
|
From the above options, `ContainerSource` is probably the less
|
||||||
|
verbose.
|
||||||
|
However, the true power of `SinkBinding` comes from the fact that
|
||||||
|
it can work not just with `Deployments`
|
||||||
|
but with **any** PodSpecable (e.g., `StatefulSet`, `ReplicateSet`,
|
||||||
|
`DaemonSet`, `Knative Service`, etc.).
|
||||||
|
If you do need that flexibility, we highly recommend you to use `SinkBinding`.
|
||||||
|
|
|
||||||
|
|
@ -82,7 +82,7 @@ file. Note that arguments and environment variables are set and will be passed
|
||||||
to the container.
|
to the container.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
apiVersion: sources.eventing.knative.dev/v1alpha1
|
apiVersion: sources.knative.dev/v1alpha2
|
||||||
kind: ContainerSource
|
kind: ContainerSource
|
||||||
metadata:
|
metadata:
|
||||||
name: test-heartbeats
|
name: test-heartbeats
|
||||||
|
|
@ -129,7 +129,7 @@ message sent by the heartbeats source to the display function:
|
||||||
☁️ cloudevents.Event
|
☁️ cloudevents.Event
|
||||||
Validation: valid
|
Validation: valid
|
||||||
Context Attributes,
|
Context Attributes,
|
||||||
specversion: 0.3
|
specversion: 1.0
|
||||||
type: dev.knative.eventing.samples.heartbeat
|
type: dev.knative.eventing.samples.heartbeat
|
||||||
source: https://knative.dev/eventing-contrib/cmd/heartbeats/#event-test/mypod
|
source: https://knative.dev/eventing-contrib/cmd/heartbeats/#event-test/mypod
|
||||||
id: 2b72d7bf-c38f-4a98-a433-608fbcdd2596
|
id: 2b72d7bf-c38f-4a98-a433-608fbcdd2596
|
||||||
|
|
@ -160,11 +160,9 @@ any tools you like. Here are some basic guidelines:
|
||||||
- The container image must have a `main` method to start with.
|
- The container image must have a `main` method to start with.
|
||||||
- The `main` method will accept parameters from arguments and environment
|
- The `main` method will accept parameters from arguments and environment
|
||||||
variables.
|
variables.
|
||||||
- The arguments may include a `sink` if a flag `--sink` is set or a Sink object
|
- Two environments variables will be injected by the `ContainerSource` controller,
|
||||||
is provided in the ContainerSource YAML file.
|
`K_SINK` and `K_CE_OVERRIDES`, resolved from `spec.sink` and `spec.ceOverrides` respectively.
|
||||||
- The environment variables may include a `SINK` if a `SINK` variable is set in
|
- The event messages shall be sent to the sink URI specified in `K_SINK`. The message can be any
|
||||||
the `env` or a Sink object is provided in the ContainerSource YAML file.
|
|
||||||
- The event messages shall be sent to the sink uri. The message can be any
|
|
||||||
format.
|
format.
|
||||||
[CloudEvents](https://github.com/cloudevents/spec/blob/master/spec.md#design-goals)
|
[CloudEvents](https://github.com/cloudevents/spec/blob/master/spec.md#design-goals)
|
||||||
format is recommended.
|
format is recommended.
|
||||||
|
|
@ -175,6 +173,6 @@ event source is a sample for your reference.
|
||||||
### Create the ContainerSource using this container image
|
### Create the ContainerSource using this container image
|
||||||
|
|
||||||
When the container image is ready, a YAML file will be used to create a concrete
|
When the container image is ready, a YAML file will be used to create a concrete
|
||||||
ContainerSource. Use [heartbeats-source.yaml](./heartbeats-source.yaml) as a
|
`ContainerSource`. Use [heartbeats-source.yaml](./heartbeats-source.yaml) as a
|
||||||
sample for reference. [Learn more about the ContainerSource
|
sample for reference. [Learn more about the ContainerSource
|
||||||
specification](../../../eventing#containersource).
|
specification](../../../eventing#containersource).
|
||||||
|
|
|
||||||
|
|
@ -1,4 +1,4 @@
|
||||||
apiVersion: sources.eventing.knative.dev/v1alpha1
|
apiVersion: sources.knative.dev/v1alpha2
|
||||||
kind: ContainerSource
|
kind: ContainerSource
|
||||||
metadata:
|
metadata:
|
||||||
name: test-heartbeats
|
name: test-heartbeats
|
||||||
|
|
|
||||||
|
|
@ -122,7 +122,6 @@ apiVersion: batch/v1beta1
|
||||||
kind: CronJob
|
kind: CronJob
|
||||||
metadata:
|
metadata:
|
||||||
name: heartbeat-cron
|
name: heartbeat-cron
|
||||||
spec:
|
|
||||||
spec:
|
spec:
|
||||||
# Run every minute
|
# Run every minute
|
||||||
schedule: "* * * * *"
|
schedule: "* * * * *"
|
||||||
|
|
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
---
|
---
|
||||||
title: "Knative Eventing sources"
|
title: "Knative Eventing sources"
|
||||||
linkTitle: "Eventing sources"
|
linkTitle: "Eventing sources"
|
||||||
weight: 30
|
weight: 20
|
||||||
type: "docs"
|
type: "docs"
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -58,10 +58,10 @@ These are not directly usable, but make writing a Source much easier.
|
||||||
Name | Status | Support | Description
|
Name | Status | Support | Description
|
||||||
--- | --- | --- | ---
|
--- | --- | --- | ---
|
||||||
[Auto Container Source](https://github.com/Harwayne/auto-container-source) | Proof of Concept | None | AutoContainerSource is a controller that allows the Source CRDs _without_ needing a controller. It notices CRDs with a specific label and starts controlling resources of that type. It utilizes Container Source as underlying infrastructure.
|
[Auto Container Source](https://github.com/Harwayne/auto-container-source) | Proof of Concept | None | AutoContainerSource is a controller that allows the Source CRDs _without_ needing a controller. It notices CRDs with a specific label and starts controlling resources of that type. It utilizes Container Source as underlying infrastructure.
|
||||||
[Container Source](https://knative.dev/docs/eventing/migration/sinkbinding) | Deprecated, replaced by SinkBinding | Knative | ContainerSource was an earlier version of SinkBinding which controlled the lifetime of a single Pod which acted as an event source. SinkBinding is more flexible and is preferred.
|
[Container Source](https://knative.dev/docs/eventing/migration/sinkbinding) | Active Development | Knative | Given a `spec.template` with at least a container image specified, ContainerSource will keep a `Pod` running with the specified image(s). `K_SINK` (destination address) and `KE_CE_OVERRIDES` (JSON CloudEvents attributes) environment variables are injected into the running image(s). It is used by multiple other Sources as underlying infrastructure.
|
||||||
[Kubebuilder Sample Source](https://github.com/grantr/sample-source) | Proof of Concept | None | Kubebuilder SampleSource is a kubebuilder based implementation supporting the [Writing an Event Source the Hard Way tutorial](../samples/writing-a-source).
|
[Kubebuilder Sample Source](https://github.com/grantr/sample-source) | Proof of Concept | None | Kubebuilder SampleSource is a kubebuilder based implementation supporting the [Writing an Event Source the Hard Way tutorial](../samples/writing-a-source).
|
||||||
[Sample Source](https://github.com/knative/sample-source) | Active Development | Knative | Used as reference implementation supporting [Writing an Event Source from Scratch tutorial](../samples/writing-receive-adapter-source).
|
[Sample Source](https://github.com/knative/sample-source) | Active Development | Knative | Used as reference implementation supporting [Writing an Event Source from Scratch tutorial](../samples/writing-receive-adapter-source).
|
||||||
[SinkBinding](https://knative.dev/docs/eventing/samples/sinkbinding/) | Active Development | Knative | 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 PodSpeccable).
|
[SinkBinding](https://knative.dev/docs/eventing/samples/sinkbinding/) | Active Development | Knative | 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).
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -8,14 +8,16 @@ metaSources:
|
||||||
description: >
|
description: >
|
||||||
SinkBinding provides a framework for injecting `K_SINK` (destination address) and
|
SinkBinding provides a framework for injecting `K_SINK` (destination address) and
|
||||||
`K_CE_OVERRIDES` (JSON cloudevents attributes) environment variables into any Kubernetes
|
`K_CE_OVERRIDES` (JSON cloudevents attributes) environment variables into any Kubernetes
|
||||||
resource which has a `spec.template` that looks like a Pod (aka PodSpeccable).
|
resource which has a `spec.template` that looks like a Pod (aka PodSpecable).
|
||||||
- name: Container Source
|
- name: Container Source
|
||||||
url: https://knative.dev/docs/eventing/migration/sinkbinding
|
url: https://knative.dev/docs/eventing/migration/sinkbinding
|
||||||
status: Deprecated, replaced by SinkBinding
|
status: Active Development
|
||||||
support: Knative
|
support: Knative
|
||||||
description: >
|
description: >
|
||||||
ContainerSource was an earlier version of SinkBinding which controlled the lifetime of a single
|
Given a `spec.template` with at least a container image specified, ContainerSource will keep a `Pod`
|
||||||
Pod which acted as an event source. SinkBinding is more flexible and is preferred.
|
running with the specified image(s). `K_SINK` (destination address) and `KE_CE_OVERRIDES` (JSON
|
||||||
|
CloudEvents attributes) environment variables are injected into the running image(s). It is used by multiple
|
||||||
|
other Sources as underlying infrastructure.
|
||||||
- name: Auto Container Source
|
- name: Auto Container Source
|
||||||
url: https://github.com/Harwayne/auto-container-source
|
url: https://github.com/Harwayne/auto-container-source
|
||||||
status: Proof of Concept
|
status: Proof of Concept
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue