Chapter 5. Develop

Procedure

1. In offline mode, create a local Knative service descriptor file:

   $ kn service create event-display \
       --image quay.io/openshift-knative/knative-eventing-sources-event-display:latest \
       --target ./ \
       --namespace test

   Example output

   Service 'event-display' created in namespace 'test'.

   • The --target ./ flag enables offline mode and specifies ./ as the directory for storing the new directory tree.

     If you do not specify an existing directory, but use a filename, such as --target my-service.yaml, then no directory tree is created. Instead, only the service descriptor file my-service.yaml is created in the current directory.

     The filename can have the .yaml, .yml, or .json extension. Choosing .json creates the service descriptor file in the JSON format.

   • The --namespace test option places the new service in the test namespace.

     If you do not use --namespace, and you are logged in to an OpenShift Container Platform cluster, the descriptor file is created in the current namespace. Otherwise, the descriptor file is created in the default namespace.

2. Examine the created directory structure:

   $ tree ./

   Example output

   ./
   └── test
       └── ksvc
           └── event-display.yaml
   
   2 directories, 1 file

   • The current ./ directory specified with --target contains the new test/ directory that is named after the specified namespace.
   • The test/ directory contains the ksvc directory, named after the resource type.
   • The ksvc directory contains the descriptor file event-display.yaml, named according to the specified service name.

3. Examine the generated service descriptor file:

   $ cat test/ksvc/event-display.yaml

   Example output

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
     creationTimestamp: null
     name: event-display
     namespace: test
   spec:
     template:
       metadata:
         annotations:
           client.knative.dev/user-image: quay.io/openshift-knative/knative-eventing-sources-event-display:latest
         creationTimestamp: null
       spec:
         containers:
         - image: quay.io/openshift-knative/knative-eventing-sources-event-display:latest
           name: ""
           resources: {}
   status: {}

4. List information about the new service:

   $ kn service describe event-display --target ./ --namespace test

   Example output

   Name:       event-display
   Namespace:  test
   Age:
   URL:
   
   Revisions:
   
   Conditions:
     OK TYPE    AGE REASON

   • The --target ./ option specifies the root directory for the directory structure containing namespace subdirectories.

     Alternatively, you can directly specify a YAML or JSON filename with the --target option. The accepted file extensions are .yaml, .yml, and .json.

   • The --namespace option specifies the namespace, which communicates to kn the subdirectory that contains the necessary service descriptor file.

     If you do not use --namespace, and you are logged in to an OpenShift Container Platform cluster, kn searches for the service in the subdirectory that is named after the current namespace. Otherwise, kn searches in the default/ subdirectory.

5. Use the service descriptor file to create the service on the cluster:

   $ kn service create -f test/ksvc/event-display.yaml

   Example output

   Creating service 'event-display' in namespace 'test':
   
     0.058s The Route is still working to reflect the latest desired specification.
     0.098s ...
     0.168s Configuration "event-display" is waiting for a Revision to become ready.
    23.377s ...
    23.419s Ingress has not yet been reconciled.
    23.534s Waiting for load balancer to be ready
    23.723s Ready to serve.
   
   Service 'event-display' created to latest revision 'event-display-00001' is available at URL:
   http://event-display-test.apps.example.com

Procedure

1. Create a YAML file containing the following sample code:

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
     name: event-delivery
     namespace: default
   spec:
     template:
       spec:
         containers:
           - image: quay.io/openshift-knative/knative-eventing-sources-event-display:latest
             env:
               - name: RESPONSE
                 value: "Hello Serverless!"

2. Navigate to the directory where the YAML file is contained, and deploy the application by applying the YAML file:

   $ oc apply -f <filename>

Procedure

1. Find the application URL:

   $ oc get ksvc <service_name>

   Example output

   NAME            URL                                        LATESTCREATED         LATESTREADY           READY   REASON
   event-delivery   http://event-delivery-default.example.com   event-delivery-4wsd2   event-delivery-4wsd2   True

2. Make a request to your cluster and observe the output.

   Example HTTP request

   $ curl http://event-delivery-default.example.com

   Example HTTPS request

   $ curl https://event-delivery-default.example.com

   Example output

   Hello Serverless!

