rest

package
v0.15.1-0...-d7b79a7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 16, 2017 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Overview

Package rest defines common logic around changes to Kubernetes-style resources.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BeforeCreate 

func BeforeCreate(strategy RESTCreateStrategy, ctx genericapirequest.Context, obj runtime.Object) error

BeforeCreate ensures that common operations for all resources are performed on creation. It only returns errors that can be converted to api.Status. It invokes PrepareForCreate, then GenerateName, then Validate. It returns nil if the object should be created.

func BeforeDelete 

func BeforeDelete(strategy RESTDeleteStrategy, ctx genericapirequest.Context, obj runtime.Object, options *metav1.DeleteOptions) (graceful, gracefulPending bool, err error)

BeforeDelete tests whether the object can be gracefully deleted. If graceful is set the object should be gracefully deleted, if gracefulPending is set the object has already been gracefully deleted (and the provided grace period is longer than the time to deletion), and an error is returned if the condition cannot be checked or the gracePeriodSeconds is invalid. The options argument may be updated with default values if graceful is true. Second place where we set deletionTimestamp is pkg/registry/generic/registry/store.go this function is responsible for setting deletionTimestamp during gracefulDeletion, other one for cascading deletions.

func BeforeUpdate 

func BeforeUpdate(strategy RESTUpdateStrategy, ctx genericapirequest.Context, obj, old runtime.Object) error

BeforeUpdate ensures that common operations for all resources are performed on update. It only returns errors that can be converted to api.Status. It will invoke update validation with the provided existing and updated objects.

func CheckGeneratedNameError 

func CheckGeneratedNameError(strategy RESTCreateStrategy, err error, obj runtime.Object) error

CheckGeneratedNameError checks whether an error that occurred creating a resource is due to generation being unable to pick a valid name.

func FillObjectMetaSystemFields 

func FillObjectMetaSystemFields(ctx genericapirequest.Context, meta *metav1.ObjectMeta)

FillObjectMetaSystemFields populates fields that are managed by the system on ObjectMeta.

func ValidNamespace 

func ValidNamespace(ctx genericapirequest.Context, resource *metav1.ObjectMeta) bool

ValidNamespace returns false if the namespace on the context differs from the resource. If the resource has no namespace, it is set to the value in the context.

TODO(sttts): move into pkg/genericapiserver/endpoints

Types

type CollectionDeleter 

type CollectionDeleter interface {
	// DeleteCollection selects all resources in the storage matching given 'listOptions'
	// and deletes them. If 'options' are provided, the resource will attempt to honor
	// them or return an invalid request error.
	// DeleteCollection may not be atomic - i.e. it may delete some objects and still
	// return an error after it. On success, returns a list of deleted objects.
	DeleteCollection(ctx genericapirequest.Context, options *metav1.DeleteOptions, listOptions *metainternalversion.ListOptions) (runtime.Object, error)
}

CollectionDeleter is an object that can delete a collection of RESTful resources.

type ConnectRequest 

type ConnectRequest struct {
	// Name is the name of the object on which the connect request was made
	Name string

	// Options is the options object passed to the connect request. See the NewConnectOptions method on Connecter
	Options runtime.Object

	// ResourcePath is the path for the resource in the REST server (ie. "pods/proxy")
	ResourcePath string
}

ConnectRequest is an object passed to admission control for Connect operations

func (*ConnectRequest) GetObjectKind 

func (obj *ConnectRequest) GetObjectKind() schema.ObjectKind

type Connecter 

type Connecter interface {
	// Connect returns an http.Handler that will handle the request/response for a given API invocation.
	// The provided responder may be used for common API responses. The responder will write both status
	// code and body, so the ServeHTTP method should exit after invoking the responder. The Handler will
	// be used for a single API request and then discarded. The Responder is guaranteed to write to the
	// same http.ResponseWriter passed to ServeHTTP.
	Connect(ctx genericapirequest.Context, id string, options runtime.Object, r Responder) (http.Handler, error)

	// NewConnectOptions returns an empty options object that will be used to pass
	// options to the Connect method. If nil, then a nil options object is passed to
	// Connect. It may return a bool and a string. If true, the value of the request
	// path below the object will be included as the named string in the serialization
	// of the runtime object.
	NewConnectOptions() (runtime.Object, bool, string)

	// ConnectMethods returns the list of HTTP methods handled by Connect
	ConnectMethods() []string
}

