Clean up sources docs (#4304)

* Edit PR #4301

* Tweak other sources pages to match

* make v1 badges green

* Update event display image

Author: snneji

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.

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.<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,14 +192,16 @@ 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:
 
             ```yaml
             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:
 

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

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:

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"`.
-
-<!-- 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