knative
/
docs
mirror of https://github.com/knative/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Clean up sources docs (#4304) 

* Edit PR #4301

* Tweak other sources pages to match

* make v1 badges green

* Update event display image
This commit is contained in:
Samia Nneji 2021-09-29 15:56:23 +01:00 committed by GitHub
parent 947f487b4c
commit ffb93b29f5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 67 additions and 155 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/developer/eventing/sources/apiserversource/README.md
View File

@ -1,6 +1,6 @@
# ApiServerSource
![version](https://img.shields.io/badge/API_Version-v1-red?style=flat-square)
![version](https://img.shields.io/badge/API_Version-v1-green?style=flat-square)
The API server source is a Knative Eventing Kubernetes custom resource that listens for events emitted by the
Kubernetes API server (eg. pod creation, deployment updates, etc...) and forwards them as CloudEvents to a sink.

37
docs/developer/eventing/sources/apiserversource/getting-started.md
View File

@ -26,9 +26,9 @@ command:
!!! note
Creating a namespace for your ApiServerSource and related components
allows you to view changes and events for this workflow more easily, since
these are isolated from the many other components that may exist in your `default` namespace.<br><br>
It also makes removing the source easier, since you can simply delete the namespace to remove all of the resources.
allows you to view changes and events for this workflow more easily, because
these are isolated from the other components that might exist in your `default` namespace.<br><br>
It also makes removing the source easier, because you can delete the namespace to remove all of the resources.
1. Create a ServiceAccount:
@ -65,10 +65,11 @@ command:
rules:
<rules>
```
Where
- `<role>` is the name of the Role that you want to create.
- `<rules>` are the set of permissions you want to grant to the APIServerSource object. This set of permissions must match the resources you want to received events from.
Where:
- `<role>` is the name of the Role that you want to create.
- `<rules>` are the set of permissions you want to grant to the APIServerSource object.
This set of permissions must match the resources you want to receive events from.
For example, to receive events related to the `events` resource, use the following set of permissions:
```yaml
- apiGroups:
@ -81,8 +82,8 @@ command:
- watch
```
!!! note
The only required verbs are `get`, `list` and `watch`.
!!! note
The only required verbs are `get`, `list` and `watch`.
1. Apply the YAML file by running the command:
@ -112,7 +113,7 @@ command:
Where:
- `<role-binding>` is the name of the RoleBinding that you want to create.
- `<cluster-role>` is the name of the Role that you created in step 3 earlier.
- `<role>` is the name of the Role that you created in step 3 earlier.
- `<service-account>` is the name of the ServiceAccount that you created in step 2 earlier.
- `<namespace>` is the name of the namespace that you created in step 1 earlier.
@ -144,7 +145,7 @@ command:
spec:
containers:
- name: event-display
image: gcr.io/knative-releases/knative.dev/eventing-contrib/cmd/event_display
image: gcr.io/knative-releases/knative.dev/eventing/cmd/event_display
---
@ -191,6 +192,8 @@ command:
- `<service-account>` is the name of the ServiceAccount that you created in step 2 earlier.
- `<sink-name>` is the name of your sink, for example, `http://event-display.pingsource-example.svc.cluster.local`.
For a list of available options, see the [Knative client documentation](https://github.com/knative/client/blob/main/docs/cmd/kn_source_apiserver_create.md#kn-source-apiserver-create).
=== "YAML"
1. Create a YAML file using the following template:
@ -198,7 +201,7 @@ command:
apiVersion: sources.knative.dev/v1
kind: ApiServerSource
metadata:
name: <apiserversource>
name: <apiserversource-name>
namespace: <namespace>
spec:
serviceAccountName: <service-account>
@ -214,13 +217,15 @@ command:
```
Where:
- `<apiserversource>` is the name of the source that you want to create.
- `<apiserversource-name>` is the name of the source that you want to create.
- `<namespace>` is the name of the namespace that you created in step 1 earlier.
- `<service-account>` is the name of the ServiceAccount that you created in step 2 earlier.
- `<event-mode>` is either `Resource` or `Reference`. If set to `Resource`, the event payload contains the entire resource that the event is for. If set to `Reference`, the event payload only contains a reference to the resource that the event is for. The default is `Reference`.
- `<sink-kind>` is any supported [Addressable](https://knative.dev/docs/developer/concepts/duck-typing/#addressable) object that you want to use as a sink, for example, `Service` or `Deployment`.
- `<sink-kind>` is any supported [Addressable](../../../concepts/duck-typing.md#addressable) object that you want to use as a sink, for example, `Service` or `Deployment`.
- `<sink-name>` is the name of your sink.
For more information about the fields you can configure for the ApiServerSource object, see [ApiServerSource reference](reference.md).
1. Apply the YAML file by running the command:
```bash
@ -230,14 +235,14 @@ command:
## Verify the ApiServerSource object
1. Make the Kubernetes API server create events by launching a test pod in your namespace by running the command:
1. Make the Kubernetes API server create events by launching a test Pod in your namespace by running the command:
```bash
kubectl run busybox --image=busybox --namespace=<namespace> --restart=Never -- ls
```
Where `<namespace>` is the name of the namespace that you created in step 1 earlier.
1. Delete the test pod by running the command:
1. Delete the test Pod by running the command:
```bash
kubectl --namespace=<namespace> delete pod busybox
@ -308,7 +313,7 @@ command:
}
```
## Delete the ApiServerSource
## Delete the ApiServerSource object
To remove the ApiServerSource object and all of the related resources:

94
docs/developer/eventing/sources/apiserversource/reference.md
View File

@ -20,7 +20,7 @@ An ApiServerSource definition supports the following fields:
| `spec.mode` | EventMode controls the format of the event. Set to `Reference` to send a `dataref` event type for the resource being watched. Only a reference to the resource is included in the event payload. Set to `Resource` to have the full resource lifecycle event in the payload. Defaults to `Reference`. | Optional |
| [`spec.owner`](#owner-parameter) | ResourceOwner is an additional filter to only track resources that are owned by a specific resource type. If ResourceOwner matches Resources[n] then Resources[n] is allowed to pass the ResourceOwner filter. | Optional |
| [`spec.serviceAccountName`](#serviceaccountname-parameter) | The name of the ServiceAccount to use to run this source. Defaults to `default` if not set. | Optional |
| [`spec.sink`](#sink-parameter) | A reference to an object that resolves to a URI to use as the sink. | Required |
| [`spec.sink`](../../sinks/README.md#sink-as-a-parameter) | A reference to an object that resolves to a URI to use as the sink. | Required |
| [`spec.ceOverrides`](#cloudevent-overrides) | Defines overrides to control the output format and modifications to the event sent to the sink. | Optional |
@ -113,28 +113,32 @@ spec:
ServiceAccountName is a reference to a Kubernetes service account.
The proper permissions need to be assigned to the ApiServerSource object in order
to track the lifecycle events of the specified [`resources`](#resources-parameter).
To track the lifecycle events of the specified [`resources`](#resources-parameter),
you must assign the proper permissions to the ApiServerSource object.
#### Example: tracking pods
#### Example: tracking Pods
The following 4 YAMLs create a ServiceAccount, Role and RoleBinding
and grant the permission to get, list and watch Pod resources in `<namespace>` for the
ApiServerSource.
The following YAML files create a ServiceAccount, Role and RoleBinding
and grant the permission to get, list and watch Pod resources in the namespace
`apiserversource-example` for the ApiServerSource.
Example ServiceAccount:
```yaml
apiVersion: v1
kind: ServiceAccount
metadata:
name: <service-account>
namespace: <namespace>
name: test-service-account
namespace: apiserversource-example
```
Example Role with permission to get, list and watch Pod resources:
```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: <role>
name: test-role
rules:
- apiGroups:
- ""
@ -146,30 +150,34 @@ rules:
- watch
```
Example RoleBinding:
```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: <role-binding>
name: test-role-binding
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: Role
name: <role>
name: test-role
subjects:
- kind: ServiceAccount
name: <service-account>
namespace: <namespace>
name: test-service-account
namespace: apiserversource-example
```
Example ApiServerSource using `test-service-account`:
```yaml
apiVersion: sources.knative.dev/v1
kind: ApiServerSource
metadata:
name: <apiserversource>
namespace: <namespace>
name: test-apiserversource
namespace: apiserversource-example
spec:
# ...
serviceAccountName: <service-account>
serviceAccountName: test-service-account
...
```
@ -202,54 +210,6 @@ spec:
...
```
### 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"`.
<!-- 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. -->
```yaml
apiVersion: sources.knative.dev/v1
kind: ApiServerSource
metadata:
name: <apiserversource>
namespace: <namespace>
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 sink container
as `"http://mysink.default.svc.cluster.local/extra/path"`.
### CloudEvent Overrides
@ -298,9 +258,5 @@ spec:
https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
[label-selectors]:
http://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors
[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

4
docs/developer/eventing/sources/containersource/README.md
View File

@ -1,6 +1,6 @@
# Creating a ContainerSource object
![API version v1](https://img.shields.io/badge/API_Version-v1-red?style=flat-square)
![API version v1](https://img.shields.io/badge/API_Version-v1-green?style=flat-square)
This topic describes how to configure ContainerSource as an event source for
functions.
@ -220,7 +220,7 @@ of the events that the ContainerSource sent to the `event-display` Service:
}
```
## Cleanup
## Delete the ContainerSource object
To delete the ContainerSource object and all of the related resources in the
namespace:

58
docs/developer/eventing/sources/containersource/reference.md
View File

@ -1,5 +1,7 @@
# ContainerSource reference
![API version v1](https://img.shields.io/badge/API_Version-v1-green?style=flat-square)
This topic provides reference information about the configurable fields for the
ContainerSource object.
@ -14,59 +16,11 @@ A ContainerSource definition supports the following fields:
| [`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.sink`](../../sinks/README.md#sink-as-a-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"`.
<!-- 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. -->
```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"`. <!-- unsure about this -->
### Template parameter
This is a `template` in the shape of `Deployment.spec.template` to use for the ContainerSource.
@ -139,11 +93,5 @@ spec:
[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

6
docs/developer/eventing/sources/ping-source/README.md
View File

@ -61,7 +61,7 @@ during the verification step in this procedure.
spec:
containers:
- name: event-display
image: gcr.io/knative-releases/knative.dev/eventing-contrib/cmd/event_display
image: gcr.io/knative-releases/knative.dev/eventing/cmd/event_display
---
@ -150,7 +150,7 @@ during the verification step in this procedure.
- `<cron-schedule>` is a cron expression for the schedule for the PingSource to send events, for example, `*/1 * * * *` sends an event every minute.
- `<content-type>` is the media type of the data you want to send, for example, `application/json`.
- `<data>` is the data you want to send. This data must be represented as text, not binary. For example, a JSON object such as `{"message": "Hello world!"}`.
- `<sink-kind>` is any supported [Addressable](https://knative.dev/docs/developer/concepts/duck-typing/#addressable) object that you want to use as a sink, for example, `Service` or `Deployment`.
- `<sink-kind>` is any supported [Addressable](../../../concepts/duck-typing.md#addressable) object that you want to use as a sink, for example, `Service` or `Deployment`.
- `<sink-name>` is the name of your sink, for example, `event-display`.
For more information about the fields you can configure for the PingSource object, see [PingSource reference](reference.md).
@ -191,7 +191,7 @@ during the verification step in this procedure.
- `<cron-schedule>` is a cron expression for the schedule for the PingSource to send events, for example, `*/1 * * * *` sends an event every minute.
- `<content-type>` is the media type of the data you want to send, for example, `application/json`.
- `<base64-data>` is the base64 encoded binary data that you want to send, for example, `ZGF0YQ==`.
- `<sink-kind>` is any supported [Addressable](https://knative.dev/docs/developer/concepts/duck-typing/#addressable) object that you want to use as a sink, for example, `Service` or `Deployment`.
- `<sink-kind>` is any supported [Addressable](../../../concepts/duck-typing.md#addressable) object that you want to use as a sink, for example, `Service` or `Deployment`.
- `<sink-name>` is the name of your sink, for example, `event-display`.
For more information about the fields you can configure for the PingSource object, see [PingSource reference](reference.md).

4
docs/developer/eventing/sources/ping-source/reference.md
View File

@ -1,5 +1,7 @@
# PingSource reference
![API version v1](https://img.shields.io/badge/API_Version-v1-green?style=flat-square)
This topic provides reference information about the configurable fields for the
PingSource object.
@ -18,7 +20,7 @@ A PingSource definition supports the following fields:
| `spec.data` | The data used as the body of the event posted to the sink. Default is empty. Mutually exclusive with `dataBase64`. | Required if not sending base64 encoded data |
| `spec.dataBase64` | A base64-encoded string of the actual event's body posted to the sink. Default is empty. Mutually exclusive with `data`. | Required if sending base64 encoded data |
| `spec.schedule` | Specifies the cron schedule. Defaults to `* * * * *`. | Optional |
| [`spec.sink`](../../sinks/README.md) | A reference to an object that resolves to a URI to use as the sink. | Required |
| [`spec.sink`](../../sinks/README.md#sink-as-a-parameter) | A reference to an object that resolves to a URI to use as the sink. | Required |
| `spec.timezone` | Modifies the actual time relative to the specified timezone. Defaults to the system time zone. <br><br> See the [list of valid tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) on Wikipedia. For general information about time zones, see the [IANA](https://www.iana.org/time-zones) website. | Optional |
| [`spec.ceOverrides`](#cloudevent-overrides) | Defines overrides to control the output format and modifications to the event sent to the sink. | Optional |
| `status`| Defines the observed state of PingSource. | Optional |

2
docs/developer/eventing/sources/sinkbinding/README.md
View File

@ -1,6 +1,6 @@
# SinkBinding
![API version v1](https://img.shields.io/badge/API_Version-v1-red?style=flat-square)
![API version v1](https://img.shields.io/badge/API_Version-v1-green?style=flat-square)
The SinkBinding object supports decoupling event production from
delivery addressing.

11
docs/developer/eventing/sources/sinkbinding/getting-started.md
View File

@ -1,6 +1,6 @@
# Creating a SinkBinding object
![API version v1](https://img.shields.io/badge/API_Version-v1-red?style=flat-square)
![API version v1](https://img.shields.io/badge/API_Version-v1-green?style=flat-square)
This topic describes how to create a SinkBinding object.
SinkBinding resolves a sink as a URI, sets the URI in the environment
@ -88,7 +88,7 @@ create a Knative service.
For example:
```bash
$ kn service create event-display --image gcr.io/knative-releases/knative.dev/eventing-contrib/cmd/event_display
$ kn service create event-display --image gcr.io/knative-releases/knative.dev/eventing/cmd/event_display
```
=== "YAML"
@ -109,7 +109,7 @@ create a Knative service.
- `<app-name>` is the name of the application. For example, `event-display`.
- `<image-url>` is the URL of the image container.
For example, `gcr.io/knative-releases/knative.dev/eventing-contrib/cmd/event_display`.
For example, `gcr.io/knative-releases/knative.dev/eventing/cmd/event_display`.
1. Apply the YAML file by running the command:
@ -205,7 +205,8 @@ Create a `SinkBinding` object that directs events from your subject to the sink.
Cloud Event overrides control the output format and modifications of the event
sent to the sink and are applied before sending the event.
You can provide this flag multiple times.
<!-- TODO provide link to information about the flags for the kn command -->
For a list of available options, see the [Knative client documentation](https://github.com/knative/client/blob/main/docs/cmd/kn_source_binding_create.md#kn-source-binding-create).
For example:
```bash
@ -300,7 +301,7 @@ sent by the source to the display function. For example:
}
```
## Cleanup
## Delete the SinkBinding object
To delete the SinkBinding object and all of the related resources in the namespace,
delete the namespace by running:

4
docs/developer/eventing/sources/sinkbinding/reference.md
View File

@ -1,6 +1,6 @@
# SinkBinding reference
![API version v1](https://img.shields.io/badge/API_Version-v1-red?style=flat-square)
![API version v1](https://img.shields.io/badge/API_Version-v1-green?style=flat-square)
This topic provides reference information about the configurable parameters for SinkBinding objects.
@ -14,7 +14,7 @@ A `SinkBinding` resource supports the following parameters:
| [`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`](../../../../developer/eventing/sinks/README.md) | A reference to an object that resolves to a URI to use as the sink. | Required |
| [`spec.sink`](../../sinks/README.md#sink-as-a-parameter) | 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 |