3. Optional. If you receive an error relating to a self-signed certificate in the certificate chain, you can add the --insecure flag to the curl command to ignore the error:

   $ curl https://event-delivery-default.example.com --insecure

   Example output

   Hello Serverless!

   Important

   Self-signed certificates must not be used in a production deployment. This method is only for testing purposes.

4. Optional. If your OpenShift Container Platform cluster is configured with a certificate that is signed by a certificate authority (CA) but not yet globally configured for your system, you can specify this with the curl command. The path to the certificate can be passed to the curl command by using the --cacert flag:

   $ curl https://event-delivery-default.example.com --cacert <file>

   Example output

   Hello Serverless!

Procedure

1. Find the application host. See the instructions in Verifying your serverless application deployment.

2. Find the ingress gateway’s public address:

   $ oc -n knative-serving-ingress get svc kourier

   Example output

   NAME                   TYPE           CLUSTER-IP      EXTERNAL-IP                                                             PORT(S)                                                                                                                                      AGE
   kourier   LoadBalancer   172.30.51.103   a83e86291bcdd11e993af02b7a65e514-33544245.us-east-1.elb.amazonaws.com   80:31380/TCP,443:31390/TCP   67m

   The public address is surfaced in the EXTERNAL-IP field, and in this case is a83e86291bcdd11e993af02b7a65e514-33544245.us-east-1.elb.amazonaws.com.

3. Manually set the host header of your HTTP request to the application’s host, but direct the request itself against the public address of the ingress gateway.

   $ curl -H "Host: hello-default.example.com" a83e86291bcdd11e993af02b7a65e514-33544245.us-east-1.elb.amazonaws.com

   Example output

   Hello Serverless!

   You can also make a gRPC request by setting the authority to the application’s host, while directing the request against the ingress gateway directly:

   grpc.Dial(
       "a83e86291bcdd11e993af02b7a65e514-33544245.us-east-1.elb.amazonaws.com:80",
       grpc.WithAuthority("hello-default.example.com:80"),
       grpc.WithInsecure(),
   )

   Note

   Ensure that you append the respective port, 80 by default, to both hosts as shown in the previous example.

Procedure

1. Add the knative.openshift.io/system-namespace=true label to each Knative system namespace that requires access to your application:

   1. Label the knative-serving namespace:

      $ oc label namespace knative-serving knative.openshift.io/system-namespace=true

   2. Label the knative-serving-ingress namespace:

      $ oc label namespace knative-serving-ingress knative.openshift.io/system-namespace=true

   3. Label the knative-eventing namespace:

      $ oc label namespace knative-eventing knative.openshift.io/system-namespace=true

   4. Label the knative-kafka namespace:

      $ oc label namespace knative-kafka knative.openshift.io/system-namespace=true

2. Create a NetworkPolicy object in your application namespace to allow access from namespaces with the knative.openshift.io/system-namespace label:

   Example NetworkPolicy object

   apiVersion: networking.k8s.io/v1
   kind: NetworkPolicy
   metadata:
     name: <network_policy_name> 1
     namespace: <namespace> 2
   spec:
     ingress:
     - from:
       - namespaceSelector:
           matchLabels:
             knative.openshift.io/system-namespace: "true"
     podSelector: {}
     policyTypes:
     - Ingress

   1

   Provide a name for your network policy.

   2

   The namespace where your application exists.

1. Click the Knative service to see its overview in the side panel.

2. Click the Resources tab, to see a list of Revisions and Routes for the service.

   Figure 5.1. Serverless application

   
3. Click the service, indicated by the S icon at the top of the side panel, to see an overview of the service details.
4. Click the YAML tab and modify the service configuration in the YAML editor, and click Save. For example, change the timeoutseconds from 300 to 301 . This change in the configuration triggers a new revision. In the Topology view, the latest revision is displayed and the Resources tab for the service now displays the two revisions.

5. In the Resources tab, click Set Traffic Distribution to see the traffic distribution dialog box:

   1. Add the split traffic percentage portion for the two revisions in the Splits field.
   2. Add tags to create custom URLs for the two revisions.

   3. Click Save to see two nodes representing the two revisions in the Topology view.

      Figure 5.2. Serverless application revisions

      

