Skip to content

Commit 4763c17

Browse files
abrennan89abrennan89
authored
Cleaning up sink docs (#3814)
* Cleaning up sink docs * fix links and heading
1 parent 80399a9 commit 4763c17

File tree

2 files changed

+55
-64
lines changed

2 files changed

+55
-64
lines changed

‎docs/developer/eventing/sinks/README.md

+49-2
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Event sinks
1+
# About sinks
22

33
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.
44

@@ -25,6 +25,53 @@ Where;
2525
- `<trigger-name>` is the name of the Trigger being connected to the sink.
2626
- `<kafka-sink-name>` is the name of a KafkaSink object.
2727

28+
## Sink as a parameter
29+
30+
Sink is used as a reference to an object that resolves to a URI to use as the sink.
31+
32+
A `sink` definition supports the following fields:
33+
34+
| Field | Description | Required or optional |
35+
|-------|-------------|----------------------|
36+
| `ref` | This points to an Addressable. | Required if _not_ using `uri` |
37+
| `ref.apiVersion` | API version of the referent. | Required if using `ref` |
38+
| [`ref.kind`][kubernetes-kinds] | Kind of the referent. | Required if using `ref` |
39+
| [`ref.namespace`][kubernetes-namespaces] | Namespace of the referent. If omitted this defaults to the object holding it. | Optional |
40+
| [`ref.name`][kubernetes-names] | Name of the referent. | Required if using `ref` |
41+
| `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` |
42+
43+
!!! note
44+
At least one of `ref` or `uri` is required. If both are specified, `uri` is
45+
resolved into the URL from the Addressable `ref` result.
46+
47+
### Sink parameter example
48+
49+
Given the following YAML, if `ref` resolves into
50+
`"http://mysink.default.svc.cluster.local"`, then `uri` is added to this
51+
resulting in `"http://mysink.default.svc.cluster.local/extra/path"`.
52+
53+
<!-- 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. -->
54+
55+
```yaml
56+
apiVersion: sources.knative.dev/v1
57+
kind: SinkBinding
58+
metadata:
59+
name: bind-heartbeat
60+
spec:
61+
...
62+
sink:
63+
ref:
64+
apiVersion: v1
65+
kind: Service
66+
namespace: default
67+
name: mysink
68+
uri: /extra/path
69+
```
70+
71+
!!! contract
72+
This results in the `K_SINK` environment variable being set on the `subject`
73+
as `"http://mysink.default.svc.cluster.local/extra/path"`.
74+
2875
## Using custom resources as sinks
2976

3077
To use a Kubernetes custom resource (CR) as a sink for events, you must:
@@ -73,7 +120,7 @@ kn source binding create bind-heartbeat \
73120
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.
74121

75122
!!! tip
76-
You can configure which resources can be used with the `--sink` flag for `kn` CLI commands by [Customizing kn](../../../../client/configure-kn/#customizing-kn).
123+
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).
77124

78125
## Supported third-party sink types
79126

‎docs/eventing/sources/sinkbinding/reference.md

+6-62
Original file line numberDiff line numberDiff line change
@@ -2,73 +2,22 @@
22

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

5-
This topic provides reference information about the configurable fields for the
6-
SinkBinding object.
5+
This topic provides reference information about the configurable parameters for SinkBinding objects.
76

7+
## Supported parameters
88

9-
## SinkBinding
10-
11-
A `SinkBinding` definition supports the following fields:
9+
A `SinkBinding` resource supports the following parameters:
1210

1311
| Field | Description | Required or optional |
1412
|-------|-------------|----------------------|
1513
| [`apiVersion`][kubernetes-overview] | Specifies the API version, for example `sources.knative.dev/v1`. | Required |
1614
| [`kind`][kubernetes-overview] | Identifies this resource object as a `SinkBinding` object. | Required |
1715
| [`metadata`][kubernetes-overview] | Specifies metadata that uniquely identifies the `SinkBinding` object. For example, a `name`. | Required |
1816
| [`spec`][kubernetes-overview] | Specifies the configuration information for this `SinkBinding` object. | Required |
19-
| [`spec.sink`](#sink-parameter) | A reference to an object that resolves to a URI to use as the sink. | Required |
17+
| [`spec.sink`](../../../../developer/eventing/sinks) | A reference to an object that resolves to a URI to use as the sink. | Required |
2018
| [`spec.subject`](#subject-parameter) | A reference to the resources for which the "runtime contract" is augmented by Binding implementations. | Required |
2119
| [`spec.ceOverrides`](#cloudevent-overrides) | Defines overrides to control the output format and modifications to the event sent to the sink. | Optional |
2220

23-
24-
### Sink parameter
25-
26-
Sink is a reference to an object that resolves to a URI to use as the sink.
27-
28-
A `sink` definition supports the following fields:
29-
30-
| Field | Description | Required or optional |
31-
|-------|-------------|----------------------|
32-
| `ref` | This points to an Addressable. | Required if _not_ using `uri` |
33-
| `ref.apiVersion` | API version of the referent. | Required if using `ref` |
34-
| [`ref.kind`][kubernetes-kinds] | Kind of the referent. | Required if using `ref` |
35-
| [`ref.namespace`][kubernetes-namespaces] | Namespace of the referent. If omitted this defaults to the object holding it. | Optional |
36-
| [`ref.name`][kubernetes-names] | Name of the referent. | Required if using `ref` |
37-
| `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` |
38-
39-
!!! note
40-
At least one of `ref` or `uri` is required. If both are specified, `uri` is
41-
resolved into the URL from the Addressable `ref` result.
42-
43-
#### Example: Sink parameter
44-
45-
Given the following YAML, if `ref` resolves into
46-
`"http://mysink.default.svc.cluster.local"`, then `uri` is added to this
47-
resulting in `"http://mysink.default.svc.cluster.local/extra/path"`.
48-
49-
<!-- 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. -->
50-
51-
```yaml
52-
apiVersion: sources.knative.dev/v1
53-
kind: SinkBinding
54-
metadata:
55-
name: bind-heartbeat
56-
spec:
57-
...
58-
sink:
59-
ref:
60-
apiVersion: v1
61-
kind: Service
62-
namespace: default
63-
name: mysink
64-
uri: /extra/path
65-
```
66-
67-
!!! contract
68-
This results in the `K_SINK` environment variable being set on the `subject`
69-
as `"http://mysink.default.svc.cluster.local/extra/path"`.
70-
71-
7221
### Subject parameter
7322

7423
The Subject parameter references the resources for which the "runtime contract"
@@ -89,7 +38,7 @@ A `subject` definition supports the following fields:
8938
| `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` |
9039
| `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>". The requirements are ANDed. | Use one of `matchExpressions` or `matchLabels` |
9140

92-
#### Example: Subject parameter using name
41+
#### Subject parameter examples
9342

9443
Given the following YAML, the `Deployment` named `mysubject` in the `default`
9544
namespace is selected:
@@ -108,8 +57,6 @@ spec:
10857
...
10958
```
11059

111-
#### Example: Subject parameter using matchLabels
112-
11360
Given the following YAML, any `Job` with the label `working=example` in the
11461
`default` namespace is selected:
11562

@@ -129,8 +76,6 @@ spec:
12976
...
13077
```
13178

132-
#### Example: Subject parameter using matchExpression
133-
13479
Given the following YAML, any `Pod` with the label `working=example` OR
13580
`working=sample` in the ` default` namespace is selected:
13681

@@ -154,7 +99,6 @@ spec:
15499
...
155100
```
156101

157-
158102
### CloudEvent Overrides
159103

160104
CloudEvent Overrides defines overrides to control the output format and
@@ -172,7 +116,7 @@ A `ceOverrides` definition supports the following fields:
172116
the extensions override configuration. For example, you can not modify the
173117
`type` attribute.
174118

175-
#### Example: CloudEvent Overrides
119+
#### CloudEvent Overrides example
176120

177121
```yaml
178122
apiVersion: sources.knative.dev/v1

0 commit comments

Comments
 (0)