duck

README

Duck Types

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

For APIs leveraging ObjectReference, the context of the resource in question identifies the duck-type. To enable the case where no ObjectRefrence 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/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

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

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
• func AsStructuredWatcher(wf cache.WatchFunc, obj runtime.Object) cache.WatchFunc
• func ConformsToType(instance interface{}, iface Implementable) (bool, error)
• func CreateBytePatch(before, after interface{}) ([]byte, error)
• func CreateMergePatch(before, after interface{}) ([]byte, error)
• func FromUnstructured(obj Marshalable, target interface{}) error
• func NewProxyWatcher(ch chan watch.Event) watch.Interface
• func VerifyType(instance interface{}, iface Implementable) error
• type CachedInformerFactory
  • func (cif *CachedInformerFactory) Get(gvr schema.GroupVersionResource) (cache.SharedIndexInformer, cache.GenericLister, error)
• type EnqueueInformerFactory
  • func (cif *EnqueueInformerFactory) Get(gvr schema.GroupVersionResource) (cache.SharedIndexInformer, cache.GenericLister, error)
• type Implementable
• type InformerFactory
• type JSONPatch
  • func CreatePatch(before, after interface{}) (JSONPatch, error)
  • func (p JSONPatch) MarshalJSON() ([]byte, error)
• type Marshalable
• type Populatable
• type TypedInformerFactory
  • func (dif *TypedInformerFactory) Get(gvr schema.GroupVersionResource) (cache.SharedIndexInformer, cache.GenericLister, error)

Constants

const (
	GroupName = "duck.knative.dev"
)

Functions

func AsStructuredWatcher

func AsStructuredWatcher(wf cache.WatchFunc, 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 Marshalable, target interface{}) error

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

func NewProxyWatcher

func NewProxyWatcher(ch chan watch.Event) watch.Interface

NewProxyWatcher creates new proxyWatcher by wrapping a channel

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

func (cif *CachedInformerFactory) Get(gvr schema.GroupVersionResource) (cache.SharedIndexInformer, cache.GenericLister, error)

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

func (cif *EnqueueInformerFactory) Get(gvr schema.GroupVersionResource) (cache.SharedIndexInformer, cache.GenericLister, error)

Get implements InformerFactory.

type Implementable

type Implementable interface {
	// GetFullType returns an instance of a full resource wrapping
	// an instance of this Implementable that can populate its fields
	// to verify json roundtripping.
	GetFullType() Populatable
}

Implementable is implemented by the Fooable duck type that consumers are expected to embed as a `.status.fooable` field.

type InformerFactory

type InformerFactory interface {
	// Get returns a synced Informer/Lister pair for the provided schema.GroupVersionResource.
	Get(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 Marshalable

type Marshalable interface {
	MarshalJSON() ([]byte, error)
}

Marshallable is implementated by the Unstructured K8s types.

type Populatable

type Populatable interface {
	// Populate fills in all possible fields, so that we can verify that
	// they roundtrip properly through JSON.
	Populate()
}

Populatable is implemented by a skeleton resource wrapping an Implementable duck type. It will generally have TypeMeta, ObjectMeta, and a Status field wrapping a Fooable field.

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

func (dif *TypedInformerFactory) Get(gvr schema.GroupVersionResource) (cache.SharedIndexInformer, cache.GenericLister, error)

Get implements InformerFactory.