Connecter is a storage object that responds to a connection request.

type Creater 

type Creater interface {
	// New returns an empty object that can be used with Create after request data has been put into it.
	// This object must be a pointer type for use with Codec.DecodeInto([]byte, runtime.Object)
	New() runtime.Object

	// Create creates a new version of a resource.
	Create(ctx genericapirequest.Context, obj runtime.Object) (runtime.Object, error)
}

Creater is an object that can create an instance of a RESTful object.

type CreaterUpdater 

type CreaterUpdater interface {
	Creater
	Update(ctx genericapirequest.Context, name string, objInfo UpdatedObjectInfo) (runtime.Object, bool, error)
}

CreaterUpdater is a storage object that must support both create and update. Go prevents embedded interfaces that implement the same method.

type Deleter 

type Deleter interface {
	// Delete finds a resource in the storage and deletes it.
	// Although it can return an arbitrary error value, IsNotFound(err) is true for the
	// returned error value err when the specified resource is not found.
	// Delete *may* return the object that was deleted, or a status object indicating additional
	// information about deletion.
	Delete(ctx genericapirequest.Context, name string) (runtime.Object, error)
}

Deleter is an object that can delete a named RESTful resource.

type Exporter 

type Exporter interface {
	// Export an object.  Fields that are not user specified (e.g. Status, ObjectMeta.ResourceVersion) are stripped out
	// Returns the stripped object.  If 'exact' is true, fields that are specific to the cluster (e.g. namespace) are
	// retained, otherwise they are stripped also.
	Export(ctx genericapirequest.Context, name string, opts metav1.ExportOptions) (runtime.Object, error)
}

Exporter is an object that knows how to strip a RESTful resource for export

type GarbageCollectionDeleteStrategy 

type GarbageCollectionDeleteStrategy interface {
	// DefaultGarbageCollectionPolicy returns the default garbage collection behavior.
	DefaultGarbageCollectionPolicy() GarbageCollectionPolicy
}

GarbageCollectionDeleteStrategy must be implemented by the registry that wants to orphan dependents by default.

type GarbageCollectionPolicy 

type GarbageCollectionPolicy string
const (
	DeleteDependents GarbageCollectionPolicy = "DeleteDependents"
	OrphanDependents GarbageCollectionPolicy = "OrphanDependents"
)

type Getter 

type Getter interface {
	// Get finds a resource in the storage by name and returns it.
	// Although it can return an arbitrary error value, IsNotFound(err) is true for the
	// returned error value err when the specified resource is not found.
	Get(ctx genericapirequest.Context, name string, options *metav1.GetOptions) (runtime.Object, error)
}

Getter is an object that can retrieve a named RESTful resource.

type GetterWithOptions 

type GetterWithOptions interface {
	// Get finds a resource in the storage by name and returns it.
	// Although it can return an arbitrary error value, IsNotFound(err) is true for the
	// returned error value err when the specified resource is not found.
	// The options object passed to it is of the same type returned by the NewGetOptions
	// method.
	// TODO: Pass metav1.GetOptions.
	Get(ctx genericapirequest.Context, name string, options runtime.Object) (runtime.Object, error)

	// NewGetOptions returns an empty options object that will be used to pass
	// options to the Get method. It may return a bool and a string, if true, the
	// value of the request path below the object will be included as the named
	// string in the serialization of the runtime object. E.g., returning "path"
	// will convert the trailing request scheme value to "path" in the map[string][]string
	// passed to the converter.
	NewGetOptions() (runtime.Object, bool, string)
}

GetterWithOptions is an object that retrieve a named RESTful resource and takes additional options on the get request. It allows a caller to also receive the subpath of the GET request.

type GracefulDeleteAdapter 

type GracefulDeleteAdapter struct {
	Deleter
}