Procedure

1. Create and deploy an app as a Knative service.

2. Find the name of the first revision that was created when you deployed the service, by viewing the output from the following command:

   $ oc get ksvc <service_name> -o=jsonpath='{.status.latestCreatedRevisionName}'

   Example command

   $ oc get ksvc example-service -o=jsonpath='{.status.latestCreatedRevisionName}'

   Example output

   $ example-service-00001

3. Add the following YAML to the service spec to send inbound traffic to the revision:

   ...
   spec:
     traffic:
       - revisionName: <first_revision_name>
         percent: 100 # All traffic goes to this revision
   ...

4. Verify that you can view your app at the URL output you get from running the following command:

   $ oc get ksvc <service_name>

5. Deploy a second revision of your app by modifying at least one field in the template spec of the service and redeploying it. For example, you can modify the image of the service, or an env environment variable. You can redeploy the service by applying the service YAML file, or by using the kn service update command if you have installed the Knative (kn) CLI.

6. Find the name of the second, latest revision that was created when you redeployed the service, by running the command:

   $ oc get ksvc <service_name> -o=jsonpath='{.status.latestCreatedRevisionName}'

   At this point, both the first and second revisions of the service are deployed and running.

7. Update your existing service to create a new, test endpoint for the second revision, while still sending all other traffic to the first revision:

   Example of updated service spec with test endpoint

   ...
   spec:
     traffic:
       - revisionName: <first_revision_name>
         percent: 100 # All traffic is still being routed to the first revision
       - revisionName: <second_revision_name>
         percent: 0 # No traffic is routed to the second revision
         tag: v2 # A named route
   ...

   After you redeploy this service by reapplying the YAML resource, the second revision of the app is now staged. No traffic is routed to the second revision at the main URL, and Knative creates a new service named v2 for testing the newly deployed revision.

8. Get the URL of the new service for the second revision, by running the following command:

   $ oc get ksvc <service_name> --output jsonpath="{.status.traffic[*].url}"

   You can use this URL to validate that the new version of the app is behaving as expected before you route any traffic to it.

9. Update your existing service again, so that 50% of traffic is sent to the first revision, and 50% is sent to the second revision:

   Example of updated service spec splitting traffic 50/50 between revisions

   ...
   spec:
     traffic:
       - revisionName: <first_revision_name>
         percent: 50
       - revisionName: <second_revision_name>
         percent: 50
         tag: v2
   ...

10. When you are ready to route all traffic to the new version of the app, update the service again to send 100% of traffic to the second revision:

    Example of updated service spec sending all traffic to the second revision

    ...
    spec:
      traffic:
        - revisionName: <first_revision_name>
          percent: 0
        - revisionName: <second_revision_name>
          percent: 100
          tag: v2
    ...

    Tip

    You can remove the first revision instead of setting it to 0% of traffic if you do not plan to roll back the revision. Non-routeable revision objects are then garbage-collected.

11. Visit the URL of the first revision to verify that no more traffic is being sent to the old version of the app.

Procedure

1. Create a Knative service that contains the label or annotation that you want to propagate to the OpenShift Container Platform route:

   • To create a service by using YAML:

     Example service created by using YAML

     apiVersion: serving.knative.dev/v1
     kind: Service
     metadata:
       name: <service_name>
       labels:
         <label_name>: <label_value>
       annotations:
         <annotation_name>: <annotation_value>
     ...

   • To create a service by using the Knative (kn) CLI, enter:

     Example service created by using a kn command

     $ kn service create <service_name> \
       --image=<image> \
       --annotation <annotation_name>=<annotation_value> \
       --label <label_value>=<label_value>

2. Verify that the OpenShift Container Platform route has been created with the annotation or label that you added by inspecting the output from the following command:

   Example command for verification

   $ oc get routes.route.openshift.io \
        -l serving.knative.openshift.io/ingressName=<service_name> \ 1
        -l serving.knative.openshift.io/ingressNamespace=<service_namespace> \ 2
        -n knative-serving-ingress -o yaml \
            | grep -e "<label_name>: \"<label_value>\""  -e "<annotation_name>: <annotation_value>" 3

   1

   Use the name of your service.

   2

   Use the namespace where your service was created.

   3

   Use your values for the label and annotation names and values.

