Create a SinkBinding

    This topic describes how to create a SinkBinding object. SinkBinding resolves a sink as a URI, sets the URI in the environment variable , and adds the URI to a subject using K_SINK. If the URI changes, SinkBinding updates the value of K_SINK.

    In the following examples, the sink is a Knative Service and the subject is a CronJob. If you have an existing subject and sink, you can replace the examples with your own values.

    Before you can create a SinkBinding object:

    • You must have Knative Eventing installed on your cluster.
    • Optional: If you want to use kn commands with SinkBinding, install the kn CLI.

    Optional: Choose SinkBinding namespace selection behavior

    The SinkBinding object operates in one of two modes: exclusion or inclusion.

    The default mode is exclusion. In exclusion mode, SinkBinding behavior is enabled for the namespace by default. To disallow a namespace from being evaluated for mutation you must exclude it using the label bindings.knative.dev/exclude: true.

    In inclusion mode, SinkBinding behavior is not enabled for the namespace. Before a namespace can be evaluated for mutation, you must explicitly include it using the label bindings.knative.dev/include: true.

    To set the SinkBinding object to inclusion mode:

    1. Change the value of SINK_BINDING_SELECTION_MODE from exclusion to inclusion by running:

    2. To verify that SINK_BINDING_SELECTION_MODE is set as desired, run:

      1. kubectl -n knative-eventing set env deployments eventing-webhook --containers="eventing-webhook" --list | grep SINK_BINDING

    If you do not have an existing namespace, create a namespace for the SinkBinding object:

    1. kubectl create namespace <namespace>

    Where <namespace> is the namespace that you want your SinkBinding to use. For example, sinkbinding-example.

    Note

    If you have selected inclusion mode, you must add the bindings.knative.dev/include: true label to the namespace to enable SinkBinding behavior.

    Create a sink

    The sink can be any addressable Kubernetes object that can receive events.

    If you do not have an existing sink that you want to connect to the SinkBinding object, create a Knative service.

    To create a Knative service you must have Knative Serving installed on your cluster.

    knYAML

    Create a Knative service by running:

    1. kn service create <app-name> --image <image-url>

    Where:

    • <app-name> is the name of the application.
    • <image-url> is the URL of the image container.

    For example:

    1. $ kn service create event-display --image gcr.io/knative-releases/knative.dev/eventing/cmd/event_display

    1. Create a YAML file for the Knative service using the following template:

      Where:

      • <app-name> is the name of the application. For example, event-display.
      • <image-url> is the URL of the image container. For example, gcr.io/knative-releases/knative.dev/eventing/cmd/event_display.

    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.

    The subject must be a PodSpecable resource. You can use any PodSpecable resource in your cluster, for example:

    • Deployment
    • Job
    • DaemonSet
    • StatefulSet
    • Service.serving.knative.dev

    If you do not have an existing PodSpecable subject that you want to use, you can use the following sample to create a CronJob object as the subject. The following CronJob makes a single cloud event that targets K_SINK and adds any extra overrides given by CE_OVERRIDES.

    1. Create a YAML file for the CronJob using the following example:

      1. apiVersion: batch/v1beta1
      2. kind: CronJob
      3. metadata:
      4.   name: heartbeat-cron
      5. spec:
      6.   schedule: "*/1 * * * *"
      7.   jobTemplate:
      8.     metadata:
      9.       labels:
      10.         app: heartbeat-cron
      11.     spec:
      12.       template:
      13.         spec:
      14.           restartPolicy: Never
      15.           containers:
      16.             - name: single-heartbeat
      17.               image: gcr.io/knative-nightly/knative.dev/eventing/cmd/heartbeats
      18.               args:
      19.               - --period=1
      20.               env:
      21.                 - name: ONE_SHOT
      22.                   value: "true"
      23.                 - name: POD_NAME
      24.                   valueFrom:
      25.                     fieldRef:
      26.                       fieldPath: metadata.name
      27.                 - name: POD_NAMESPACE
      28.                   valueFrom:
      29.                     fieldRef:
      30.                       fieldPath: metadata.namespace

    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.

    Create a SinkBinding object

    Create a SinkBinding object that directs events from your subject to the sink.

    Create a SinkBinding object by running:

    1. kn source binding create <name> \
    2.   --namespace <namespace> \
    3.   --subject "<subject>" \
    4.   --sink <sink> \
    5.   --ce-override "<cloudevent-overrides>"

    Where:

    • <name> is the name of the SinkBinding object you want to create.
    • <namespace> is the namespace you created for your SinkBinding to use.
    • <sink> is the sink to connect. For example http://event-display.svc.cluster.local.
    • Optional: <cloudevent-overrides> in the form key=value. Cloud Event overrides control the output format and modifications of the event sent to the sink and are applied before sending the event. You can provide this flag multiple times.

    For a list of available options, see the Knative client documentation.

    For example:

    1. Create a YAML file for the SinkBinding object using the following template:

      1. apiVersion: sources.knative.dev/v1
      2. kind: SinkBinding
      3. metadata:
      4.   name: <name>
      5. spec:
      6.   subject:
      7.     apiVersion: <api-version>
      8.     kind: <kind>
      9.     selector:
      10.       matchLabels:
      11.         <label-key>: <label-value>
      12.   sink:
      13.     ref:
      14.       apiVersion: serving.knative.dev/v1
      15.       kind: Service
      16.       name: <sink>

      Where:

      • <name> is the name of the SinkBinding object you want to create. For example, bind-heartbeat.
      • <api-version> is the API version of the subject. For example batch/v1.
      • <kind> is the Kind of your subject. For example Job.
      • <label-key>: <label-value> is a map of key-value pairs to select subjects that have a matching label. For example, app: heartbeat-cron selects any subject with the label app=heartbeat-cron.
      • <sink> is the sink to connect. For example event-display.

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

    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.

    1. Verify that a message was sent to the Knative eventing system by looking at the service logs for your sink:

      1. kubectl logs -l <sink> -c <container> --since=10m

      Where:

      • <sink> is the name of your sink.
      • <container> is the name of the container your sink is running in.

      For example:

      1. $ kubectl logs -l serving.knative.dev/service=event-display -c user-container --since=10m

    Delete a SinkBinding

    To delete the SinkBinding object and all of the related resources in the namespace, delete the namespace by running:

    Where <namespace> is the name of the namespace that contains the SinkBinding object.