Using ApiServerSource - Event sources | Serverless applications

Using the API server source with the Knative CLI
Deleting an API server source using the Knative CLI
Creating an API server source using YAML files
Deleting the API server source

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.

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

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

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

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

Create a trigger to filter events from the default broker to the service:
```
$ kn trigger create <trigger_name> --sink svc:<service_name>
```

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

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/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 to Knative by looking at the message dumper function logs.

Get the pods:
```
$ oc get pods
```

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

Delete the trigger:
```
$ kn trigger delete <trigger_name>
```
Delete the service:
```
$ kn service delete <service_name>
```

Delete the API server source:

$ kn source apiserver delete <source_name>

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

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

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

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

$ oc apply -f k8s-events.yaml

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:v0.13.2

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

$ oc apply -f service.yaml

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

$ oc apply -f trigger.yaml

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

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

Verification steps

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

Get the pods:
```
$ oc get pods
```

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

Delete the trigger:
```
$ oc delete -f trigger.yaml
```
Delete the service:
```
$ oc delete -f service.yaml
```
Delete the API server source:
```
$ oc delete -f k8s-events.yaml
```
Delete the service account, cluster role, and cluster binding:
```
$ oc delete -f authentication.yaml
```