mirror of https://github.com/knative/docs.git
Edit ContainerSource docs (#3774)
* Edit ContainerSource docs * Update docs/eventing/sources/containersource/README.md Co-authored-by: Ashleigh Brennan <abrennan@redhat.com> * Fix command * Move ContainerSource docs to dev guide * Apply feedback for code snippets * remove copy icon Co-authored-by: Ashleigh Brennan <abrennan@redhat.com>
This commit is contained in:
Samia Nneji
GitHub
parent
56dae919e8
commit
a3df56f125
|
|
@ -1,182 +0,0 @@
|
|||
---
|
||||
title: "ContainerSource"
|
||||
linkTitle: "ContainerSource"
|
||||
weight: 31
|
||||
type: "docs"
|
||||
---
|
||||
|
||||
# ContainerSource
|
||||
|
||||
|
||||
|
||||
ContainerSource will start a container image which will generate events under
|
||||
certain situations and send messages to a sink URI. It also can be an easy way
|
||||
to support your own event sources in Knative. This guide shows how to configure
|
||||
ContainerSource as an event source for functions and summarizes guidelines for
|
||||
creating your own event source as a ContainerSource.
|
||||
|
||||
### Prerequisites
|
||||
- Install [ko](https://github.com/google/ko)
|
||||
- Set `KO_DOCKER_REPO`
|
||||
(e.g. `gcr.io/[gcloud-project]` or `docker.io/<username>`)
|
||||
- Authenticated with your `KO_DOCKER_REPO`
|
||||
- Install [`docker`](https://docs.docker.com/install/)
|
||||
|
||||
## Installation
|
||||
|
||||
The ContainerSource source type is enabled by default when you install Knative Eventing.
|
||||
|
||||
## Example
|
||||
|
||||
This example shows how the heartbeats container sends events to the Event Display Service.
|
||||
|
||||
### Preparing the heartbeats image
|
||||
Knative [event-sources](https://github.com/knative/eventing) has a
|
||||
sample of heartbeats event source. You could clone the source code by
|
||||
|
||||
```
|
||||
git clone -b "{{ branch }}" https://github.com/knative/eventing.git
|
||||
```
|
||||
|
||||
And then build a heartbeats image and publish to your image repo with
|
||||
|
||||
```
|
||||
ko publish ko://knative.dev/eventing/cmd/heartbeats
|
||||
```
|
||||
### Creating a namespace
|
||||
|
||||
Create a new namespace called `containersource-example` by entering the following
|
||||
command:
|
||||
|
||||
```bash
|
||||
kubectl create namespace containersource-example
|
||||
```
|
||||
|
||||
### Creating the Event Display Service
|
||||
|
||||
In order to verify `ContainerSource` is working, we will create a Event Display
|
||||
Service that dumps incoming messages to its log.
|
||||
|
||||
```bash
|
||||
kubectl -n containersource-example apply -f - << EOF
|
||||
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/cmd/event_display
|
||||
|
||||
---
|
||||
|
||||
kind: Service
|
||||
apiVersion: v1
|
||||
metadata:
|
||||
name: event-display
|
||||
spec:
|
||||
selector:
|
||||
app: event-display
|
||||
ports:
|
||||
- protocol: TCP
|
||||
port: 80
|
||||
targetPort: 8080
|
||||
EOF
|
||||
```
|
||||
|
||||
|
||||
### Creating the ContainerSource using the heartbeats image
|
||||
|
||||
In order to run the heartbeats container as an event source, you have to create
|
||||
a concrete ContainerSource with specific arguments and environment settings. Be
|
||||
sure to replace `heartbeats_image_uri` with a valid uri for your heartbeats
|
||||
image you published in the previous step.
|
||||
Note that arguments and environment variables are set and will be passed
|
||||
to the container.
|
||||
|
||||
```bash
|
||||
kubectl -n containersource-example apply -f - << EOF
|
||||
apiVersion: sources.knative.dev/v1
|
||||
kind: ContainerSource
|
||||
metadata:
|
||||
name: test-heartbeats
|
||||
spec:
|
||||
template:
|
||||
spec:
|
||||
containers:
|
||||
# This corresponds to a heartbeats image uri you build and publish in the previous step
|
||||
# e.g. gcr.io/[gcloud-project]/knative.dev/eventing/cmd/heartbeats
|
||||
- image: <heartbeats_image_uri>
|
||||
name: heartbeats
|
||||
args:
|
||||
- --period=1
|
||||
env:
|
||||
- name: POD_NAME
|
||||
value: "mypod"
|
||||
- name: POD_NAMESPACE
|
||||
value: "event-test"
|
||||
sink:
|
||||
ref:
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
name: event-display
|
||||
EOF
|
||||
```
|
||||
|
||||
### Verify
|
||||
|
||||
View the logs for the `event-display` event consumer by
|
||||
entering the following command:
|
||||
|
||||
```bash
|
||||
kubectl -n containersource-example logs -l app=event-display --tail=200
|
||||
```
|
||||
|
||||
This returns the `Attributes` and `Data` of the events that the ContainerSource sent to the `event-display` Service:
|
||||
|
||||
```
|
||||
☁️ cloudevents.Event
|
||||
Validation: valid
|
||||
Context Attributes,
|
||||
specversion: 1.0
|
||||
type: dev.knative.eventing.samples.heartbeat
|
||||
source: https://knative.dev/eventing/cmd/heartbeats/#event-test/mypod
|
||||
id: 2b72d7bf-c38f-4a98-a433-608fbcdd2596
|
||||
time: 2019-10-18T15:23:20.809775386Z
|
||||
contenttype: application/json
|
||||
Extensions,
|
||||
beats: true
|
||||
heart: yes
|
||||
the: 42
|
||||
Data,
|
||||
{
|
||||
"id": 2,
|
||||
"label": ""
|
||||
}
|
||||
```
|
||||
|
||||
### Cleanup
|
||||
|
||||
Delete the `containersource-example` namespace and all of its resources from your
|
||||
cluster by entering the following command:
|
||||
|
||||
```bash
|
||||
kubectl delete namespace containersource-example
|
||||
```
|
||||
|
||||
## Reference Documentation
|
||||
|
||||
See the [ContainerSource specification](../../reference/api/eventing/#sources.knative.dev/v1.ContainerSource).
|
||||
|
||||
## Contact
|
||||
|
||||
For any inquiries about this source, please reach out on to the
|
||||
[Knative users group](https://groups.google.com/forum/#!forum/knative-users).
|
||||
|
|
@ -0,0 +1,224 @@
|
|||
# Creating a ContainerSource object
|
||||
|
||||
|
||||
|
||||
This topic describes how to configure ContainerSource as an event source for
|
||||
functions.
|
||||
|
||||
The ContainerSource object starts a container image that generates events and
|
||||
sends messages to a sink URI. You can also use ContainerSource to support your
|
||||
own event sources in Knative.
|
||||
|
||||
In the examples below, the event source is a heartbeats container and the sink
|
||||
is a Knative Service.
|
||||
If you have an existing event source and sink, you can replace the examples with
|
||||
your own values.
|
||||
|
||||
## Before you begin
|
||||
|
||||
Before you can create a ContainerSource object:
|
||||
|
||||
- You must have [Knative Eventing](../../../admin/install/install-eventing-with-yaml)
|
||||
installed on your cluster.
|
||||
- If you want to use the example heartbeats event source below, you must also:
|
||||
- Install [ko](https://github.com/google/ko)
|
||||
- Set `KO_DOCKER_REPO`. For example, `gcr.io/[gcloud-project]` or `docker.io/<username>`
|
||||
- Authenticate with your `KO_DOCKER_REPO`
|
||||
- Install [`docker`](https://docs.docker.com/install/)
|
||||
|
||||
## Create a ContainerSource object
|
||||
|
||||
1. Build an image of your event source and publish it to your image repository.
|
||||
Your image must read the environment variable `K_SINK` and post messages to the
|
||||
URL specified in `K_SINK`. If you do not already have an image, you can use
|
||||
the following example heartbeats event source by running the commands:
|
||||
|
||||
```bash
|
||||
git clone -b "{{ branch }}" https://github.com/knative/eventing.git
|
||||
```
|
||||
|
||||
```bash
|
||||
ko publish ko://knative.dev/eventing/cmd/heartbeats
|
||||
```
|
||||
|
||||
1. Create a namespace for your ContainerSource by running the command:
|
||||
|
||||
```bash
|
||||
kubectl create namespace <namespace>
|
||||
```
|
||||
|
||||
Where `<namespace>` is the namespace that you want your ContainerSource to use.
|
||||
For example, `containersource-example`.
|
||||
|
||||
1. Create a sink. If you do not already have a sink, you can use the following Knative
|
||||
Service, which dumps incoming messages into its log, by running the command:
|
||||
|
||||
!!! note
|
||||
To create a Knative service you must have Knative Serving installed on your cluster.
|
||||
|
||||
=== "kn"
|
||||
|
||||
```bash
|
||||
kn service create event-display --port 8080 --image gcr.io/knative-releases/knative.dev/eventing/cmd/event_display
|
||||
```
|
||||
|
||||
=== "YAML"
|
||||
|
||||
```yaml
|
||||
kubectl -n containersource-example apply -f - <<EOF
|
||||
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/cmd/event_display
|
||||
|
||||
---
|
||||
|
||||
kind: Service
|
||||
apiVersion: v1
|
||||
metadata:
|
||||
name: event-display
|
||||
spec:
|
||||
selector:
|
||||
app: event-display
|
||||
ports:
|
||||
- protocol: TCP
|
||||
port: 80
|
||||
targetPort: 8080
|
||||
EOF
|
||||
```
|
||||
|
||||
1. Create a concrete ContainerSource with specific arguments and environment
|
||||
settings by running the command:
|
||||
|
||||
=== "kn"
|
||||
|
||||
```bash
|
||||
kn source container create <name> --image <image-uri> --sink <sink>
|
||||
```
|
||||
Where:
|
||||
|
||||
- `<name>` is the name you want for your ContainerSource object,
|
||||
for example, `test-heartbeats`.
|
||||
- `<image-uri>` corresponds to the image URI you built and published
|
||||
in step 1, for example, `gcr.io/[gcloud-project]/knative.dev/eventing/cmd/heartbeats`.
|
||||
- `<sink>` is the name of your sink, for example `<event-display>`.
|
||||
|
||||
For a list of available options, see the [Knative client documentation](https://github.com/knative/client/blob/main/docs/cmd/kn_source_container_create.md#kn-source-container-create).
|
||||
|
||||
=== "YAML"
|
||||
|
||||
```yaml
|
||||
kubectl -n <namespace> apply -f - <<EOF
|
||||
apiVersion: sources.knative.dev/v1
|
||||
kind: ContainerSource
|
||||
metadata:
|
||||
name: <containersource-name>
|
||||
spec:
|
||||
template:
|
||||
spec:
|
||||
containers:
|
||||
- image: <event-source-image-uri>
|
||||
name: <container-name>
|
||||
env:
|
||||
- name: POD_NAME
|
||||
value: "<pod-name>"
|
||||
- name: POD_NAMESPACE
|
||||
value: "<pod-namespace>"
|
||||
sink:
|
||||
ref:
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
name: <sink>
|
||||
EOF
|
||||
```
|
||||
Where:
|
||||
|
||||
- `<namespace>` is the namespace you created for your ContainerSource,
|
||||
for example, `containersource-example`.
|
||||
- `<containersource-name>` is the name you want for your ContainerSource,
|
||||
for example, `test-heartbeats`.
|
||||
- `<event-source-image-uri>` corresponds to the image URI you built and published
|
||||
in step 1, for example, `gcr.io/[gcloud-project]/knative.dev/eventing/cmd/heartbeats`.
|
||||
- `<container-name>` is the name of your event source, for example, `heartbeats`.
|
||||
- `<pod-name>` is the name of the Pod that the container runs in, for example, `mypod`.
|
||||
- `<pod-namespace>` is the namespace that the Pod runs in, for example, `event-test`.
|
||||
- `<sink>` is the name of your sink, for example, `event-display`.
|
||||
|
||||
For more information about the fields you can configure for the ContainerSource
|
||||
object, see [ContainerSource Reference](reference.md).
|
||||
|
||||
!!! note
|
||||
Arguments and environment variables are set and are passed to the container.
|
||||
|
||||
## Verify the ContainerSource object
|
||||
|
||||
1. View the logs for your event consumer by running the command:
|
||||
|
||||
```shell
|
||||
kubectl -n <namespace> logs -l <pod-name> --tail=200
|
||||
```
|
||||
Where:
|
||||
|
||||
- `<namespace>` is the namespace that contains the ContainerSource object.
|
||||
- `<pod-name>` is the name of the Pod that the container runs in.
|
||||
|
||||
For example:
|
||||
|
||||
```shell
|
||||
$ kubectl -n containersource-example logs -l app=event-display --tail=200
|
||||
```
|
||||
|
||||
1. Verify that the output returns the properties of the events that your
|
||||
ContainerSource sent to your sink.
|
||||
In the example below, the command has returned the `Attributes` and `Data` properties
|
||||
of the events that the ContainerSource sent to the `event-display` Service:
|
||||
|
||||
```
|
||||
☁️ cloudevents.Event
|
||||
Validation: valid
|
||||
Context Attributes,
|
||||
specversion: 1.0
|
||||
type: dev.knative.eventing.samples.heartbeat
|
||||
source: https://knative.dev/eventing/cmd/heartbeats/#event-test/mypod
|
||||
id: 2b72d7bf-c38f-4a98-a433-608fbcdd2596
|
||||
time: 2019-10-18T15:23:20.809775386Z
|
||||
contenttype: application/json
|
||||
Extensions,
|
||||
beats: true
|
||||
heart: yes
|
||||
the: 42
|
||||
Data,
|
||||
{
|
||||
"id": 2,
|
||||
"label": ""
|
||||
}
|
||||
```
|
||||
|
||||
## Cleanup
|
||||
|
||||
To delete the ContainerSource object and all of the related resources in the
|
||||
namespace:
|
||||
|
||||
- Delete the namespace by running the command:
|
||||
|
||||
```shell
|
||||
kubectl delete namespace <namespace>
|
||||
```
|
||||
|
||||
Where `<namespace>` is the namespace that contains the ContainerSource object.
|
||||
|
||||
## Reference Documentation
|
||||
|
||||
See the [ContainerSource specification](../../../reference/api/eventing/eventing/#sources.knative.dev/v1.ContainerSource).
|
||||
|
|
@ -0,0 +1,149 @@
|
|||
# ContainerSource reference
|
||||
|
||||
This topic provides reference information about the configurable fields for the
|
||||
ContainerSource object.
|
||||
|
||||
|
||||
## ContainerSource
|
||||
|
||||
A ContainerSource 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 ContainerSource object. | Required |
|
||||
| [`metadata`][kubernetes-overview] | Specifies metadata that uniquely identifies the ContainerSource object. For example, a `name`. | Required |
|
||||
| [`spec`][kubernetes-overview] | Specifies the configuration information for this ContainerSource object. | Required |
|
||||
| [`spec.sink`](#sink-parameter) | A reference to an object that resolves to a URI to use as the sink. | Required |
|
||||
| [`spec.template`](#template-parameter) | A `template` in the shape of `Deployment.spec.template` to be used for this ContainerSource. | Required |
|
||||
| [`spec.ceOverrides`](#cloudevent-overrides) | Defines overrides to control the output format and modifications to the event sent to the sink. | Optional |
|
||||
|
||||
|
||||
### Sink parameter
|
||||
|
||||
The `sink` parameter is a reference to an object that resolves to a URI to use as the sink.
|
||||
|
||||
A `sink` definition supports the following fields:
|
||||
|
||||
| Field | Description | Required or optional |
|
||||
|-------|-------------|----------------------|
|
||||
| `ref` | This points to an Addressable. | Required if _not_ using `uri` |
|
||||
| `ref.apiVersion` | API version of the referent. | Required if using `ref` |
|
||||
| [`ref.kind`][kubernetes-kinds] | Kind of the referent. | Required if using `ref` |
|
||||
| [`ref.name`][kubernetes-names] | Name of the referent. | Required if using `ref` |
|
||||
| [`ref.namespace`][kubernetes-namespaces] | Namespace of the referent. If omitted this defaults to the object holding it. | Optional |
|
||||
| `uri` | This can be an absolute URL with a non-empty scheme and non-empty host that points to the target or a relative URI. Relative URIs are resolved using the base URI retrieved from Ref. | Required if _not_ using `ref` |
|
||||
|
||||
!!! note
|
||||
At least one of `ref` or `uri` is required. If both are specified, `uri` is
|
||||
resolved into the URL from the Addressable `ref` result.
|
||||
|
||||
#### Example: sink parameter
|
||||
|
||||
Given the following YAML, if `ref` resolves into
|
||||
`"http://mysink.default.svc.cluster.local"`, then `uri` is added to this
|
||||
resulting in `"http://mysink.default.svc.cluster.local/extra/path"`.
|
||||
|
||||
<!-- TODO we should have a page to point to describing the ref+uri destinations and the rules we use to resolve those and reuse the page. -->
|
||||
|
||||
```yaml
|
||||
apiVersion: sources.knative.dev/v1
|
||||
kind: ContainerSource
|
||||
metadata:
|
||||
name: test-heartbeats
|
||||
spec:
|
||||
...
|
||||
sink:
|
||||
ref:
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
namespace: default
|
||||
name: mysink
|
||||
uri: /extra/path
|
||||
```
|
||||
|
||||
!!! contract
|
||||
This results in the `K_SINK` environment variable being set as
|
||||
`"http://mysink.default.svc.cluster.local/extra/path"`. <!-- unsure about this -->
|
||||
|
||||
|
||||
### Template parameter
|
||||
|
||||
This is a `template` in the shape of `Deployment.spec.template` to use for the ContainerSource.
|
||||
For more information, see the [Kubernetes Documentation](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/).
|
||||
|
||||
<!-- not sure what the required and optional fields are for this. -->
|
||||
|
||||
#### Example: template parameter
|
||||
|
||||
```yaml
|
||||
apiVersion: sources.knative.dev/v1
|
||||
kind: ContainerSource
|
||||
metadata:
|
||||
name: test-heartbeats
|
||||
spec:
|
||||
template:
|
||||
spec:
|
||||
containers:
|
||||
- image: gcr.io/[gcloud-project]/knative.dev/eventing/cmd/heartbeats
|
||||
name: heartbeats
|
||||
args:
|
||||
- --period=1
|
||||
env:
|
||||
- name: POD_NAME
|
||||
value: "mypod"
|
||||
- name: POD_NAMESPACE
|
||||
value: "event-test"
|
||||
...
|
||||
```
|
||||
|
||||
|
||||
### 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: ContainerSource
|
||||
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
|
||||
|
|
@ -75,6 +75,11 @@ nav:
|
|||
- Configure resource requests and limits: developer/serving/services/configure-requests-limits-services.md
|
||||
- Troubleshooting:
|
||||
- Debugging application issues: developer/serving/troubleshooting/debugging-application-issues.md
|
||||
- Knative Eventing:
|
||||
- Event sources:
|
||||
- ContainerSource:
|
||||
- Creating a ContainerSource object: eventing/sources/containersource/README.md
|
||||
- ContainerSource Reference: eventing/sources/containersource/reference.md
|
||||
# Serving
|
||||
- Knative Serving:
|
||||
- Overview: serving/README.md
|
||||
|
|
@ -151,7 +156,6 @@ nav:
|
|||
- API server source:
|
||||
- Overview: eventing/sources/apiserversource/README.md
|
||||
- Getting started: eventing/sources/apiserversource/getting-started/README.md
|
||||
- ContainerSource: eventing/sources/containersource.md
|
||||
- PingSource: eventing/sources/ping-source/README.md
|
||||
- SinkBinding:
|
||||
- Overview: eventing/sources/sinkbinding/README.md
|
||||
|
|
|
|||
Loading…
Reference in New Issue