diff --git a/docs/developer/eventing/sinks/README.md b/docs/developer/eventing/sinks/README.md index befb29557..594bd23df 100644 --- a/docs/developer/eventing/sinks/README.md +++ b/docs/developer/eventing/sinks/README.md @@ -1,4 +1,4 @@ -# Event sinks +# About sinks When you create an event source, you can specify a _sink_ where events are sent to from the source. A sink is an Addressable resource that can receive incoming events from other resources. Knative Services, Channels, and Brokers are all examples of sinks. @@ -25,6 +25,53 @@ Where; - `` is the name of the Trigger being connected to the sink. - `` is the name of a KafkaSink object. +## Sink as a parameter + +Sink is used as 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.namespace`][kubernetes-namespaces] | Namespace of the referent. If omitted this defaults to the object holding it. | Optional | +| [`ref.name`][kubernetes-names] | Name of the referent. | Required if using `ref` | +| `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. + +### Sink parameter example + +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: SinkBinding +metadata: + name: bind-heartbeat +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 on the `subject` + as `"http://mysink.default.svc.cluster.local/extra/path"`. + ## Using custom resources as sinks To use a Kubernetes custom resource (CR) as a sink for events, you must: @@ -73,7 +120,7 @@ kn source binding create bind-heartbeat \ The `svc` in `http://event-display.svc.cluster.local` determines that the sink is a Knative Service. Other default sink prefixes include Channel and Broker. !!! tip - You can configure which resources can be used with the `--sink` flag for `kn` CLI commands by [Customizing kn](../../../../client/configure-kn/#customizing-kn). + You can configure which resources can be used with the `--sink` flag for `kn` CLI commands by [Customizing kn](../../../../client/configure-kn/#example-configuration-file). ## Supported third-party sink types diff --git a/docs/eventing/sources/sinkbinding/reference.md b/docs/eventing/sources/sinkbinding/reference.md index 58bd07ba9..a8b32c6c0 100644 --- a/docs/eventing/sources/sinkbinding/reference.md +++ b/docs/eventing/sources/sinkbinding/reference.md @@ -2,13 +2,11 @@ ![API version v1](https://img.shields.io/badge/API_Version-v1-red?style=flat-square) -This topic provides reference information about the configurable fields for the -SinkBinding object. +This topic provides reference information about the configurable parameters for SinkBinding objects. +## Supported parameters -## SinkBinding - -A `SinkBinding` definition supports the following fields: +A `SinkBinding` resource supports the following parameters: | Field | Description | Required or optional | |-------|-------------|----------------------| @@ -16,59 +14,10 @@ A `SinkBinding` definition supports the following fields: | [`kind`][kubernetes-overview] | Identifies this resource object as a `SinkBinding` object. | Required | | [`metadata`][kubernetes-overview] | Specifies metadata that uniquely identifies the `SinkBinding` object. For example, a `name`. | Required | | [`spec`][kubernetes-overview] | Specifies the configuration information for this `SinkBinding` object. | Required | -| [`spec.sink`](#sink-parameter) | A reference to an object that resolves to a URI to use as the sink. | Required | +| [`spec.sink`](../../../../developer/eventing/sinks) | A reference to an object that resolves to a URI to use as the sink. | Required | | [`spec.subject`](#subject-parameter) | A reference to the resources for which the "runtime contract" is augmented by Binding implementations. | Required | | [`spec.ceOverrides`](#cloudevent-overrides) | Defines overrides to control the output format and modifications to the event sent to the sink. | Optional | - -### Sink parameter - -Sink 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.namespace`][kubernetes-namespaces] | Namespace of the referent. If omitted this defaults to the object holding it. | Optional | -| [`ref.name`][kubernetes-names] | Name of the referent. | Required if using `ref` | -| `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: SinkBinding -metadata: - name: bind-heartbeat -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 on the `subject` - as `"http://mysink.default.svc.cluster.local/extra/path"`. - - ### Subject parameter The Subject parameter references the resources for which the "runtime contract" @@ -89,7 +38,7 @@ A `subject` definition supports the following fields: | `selector.matchExpressions.values` | An array of string values. If `operator` is `In` or `NotIn`, the values array must be non-empty. If `operator` is `Exists` or `DoesNotExist`, the values array must be empty. This array is replaced during a strategic merge patch. | Required if using `matchExpressions` | | `selector.matchLabels` | A map of key-value pairs. Each key-value pair in the `matchLabels` map is equivalent to an element of `matchExpressions`, where the key field is `matchLabels.`, the `operator` is `In`, and the `values` array contains only "matchLabels.". The requirements are ANDed. | Use one of `matchExpressions` or `matchLabels` | -#### Example: Subject parameter using name +#### Subject parameter examples Given the following YAML, the `Deployment` named `mysubject` in the `default` namespace is selected: @@ -108,8 +57,6 @@ spec: ... ``` -#### Example: Subject parameter using matchLabels - Given the following YAML, any `Job` with the label `working=example` in the `default` namespace is selected: @@ -129,8 +76,6 @@ spec: ... ``` -#### Example: Subject parameter using matchExpression - Given the following YAML, any `Pod` with the label `working=example` OR `working=sample` in the ` default` namespace is selected: @@ -154,7 +99,6 @@ spec: ... ``` - ### CloudEvent Overrides CloudEvent Overrides defines overrides to control the output format and @@ -172,7 +116,7 @@ A `ceOverrides` definition supports the following fields: the extensions override configuration. For example, you can not modify the `type` attribute. -#### Example: CloudEvent Overrides +#### CloudEvent Overrides example ```yaml apiVersion: sources.knative.dev/v1