apiserver: k8s.io/apiserver/pkg/storage Index | Files | Directories

package storage

import "k8s.io/apiserver/pkg/storage"

Interfaces for database-related operations.

Index

Package Files

doc.go errors.go interfaces.go selection_predicate.go util.go

Constants

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

Variables

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

Everything accepts all objects.

func DefaultClusterScopedAttr Uses

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

func DefaultNamespaceScopedAttr Uses

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

func EverythingFunc Uses

func EverythingFunc(runtime.Object) bool

func IsConflict Uses

func IsConflict(err error) bool

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

func IsInternalError Uses

func IsInternalError(err error) bool

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

func IsInvalidError Uses

func IsInvalidError(err error) bool

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

func IsInvalidObj Uses

func IsInvalidObj(err error) bool

IsInvalidObj returns true if and only if err is invalid error

func IsNodeExist Uses

func IsNodeExist(err error) bool

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

func IsNotFound Uses

func IsNotFound(err error) bool

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

func IsTooLargeResourceVersion Uses

func IsTooLargeResourceVersion(err error) bool

IsTooLargeResourceVersion returns true if the error is a TooLargeResourceVersion error.

func IsUnreachable Uses

func IsUnreachable(err error) bool

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

func NamespaceKeyFunc Uses

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

func NewTooLargeResourceVersionError Uses

func NewTooLargeResourceVersionError(minimumResourceVersion, currentRevision uint64, retrySeconds int) error

NewTooLargeResourceVersionError returns a timeout error with the given retrySeconds for a request for a minimum resource version that is larger than the largest currently available resource version for a requested resource.

func NoNamespaceKeyFunc Uses

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

func ValidateAllObjectFunc Uses

func ValidateAllObjectFunc(ctx context.Context, obj runtime.Object) error

ValidateAllObjectFunc is a "admit everything" instance of ValidateObjectFunc.

type AttrFunc Uses

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

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

func (AttrFunc) WithFieldMutation Uses

func (f AttrFunc) WithFieldMutation(fieldMutator FieldMutationFunc) AttrFunc

type FieldMutationFunc Uses

type FieldMutationFunc func(obj runtime.Object, fieldSet fields.Set) error

FieldMutationFunc allows the mutation of the field selection fields. It is mutating to avoid the extra allocation on this common path

type HighWaterMark Uses

type HighWaterMark int64

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

func (*HighWaterMark) Update Uses

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

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

type IndexerFunc Uses

type IndexerFunc func(obj runtime.Object) string

IndexerFunc is a function that for a given object computes <value of an index> for a particular <index>.

type IndexerFuncs Uses

type IndexerFuncs map[string]IndexerFunc

IndexerFuncs is a mapping from <index name> to function that for a given object computes <value for that index>.

type Interface Uses

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, validateDeletion ValidateObjectFunc) 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

    // Count returns number of different entries under the key (generally being path prefix).
    Count(key string) (int64, error)
}

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

type InternalError Uses

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 Uses

func NewInternalError(reason string) InternalError

func NewInternalErrorf Uses

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

func (InternalError) Error Uses

func (e InternalError) Error() string

type InvalidError Uses

type InvalidError struct {
    Errs field.ErrorList
}

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

func NewInvalidError Uses

func NewInvalidError(errors field.ErrorList) InvalidError

func (InvalidError) Error Uses

func (e InvalidError) Error() string

type Preconditions Uses

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

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

func NewUIDPreconditions Uses

func NewUIDPreconditions(uid string) *Preconditions

NewUIDPreconditions returns a Preconditions with UID set.

func (*Preconditions) Check Uses

func (p *Preconditions) Check(key string, obj runtime.Object) error

type ResponseMeta Uses

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 Uses

type SelectionPredicate struct {
    Label               labels.Selector
    Field               fields.Selector
    GetAttrs            AttrFunc
    IndexFields         []string
    Limit               int64
    Continue            string
    AllowWatchBookmarks bool
}

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

func (*SelectionPredicate) Empty Uses

func (s *SelectionPredicate) Empty() bool

Empty returns true if the predicate performs no filtering.

func (*SelectionPredicate) Matches Uses

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) MatchesObjectAttributes Uses

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

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

func (*SelectionPredicate) MatchesSingle Uses

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 Uses

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

type StorageError Uses

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

func NewInvalidObjError Uses

func NewInvalidObjError(key, msg string) *StorageError

func NewKeyExistsError Uses

func NewKeyExistsError(key string, rv int64) *StorageError

func NewKeyNotFoundError Uses

func NewKeyNotFoundError(key string, rv int64) *StorageError

func NewResourceVersionConflictsError Uses

func NewResourceVersionConflictsError(key string, rv int64) *StorageError

func NewUnreachableError Uses

func NewUnreachableError(key string, rv int64) *StorageError

func (*StorageError) Error Uses

func (e *StorageError) Error() string

type UpdateFunc Uses

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 Uses

func SimpleUpdate(fn SimpleUpdateFunc) UpdateFunc

SimpleUpdateFunc converts SimpleUpdateFunc into UpdateFunc

type ValidateObjectFunc Uses

type ValidateObjectFunc func(ctx context.Context, obj runtime.Object) error

ValidateObjectFunc is a function to act on a given object. An error may be returned if the hook cannot be completed. The function may NOT transform the provided object.

type Versioner Uses

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. continueValue is optional and indicates that more results are available if the client
    // passes that value to the server in a subsequent call. remainingItemCount indicates the number
    // of remaining objects if the list is partial. The remainingItemCount field is omitted during
    // serialization if it is set to nil.
    UpdateList(obj runtime.Object, resourceVersion uint64, continueValue string, remainingItemCount *int64) error
    // PrepareObjectForStorage should set SelfLink and ResourceVersion to the empty value. Should
    // return an error if the specified object cannot be updated.
    PrepareObjectForStorage(obj runtime.Object) 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)

    // ParseResourceVersion takes a resource version argument and
    // converts it to the storage backend. For watch 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).
    ParseResourceVersion(resourceVersion string) (uint64, error)
}

Versioner abstracts setting and retrieving metadata fields from database response onto the object ot list. It is required to maintain storage invariants - updating an object twice with the same data except for the ResourceVersion and SelfLink must be a no-op. A resourceVersion of type uint64 is a 'raw' resourceVersion, intended to be sent directly to or from the backend. A resourceVersion of type string is a 'safe' resourceVersion, intended for consumption by users.

Directories

PathSynopsis
cacher
errorsPackage storage provides conversion of storage errors to API errors.
etcd3
etcd3/metrics
etcd3/preflight
etcd3/testing
etcd3/testing/testingcert
names
storagebackend
storagebackend/factory
testing
valuePackage value contains methods for assisting with transformation of values in storage.
value/encrypt/aesPackage aes transforms values for storage at rest using AES-GCM.
value/encrypt/envelopePackage envelope transforms values for storage at rest using a Envelope provider
value/encrypt/envelope/testing
value/encrypt/envelope/v1beta1Package v1beta1 contains definition of kms-plugin's gRPC service.
value/encrypt/identity
value/encrypt/secretboxPackage secretbox transforms values for storage at rest using XSalsa20 and Poly1305.

Package storage imports 13 packages (graph) and is imported by 142 packages. Updated 2019-12-06. Refresh now. Tools for package owners.