// Module included in the following assemblies:
//
// * /serverless/develop/serverless-custom-event-sources.adoc

:_content-type: REFERENCE
[id="serverless-sinkbinding-reference_{context}"]
= Sink binding reference
// this section probably needs a rewrite / restructure; feels like multiple modules maybe for a larger ref doc. Out of scope for this PR.

You can use a `PodSpecable` object as an event source by creating a sink binding. You can configure multiple parameters when creating a `SinkBinding` object.

`SinkBinding` objects support the following parameters:

[cols=3*,options="header"]
|===
|Field
|Description
|Required or optional

|`apiVersion`
|Specifies the API version, for example `sources.knative.dev/v1`.
|Required

|`kind`
|Identifies this resource object as a `SinkBinding` object.
|Required

|`metadata`
|Specifies metadata that uniquely identifies the `SinkBinding` object. For example, a `name`.
|Required

|`spec`
|Specifies the configuration information for this `SinkBinding` object.
|Required

|`spec.sink`
|A reference to an object that resolves to a URI to use as the sink.
|Required

|`spec.subject`
|References the resources for which the runtime contract is augmented by binding implementations.
|Required

|`spec.ceOverrides`
|Defines overrides to control the output format and modifications to the event sent to the sink.
|Optional

|===

[id="serverless-sinkbinding-reference-subject-parameters_{context}"]
== Subject parameter

The `Subject` parameter references the resources for which the runtime contract is augmented by binding implementations. You can configure multiple fields for a `Subject` definition.

The `Subject` definition supports the following fields:

[cols=3*,options="header"]
|===
|Field
|Description
|Required or optional

|`apiVersion`
|API version of the referent.
|Required

|`kind`
|Kind of the referent.
|Required

|`namespace`
|Namespace of the referent. If omitted, this defaults to the namespace of the object.
|Optional

|`name`
|Name of the referent.
|Do not use if you configure `selector`.

|`selector`
|Selector of the referents.
|Do not use if you configure `name`.

|`selector.matchExpressions`
|A list of label selector requirements.
|Only use one of either `matchExpressions` or `matchLabels`.

|`selector.matchExpressions.key`
|The label key that the selector applies to.
|Required if using `matchExpressions`.

|`selector.matchExpressions.operator`
|Represents a key's relationship to a set of values. Valid operators are `In`, `NotIn`, `Exists` and `DoesNotExist`.
|Required if using `matchExpressions`.

|`selector.matchExpressions.values`
|An array of string values. If the `operator` parameter value is `In` or `NotIn`, the values array must be non-empty. If the `operator` parameter value 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.<key>`, the `operator` is `In`, and the `values` array contains only `matchLabels.<value>`.
|Only use one of either `matchExpressions` or `matchLabels`.

|===

.Subject parameter examples

Given the following YAML, the `Deployment` object named `mysubject` in the `default` namespace is selected:

[source,yaml]
----
apiVersion: sources.knative.dev/v1
kind: SinkBinding
metadata:
  name: bind-heartbeat
spec:
  subject:
    apiVersion: apps/v1
    kind: Deployment
    namespace: default
    name: mysubject
  ...
----

Given the following YAML, any `Job` object with the label `working=example` in the `default` namespace is selected:

[source,yaml]
----
apiVersion: sources.knative.dev/v1
kind: SinkBinding
metadata:
  name: bind-heartbeat
spec:
  subject:
    apiVersion: batch/v1
    kind: Job
    namespace: default
    selector:
      matchLabels:
        working: example
  ...
----

Given the following YAML, any `Pod` object with the label `working=example` or `working=sample` in the `default` namespace is selected:

[source,yaml]
----
apiVersion: sources.knative.dev/v1
kind: SinkBinding
metadata:
  name: bind-heartbeat
spec:
  subject:
    apiVersion: v1
    kind: Pod
    namespace: default
    selector:
      - matchExpression:
        key: working
        operator: In
        values:
          - example
          - sample
  ...
----

[id="serverless-sinkbinding-reference-cloudevent-overrides_{context}"]
== CloudEvent overrides

A `ceOverrides` definition provides overrides that control the CloudEvent's output format and modifications sent to the sink. You can configure multiple fields for the `ceOverrides` definition.

A `ceOverrides` definition supports the following fields:

[cols=3*,options="header"]
|===
|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 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.
====

.CloudEvent Overrides example
[source,yaml]
----
apiVersion: sources.knative.dev/v1
kind: SinkBinding
metadata:
  name: bind-heartbeat
spec:
  ...
  ceOverrides:
    extensions:
      extra: this is an extra attribute
      additional: 42
----

This sets the `K_CE_OVERRIDES` environment variable on the `subject`:

.Example output
[source,terminal]
----
{ "extensions": { "extra": "this is an extra attribute", "additional": "42" } }
----

[id="serverless-sinkbinding-reference-include-label_{context}"]
== The include label

To use a sink binding, you need to do assign the `bindings.knative.dev/include: "true"` label to either the resource or the namespace that the resource is included in. If the resource definition does not include the label, a cluster administrator can attach it to the namespace by running:

[source,terminal]
----
$ oc label namespace <namespace> bindings.knative.dev/include=true
----