×

An API server source is an event source that can be used to connect an event sink, such as a Knative service, to the Kubernetes API server. An API server source watches for Kubernetes events and forwards them to the Knative Eventing broker.

Prerequisites

  • You must have a current installation of OpenShift Serverless, including Knative Serving and Eventing, in your OpenShift Container Platform cluster. This can be installed by a cluster administrator.

  • Event sources need a service to use as an event sink. The sink is the service or application that events are sent to from the event source.

  • You must create or update a service account, role and role binding for the event source.

Some of the following procedures require you to create YAML files.

If you change the names of the YAML files from those used in the examples, you must ensure that you also update the corresponding CLI commands.

Creating a service account, role, and binding for event sources

Procedure
  1. Create a service account, role, and role binding for the event source by creating a file named authentication.yaml and copying the following sample code into it:

    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: events-sa
      namespace: default (1)
    
    ---
    apiVersion: rbac.authorization.k8s.io/v1
    kind: Role
    metadata:
      name: event-watcher
      namespace: default (1)
    rules:
      - apiGroups:
          - ""
        resources:
          - events
        verbs:
          - get
          - list
          - watch
    
    ---
    apiVersion: rbac.authorization.k8s.io/v1
    kind: RoleBinding
    metadata:
      name: k8s-ra-event-watcher
      namespace: default (1)
    roleRef:
      apiGroup: rbac.authorization.k8s.io
      kind: Role
      name: event-watcher
    subjects:
      - kind: ServiceAccount
        name: events-sa
        namespace: default (1)
    1 Change this namespace to the namespace that you have selected for installing the event source.

    If you want to re-use an existing service account with the appropriate permissions, you must modify the authentication.yaml for that service account.

  2. Create the service account, role binding, and cluster binding by entering the following command:

    $ oc apply --filename authentication.yaml

Creating an ApiServerSource event source using the Developer perspective

Procedure
  1. Navigate to the Add page and select Event Source.

  2. In the Event Sources page, select ApiServerSource in the Type section.

    Create an ApiServerSource
  3. Configure the ApiServerSource settings:

    1. Enter v1 as the APIVERSION, and Event as the KIND.

    2. Select the Service Account Name for the service account that you created.

      Select the Service Account Name and Sink
    3. Select the targeted Knative service from the dropdown menu in SinkKnative Service.

  4. Click Create.

Verification
  1. After you have created the ApiServerSource, you will see it connected to the service it is sinked to in the Topology view.

    ApiServerSource Topology view

Deleting the ApiServerSource

Procedure
  1. Navigate to the Topology view.

  2. Right-click the ApiServerSource and select Delete ApiServerSource.

    Delete the ApiServerSource

Using the API server source with the Knative CLI

This section describes the steps required to create an ApiServerSource object using kn commands.

Prerequisites
  • Knative Serving and Eventing are installed on your cluster.

  • You have created the default broker in the same namespace that the API server source will be installed in.

  • You have the kn CLI installed.

