Creating an ApiServerSource object

    This topic describes how to create an ApiServerSource object.

    Before you can create an ApiServerSource object:

    • You must have installed on your cluster.
    • You must install the kubectl CLI tool.
    • Optional: If you want to use the commands, install the tool.

    1. Optional: Create a namespace for the API server source instance by running the command:

      Where <namespace> is the name of the namespace that you want to create.

      Note

      Creating a namespace for your ApiServerSource and related components 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.

    2. Create a ServiceAccount:

      1. Create a YAML file using the following template:

        1. apiVersion: v1
        2. kind: ServiceAccount
        3. metadata:
        4.   name: <service-account>
        5.   namespace: <namespace>

        Where:

        • <service-account> is the name of the ServiceAccount that you want to create.
        • <namespace> is the namespace that you created in step 1 earlier.

      2. Apply the YAML file by running the command:

        1. kubectl apply -f <filename>.yaml

        Where <filename> is the name of the file you created in the previous step.

    3. Create a Role:

      1. Create a YAML file using the following template:

        1. apiVersion: rbac.authorization.k8s.io/v1
        2. kind: Role
        3. metadata:
        4.   name: <role>
        5.   namespace: <namespace>
        6. rules:
        7.   <rules>

        Where:

        • <role> is the name of the Role that you want to create.
        • <namespace> is the name of the namespace that you created in step 1 earlier.

        • <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:

          1. - apiGroups:
          2.   - ""
          3.   resources:
          4.   - events
          5.   verbs:
          6.   - get
          7.   - list
          8.   - watch

          The only required verbs are get, list and watch.

      2. Apply the YAML file by running the command:

        1. kubectl apply -f <filename>.yaml

        Where <filename> is the name of the file you created in the previous step.

    4. Create a RoleBinding:

      1. Create a YAML file using the following template:

        Where:

        • <role-binding> is the name of the RoleBinding that you want to create.
        • <namespace> is the name of the namespace that you created in step 1 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.

      2. Apply the YAML file by running the command:

        1. kubectl apply -f <filename>.yaml

        Where <filename> is the name of the file you created in the previous step.

    5. Create a sink. If you do not have your own sink, you can use the following example Service that dumps incoming messages to a log:

      1. Copy the YAML below into a file:

        1. apiVersion: apps/v1
        2. kind: Deployment
        3. metadata:
        4.   name: event-display
        5.   namespace: <namespace>
        6. spec:
        7.   replicas: 1
        8.   selector:
        9.       app: event-display
        10.   template:
        11.     metadata:
        12.       labels: *labels
        13.     spec:
        14.       containers:
        15.         - name: event-display
        18. ---
        20. kind: Service
        21. apiVersion: v1
        22. metadata:
        23.   name: event-display
        24.   namespace: <namespace>
        25. spec:
        26.   selector:
        27.     app: event-display
        28.   ports:
        29.   - protocol: TCP
        30.     port: 80
        31.     targetPort: 8080

        Where <namespace> is the name of the namespace that you created in step 1 above.

      2. Apply the YAML file by running the command:

        1. kubectl apply -f <filename>.yaml

        Where <filename> is the name of the file you created in the previous step.

    6. Create the ApiServerSource object:

      knYAML

      • To create the ApiServerSource, run the command:

        1. kn source apiserver create <apiserversource> \
        2.   --namespace <namespace> \
        3.   --mode "Resource" \
        4.   --resource "Event:v1" \
        5.   --service-account <service-account> \
        6.   --sink <sink-name>
        • <apiserversource> 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.
        • <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 .

      1. Create a YAML file using the following template:

        1. apiVersion: sources.knative.dev/v1
        2. kind: ApiServerSource
        3. metadata:
        4.  name: <apiserversource-name>
        5.  namespace: <namespace>
        6. spec:
        7.  serviceAccountName: <service-account>
        8.  mode: <event-mode>
        9.  resources:
        10.    - apiVersion: v1
        11.      kind: Event
        12.  sink:
        13.    ref:
        14.      apiVersion: v1
        15.      kind: <sink-kind>
        16.      name: <sink-name>

        Where:

        • <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 object that you want to use as a sink, for example, a Service or Deployment.

        For more information about the fields you can configure for the ApiServerSource object, see ApiServerSource reference.

      2. Apply the YAML file by running the command:

        Where <filename> is the name of the file you created in the previous step.

    1. Make the Kubernetes API server create events by launching a test Pod in your namespace by running the command:

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

    2. Delete the test Pod by running the command:

      1. kubectl --namespace=<namespace> delete pod busybox

      Where <namespace> is the name of the namespace that you created in step 1 earlier.

    3. View the logs to verify that Kubernetes events were sent to the sink by the Knative Eventing system by running the command:

      1. kubectl logs --namespace=<namespace> -l app=<sink> --tail=100

      Where:

      • <namespace> is the name of the namespace that you created in step 1 earlier.
      • <sink> is the name of the PodSpecable object that you used as a sink in step 5 earlier.

      Example log output:

      1. ☁️  cloudevents.Event
      2. Validation: valid
      3. Context Attributes,
      4.   specversion: 1.0
      5.   type: dev.knative.apiserver.resource.update
      6.   source: https://10.96.0.1:443
      7.   subject: /apis/v1/namespaces/apiserversource-example/events/testevents.15dd3050eb1e6f50
      8.   id: e0447eb7-36b5-443b-9d37-faf4fe5c62f0
      9.   time: 2020-07-28T19:14:54.719501054Z
      10.   datacontenttype: application/json
      11. Extensions,
      12.   kind: Event
      13.   name: busybox.1626008649e617e3
      14.   namespace: apiserversource-example
      15. Data,
      16.   {
      17.     "apiVersion": "v1",
      18.     "count": 1,
      19.     "eventTime": null,
      20.     "firstTimestamp": "2020-07-28T19:14:54Z",
      21.     "involvedObject": {
      22.       "apiVersion": "v1",
      23.       "fieldPath": "spec.containers{busybox}",
      24.       "kind": "Pod",
      25.       "name": "busybox",
      26.       "namespace": "apiserversource-example",
      27.       "resourceVersion": "28987493",
      28.       "uid": "1efb342a-737b-11e9-a6c5-42010a8a00ed"
      29.     },
      30.     "kind": "Event",
      31.     "lastTimestamp": "2020-07-28T19:14:54Z",
      32.     "message": "Started container",
      33.     "metadata": {
      34.       "creationTimestamp": "2020-07-28T19:14:54Z",
      35.       "name": "busybox.1626008649e617e3",
      36.       "namespace": "default",
      37.       "resourceVersion": "506088",
      38.     "selfLink": "/api/v1/namespaces/apiserversource-example/events/busybox.1626008649e617e3",
      39.       "uid": "2005af47-737b-11e9-a6c5-42010a8a00ed"
      40.     },
      41.     "reason": "Started",
      42.     "reportingComponent": "",
      43.     "reportingInstance": "",
      44.     "source": {
      45.       "component": "kubelet",
      46.       "host": "gke-knative-auto-cluster-default-pool-23c23c4f-xdj0"
      47.     },
      48.     "type": "Normal"
      49.   }

    To remove the ApiServerSource object and all of the related resources:

    • Delete the namespace by running the command:

        Where <namespace> is the name of the namespace that you created in step 1 earlier.