Procedure

1. Create a Knative service that includes the serving.knative.openshift.io/disableRoute=true annotation:

   Important

   The serving.knative.openshift.io/disableRoute=true annotation instructs OpenShift Serverless to not automatically create a route for you. However, the service still shows a URL and reaches a status of Ready. This URL does not work externally until you create your own route with the same hostname as the hostname in the URL.

   1. Create a Knative Service resource:

      Example resource

      apiVersion: serving.knative.dev/v1
      kind: Service
      metadata:
        name: <service_name>
        annotations:
          serving.knative.openshift.io/disableRoute: "true"
      spec:
        template:
          spec:
            containers:
            - image: <image>
      ...

   2. Apply the Service resource:

      $ oc apply -f <filename>

   3. Optional. Create a Knative service by using the kn service create command:

      Example kn command

      $ kn service create <service_name> \
        --image=gcr.io/knative-samples/helloworld-go \
        --annotation serving.knative.openshift.io/disableRoute=true

2. Verify that no OpenShift Container Platform route has been created for the service:

   Example command

   $ $ oc get routes.route.openshift.io \
     -l serving.knative.openshift.io/ingressName=$KSERVICE_NAME \
     -l serving.knative.openshift.io/ingressNamespace=$KSERVICE_NAMESPACE \
     -n knative-serving-ingress

   You will see the following output:

   No resources found in knative-serving-ingress namespace.

3. Create a Route resource in the knative-serving-ingress namespace:

   apiVersion: route.openshift.io/v1
   kind: Route
   metadata:
     annotations:
       haproxy.router.openshift.io/timeout: 600s 1
     name: <route_name> 2
     namespace: knative-serving-ingress 3
   spec:
     host: <service_host> 4
     port:
       targetPort: http2
     to:
       kind: Service
       name: kourier
       weight: 100
     tls:
       insecureEdgeTerminationPolicy: Allow
       termination: edge 5
       key: |-
         -----BEGIN PRIVATE KEY-----
         [...]
         -----END PRIVATE KEY-----
       certificate: |-
         -----BEGIN CERTIFICATE-----
         [...]
         -----END CERTIFICATE-----
       caCertificate: |-
         -----BEGIN CERTIFICATE-----
         [...]
         -----END CERTIFICATE----
     wildcardPolicy: None

   1

   The timeout value for the OpenShift Container Platform route. You must set the same value as the max-revision-timeout-seconds setting (600s by default).

   2

   The name of the OpenShift Container Platform route.

   3

   The namespace for the OpenShift Container Platform route. This must be knative-serving-ingress.

   4

   The hostname for external access. You can set this to <service_name>-<service_namespace>.<domain>.

   5

   The certificates you want to use. Currently, only edge termination is supported.

4. Apply the Route resource:

   $ oc apply -f <filename>

Procedure

1. Create an event source of any type, by navigating to +Add Event Source and selecting the event source type that you want to create.
2. In the Sink section of the Create Event Source form view, select your sink in the Resource list.
3. Click Create.

1. In the Developer perspective, navigate to Topology.
2. View the event source and click the connected sink to see the sink details in the right panel.

Procedure

1. Create or modify a Trigger object and set the kafka.eventing.knative.dev/delivery.order annotation:

   apiVersion: eventing.knative.dev/v1
   kind: Trigger
   metadata:
     name: <trigger_name>
     annotations:
        kafka.eventing.knative.dev/delivery.order: ordered
   ...

   The supported consumer delivery guarantees are:

   unordered

   An unordered consumer is a non-blocking consumer that delivers messages unordered, while preserving proper offset management.

   ordered

   An ordered consumer is a per-partition blocking consumer that waits for a successful response from the CloudEvent subscriber before it delivers the next message of the partition.

   The default ordering guarantee is unordered.

2. Apply the Trigger object:

   $ oc apply -f <filename>

Procedure

