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

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

Using the ApiServerSource with the Knative CLI (kn)

This guide describes the steps required to create, manage, and delete an ApiServerSource using kn commands.

Prerequisites
  • You will need to have a Knative Serving and Eventing installation.

  • You will need to have created the default broker in the same namespace that the ApiServerSource will be installed in.

  • You will need to have the kn CLI installed.

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

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

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

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

    $ oc apply --filename authentication.yaml
  2. Create an ApiServerSource event source by entering the following command:

    $ kn source apiserver create testevents --sink broker:default --resource "event:v1" --service-account events-sa --mode Resource
  3. To check that the ApiServerSource is set up correctly, create a Knative service that dumps incoming messages to its log by entering the following command:

    $ kn service create event-display --image quay.io/openshift-knative/knative-eventing-sources-event-display:v0.13.2
  4. Create a trigger from the default broker to filter events to the service created in the previous step by entering the following kn command:

    $ kn trigger create event-display-trigger --sink svc:event-display
  5. Create events by launching a pod in the default namespace. You can do this by entering the following command:

    $ oc create deployment hello-node --image=gcr.io/hello-minikube-zero-install/hello-node
  6. Check that the controller is mapped correctly by entering the following command and inspecting the output:

    $ kn source apiserver describe testevents

    The output should be similar to:

    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/v1alpha1)
    Resources:
      Kind:        event (v1)
      Controller:  false
    Conditions:
      OK TYPE                     AGE REASON
      ++ Ready                     3m
      ++ Deployed                  3m
      ++ SinkProvided              3m
      ++ SufficientPermissions     3m
      ++ EventTypesProvided        3m
Verification steps

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

You can view the message dumper function logs by entering the following commands:

$ oc get pods
$ oc logs $(oc get pod -o name | grep event-display) -c user-container

The logs should contain lines similar to the following:

☁️  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 ApiServerSource

You can delete the ApiServerSource, trigger, service, service account, cluster role, and cluster binding created in this guide by entering the following kn and oc commands:

$ kn trigger delete event-display-trigger
$ kn service delete event-display
$ kn source apiserver delete testevents
$ oc delete -f authentication.yaml

Using the ApiServerSource with the YAML method

This guide describes the steps required to create, manage, and delete an ApiServerSource using YAML files.

Prerequisites
  • You will need to have a Knative Serving and Eventing installation.

  • You will need to have created the default broker in the same namespace as the one defined in the ApiServerSource YAML file.

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

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

    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 by entering the following command:

    $ oc apply --filename authentication.yaml
  2. Create an ApiServerSource event source.

    You can do this by creating a file named k8s-events.yaml and copying 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/v1beta1
          kind: Broker
          name: default

    After you have created the k8s-events.yaml file, apply it by entering the following command:

    $ oc apply --filename k8s-events.yaml
  3. To check that the ApiServerSource 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:v0.13.2

    After you have created the service.yaml file, apply it by entering the following command:

    $ oc apply --filename service.yaml
  4. Create a trigger from the default broker to filter events to the service created in the previous step.

    You can create the trigger by creating a file named trigger.yaml and copying the following sample code into it:

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

    After you have created the trigger.yaml file, apply it by entering the following command:

    $ oc apply --filename trigger.yaml
  5. Create events by launching a pod in the default namespace. You can do this by entering the following command:

    $ oc create deployment hello-node --image=gcr.io/hello-minikube-zero-install/hello-node
  6. Check that the controller is mapped correctly by entering the following command and inspecting the output:

    $ oc get apiserversource.sources.knative.dev testevents -o yaml

    The output should be similar to:

    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/v1beta1
          kind: Broker
          name: default
Verification steps

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

You can view the message dumper function logs by entering the following commands:

$ oc get pods
$ oc logs $(oc get pod -o name | grep event-display) -c user-container

The logs should contain lines similar to the following:

☁️  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 ApiServerSource

You can delete the ApiServerSource, trigger, service, service account, cluster role, and cluster binding created in this guide by entering the following oc commands:

$ oc delete --filename trigger.yaml
$ oc delete --filename service.yaml
$ oc delete --filename k8s-events.yaml
$ oc delete --filename authentication.yaml