From e7cc778d70b2fa5c40df288491c16dd6d5fba29b Mon Sep 17 00:00:00 2001 From: Samia Nneji Date: Tue, 15 Jun 2021 14:22:37 +0100 Subject: [PATCH 1/2] Relocating container source docs to dev guide --- .../sources/containersource/README.md | 224 ++++++++++++++++++ .../sources/containersource/reference.md | 149 ++++++++++++ 2 files changed, 373 insertions(+) create mode 100644 docs/developer/eventing/sources/containersource/README.md create mode 100644 docs/developer/eventing/sources/containersource/reference.md diff --git a/docs/developer/eventing/sources/containersource/README.md b/docs/developer/eventing/sources/containersource/README.md new file mode 100644 index 00000000000..8769a595b7b --- /dev/null +++ b/docs/developer/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/developer/eventing/sources/containersource/reference.md b/docs/developer/eventing/sources/containersource/reference.md new file mode 100644 index 00000000000..23a8c5d5ab3 --- /dev/null +++ b/docs/developer/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 From afefd1b12f0f9ab56776d2539767897a37c4b656 Mon Sep 17 00:00:00 2001 From: Samia Nneji Date: Mon, 28 Jun 2021 13:18:59 +0100 Subject: [PATCH 2/2] Fix URL --- mkdocs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 1e5e6c6b20d..8592d96663d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -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: