README

Duck Types

Knative leverages duck-typing to interact with resources inside of Kubernetes without explicit knowledge of the full resource shape. knative/pkg defines three duck types that are used throughout Knative: Addressable, Binding, and Source.

For APIs leveraging ObjectReference, the context of the resource in question identifies the duck-type. To enable the case where no ObjectReference is used, we have labeled the Custom Resource Definition with the duck-type. Those labels are as follows:

Label Duck-Type
duck.knative.dev/addressable=true Addressable
duck.knative.dev/binding=true Binding
duck.knative.dev/source=true Source

Addressable Shape

Addressable is expected to be the following shape:

apiVersion: group/version
kind: Kind
status:
  address:
    url: http://host/path?query

Binding Shape

Binding is expected to be in the following shape:

(with direct subject)

apiVersion: group/version
kind: Kind
spec:
  subject:
    apiVersion: group/version
    kind: SomeKind
    namespace: the-namespace
    name: a-name

(with indirect subject)

apiVersion: group/version
kind: Kind
spec:
  subject:
    apiVersion: group/version
    kind: SomeKind
    namespace: the-namespace
    selector:
      matchLabels:
        key: value

Source Shape

Source is expected to be in the following shape:

(with ref sink)

apiVersion: group/version
kind: Kind
spec:
  sink:
    ref:
      apiVersion: group/version
      kind: AnAddressableKind
      name: a-name
  ceOverrides:
    extensions:
      key: value
status:
  observedGeneration: 1
  conditions:
    - type: Ready
      status: "True"
  sinkUri: http://host

(with uri sink)

apiVersion: group/version
kind: Kind
spec:
  sink:
    uri: http://host/path?query
  ceOverrides:
    extensions:
      key: value
status:
  observedGeneration: 1
  conditions:
    - type: Ready
      status: "True"
  sinkUri: http://host/path?query

(with ref and uri sink)

apiVersion: group/version
kind: Kind
spec:
  sink:
    ref:
      apiVersion: group/version
      kind: AnAddressableKind
      name: a-name
    uri: /path?query
  ceOverrides:
    extensions:
      key: value
status:
  observedGeneration: 1
  conditions:
    - type: Ready
      status: "True"
  sinkUri: http://host/path?query
Expand ▾ Collapse ▴

Documentation

