diff --git a/docs/eventing/sources/containersource.md b/docs/eventing/sources/containersource.md deleted file mode 100644 index d2dc5ddce..000000000 --- a/docs/eventing/sources/containersource.md +++ /dev/null @@ -1,182 +0,0 @@ ---- -title: "ContainerSource" -linkTitle: "ContainerSource" -weight: 31 -type: "docs" ---- - -# ContainerSource - -![version](https://img.shields.io/badge/API_Version-v1-red?style=flat-square) - -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/`) -- 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: - 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). diff --git a/docs/eventing/sources/containersource/README.md b/docs/eventing/sources/containersource/README.md new file mode 100644 index 000000000..8769a595b --- /dev/null +++ b/docs/eventing/sources/containersource/README.md @@ -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/` + - 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 + ``` + + Where `` 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 - < --image --sink + ``` + Where: + + - `` is the name you want for your ContainerSource object, + for example, `test-heartbeats`. + - `` corresponds to the image URI you built and published + in step 1, for example, `gcr.io/[gcloud-project]/knative.dev/eventing/cmd/heartbeats`. + - `` is the name of your sink, for example ``. + + 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 apply -f - < + spec: + template: + spec: + containers: + - image: + name: + env: + - name: POD_NAME + value: "" + - name: POD_NAMESPACE + value: "" + sink: + ref: + apiVersion: v1 + kind: Service + name: + EOF + ``` + Where: + + - `` is the namespace you created for your ContainerSource, + for example, `containersource-example`. + - `` is the name you want for your ContainerSource, + for example, `test-heartbeats`. + - `` corresponds to the image URI you built and published + in step 1, for example, `gcr.io/[gcloud-project]/knative.dev/eventing/cmd/heartbeats`. + - `` is the name of your event source, for example, `heartbeats`. + - `` is the name of the Pod that the container runs in, for example, `mypod`. + - `` is the namespace that the Pod runs in, for example, `event-test`. + - `` 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 logs -l --tail=200 + ``` + Where: + + - `` is the namespace that contains the ContainerSource object. + - `` 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 + ``` + + Where `` is the namespace that contains the ContainerSource object. + +## Reference Documentation + +See the [ContainerSource specification](../../../reference/api/eventing/eventing/#sources.knative.dev/v1.ContainerSource). diff --git a/docs/eventing/sources/containersource/reference.md b/docs/eventing/sources/containersource/reference.md new file mode 100644 index 000000000..23a8c5d5a --- /dev/null +++ b/docs/eventing/sources/containersource/reference.md @@ -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"`. + + + +```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"`. + + +### 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/). + + + +#### 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: + ```{ .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 diff --git a/mkdocs.yml b/mkdocs.yml index 854fd2fe8..79110a1ce 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -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