GracefulDeleteAdapter adapts the Deleter interface to GracefulDeleter

func (GracefulDeleteAdapter) Delete 

func (w GracefulDeleteAdapter) Delete(ctx genericapirequest.Context, name string, options *metav1.DeleteOptions) (runtime.Object, bool, error)

Delete implements RESTGracefulDeleter in terms of Deleter

type GracefulDeleter 

type GracefulDeleter interface {
	// Delete finds a resource in the storage and deletes it.
	// If options are provided, the resource will attempt to honor them or return an invalid
	// request error.
	// Although it can return an arbitrary error value, IsNotFound(err) is true for the
	// returned error value err when the specified resource is not found.
	// Delete *may* return the object that was deleted, or a status object indicating additional
	// information about deletion.
	// It also returns a boolean which is set to true if the resource was instantly
	// deleted or false if it will be deleted asynchronously.
	Delete(ctx genericapirequest.Context, name string, options *metav1.DeleteOptions) (runtime.Object, bool, error)
}

GracefulDeleter knows how to pass deletion options to allow delayed deletion of a RESTful object.

type KindProvider 

type KindProvider interface {
	Kind() string
}

KindProvider specifies a different kind for its API than for its internal storage. This is necessary for external objects that are not compiled into the api server. For such objects, there is no in-memory representation for the object, so they must be represented as generic objects (e.g. runtime.Unknown), but when we present the object as part of API discovery we want to present the specific kind, not the generic internal representation.

type Lister 

type Lister interface {
	// NewList returns an empty object that can be used with the List call.
	// This object must be a pointer type for use with Codec.DecodeInto([]byte, runtime.Object)
	NewList() runtime.Object
	// List selects resources in the storage which match to the selector. 'options' can be nil.
	List(ctx genericapirequest.Context, options *metainternalversion.ListOptions) (runtime.Object, error)
}

Lister is an object that can retrieve resources that match the provided field and label criteria.

type NamedCreater 

type NamedCreater interface {
	// New returns an empty object that can be used with Create after request data has been put into it.
	// This object must be a pointer type for use with Codec.DecodeInto([]byte, runtime.Object)
	New() runtime.Object

	// Create creates a new version of a resource. It expects a name parameter from the path.
	// This is needed for create operations on subresources which include the name of the parent
	// resource in the path.
	Create(ctx genericapirequest.Context, name string, obj runtime.Object) (runtime.Object, error)
}

NamedCreater is an object that can create an instance of a RESTful object using a name parameter.

type NamespaceScopedStrategy 

type NamespaceScopedStrategy interface {
	// NamespaceScoped returns if the object must be in a namespace.
	NamespaceScoped() bool
}

NamespaceScopedStrategy has a method to tell if the object must be in a namespace.

type Patcher 

type Patcher interface {
	Getter
	Updater
}

Patcher is a storage object that supports both get and update.

type RESTCreateStrategy 

type RESTCreateStrategy interface {
	runtime.ObjectTyper
	// The name generator is used when the standard GenerateName field is set.
	// The NameGenerator will be invoked prior to validation.
	names.NameGenerator

	// NamespaceScoped returns true if the object must be within a namespace.
	NamespaceScoped() bool
	// PrepareForCreate is invoked on create before validation to normalize
	// the object.  For example: remove fields that are not to be persisted,
	// sort order-insensitive list fields, etc.  This should not remove fields
	// whose presence would be considered a validation error.
	PrepareForCreate(ctx genericapirequest.Context, obj runtime.Object)
	// Validate returns an ErrorList with validation errors or nil.  Validate
	// is invoked after default fields in the object have been filled in
	// before the object is persisted.  This method should not mutate the
	// object.
	Validate(ctx genericapirequest.Context, obj runtime.Object) field.ErrorList
	// Canonicalize allows an object to be mutated into a canonical form. This
	// ensures that code that operates on these objects can rely on the common
	// form for things like comparison.  Canonicalize is invoked after
	// validation has succeeded but before the object has been persisted.
	// This method may mutate the object.
	Canonicalize(obj runtime.Object)
}

