diff --git a/docs/developer/eventing/sources/apiserversource/README.md b/docs/developer/eventing/sources/apiserversource/README.md index 2e18f05a2..97952fea8 100644 --- a/docs/developer/eventing/sources/apiserversource/README.md +++ b/docs/developer/eventing/sources/apiserversource/README.md @@ -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. diff --git a/docs/developer/eventing/sources/apiserversource/getting-started.md b/docs/developer/eventing/sources/apiserversource/getting-started.md index 5eb30d1bf..982fe92b8 100644 --- a/docs/developer/eventing/sources/apiserversource/getting-started.md +++ b/docs/developer/eventing/sources/apiserversource/getting-started.md @@ -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.

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

+ 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: ``` - Where - - `` is the name of the Role that you want to create. - - `` 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: + - `` is the name of the Role that you want to create. + - `` 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: - `` is the name of the RoleBinding that you want to create. - - `` is the name of the Role that you created in step 3 earlier. + - `` is the name of the Role that you created in step 3 earlier. - `` is the name of the ServiceAccount that you created in step 2 earlier. - `` 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: - `` is the name of the ServiceAccount that you created in step 2 earlier. - `` 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: + name: namespace: spec: serviceAccountName: @@ -214,13 +217,15 @@ command: ``` Where: - - `` is the name of the source that you want to create. + - `` is the name of the source that you want to create. - `` is the name of the namespace that you created in step 1 earlier. - `` is the name of the ServiceAccount that you created in step 2 earlier. - `` 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`. - - `` 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`. + - `` is any supported [Addressable](../../../concepts/duck-typing.md#addressable) object that you want to use as a sink, for example, `Service` or `Deployment`. - `` 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= --restart=Never -- ls ``` Where `` 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= 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: diff --git a/docs/developer/eventing/sources/apiserversource/reference.md b/docs/developer/eventing/sources/apiserversource/reference.md index bf0cb0898..4ca923370 100644 --- a/docs/developer/eventing/sources/apiserversource/reference.md +++ b/docs/developer/eventing/sources/apiserversource/reference.md @@ -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 `` 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: - 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: + name: test-role rules: - apiGroups: - "" @@ -146,30 +150,34 @@ rules: - watch ``` +Example RoleBinding: + ```yaml apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: - name: + name: test-role-binding roleRef: apiGroup: rbac.authorization.k8s.io kind: Role - name: + name: test-role subjects: - kind: ServiceAccount - name: - namespace: + name: test-service-account + namespace: apiserversource-example ``` +Example ApiServerSource using `test-service-account`: + ```yaml apiVersion: sources.knative.dev/v1 kind: ApiServerSource metadata: - name: - namespace: + name: test-apiserversource + namespace: apiserversource-example spec: # ... - serviceAccountName: + 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"`. - - - -```yaml -apiVersion: sources.knative.dev/v1 -kind: ApiServerSource -metadata: - name: - 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 diff --git a/docs/developer/eventing/sources/containersource/README.md b/docs/developer/eventing/sources/containersource/README.md index eea04d5d7..3bef05826 100644 --- a/docs/developer/eventing/sources/containersource/README.md +++ b/docs/developer/eventing/sources/containersource/README.md @@ -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: diff --git a/docs/developer/eventing/sources/containersource/reference.md b/docs/developer/eventing/sources/containersource/reference.md index 23a8c5d5a..53fa5c807 100644 --- a/docs/developer/eventing/sources/containersource/reference.md +++ b/docs/developer/eventing/sources/containersource/reference.md @@ -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"`. - - - -```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. @@ -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 diff --git a/docs/developer/eventing/sources/ping-source/README.md b/docs/developer/eventing/sources/ping-source/README.md index c16ef0302..234e6202c 100644 --- a/docs/developer/eventing/sources/ping-source/README.md +++ b/docs/developer/eventing/sources/ping-source/README.md @@ -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. - `` is a cron expression for the schedule for the PingSource to send events, for example, `*/1 * * * *` sends an event every minute. - `` is the media type of the data you want to send, for example, `application/json`. - `` 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!"}`. - - `` 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`. + - `` is any supported [Addressable](../../../concepts/duck-typing.md#addressable) object that you want to use as a sink, for example, `Service` or `Deployment`. - `` 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. - `` is a cron expression for the schedule for the PingSource to send events, for example, `*/1 * * * *` sends an event every minute. - `` is the media type of the data you want to send, for example, `application/json`. - `` is the base64 encoded binary data that you want to send, for example, `ZGF0YQ==`. - - `` 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`. + - `` is any supported [Addressable](../../../concepts/duck-typing.md#addressable) object that you want to use as a sink, for example, `Service` or `Deployment`. - `` 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). diff --git a/docs/developer/eventing/sources/ping-source/reference.md b/docs/developer/eventing/sources/ping-source/reference.md index b714923b7..959fef10b 100644 --- a/docs/developer/eventing/sources/ping-source/reference.md +++ b/docs/developer/eventing/sources/ping-source/reference.md @@ -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.

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 | diff --git a/docs/developer/eventing/sources/sinkbinding/README.md b/docs/developer/eventing/sources/sinkbinding/README.md index 02b011662..277121579 100644 --- a/docs/developer/eventing/sources/sinkbinding/README.md +++ b/docs/developer/eventing/sources/sinkbinding/README.md @@ -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. diff --git a/docs/developer/eventing/sources/sinkbinding/getting-started.md b/docs/developer/eventing/sources/sinkbinding/getting-started.md index 8fa19574d..e485dc2c7 100644 --- a/docs/developer/eventing/sources/sinkbinding/getting-started.md +++ b/docs/developer/eventing/sources/sinkbinding/getting-started.md @@ -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. - `` is the name of the application. For example, `event-display`. - `` 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. - + + 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: diff --git a/docs/developer/eventing/sources/sinkbinding/reference.md b/docs/developer/eventing/sources/sinkbinding/reference.md index b635544e5..913726fd5 100644 --- a/docs/developer/eventing/sources/sinkbinding/reference.md +++ b/docs/developer/eventing/sources/sinkbinding/reference.md @@ -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 |