Documentation

Overview

    Interfaces for database-related operations.

    Index

    Constants

    View Source
    const (
    	ErrCodeKeyNotFound int = iota + 1
    	ErrCodeKeyExists
    	ErrCodeResourceVersionConflicts
    	ErrCodeInvalidObj
    	ErrCodeUnreachable
    )

    Variables

    View Source
    var Everything = SelectionPredicate{
    	Label: labels.Everything(),
    	Field: fields.Everything(),
    }

      Everything accepts all objects.

      Functions

      func EverythingFunc

      func EverythingFunc(runtime.Object) bool

      func IsConflict

      func IsConflict(err error) bool

        IsConflict returns true if and only if err is a write conflict.

        func IsInternalError

        func IsInternalError(err error) bool

          IsInternalError returns true if and only if err is an InternalError.

          func IsInvalidError

          func IsInvalidError(err error) bool

            IsInvalidError returns true if and only if err is an InvalidError.

            func IsInvalidObj

            func IsInvalidObj(err error) bool

              IsInvalidObj returns true if and only if err is invalid error

              func IsNodeExist

              func IsNodeExist(err error) bool

                IsNodeExist returns true if and only if err is an node already exist error.

                func IsNotFound

                func IsNotFound(err error) bool

                  IsNotFound returns true if and only if err is "key" not found error.

                  func IsUnreachable

                  func IsUnreachable(err error) bool

                    IsUnreachable returns true if and only if err indicates the server could not be reached.

                    func NamespaceKeyFunc

                    func NamespaceKeyFunc(prefix string, obj runtime.Object) (string, error)

                    func NoNamespaceKeyFunc

                    func NoNamespaceKeyFunc(prefix string, obj runtime.Object) (string, error)

                    func ParseListResourceVersion

                    func ParseListResourceVersion(resourceVersion string) (uint64, error)

                      ParseListResourceVersion takes a resource version argument and converts it to the etcd version.

                      func ParseWatchResourceVersion

                      func ParseWatchResourceVersion(resourceVersion string) (uint64, error)

                        ParseWatchResourceVersion takes a resource version argument and converts it to the etcd version we should pass to helper.Watch(). Because resourceVersion is an opaque value, the default watch behavior for non-zero watch is to watch the next value (if you pass "1", you will see updates from "2" onwards).

                        Types

                        type AttrFunc

                        type AttrFunc func(obj runtime.Object) (labels.Set, fields.Set, error)

                          AttrFunc returns label and field sets for List or Watch to match. In any failure to parse given object, it returns error.

                          type Cacher

                          type Cacher struct {
                          	sync.RWMutex
                          	// contains filtered or unexported fields
                          }

                            Cacher is responsible for serving WATCH and LIST requests for a given resource from its internal cache and updating its cache in the background based on the underlying storage contents. Cacher implements storage.Interface (although most of the calls are just delegated to the underlying storage).

                            func NewCacherFromConfig

                            func NewCacherFromConfig(config CacherConfig) *Cacher

                              Create a new Cacher responsible for servicing WATCH and LIST requests from its internal cache and updating its cache in the background based on the given configuration.

                              func (*Cacher) Create

                              func (c *Cacher) Create(ctx context.Context, key string, obj, out runtime.Object, ttl uint64) error

                                Implements storage.Interface.

                                func (*Cacher) Delete

                                func (c *Cacher) Delete(ctx context.Context, key string, out runtime.Object, preconditions *Preconditions) error

                                  Implements storage.Interface.

                                  func (*Cacher) Get

                                  func (c *Cacher) Get(ctx context.Context, key string, resourceVersion string, objPtr runtime.Object, ignoreNotFound bool) error

                                    Implements storage.Interface.

                                    func (*Cacher) GetToList

                                    func (c *Cacher) GetToList(ctx context.Context, key string, resourceVersion string, pred SelectionPredicate, listObj runtime.Object) error

                                      Implements storage.Interface.

                                      func (*Cacher) GuaranteedUpdate

                                      func (c *Cacher) GuaranteedUpdate(
                                      	ctx context.Context, key string, ptrToType runtime.Object, ignoreNotFound bool,
                                      	preconditions *Preconditions, tryUpdate UpdateFunc, _ ...runtime.Object) error

                                        Implements storage.Interface.

                                        func (*Cacher) LastSyncResourceVersion

                                        func (c *Cacher) LastSyncResourceVersion() (uint64, error)

                                          Returns resource version to which the underlying cache is synced.

                                          func (*Cacher) List

                                          func (c *Cacher) List(ctx context.Context, key string, resourceVersion string, pred SelectionPredicate, listObj runtime.Object) error

                                            Implements storage.Interface.

                                            func (*Cacher) Stop

                                            func (c *Cacher) Stop()

                                            func (*Cacher) Versioner

                                            func (c *Cacher) Versioner() Versioner

                                              Implements storage.Interface.

                                              func (*Cacher) Watch

                                              func (c *Cacher) Watch(ctx context.Context, key string, resourceVersion string, pred SelectionPredicate) (watch.Interface, error)

                                                Implements storage.Interface.

                                                func (*Cacher) WatchList

                                                func (c *Cacher) WatchList(ctx context.Context, key string, resourceVersion string, pred SelectionPredicate) (watch.Interface, error)

                                                  Implements storage.Interface.

                                                  type CacherConfig

                                                  type CacherConfig struct {
                                                  	// Maximum size of the history cached in memory.
                                                  	CacheCapacity int
                                                  
                                                  	// An underlying storage.Interface.
                                                  	Storage Interface
                                                  
                                                  	// An underlying storage.Versioner.
                                                  	Versioner Versioner
                                                  
                                                  	Copier runtime.ObjectCopier
                                                  
                                                  	// The Cache will be caching objects of a given Type and assumes that they
                                                  	// are all stored under ResourcePrefix directory in the underlying database.
                                                  	Type           interface{}
                                                  	ResourcePrefix string
                                                  
                                                  	// KeyFunc is used to get a key in the underlying storage for a given object.
                                                  	KeyFunc func(runtime.Object) (string, error)
                                                  
                                                  	// GetAttrsFunc is used to get object labels and fields.
                                                  	GetAttrsFunc func(runtime.Object) (labels.Set, fields.Set, error)
                                                  
                                                  	// TriggerPublisherFunc is used for optimizing amount of watchers that
                                                  	// needs to process an incoming event.
                                                  	TriggerPublisherFunc TriggerPublisherFunc
                                                  
                                                  	// NewList is a function that creates new empty object storing a list of
                                                  	// objects of type Type.
                                                  	NewListFunc func() runtime.Object
                                                  
                                                  	Codec runtime.Codec
                                                  }

                                                    CacherConfig contains the configuration for a given Cache.

                                                    type FilterFunc

                                                    type FilterFunc func(obj runtime.Object) bool

                                                      FilterFunc takes an API object and returns true if the object satisfies some requirements. TODO: We will remove this type and use SelectionPredicate everywhere.

                                                      func SimpleFilter

                                                      func SimpleFilter(p SelectionPredicate) FilterFunc

                                                        SimpleFilter converts a selection predicate into a FilterFunc. It ignores any error from Matches().

                                                        type HighWaterMark

                                                        type HighWaterMark int64

                                                          HighWaterMark is a thread-safe object for tracking the maximum value seen for some quantity.

                                                          func (*HighWaterMark) Update

                                                          func (hwm *HighWaterMark) Update(current int64) bool

                                                            Update returns true if and only if 'current' is the highest value ever seen.

                                                            type Interface

                                                            type Interface interface {
                                                            	// Returns Versioner associated with this interface.
                                                            	Versioner() Versioner
                                                            
                                                            	// Create adds a new object at a key unless it already exists. 'ttl' is time-to-live
                                                            	// in seconds (0 means forever). If no error is returned and out is not nil, out will be
                                                            	// set to the read value from database.
                                                            	Create(ctx context.Context, key string, obj, out runtime.Object, ttl uint64) error
                                                            
                                                            	// Delete removes the specified key and returns the value that existed at that spot.
                                                            	// If key didn't exist, it will return NotFound storage error.
                                                            	Delete(ctx context.Context, key string, out runtime.Object, preconditions *Preconditions) error
                                                            
                                                            	// Watch begins watching the specified key. Events are decoded into API objects,
                                                            	// and any items selected by 'p' are sent down to returned watch.Interface.
                                                            	// resourceVersion may be used to specify what version to begin watching,
                                                            	// which should be the current resourceVersion, and no longer rv+1
                                                            	// (e.g. reconnecting without missing any updates).
                                                            	// If resource version is "0", this interface will get current object at given key
                                                            	// and send it in an "ADDED" event, before watch starts.
                                                            	Watch(ctx context.Context, key string, resourceVersion string, p SelectionPredicate) (watch.Interface, error)
                                                            
                                                            	// WatchList begins watching the specified key's items. Items are decoded into API
                                                            	// objects and any item selected by 'p' are sent down to returned watch.Interface.
                                                            	// resourceVersion may be used to specify what version to begin watching,
                                                            	// which should be the current resourceVersion, and no longer rv+1
                                                            	// (e.g. reconnecting without missing any updates).
                                                            	// If resource version is "0", this interface will list current objects directory defined by key
                                                            	// and send them in "ADDED" events, before watch starts.
                                                            	WatchList(ctx context.Context, key string, resourceVersion string, p SelectionPredicate) (watch.Interface, error)
                                                            
                                                            	// Get unmarshals json found at key into objPtr. On a not found error, will either
                                                            	// return a zero object of the requested type, or an error, depending on ignoreNotFound.
                                                            	// Treats empty responses and nil response nodes exactly like a not found error.
                                                            	// The returned contents may be delayed, but it is guaranteed that they will
                                                            	// be have at least 'resourceVersion'.
                                                            	Get(ctx context.Context, key string, resourceVersion string, objPtr runtime.Object, ignoreNotFound bool) error
                                                            
                                                            	// GetToList unmarshals json found at key and opaque it into *List api object
                                                            	// (an object that satisfies the runtime.IsList definition).
                                                            	// The returned contents may be delayed, but it is guaranteed that they will
                                                            	// be have at least 'resourceVersion'.
                                                            	GetToList(ctx context.Context, key string, resourceVersion string, p SelectionPredicate, listObj runtime.Object) error
                                                            
                                                            	// List unmarshalls jsons found at directory defined by key and opaque them
                                                            	// into *List api object (an object that satisfies runtime.IsList definition).
                                                            	// The returned contents may be delayed, but it is guaranteed that they will
                                                            	// be have at least 'resourceVersion'.
                                                            	List(ctx context.Context, key string, resourceVersion string, p SelectionPredicate, listObj runtime.Object) error
                                                            
                                                            	// GuaranteedUpdate keeps calling 'tryUpdate()' to update key 'key' (of type 'ptrToType')
                                                            	// retrying the update until success if there is index conflict.
                                                            	// Note that object passed to tryUpdate may change across invocations of tryUpdate() if
                                                            	// other writers are simultaneously updating it, so tryUpdate() needs to take into account
                                                            	// the current contents of the object when deciding how the update object should look.
                                                            	// If the key doesn't exist, it will return NotFound storage error if ignoreNotFound=false
                                                            	// or zero value in 'ptrToType' parameter otherwise.
                                                            	// If the object to update has the same value as previous, it won't do any update
                                                            	// but will return the object in 'ptrToType' parameter.
                                                            	// If 'suggestion' can contain zero or one element - in such case this can be used as
                                                            	// a suggestion about the current version of the object to avoid read operation from
                                                            	// storage to get it.
                                                            	//
                                                            	// Example:
                                                            	//
                                                            	// s := /* implementation of Interface */
                                                            	// err := s.GuaranteedUpdate(
                                                            	//     "myKey", &MyType{}, true,
                                                            	//     func(input runtime.Object, res ResponseMeta) (runtime.Object, *uint64, error) {
                                                            	//       // Before each incovation of the user defined function, "input" is reset to
                                                            	//       // current contents for "myKey" in database.
                                                            	//       curr := input.(*MyType)  // Guaranteed to succeed.
                                                            	//
                                                            	//       // Make the modification
                                                            	//       curr.Counter++
                                                            	//
                                                            	//       // Return the modified object - return an error to stop iterating. Return
                                                            	//       // a uint64 to alter the TTL on the object, or nil to keep it the same value.
                                                            	//       return cur, nil, nil
                                                            	//    }
                                                            	// })
                                                            	GuaranteedUpdate(
                                                            		ctx context.Context, key string, ptrToType runtime.Object, ignoreNotFound bool,
                                                            		precondtions *Preconditions, tryUpdate UpdateFunc, suggestion ...runtime.Object) error
                                                            }

                                                              Interface offers a common interface for object marshaling/unmarshaling operations and hides all the storage-related operations behind it.

                                                              type InternalError

                                                              type InternalError struct {
                                                              	Reason string
                                                              }

                                                                InternalError is generated when an error occurs in the storage package, i.e., not from the underlying storage backend (e.g., etcd).

                                                                func NewInternalError

                                                                func NewInternalError(reason string) InternalError

                                                                func NewInternalErrorf

                                                                func NewInternalErrorf(format string, a ...interface{}) InternalError

                                                                func (InternalError) Error

                                                                func (e InternalError) Error() string

                                                                type InvalidError

                                                                type InvalidError struct {
                                                                	Errs field.ErrorList
                                                                }

                                                                  InvalidError is generated when an error caused by invalid API object occurs in the storage package.

                                                                  func NewInvalidError

                                                                  func NewInvalidError(errors field.ErrorList) InvalidError

                                                                  func (InvalidError) Error

                                                                  func (e InvalidError) Error() string

                                                                  type MatchValue

                                                                  type MatchValue struct {
                                                                  	IndexName string
                                                                  	Value     string
                                                                  }

                                                                    MatchValue defines a pair (<index name>, <value for that index>).

                                                                    func NoTriggerFunc

                                                                    func NoTriggerFunc() []MatchValue

                                                                    func NoTriggerPublisher

                                                                    func NoTriggerPublisher(runtime.Object) []MatchValue

                                                                    type Preconditions

                                                                    type Preconditions struct {
                                                                    	// Specifies the target UID.
                                                                    	// +optional
                                                                    	UID *types.UID `json:"uid,omitempty"`
                                                                    }

                                                                      Preconditions must be fulfilled before an operation (update, delete, etc.) is carried out.

                                                                      func NewUIDPreconditions

                                                                      func NewUIDPreconditions(uid string) *Preconditions

                                                                        NewUIDPreconditions returns a Preconditions with UID set.

                                                                        type ResponseMeta

                                                                        type ResponseMeta struct {
                                                                        	// TTL is the time to live of the node that contained the returned object. It may be
                                                                        	// zero or negative in some cases (objects may be expired after the requested
                                                                        	// expiration time due to server lag).
                                                                        	TTL int64
                                                                        	// The resource version of the node that contained the returned object.
                                                                        	ResourceVersion uint64
                                                                        }

                                                                          ResponseMeta contains information about the database metadata that is associated with an object. It abstracts the actual underlying objects to prevent coupling with concrete database and to improve testability.

                                                                          type SelectionPredicate

                                                                          type SelectionPredicate struct {
                                                                          	Label       labels.Selector
                                                                          	Field       fields.Selector
                                                                          	GetAttrs    AttrFunc
                                                                          	IndexFields []string
                                                                          }

                                                                            SelectionPredicate is used to represent the way to select objects from api storage.

                                                                            func (*SelectionPredicate) MatcherIndex

                                                                            func (s *SelectionPredicate) MatcherIndex() []MatchValue

                                                                              For any index defined by IndexFields, if a matcher can match only (a subset) of objects that return <value> for a given index, a pair (<index name>, <value>) wil be returned. TODO: Consider supporting also labels.

                                                                              func (*SelectionPredicate) Matches

                                                                              func (s *SelectionPredicate) Matches(obj runtime.Object) (bool, error)

                                                                                Matches returns true if the given object's labels and fields (as returned by s.GetAttrs) match s.Label and s.Field. An error is returned if s.GetAttrs fails.

                                                                                func (*SelectionPredicate) MatchesLabelsAndFields

                                                                                func (s *SelectionPredicate) MatchesLabelsAndFields(l labels.Set, f fields.Set) bool

                                                                                  MatchesLabelsAndFields returns true if the given labels and fields match s.Label and s.Field.

                                                                                  func (*SelectionPredicate) MatchesSingle

                                                                                  func (s *SelectionPredicate) MatchesSingle() (string, bool)

                                                                                    MatchesSingle will return (name, true) if and only if s.Field matches on the object's name.

                                                                                    type SimpleUpdateFunc

                                                                                    type SimpleUpdateFunc func(runtime.Object) (runtime.Object, error)

                                                                                    type StorageError

                                                                                    type StorageError struct {
                                                                                    	Code               int
                                                                                    	Key                string
                                                                                    	ResourceVersion    int64
                                                                                    	AdditionalErrorMsg string
                                                                                    }

                                                                                    func NewInvalidObjError

                                                                                    func NewInvalidObjError(key, msg string) *StorageError

                                                                                    func NewKeyExistsError

                                                                                    func NewKeyExistsError(key string, rv int64) *StorageError

                                                                                    func NewKeyNotFoundError

                                                                                    func NewKeyNotFoundError(key string, rv int64) *StorageError

                                                                                    func NewResourceVersionConflictsError

                                                                                    func NewResourceVersionConflictsError(key string, rv int64) *StorageError

                                                                                    func NewUnreachableError

                                                                                    func NewUnreachableError(key string, rv int64) *StorageError

                                                                                    func (*StorageError) Error

                                                                                    func (e *StorageError) Error() string

                                                                                    type TriggerPublisherFunc

                                                                                    type TriggerPublisherFunc func(obj runtime.Object) []MatchValue

                                                                                      TriggerPublisherFunc is a function that takes an object, and returns a list of pairs (<index name>, <index value for the given object>) for all indexes known to that function.

                                                                                      type UpdateFunc

                                                                                      type UpdateFunc func(input runtime.Object, res ResponseMeta) (output runtime.Object, ttl *uint64, err error)

                                                                                        Pass an UpdateFunc to Interface.GuaranteedUpdate to make an update that is guaranteed to succeed. See the comment for GuaranteedUpdate for more details.

                                                                                        func SimpleUpdate

                                                                                        func SimpleUpdate(fn SimpleUpdateFunc) UpdateFunc

                                                                                          SimpleUpdateFunc converts SimpleUpdateFunc into UpdateFunc

                                                                                          type Versioner

                                                                                          type Versioner interface {
                                                                                          	// UpdateObject sets storage metadata into an API object. Returns an error if the object
                                                                                          	// cannot be updated correctly. May return nil if the requested object does not need metadata
                                                                                          	// from database.
                                                                                          	UpdateObject(obj runtime.Object, resourceVersion uint64) error
                                                                                          	// UpdateList sets the resource version into an API list object. Returns an error if the object
                                                                                          	// cannot be updated correctly. May return nil if the requested object does not need metadata
                                                                                          	// from database.
                                                                                          	UpdateList(obj runtime.Object, resourceVersion uint64) error
                                                                                          	// ObjectResourceVersion returns the resource version (for persistence) of the specified object.
                                                                                          	// Should return an error if the specified object does not have a persistable version.
                                                                                          	ObjectResourceVersion(obj runtime.Object) (uint64, error)
                                                                                          }

                                                                                            Versioner abstracts setting and retrieving metadata fields from database response onto the object ot list.

                                                                                            Directories

                                                                                            Path Synopsis
                                                                                            Package etcd provides conversion of etcd errors to API errors.
                                                                                            Package etcd provides conversion of etcd errors to API errors.
                                                                                            util
                                                                                            Package util holds generic etcd-related utility functions that any user of ectd might want to use, without pulling in kubernetes-specific code.
                                                                                            Package util holds generic etcd-related utility functions that any user of ectd might want to use, without pulling in kubernetes-specific code.