Procedure
  1. Create a service account, role, and role binding for the ApiServerSource object.

    You can do this by creating a file named authentication.yaml and copying the following sample code into it:

    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: events-sa
      namespace: default (1)
    
    ---
    apiVersion: rbac.authorization.k8s.io/v1
    kind: Role
    metadata:
      name: event-watcher
      namespace: default (1)
    rules:
      - apiGroups:
          - ""
        resources:
          - events
        verbs:
          - get
          - list
          - watch
    
    ---
    apiVersion: rbac.authorization.k8s.io/v1
    kind: RoleBinding
    metadata:
      name: k8s-ra-event-watcher
      namespace: default (1)
    roleRef:
      apiGroup: rbac.authorization.k8s.io
      kind: Role
      name: event-watcher
    subjects:
      - kind: ServiceAccount
        name: events-sa
        namespace: default (1)
    1 Change this namespace to the namespace that you have selected for installing the API server source.

    If you want to reuse an existing service account with the appropriate permissions, you must modify the authentication.yaml file for that service account.

    Create the service account, role binding, and cluster binding:

    $ oc apply -f authentication.yaml
  2. Create an ApiServerSource object that uses a broker as an event sink:

    $ kn source apiserver create <event_source_name> --sink broker:<broker_name> --resource "event:v1" --service-account <service_account_name> --mode Resource
  3. Create a Knative service that dumps incoming messages to its log:

    $ kn service create <service_name> --image quay.io/openshift-knative/knative-eventing-sources-event-display:latest
  4. Create a trigger to filter events from the default broker to the service:

    $ kn trigger create <trigger_name> --sink ksvc:<service_name>
  5. Create events by launching a pod in the default namespace:

    $ oc create deployment hello-node --image=quay.io/openshift-knative/knative-eventing-sources-event-display
  6. Check that the controller is mapped correctly by inspecting the output generated by the following command:

    $ kn source apiserver describe testevents
    Example output
    Name:                testevents
    Namespace:           default
    Annotations:         sources.knative.dev/creator=developer, sources.knative.dev/lastModifier=developer
    Age:                 3m
    ServiceAccountName:  events-sa
    Mode:                Resource
    Sink:
      Name:       default
      Namespace:  default
      Kind:       Broker (eventing.knative.dev/v1)
    Resources:
      Kind:        event (v1)
      Controller:  false
    Conditions:
      OK TYPE                     AGE REASON
      ++ Ready                     3m
      ++ Deployed                  3m
      ++ SinkProvided              3m
      ++ SufficientPermissions     3m
      ++ EventTypesProvided        3m
Verification

You can verify that the Kubernetes events were sent to Knative by looking at the message dumper function logs.

  1. Get the pods:

    $ oc get pods
  2. View the message dumper function logs for the pods:

    $ oc logs $(oc get pod -o name | grep event-display) -c user-container
    Example output
    ☁️  cloudevents.Event
    Validation: valid
    Context Attributes,
      specversion: 1.0
      type: dev.knative.apiserver.resource.update
      datacontenttype: application/json
      ...
    Data,
      {
        "apiVersion": "v1",
        "involvedObject": {
          "apiVersion": "v1",
          "fieldPath": "spec.containers{hello-node}",
          "kind": "Pod",
          "name": "hello-node",
          "namespace": "default",
           .....
        },
        "kind": "Event",
        "message": "Started container",
        "metadata": {
          "name": "hello-node.159d7608e3a3572c",
          "namespace": "default",
          ....
        },
        "reason": "Started",
        ...
      }

Deleting an API server source using the Knative CLI

This section describes the steps used to delete the ApiServerSource object, trigger, service, service account, cluster role, and cluster binding using the kn and oc commands.

Prerequisites
  • You must have the kn CLI installed.

Procedure
  1. Delete the trigger:

    $ kn trigger delete <trigger_name>
  2. Delete the service:

    $ kn service delete <service_name>
  3. Delete the API server source:

    $ kn source apiserver delete <source_name>
  4. Delete the service account, cluster role, and cluster binding:

$ oc delete -f authentication.yaml

Creating an API server source using YAML files

This guide describes the steps required to create an ApiServerSource object using YAML files.

Prerequisites
  • Knative Serving and Eventing are installed on your cluster.

  • You have created the default broker in the same namespace as the one defined in the ApiServerSource object.