RESTCreateStrategy defines the minimum validation, accepted input, and name generation behavior to create an object that follows Kubernetes API conventions.

type RESTDeleteStrategy 

type RESTDeleteStrategy interface {
	runtime.ObjectTyper
}

RESTDeleteStrategy defines deletion behavior on an object that follows Kubernetes API conventions.

type RESTExportStrategy 

type RESTExportStrategy interface {
	// Export strips fields that can not be set by the user.  If 'exact' is false
	// fields specific to the cluster are also stripped
	Export(ctx genericapirequest.Context, obj runtime.Object, exact bool) error
}

RESTExportStrategy is the interface that defines how to export a Kubernetes object. An exported object is stripped of non-user-settable fields and optionally, the identifying information related to the object's identity in the cluster so that it can be loaded into a different namespace or entirely different cluster without conflict.

type RESTGracefulDeleteStrategy 

type RESTGracefulDeleteStrategy interface {
	// CheckGracefulDelete should return true if the object can be gracefully deleted and set
	// any default values on the DeleteOptions.
	CheckGracefulDelete(ctx genericapirequest.Context, obj runtime.Object, options *metav1.DeleteOptions) bool
}

RESTGracefulDeleteStrategy must be implemented by the registry that supports graceful deletion.

type RESTUpdateStrategy 

type RESTUpdateStrategy interface {
	runtime.ObjectTyper
	// NamespaceScoped returns true if the object must be within a namespace.
	NamespaceScoped() bool
	// AllowCreateOnUpdate returns true if the object can be created by a PUT.
	AllowCreateOnUpdate() bool
	// PrepareForUpdate is invoked on update before validation to normalize
	// the object.  For example: remove fields that are not to be persisted,
	// sort order-insensitive list fields, etc.  This should not remove fields
	// whose presence would be considered a validation error.
	PrepareForUpdate(ctx genericapirequest.Context, obj, old runtime.Object)
	// ValidateUpdate is invoked after default fields in the object have been
	// filled in before the object is persisted.  This method should not mutate
	// the object.
	ValidateUpdate(ctx genericapirequest.Context, obj, old runtime.Object) field.ErrorList
	// Canonicalize allows an object to be mutated into a canonical form. This
	// ensures that code that operates on these objects can rely on the common
	// form for things like comparison.  Canonicalize is invoked after
	// validation has succeeded but before the object has been persisted.
	// This method may mutate the object.
	Canonicalize(obj runtime.Object)
	// AllowUnconditionalUpdate returns true if the object can be updated
	// unconditionally (irrespective of the latest resource version), when
	// there is no resource version specified in the object.
	AllowUnconditionalUpdate() bool
}

RESTUpdateStrategy defines the minimum validation, accepted input, and name generation behavior to update an object that follows Kubernetes API conventions. A resource may have many UpdateStrategies, depending on the call pattern in use.

type Redirector 

type Redirector interface {
	// ResourceLocation should return the remote location of the given resource, and an optional transport to use to request it, or an error.
	ResourceLocation(ctx genericapirequest.Context, id string) (remoteLocation *url.URL, transport http.RoundTripper, err error)
}

Redirector know how to return a remote resource's location.

type ResourceStreamer 

type ResourceStreamer interface {
	// InputStream should return an io.ReadCloser if the provided object supports streaming. The desired
	// api version and an accept header (may be empty) are passed to the call. If no error occurs,
	// the caller may return a flag indicating whether the result should be flushed as writes occur
	// and a content type string that indicates the type of the stream.
	// If a null stream is returned, a StatusNoContent response wil be generated.
	InputStream(apiVersion, acceptHeader string) (stream io.ReadCloser, flush bool, mimeType string, err error)
}

ResourceStreamer is an interface implemented by objects that prefer to be streamed from the server instead of decoded directly.

type Responder 

type Responder interface {
	// Object writes the provided object to the response. Invoking this method multiple times is undefined.
	Object(statusCode int, obj runtime.Object)
	// Error writes the provided error to the response. This method may only be invoked once.
	Error(err error)
}

Responder abstracts the normal response behavior for a REST method and is passed to callers that may wish to handle the response directly in some cases, but delegate to the normal error or object behavior in other cases.

