Topics

    • Contributor: implement a new source with minimal k8s overhead (don’t have to learn controller/k8s internals)
    • Operator: easily install Sources and verify that they are “safe”
    • Developer: easily discover what Sources they can pull from on this cluster
    • Developer: easily configure a Source based on existing knowledge of other Sources.
    • Receive Adapter (RA) - process that receives incoming events.
    • Implement CloudEvent binding interfaces, provides libraries for standard access to configure interfaces as needed.
    • Passing configuration from the Source YAML, that the controller needs to configure the Receive Adapter

    Source library (provided by Knative):

    • Controller runtime (this is what we share via injection) incorporates protocol specific config into “generic controller” CRD.
    • Propagating events internally to the system (i.e. cloudevents)

    Theory

    Quick Introduction to Knative Eventing Sources A Knative Source is Kubernetes Custom Resource that generates or imports an event and pushes that event to another endpoint on the cluster via a CloudEvents.

    for Knative Eventing Sources contains a number of requirements that together define a well-behaved Knative Source.

    To achieve this, there are several separations of concerns that we have to keep in mind: 1. A controller to run our Event Source and reconcile the underlying Receive Adapter deployments 2. A “receive adapter” which generates or imports the actual events 3. A series of identifying characteristics for our event 4. Transporting a valid event to the serverless system for further processing

    These two roles will often not be the same person. We want to confine the job of the “contributor” to implementing the Receive Adapter, and specifying what configuration their adapter needs to connect, subscribe, or do whatever it does.

    The Knative Eventing developer exposes the protocol configuration as part of the Source CRD, and the controller passes any required configuration (which may include resolved data like URLs) to the Receive Adapter.

    API Resources required:

    • KubeClientSet.Appsv1.Deployment (Inherited via the Eventing base reconciler) Used to deploy the Receive Adapter for “importing” events
    • EventingClientSet.EventingV1Alpha1 (Inherited via the Eventing base reconciler) Used to interact with Events within the Knative system
    • SourceClientSet.SourcesV1Alpha1 Used for source — in this case, samplesource — specific config and translated to the underlying deployment (via the inherited KubeClientSet)

    Fig 1. - Via shared Knative Dependency Injection

    Specifically, the clientset, cache, informers, and listers can all be generated and shared. Thus, they can be generated, imported, and assigned to the underlying reconciler when creating a new controller source implementation:

    1. # Generation
    2. ${CODEGEN_PKG}/generate-groups.sh "deepcopy,client,informer,lister" \
    3.   knative.dev/sample-source/pkg/client knative.dev/sample-source/pkg/apis \
    4.   "samples:v1alpha1" \
    5.   --go-header-file ${REPO_ROOT}/hack/boilerplate/boilerplate.go.txt
    7. # Injection
    8. ${KNATIVE_CODEGEN_PKG}/hack/generate-knative.sh "injection" \
    9.   "samples:v1alpha1" \
    10.   --go-header-file ${REPO_ROOT}/hack/boilerplate/boilerplate.go.txt

    File Layout & Hierarchy:

    • cmd/controller/main.go - Pass source’s NewController implementation to the shared main
    • cmd/receive_adapter/main.go - Translate resource variables to underlying adapter struct (to eventually be passed into the serverless system)
    • pkg/reconciler/sample/controller.go - NewController implementation to pass to sharedmain
    • pkg/reconciler/sample/samplesource.go - reconciliation functions for the receive adapter
    • pkg/apis/samples/VERSION/samplesource_types.go - schema for the underlying api types (variables to be defined in the resource yaml)
    • - status updates for the source’s reconciliation details
    • Source ready
    • Sink provided
    • Deployed
    • Eventtype Provided
    • pkg/adapter/adapter.go - receive_adapter functions supporting translation of events to CloudEvents