1. List the available event source types in the terminal:

   $ kn source list-types

   Example output

   TYPE              NAME                                            DESCRIPTION
   ApiServerSource   apiserversources.sources.knative.dev            Watch and send Kubernetes API events to a sink
   PingSource        pingsources.sources.knative.dev                 Periodically send ping events to a sink
   SinkBinding       sinkbindings.sources.knative.dev                Binding for connecting a PodSpecable to a sink

2. Optional: You can also list the available event source types in YAML format:

   $ kn source list-types -o yaml

Procedure

1. Access the Developer perspective.
2. Click +Add.
3. Click Event Source.
4. View the available event source types.

Procedure

1. List the existing event sources in the terminal:

   $ kn source list

   Example output

   NAME   TYPE              RESOURCE                               SINK         READY
   a1     ApiServerSource   apiserversources.sources.knative.dev   ksvc:eshow2   True
   b1     SinkBinding       sinkbindings.sources.knative.dev       ksvc:eshow3   False
   p1     PingSource        pingsources.sources.knative.dev        ksvc:eshow1   True

2. Optional: You can list event sources of a specific type only, by using the --type flag:

   $ kn source list --type <event_source_type>

   Example command

   $ kn source list --type PingSource

   Example output

   NAME   TYPE              RESOURCE                               SINK         READY
   p1     PingSource        pingsources.sources.knative.dev        ksvc:eshow1   True

1. Create a service account, role, and role binding for the event source as a YAML file:

   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 2
   rules:
     - apiGroups:
         - ""
       resources:
         - events
       verbs:
         - get
         - list
         - watch
   
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: RoleBinding
   metadata:
     name: k8s-ra-event-watcher
     namespace: default 3
   roleRef:
     apiGroup: rbac.authorization.k8s.io
     kind: Role
     name: event-watcher
   subjects:
     - kind: ServiceAccount
       name: events-sa
       namespace: default 4

   1 2 3 4

   Change this namespace to the namespace that you have selected for installing the event source.

2. Apply the YAML file:

   $ oc apply -f <filename>

3. In the Developer perspective, navigate to +Add Event Source. The Event Sources page is displayed.
4. Optional: If you have multiple providers for your event sources, select the required provider from the Providers list to filter the available event sources from the provider.
5. Select ApiServerSource and then click Create Event Source. The Create Event Source page is displayed.

6. Configure the ApiServerSource settings by using the Form view or YAML view:

   Note

   You can switch between the Form view and YAML view. The data is persisted when switching between the views.

   1. Enter v1 as the APIVERSION and Event as the KIND.
   2. Select the Service Account Name for the service account that you created.
   3. Select the Sink for the event source. A Sink can be either a Resource, such as a channel, broker, or service, or a URI.
7. Click Create.

Deleting the API server source

1. Navigate to the Topology view.

2. Right-click the API server source and select Delete ApiServerSource.

   

1. Create a service account, role, and role binding for the event source as a YAML file:

   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 2
   rules:
     - apiGroups:
         - ""
       resources:
         - events
       verbs:
         - get
         - list
         - watch
   
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: RoleBinding
   metadata:
     name: k8s-ra-event-watcher
     namespace: default 3
   roleRef:
     apiGroup: rbac.authorization.k8s.io
     kind: Role
     name: event-watcher
   subjects:
     - kind: ServiceAccount
       name: events-sa
       namespace: default 4

   1 2 3 4

   Change this namespace to the namespace that you have selected for installing the event source.

2. Apply the YAML file:

   $ oc apply -f <filename>

3. Create an API server source that has an event sink. In the following example, the sink is a broker:

   $ kn source apiserver create <event_source_name> --sink broker:<broker_name> --resource "event:v1" --service-account <service_account_name> --mode Resource

4. To check that the API server source is set up correctly, 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

5. If you used a broker as an event sink, create a trigger to filter events from the default broker to the service:

   $ kn trigger create <trigger_name> --sink ksvc:<service_name>

6. 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:latest

7. Check that the controller is mapped correctly by inspecting the output generated by the following command:

   $ kn source apiserver describe <source_name>

   Example output

   Name:                mysource
   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

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

1. Delete the trigger:

   $ kn trigger delete <trigger_name>

2. Delete the event source:

   $ kn source apiserver delete <source_name>

3. Delete the service account, cluster role, and cluster binding:

   $ oc delete -f authentication.yaml