Procedure
  1. To create a service account, role, and role binding for the API server source, create a file named authentication.yaml and copy the following sample code into it:

    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: events-sa
      namespace: default (1)
    
    ---
    apiVersion: rbac.authorization.k8s.io/v1
    kind: Role
    metadata:
      name: event-watcher
      namespace: default (1)
    rules:
      - apiGroups:
          - ""
        resources:
          - events
        verbs:
          - get
          - list
          - watch
    
    ---
    apiVersion: rbac.authorization.k8s.io/v1
    kind: RoleBinding
    metadata:
      name: k8s-ra-event-watcher
      namespace: default (1)
    roleRef:
      apiGroup: rbac.authorization.k8s.io
      kind: Role
      name: event-watcher
    subjects:
      - kind: ServiceAccount
        name: events-sa
        namespace: default (1)
    1 Change this namespace to the namespace that you have selected for installing the API server source.

    If you want to re-use an existing service account with the appropriate permissions, you must modify the authentication.yaml for that service account.

    After you have created the authentication.yaml file, apply it:

    $ oc apply -f authentication.yaml
  2. To create an ApiServerSource object, create a file named k8s-events.yaml and copy the following sample code into it:

    apiVersion: sources.knative.dev/v1alpha1
    kind: ApiServerSource
    metadata:
      name: testevents
    spec:
      serviceAccountName: events-sa
      mode: Resource
      resources:
        - apiVersion: v1
          kind: Event
      sink:
        ref:
          apiVersion: eventing.knative.dev/v1
          kind: Broker
          name: default

    After you have created the k8s-events.yaml file, apply it:

    $ oc apply -f k8s-events.yaml
  3. To check that the API server source is set up correctly, create a Knative service that dumps incoming messages to its log.

    Copy the following sample YAML into a file named service.yaml:

    apiVersion: serving.knative.dev/v1
    kind: Service
    metadata:
      name: event-display
      namespace: default
    spec:
      template:
        spec:
          containers:
            - image: quay.io/openshift-knative/knative-eventing-sources-event-display:latest

    After you have created the service.yaml file, apply it:

    $ oc apply -f service.yaml
  4. To create a trigger from the default broker that filters events to the service created in the previous step, create a file named trigger.yaml and copy the following sample code into it:

    apiVersion: eventing.knative.dev/v1
    kind: Trigger
    metadata:
      name: event-display-trigger
      namespace: default
    spec:
      broker: default
      subscriber:
        ref:
          apiVersion: serving.knative.dev/v1
          kind: Service
          name: event-display

    After you have created the trigger.yaml file, apply it:

    $ oc apply -f trigger.yaml
  5. To create events, launch a pod in the default namespace:

    $ oc create deployment hello-node --image=quay.io/openshift-knative/knative-eventing-sources-event-display
  6. To check that the controller is mapped correctly, enter the following command and inspect the output:

    $ oc get apiserversource.sources.knative.dev testevents -o yaml
    Example output
    apiVersion: sources.knative.dev/v1alpha1
    kind: ApiServerSource
    metadata:
      annotations:
      creationTimestamp: "2020-04-07T17:24:54Z"
      generation: 1
      name: testevents
      namespace: default
      resourceVersion: "62868"
      selfLink: /apis/sources.knative.dev/v1alpha1/namespaces/default/apiserversources/testevents2
      uid: 1603d863-bb06-4d1c-b371-f580b4db99fa
    spec:
      mode: Resource
      resources:
      - apiVersion: v1
        controller: false
        controllerSelector:
          apiVersion: ""
          kind: ""
          name: ""
          uid: ""
        kind: Event
        labelSelector: {}
      serviceAccountName: events-sa
      sink:
        ref:
          apiVersion: eventing.knative.dev/v1
          kind: Broker
          name: default
Verification

To verify that the Kubernetes events were sent to Knative, you can look at the message dumper function logs.

  1. Get the pods:

    $ oc get pods
  2. View the message dumper function logs for the pods:

    $ oc logs $(oc get pod -o name | grep event-display) -c user-container
    Example output
    ☁️  cloudevents.Event
    Validation: valid
    Context Attributes,
      specversion: 1.0
      type: dev.knative.apiserver.resource.update
      datacontenttype: application/json
      ...
    Data,
      {
        "apiVersion": "v1",
        "involvedObject": {
          "apiVersion": "v1",
          "fieldPath": "spec.containers{hello-node}",
          "kind": "Pod",
          "name": "hello-node",
          "namespace": "default",
           .....
        },
        "kind": "Event",
        "message": "Started container",
        "metadata": {
          "name": "hello-node.159d7608e3a3572c",
          "namespace": "default",
          ....
        },
        "reason": "Started",
        ...
      }

Deleting the API server source

This section describes how to delete the ApiServerSource object, trigger, service, service account, cluster role, and cluster binding by deleting their YAML files.

Procedure
  1. Delete the trigger:

    $ oc delete -f trigger.yaml
  2. Delete the service:

    $ oc delete -f service.yaml
  3. Delete the API server source:

    $ oc delete -f k8s-events.yaml
  4. Delete the service account, cluster role, and cluster binding:

    $ oc delete -f authentication.yaml