Overview

    Package duck defines logic for defining and consuming "duck typed" Kubernetes resources. Producers define partial resource definitions that resource authors may choose to implement to interoperate with consumers of these "duck typed" interfaces. For more information see: https://docs.google.com/document/d/16j8C91jML4fQRQPhnHihNJUJDcbvW0RM1YAX2REHgyY/edit#

    Index

    Constants

    View Source
    const (
    	// BindingExcludeLabel is a label that is placed on namespaces and
    	// resources to exclude them from consideration when binding things.
    	// It is critical that bindings dealing with Deployments label their
    	// controller Deployment (or enclosing namespace). If you do not
    	// specify this label, they are considered for binding (i.e. you opt-in
    	// to getting everything considered for bindings). This is the default.
    	BindingExcludeLabel = "bindings.knative.dev/exclude"
    
    	// BindingIncludeLabel is a label that is placed on namespaces and
    	// resources to include them in consideration when binding things.
    	// This means that you have to explicitly label the namespaces/resources
    	// for consideration for bindings.
    	BindingIncludeLabel = "bindings.knative.dev/include"
    )
    View Source
    const (
    	GroupName = ducktypes.GroupName
    
    	// AddressableDuckVersionLabel is the label we use to declare
    	// that a type conforms to the Addressable duck type.
    	AddressableDuckVersionLabel = "duck.knative.dev/addressable"
    
    	// SourceDuckVersionLabel is the label we use to declare
    	// that a type conforms to the Source duck type.
    	SourceDuckVersionLabel = "duck.knative.dev/source"
    )

    Variables

    This section is empty.

    Functions

    func AsStructuredWatcher

    func AsStructuredWatcher(ctx context.Context, wf structuredWatcher, obj runtime.Object) cache.WatchFunc

      AsStructuredWatcher is public for testing only. TODO(mattmoor): Move tests for this to `package duck` and make private.

      func ConformsToType

      func ConformsToType(instance interface{}, iface Implementable) (bool, error)

        ConformsToType will return true or false depending on whether a concrete resource properly implements the provided Implementable duck type.

        It will return an error if marshal/unmarshalling fails

        func CreateBytePatch

        func CreateBytePatch(before, after interface{}) ([]byte, error)

          CreateBytePatch is a helper function that creates the same content as CreatePatch, but returns in []byte format instead of JSONPatch.

          func CreateMergePatch

          func CreateMergePatch(before, after interface{}) ([]byte, error)

            CreateMergePatch creates a json merge patch as specified in http://tools.ietf.org/html/draft-ietf-appsawg-json-merge-patch-07

            func FromUnstructured

            func FromUnstructured(obj json.Marshaler, target interface{}) error

              FromUnstructured takes unstructured object from (say from client-go/dynamic) and converts it into our duck types.

              func ToUnstructured

              func ToUnstructured(desired OneOfOurs) (*unstructured.Unstructured, error)

                ToUnstructured takes an instance of a OneOfOurs compatible type and converts it to unstructured.Unstructured. We take OneOfOurs in place or runtime.Object because sometimes we get resources that do not have their TypeMeta populated but that is required for unstructured.Unstructured to deserialize things, so we leverage our content-agnostic GroupVersionKind() method to populate this as-needed (in a copy, so that we don't modify the informer's copy, if that is what we are passed).

                func VerifyType

                func VerifyType(instance interface{}, iface Implementable) error

                  VerifyType verifies that a particular concrete resource properly implements the provided Implementable duck type. It is expected that under the resource definition implementing a particular "Fooable" that one would write:

                  type ConcreteResource struct { ... }
                  
                  // Check that ConcreteResource properly implement Fooable.
                  err := duck.VerifyType(&ConcreteResource{}, &something.Fooable{})
                  

                  This will return an error if the duck typing is not satisfied.

                  Types

                  type Bindable

                  type Bindable interface {
                  	OneOfOurs
                  
                  	// GetSubject returns the standard Binding duck's "Subject" field.
                  	GetSubject() tracker.Reference
                  
                  	// GetBindingStatus returns the status of the Binding, which must
                  	// implement BindableStatus.
                  	GetBindingStatus() BindableStatus
                  }

                    Bindable may be implemented by Binding resources to use shared libraries.

                    type BindableStatus

                    type BindableStatus interface {
                    	// InitializeConditions seeds the resource's status.conditions field
                    	// with all of the conditions that this Binding surfaces.
                    	InitializeConditions()
                    
                    	// MarkBindingAvailable notes that this Binding has been properly
                    	// configured.
                    	MarkBindingAvailable()
                    
                    	// MarkBindingUnavailable notes the provided reason for why the Binding
                    	// has failed.
                    	MarkBindingUnavailable(reason string, message string)
                    
                    	// SetObservedGeneration updates the .status.observedGeneration to the
                    	// provided generation value.
                    	SetObservedGeneration(int64)
                    }

                      BindableStatus is the interface that the .status of Bindable resources must implement to work smoothly with our BaseReconciler.

                      type CachedInformerFactory

                      type CachedInformerFactory struct {
                      	Delegate InformerFactory
                      	// contains filtered or unexported fields
                      }

                        CachedInformerFactory implements InformerFactory by delegating to another InformerFactory, but memoizing the results.

                        func (*CachedInformerFactory) Get

                          Get implements InformerFactory.

                          type EnqueueInformerFactory

                          type EnqueueInformerFactory struct {
                          	Delegate InformerFactory
                          
                          	EventHandler cache.ResourceEventHandler
                          }

                            EnqueueInformerFactory implements InformerFactory by delegating to another InformerFactory, but attaching a ResourceEventHandler to the informer.

                            func (*EnqueueInformerFactory) Get

                              Get implements InformerFactory.

                              type Implementable

                              type Implementable = ducktypes.Implementable

                              type InformerFactory

                              type InformerFactory interface {
                              	// Get returns a synced Informer/Lister pair for the provided schema.GroupVersionResource.
                              	Get(context.Context, schema.GroupVersionResource) (cache.SharedIndexInformer, cache.GenericLister, error)
                              }

                                InformerFactory is used to create Informer/Lister pairs for a schema.GroupVersionResource

                                type JSONPatch

                                type JSONPatch []jsonpatch.JsonPatchOperation

                                func CreatePatch

                                func CreatePatch(before, after interface{}) (JSONPatch, error)

                                  CreatePatch creates a patch as specified in http://jsonpatch.com/

                                  func (JSONPatch) MarshalJSON

                                  func (p JSONPatch) MarshalJSON() ([]byte, error)

                                  type OneOfOurs

                                  type OneOfOurs interface {
                                  	kmeta.Accessor
                                  	kmeta.OwnerRefable
                                  }

                                    OneOfOurs is the union of our Accessor interface and the OwnerRefable interface that is implemented by our resources that implement the kmeta.Accessor.

                                    type Populatable

                                    type Populatable = ducktypes.Populatable

                                    type TypedInformerFactory

                                    type TypedInformerFactory struct {
                                    	Client       dynamic.Interface
                                    	Type         apis.Listable
                                    	ResyncPeriod time.Duration
                                    	StopChannel  <-chan struct{}
                                    }

                                      TypedInformerFactory implements InformerFactory such that the elements tracked by the informer/lister have the type of the canonical "obj".

                                      func (*TypedInformerFactory) Get

                                        Get implements InformerFactory.

                                        Directories

                                        Path Synopsis
                                        v1
                                        +k8s:deepcopy-gen=package +groupName=duck.knative.dev
                                        +k8s:deepcopy-gen=package +groupName=duck.knative.dev
                                        +k8s:deepcopy-gen=package +groupName=duck.knative.dev
                                        +k8s:deepcopy-gen=package +groupName=duck.knative.dev
                                        +k8s:deepcopy-gen=package +groupName=duck.knative.dev
                                        +k8s:deepcopy-gen=package +groupName=duck.knative.dev