1. Create a service account, role, and role binding for the event source as a YAML file:

   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 2
   rules:
     - apiGroups:
         - ""
       resources:
         - events
       verbs:
         - get
         - list
         - watch
   
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: RoleBinding
   metadata:
     name: k8s-ra-event-watcher
     namespace: default 3
   roleRef:
     apiGroup: rbac.authorization.k8s.io
     kind: Role
     name: event-watcher
   subjects:
     - kind: ServiceAccount
       name: events-sa
       namespace: default 4

   1 2 3 4

   Change this namespace to the namespace that you have selected for installing the event source.

2. Apply the YAML file:

   $ oc apply -f <filename>

3. Create an API server source as a YAML file:

   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

4. Apply the ApiServerSource YAML file:

   $ oc apply -f <filename>

5. To check that the API server source is set up correctly, create a Knative service as a YAML file that dumps incoming messages to its log:

   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

6. Apply the Service YAML file:

   $ oc apply -f <filename>

7. Create a Trigger object as a YAML file that filters events from the default broker to the service created in the previous step:

   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

8. Apply the Trigger YAML file:

   $ oc apply -f <filename>

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

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

    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

1. Get the pods by entering the following command:

   $ oc get pods

2. View the message dumper function logs for the pods by entering the following command:

   $ 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

1. Delete the trigger:

   $ oc delete -f trigger.yaml

2. Delete the event source:

   $ oc delete -f k8s-events.yaml

3. Delete the service account, cluster role, and cluster binding:

   $ oc delete -f authentication.yaml

Procedure

1. To verify that the ping source is working, create a simple Knative service that dumps incoming messages to the logs of the service.

   1. In the Developer perspective, navigate to +Add YAML.

   2. Copy the example YAML:

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

   3. Click Create.

2. Create a ping source in the same namespace as the service created in the previous step, or any other sink that you want to send events to.

   1. In the Developer perspective, navigate to +Add Event Source. The Event Sources page is displayed.
   2. Optional: If you have multiple providers for your event sources, select the required provider from the Providers list to filter the available event sources from the provider.

   3. Select Ping Source and then click Create Event Source. The Create Event Source page is displayed.

      Note

      You can configure the PingSource settings by using the Form view or YAML view and can switch between the views. The data is persisted when switching between the views.

   4. Enter a value for Schedule. In this example, the value is */2 * * * *, which creates a PingSource that sends a message every two minutes.
   5. Optional: You can enter a value for Data, which is the message payload.
   6. Select a Sink. This can be either a Resource or a URI. In this example, the event-display service created in the previous step is used as the Resource sink.
   7. Click Create.

1. In the Developer perspective, navigate to Topology.

2. View the ping source and sink.

   

Deleting the ping source

1. Navigate to the Topology view.
2. Right-click the API server source and select Delete Ping Source.

Procedure

1. To verify that the ping source is working, create a simple Knative service that dumps incoming messages to the service logs:

   $ kn service create event-display \
       --image quay.io/openshift-knative/knative-eventing-sources-event-display:latest

2. For each set of ping events that you want to request, create a ping source in the same namespace as the event consumer:

   $ kn source ping create test-ping-source \
       --schedule "*/2 * * * *" \
       --data '{"message": "Hello world!"}' \
       --sink ksvc:event-display

3. Check that the controller is mapped correctly by entering the following command and inspecting the output:

   $ kn source ping describe test-ping-source

   Example output

   Name:         test-ping-source
   Namespace:    default
   Annotations:  sources.knative.dev/creator=developer, sources.knative.dev/lastModifier=developer
   Age:          15s
   Schedule:     */2 * * * *
   Data:         {"message": "Hello world!"}
   
   Sink:
     Name:       event-display
     Namespace:  default
     Resource:   Service (serving.knative.dev/v1)
   
   Conditions:
     OK TYPE                 AGE REASON
     ++ Ready                 8s
     ++ Deployed              8s
     ++ SinkProvided         15s
     ++ ValidSchedule        15s
     ++ EventTypeProvided    15s
     ++ ResourcesCorrect     15s

1. Watch for new pods created:

   $ watch oc get pods