type ShortNamesProvider 

type ShortNamesProvider interface {
	ShortNames() []string
}

ShortNamesProvider is an interface for RESTful storage services. Delivers a list of short names for a resource. The list is used by kubectl to have short names representation of resources.

type StandardStorage 

type StandardStorage interface {
	Getter
	Lister
	CreaterUpdater
	GracefulDeleter
	CollectionDeleter
	Watcher
}

StandardStorage is an interface covering the common verbs. Provided for testing whether a resource satisfies the normal storage methods. Use Storage when passing opaque storage objects.

type Storage 

type Storage interface {
	// New returns an empty object that can be used with Create and Update after request data has been put into it.
	// This object must be a pointer type for use with Codec.DecodeInto([]byte, runtime.Object)
	New() runtime.Object
}

Storage is a generic interface for RESTful storage services. Resources which are exported to the RESTful API of apiserver need to implement this interface. It is expected that objects may implement any of the below interfaces.

type StorageMetadata 

type StorageMetadata interface {
	// ProducesMIMETypes returns a list of the MIME types the specified HTTP verb (GET, POST, DELETE,
	// PATCH) can respond with.
	ProducesMIMETypes(verb string) []string

	// ProducesObject returns an object the specified HTTP verb respond with. It will overwrite storage object if
	// it is not nil. Only the type of the return object matters, the value will be ignored.
	ProducesObject(verb string) interface{}
}

StorageMetadata is an optional interface that callers can implement to provide additional information about their Storage objects.

type TransformFunc 

type TransformFunc func(ctx genericapirequest.Context, newObj runtime.Object, oldObj runtime.Object) (transformedNewObj runtime.Object, err error)

TransformFunc is a function to transform and return newObj

type UpdatedObjectInfo 

type UpdatedObjectInfo interface {
	// Returns preconditions built from the updated object, if applicable.
	// May return nil, or a preconditions object containing nil fields,
	// if no preconditions can be determined from the updated object.
	Preconditions() *metav1.Preconditions

	// UpdatedObject returns the updated object, given a context and old object.
	// The only time an empty oldObj should be passed in is if a "create on update" is occurring (there is no oldObj).
	UpdatedObject(ctx genericapirequest.Context, oldObj runtime.Object) (newObj runtime.Object, err error)
}

UpdatedObjectInfo provides information about an updated object to an Updater. It requires access to the old object in order to return the newly updated object.

func DefaultUpdatedObjectInfo 

func DefaultUpdatedObjectInfo(obj runtime.Object, copier runtime.ObjectCopier, transformers ...TransformFunc) UpdatedObjectInfo

DefaultUpdatedObjectInfo returns an UpdatedObjectInfo impl based on the specified object.

func WrapUpdatedObjectInfo 

func WrapUpdatedObjectInfo(objInfo UpdatedObjectInfo, transformers ...TransformFunc) UpdatedObjectInfo

WrapUpdatedObjectInfo returns an UpdatedObjectInfo impl that delegates to the specified objInfo, then calls the passed transformers

type Updater 

type Updater interface {
	// New returns an empty object that can be used with Update after request data has been put into it.
	// This object must be a pointer type for use with Codec.DecodeInto([]byte, runtime.Object)
	New() runtime.Object

	// Update finds a resource in the storage and updates it. Some implementations
	// may allow updates creates the object - they should set the created boolean
	// to true.
	Update(ctx genericapirequest.Context, name string, objInfo UpdatedObjectInfo) (runtime.Object, bool, error)
}

Updater is an object that can update an instance of a RESTful object.

type Watcher 

type Watcher interface {
	// 'label' selects on labels; 'field' selects on the object's fields. Not all fields
	// are supported; an error should be returned if 'field' tries to select on a field that
	// isn't supported. 'resourceVersion' allows for continuing/starting a watch at a
	// particular version.
	Watch(ctx genericapirequest.Context, options *metainternalversion.ListOptions) (watch.Interface, error)
}

Watcher should be implemented by all Storage objects that want to offer the ability to watch for changes through the watch api.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.