Skip to content

Relocating ContainerSource docs to dev guide #3807

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
knative-prow-robot merged 2 commits into from
Jun 28, 2021
Merged

Relocating ContainerSource docs to dev guide #3807

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e7cc778
Relocating container source docs to dev guide
snneji Jun 15, 2021
afefd1b
Fix URL
snneji Jun 28, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
224 changes: 224 additions & 0 deletions docs/developer/eventing/sources/containersource/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,224 @@
# Creating a ContainerSource object

![API version v1](https://img.shields.io/badge/API_Version-v1-red?style=flat-square)

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).
149 changes: 149 additions & 0 deletions docs/developer/eventing/sources/containersource/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
4 changes: 2 additions & 2 deletions mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,8 +78,8 @@ nav:
- Knative Eventing:
- Event sources:
- ContainerSource:
- Creating a ContainerSource object: eventing/sources/containersource/README.md
- ContainerSource Reference: eventing/sources/containersource/reference.md
- Creating a ContainerSource object: developer/eventing/sources/containersource/README.md
- ContainerSource Reference: developer/eventing/sources/containersource/reference.md
- Event delivery: developer/eventing/event-delivery.md
# Serving
- Knative Serving:
Expand Down