2. Cancel watching the pods using Ctrl+C, then look at the logs of the created pod:

   $ 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.sources.ping
     source: /apis/v1/namespaces/default/pingsources/test-ping-source
     id: 99e4f4f6-08ff-4bff-acf1-47f61ded68c9
     time: 2020-04-07T16:16:00.000601161Z
     datacontenttype: application/json
   Data,
     {
       "message": "Hello world!"
     }

Procedure

1. To verify that the ping source is working, create a simple Knative service that dumps incoming messages to the service’s logs.

   1. Create a service YAML file:

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

   2. Create the service:

      $ oc apply -f <filename>

2. For each set of ping events that you want to request, create a ping source in the same namespace as the event consumer.

   1. Create a YAML file for the ping source:

      apiVersion: sources.knative.dev/v1
      kind: PingSource
      metadata:
        name: test-ping-source
      spec:
        schedule: "*/2 * * * *"
        data: '{"message": "Hello world!"}'
        sink:
          ref:
            apiVersion: serving.knative.dev/v1
            kind: Service
            name: event-display

   2. Create the ping source:

      $ oc apply -f <filename>

3. Check that the controller is mapped correctly by entering the following command:

   $ oc get pingsource.sources.knative.dev <ping_source_name> -oyaml

   Example output

   apiVersion: sources.knative.dev/v1
   kind: PingSource
   metadata:
     annotations:
       sources.knative.dev/creator: developer
       sources.knative.dev/lastModifier: developer
     creationTimestamp: "2020-04-07T16:11:14Z"
     generation: 1
     name: test-ping-source
     namespace: default
     resourceVersion: "55257"
     selfLink: /apis/sources.knative.dev/v1/namespaces/default/pingsources/test-ping-source
     uid: 3d80d50b-f8c7-4c1b-99f7-3ec00e0a8164
   spec:
     data: '{ value: "hello" }'
     schedule: '*/2 * * * *'
     sink:
       ref:
         apiVersion: serving.knative.dev/v1
         kind: Service
         name: event-display
         namespace: default

1. Watch for new pods created:

   $ watch oc get pods

2. Cancel watching the pods using Ctrl+C, then look at the logs of the created pod:

   $ 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.sources.ping
     source: /apis/v1/namespaces/default/pingsources/test-ping-source
     id: 042ff529-240e-45ee-b40c-3a908129853e
     time: 2020-04-07T16:22:00.000791674Z
     datacontenttype: application/json
   Data,
     {
       "message": "Hello world!"
     }

Procedure

1. In the Developer perspective, navigate to +Add Channel.
2. Select the type of Channel object that you want to create in the Type list.
3. Click Create.

Procedure

1. Create a Channel object as a YAML file:

   apiVersion: messaging.knative.dev/v1
   kind: Channel
   metadata:
     name: example-channel
     namespace: default

2. Apply the YAML file:

   $ oc apply -f <filename>

Procedure

1. Create a KafkaChannel object as a YAML file:

   apiVersion: messaging.knative.dev/v1beta1
   kind: KafkaChannel
   metadata:
     name: example-channel
     namespace: default
   spec:
     numPartitions: 3
     replicationFactor: 1

   Important

   Only the v1beta1 version of the API for KafkaChannel objects on OpenShift Serverless is supported. Do not use the v1alpha1 version of this API, as this version is now deprecated.

2. Apply the KafkaChannel YAML file:

   $ oc apply -f <filename>

Procedure

1. In the Developer perspective, navigate to the Topology page.

2. Create a subscription using one of the following methods:

   1. Hover over the channel that you want to create a subscription for, and drag the arrow. The Add Subscription option is displayed.

      
      1. Select your sink in the Subscriber list.
      2. Click Add.
   2. If the service is available in the Topology view under the same namespace or project as the channel, click on the channel that you want to create a subscription for, and drag the arrow directly to a service to immediately create a subscription from the channel to that service.

Verification

1. Use the kn command to list all existing brokers:

   $ kn broker list

   Example output

   NAME      URL                                                                     AGE   CONDITIONS   READY   REASON
   default   http://broker-ingress.knative-eventing.svc.cluster.local/test/default   45s   5 OK / 5     True

2. Optional: If you are using the OpenShift Container Platform web console, you can navigate to the Topology view in the Developer perspective, and observe that the broker exists:

   

Procedure

1. Create a Trigger object as a YAML file that has the eventing.knative.dev/injection: enabled annotation:

   apiVersion: eventing.knative.dev/v1
   kind: Trigger
   metadata:
     annotations:
       eventing.knative.dev/injection: enabled
     name: <trigger_name>
   spec:
     broker: default
     subscriber: 1
       ref:
         apiVersion: serving.knative.dev/v1
         kind: Service
         name: <service_name>

   1

   Specify details about the event sink, or subscriber, that the trigger sends events to.

2. Apply the Trigger YAML file:

   $ oc apply -f <filename>

1. Enter the following oc command to get the broker:

   $ oc -n <namespace> get broker default

   Example output

   NAME      READY     REASON    URL                                                                     AGE
   default   True                http://broker-ingress.knative-eventing.svc.cluster.local/test/default   3m56s

2. Optional: If you are using the OpenShift Container Platform web console, you can navigate to the Topology view in the Developer perspective, and observe that the broker exists:

   

1. Use the oc command to get the broker:

   $ oc -n <namespace> get broker <broker_name>

   Example command

   $ oc -n default get broker default

   Example output

   NAME      READY     REASON    URL                                                                     AGE
   default   True                http://broker-ingress.knative-eventing.svc.cluster.local/test/default   3m56s

2. Optional: If you are using the OpenShift Container Platform web console, you can navigate to the Topology view in the Developer perspective, and observe that the broker exists:

   

Procedure

1. Remove the eventing.knative.dev/injection=enabled label from the namespace:

   $ oc label namespace <namespace> eventing.knative.dev/injection-

   Removing the annotation prevents Knative from recreating the broker after you delete it.

2. Delete the broker from the selected namespace:

   $ oc -n <namespace> delete broker <broker_name>

Procedure

1. In the Developer perspective, navigate to the Topology page.
2. Hover over the broker that you want to create a trigger for, and drag the arrow. The Add Trigger option is displayed.
3. Click Add Trigger.
4. Select your sink in the Subscriber list.
5. Click Add.

Deleting a trigger

1. In the Developer perspective, navigate to the Topology page.
2. Click on the trigger that you want to delete.
3. In the Actions context menu, select Delete Trigger.

Procedure

1. Print a list of available triggers:

   $ kn trigger list

   Example output

   NAME    BROKER    SINK           AGE   CONDITIONS   READY   REASON
   email   default   ksvc:edisplay   4s    5 OK / 5     True
   ping    default   ksvc:edisplay   32s   5 OK / 5     True

2. Optional: Print a list of triggers in JSON format:

   $ kn trigger list -o json

Verification

1. List existing triggers:

   $ kn trigger list

2. Verify that the trigger no longer exists:

   Example output

   No triggers found.

Procedure

1. Create or modify a Trigger object and set the kafka.eventing.knative.dev/delivery.order annotation:

   apiVersion: eventing.knative.dev/v1
   kind: Trigger
   metadata:
     name: <trigger_name>
     annotations:
        kafka.eventing.knative.dev/delivery.order: ordered
   ...

   The supported consumer delivery guarantees are:

   unordered

   An unordered consumer is a non-blocking consumer that delivers messages unordered, while preserving proper offset management.

   ordered

   An ordered consumer is a per-partition blocking consumer that waits for a successful response from the CloudEvent subscriber before it delivers the next message of the partition.

   The default ordering guarantee is unordered.

2. Apply the Trigger object:

   $ oc apply -f <filename>

Procedure

1. Create a KafkaChannel object as a YAML file:

   apiVersion: messaging.knative.dev/v1beta1
   kind: KafkaChannel
   metadata:
     name: example-channel
     namespace: default
   spec:
     numPartitions: 3
     replicationFactor: 1

   Important

   Only the v1beta1 version of the API for KafkaChannel objects on OpenShift Serverless is supported. Do not use the v1alpha1 version of this API, as this version is now deprecated.

2. Apply the KafkaChannel YAML file:

   $ oc apply -f <filename>