Documentation ¶
Overview ¶
Package resource assists clients in dealing with RESTful objects that match the Kubernetes API conventions. The Helper object provides simple CRUD operations on resources. The Visitor interface makes it easy to deal with multiple resources in bulk for retrieval and operation. The Builder object simplifies converting standard command line arguments and parameters into a Visitor that can iterate over all of the identified resources, whether on the server or on the local filesystem.
Index ¶
- func RetrieveLatest(info *Info) error
- func SplitResourceArgument(arg string) []string
- func UpdateObjectNamespace(info *Info) error
- type Builder
- func (b *Builder) ContinueOnError() *Builder
- func (b *Builder) DefaultNamespace() *Builder
- func (b *Builder) Do() *Result
- func (b *Builder) FilenameParam(paths ...string) *Builder
- func (b *Builder) Flatten() *Builder
- func (b *Builder) Latest() *Builder
- func (b *Builder) NamespaceParam(namespace string) *Builder
- func (b *Builder) Path(paths ...string) *Builder
- func (b *Builder) RequireNamespace() *Builder
- func (b *Builder) ResourceTypeAndNameArgs(args ...string) *Builder
- func (b *Builder) ResourceTypeOrNameArgs(allowEmptySelector bool, args ...string) *Builder
- func (b *Builder) ResourceTypes(types ...string) *Builder
- func (b *Builder) SelectAllParam(selectAll bool) *Builder
- func (b *Builder) Selector(selector labels.Selector) *Builder
- func (b *Builder) SelectorParam(s string) *Builder
- func (b *Builder) SingleResourceType() *Builder
- func (b *Builder) Stdin() *Builder
- func (b *Builder) Stream(r io.Reader, name string) *Builder
- func (b *Builder) URL(urls ...*url.URL) *Builder
- type ClientMapper
- type ClientMapperFunc
- type DecoratedVisitor
- type DirectoryVisitor
- type EagerVisitorList
- type ErrMatchFunc
- type FlattenListVisitor
- type Helper
- func (m *Helper) Create(namespace string, modify bool, data []byte) (runtime.Object, error)
- func (m *Helper) Delete(namespace, name string) error
- func (m *Helper) Get(namespace, name string) (runtime.Object, error)
- func (m *Helper) List(namespace string, selector labels.Selector) (runtime.Object, error)
- func (m *Helper) Update(namespace, name string, overwrite bool, data []byte) (runtime.Object, error)
- func (m *Helper) Watch(namespace, resourceVersion string, ...) (watch.Interface, error)
- func (m *Helper) WatchSingle(namespace, name, resourceVersion string) (watch.Interface, error)
- type Info
- type Mapper
- type PathVisitor
- type RESTClient
- type ResourceMapping
- type Result
- func (r *Result) Err() error
- func (r *Result) IgnoreErrors(fns ...ErrMatchFunc) *Result
- func (r *Result) Infos() ([]*Info, error)
- func (r *Result) IntoSingular(b *bool) *Result
- func (r *Result) Object() (runtime.Object, error)
- func (r *Result) ResourceMapping() (*meta.RESTMapping, error)
- func (r *Result) Visit(fn VisitorFunc) error
- func (r *Result) Watch(resourceVersion string) (watch.Interface, error)
- type Selector
- type StreamVisitor
- type URLVisitor
- type Visitor
- type VisitorFunc
- type VisitorList
- type Watchable
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RetrieveLatest ¶
RetrieveLatest updates the Object on each Info by invoking a standard client Get.
func SplitResourceArgument ¶
func UpdateObjectNamespace ¶
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder provides convenience functions for taking arguments and parameters from the command line and converting them to a list of resources to iterate over using the Visitor interface.
func NewBuilder ¶
func NewBuilder(mapper meta.RESTMapper, typer runtime.ObjectTyper, clientMapper ClientMapper) *Builder
NewBuilder creates a builder that operates on generic objects.
func (*Builder) ContinueOnError ¶
ContinueOnError will attempt to load and visit as many objects as possible, even if some visits return errors or some objects cannot be loaded. The default behavior is to terminate after the first error is returned from a VisitorFunc.
func (*Builder) DefaultNamespace ¶
DefaultNamespace instructs the builder to set the namespace value for any object found to NamespaceParam() if empty.
func (*Builder) Do ¶
Do returns a Result object with a Visitor for the resources identified by the Builder. The visitor will respect the error behavior specified by ContinueOnError. Note that stream inputs are consumed by the first execution - use Infos() or Object() on the Result to capture a list for further iteration.
func (*Builder) FilenameParam ¶
Filename is parameters passed via a filename argument which may be URLs, the "-" argument indicating STDIN, or paths to files or directories. If ContinueOnError() is set prior to this method being called, objects on the path that are unrecognized will be ignored (but logged at V(2)).
func (*Builder) Flatten ¶
Flatten will convert any objects with a field named "Items" that is an array of runtime.Object compatible types into individual entries and give them their own items. The original object is not passed to any visitors.
func (*Builder) Latest ¶
Latest will fetch the latest copy of any objects loaded from URLs or files from the server.
func (*Builder) NamespaceParam ¶
The namespace that these resources should be assumed to under - used by DefaultNamespace() and RequireNamespace()
func (*Builder) Path ¶
Path is a set of filesystem paths that may be files containing one or more resources. If ContinueOnError() is set prior to this method being called, objects on the path that are unrecognized will be ignored (but logged at V(2)).
func (*Builder) RequireNamespace ¶
RequireNamespace instructs the builder to set the namespace value for any object found to NamespaceParam() if empty, and if the value on the resource does not match NamespaceParam() an error will be returned.
func (*Builder) ResourceTypeAndNameArgs ¶
ResourceTypeAndNameArgs expects two arguments, a resource type, and a resource name. The resource matching that type and and name will be retrieved from the server.
func (*Builder) ResourceTypeOrNameArgs ¶
ResourceTypeOrNameArgs indicates that the builder should accept arguments of the form `(<type1>[,<type2>,...]|<type> <name1>[,<name2>,...])`. When one argument is received, the types provided will be retrieved from the server (and be comma delimited). When two or more arguments are received, they must be a single type and resource name(s). The allowEmptySelector permits to select all the resources (via Everything func).
func (*Builder) ResourceTypes ¶
ResourceTypes is a list of types of resources to operate on, when listing objects on the server or retrieving objects that match a selector.
func (*Builder) SelectAllParam ¶ added in v0.4.1
SelectEverythingParam
func (*Builder) Selector ¶
Selector accepts a selector directly, and if non nil will trigger a list action.
func (*Builder) SelectorParam ¶
SelectorParam defines a selector that should be applied to the object types to load. This will not affect files loaded from disk or URL. If the parameter is empty it is a no-op - to select all resources invoke `b.Selector(labels.Everything)`.
func (*Builder) SingleResourceType ¶
SingleResourceType will cause the builder to error if the user specifies more than a single type of resource.
func (*Builder) Stdin ¶
Stdin will read objects from the standard input. If ContinueOnError() is set prior to this method being called, objects in the stream that are unrecognized will be ignored (but logged at V(2)).
type ClientMapper ¶
type ClientMapper interface {
ClientForMapping(mapping *meta.RESTMapping) (RESTClient, error)
}
ClientMapper retrieves a client object for a given mapping
type ClientMapperFunc ¶
type ClientMapperFunc func(mapping *meta.RESTMapping) (RESTClient, error)
ClientMapperFunc implements ClientMapper for a function
func (ClientMapperFunc) ClientForMapping ¶
func (f ClientMapperFunc) ClientForMapping(mapping *meta.RESTMapping) (RESTClient, error)
ClientForMapping implements ClientMapper
type DecoratedVisitor ¶
type DecoratedVisitor struct {
// contains filtered or unexported fields
}
DecoratedVisitor will invoke the decorators in order prior to invoking the visitor function passed to Visit. An error will terminate the visit.
func (DecoratedVisitor) Visit ¶
func (v DecoratedVisitor) Visit(fn VisitorFunc) error
Visit implements Visitor
type DirectoryVisitor ¶
type DirectoryVisitor struct { *Mapper // The directory or file to start from Path string // Whether directories are recursed Recursive bool // The file extensions to include. If empty, all files are read. Extensions []string // Whether to ignore files that are not recognized as API objects IgnoreErrors bool }
DirectoryVisitor loads the specified files from a directory and passes them to visitors.
func (*DirectoryVisitor) Visit ¶
func (v *DirectoryVisitor) Visit(fn VisitorFunc) error
type EagerVisitorList ¶
type EagerVisitorList []Visitor
EagerVisitorList implements Visit for the sub visitors it contains. All errors will be captured and returned at the end of iteration.
func (EagerVisitorList) Visit ¶
func (l EagerVisitorList) Visit(fn VisitorFunc) error
Visit implements Visitor, and gathers errors that occur during processing until all sub visitors have been visited.
type ErrMatchFunc ¶
ErrMatchFunc can be used to filter errors that may not be true failures.
type FlattenListVisitor ¶
FlattenListVisitor flattens any objects that runtime.ExtractList recognizes as a list - has an "Items" public field that is a slice of runtime.Objects or objects satisfying that interface - into multiple Infos. An error on any sub item (for instance, if a List contains an object that does not have a registered client or resource) will terminate the visit. TODO: allow errors to be aggregated?
func (FlattenListVisitor) Visit ¶
func (v FlattenListVisitor) Visit(fn VisitorFunc) error
type Helper ¶
type Helper struct { // The name of this resource as the server would recognize it Resource string // A RESTClient capable of mutating this resource RESTClient RESTClient // A codec for decoding and encoding objects of this resource type. Codec runtime.Codec // An interface for reading or writing the resource version of this // type. Versioner runtime.ResourceVersioner // True if the resource type is scoped to namespaces NamespaceScoped bool }
Helper provides methods for retrieving or mutating a RESTful resource.
func NewHelper ¶
func NewHelper(client RESTClient, mapping *meta.RESTMapping) *Helper
NewHelper creates a Helper from a ResourceMapping
type Info ¶
type Info struct { Client RESTClient Mapping *meta.RESTMapping Namespace string Name string // Optional, this is the most recent value returned by the server if available runtime.Object // Optional, this is the most recent resource version the server knows about for // this type of resource. It may not match the resource version of the object, // but if set it should be equal to or newer than the resource version of the // object (however the server defines resource version). ResourceVersion string }
Info contains temporary info to execute a REST call, or show the results of an already completed REST call.
func NewInfo ¶
func NewInfo(client RESTClient, mapping *meta.RESTMapping, namespace, name string) *Info
NewInfo returns a new info object
func (*Info) Refresh ¶ added in v0.3.1
Refresh updates the object with another object. If ignoreError is set the Object will be updated even if name, namespace, or resourceVersion attributes cannot be loaded from the object.
func (*Info) ResourceMapping ¶
func (i *Info) ResourceMapping() *meta.RESTMapping
ResourceMapping returns the mapping for this resource and implements ResourceMapping
type Mapper ¶
type Mapper struct { runtime.ObjectTyper meta.RESTMapper ClientMapper }
Mapper is a convenience struct for holding references to the three interfaces needed to create Info for arbitrary objects.
func (*Mapper) InfoForData ¶
InfoForData creates an Info object for the given data. An error is returned if any of the decoding or client lookup steps fail. Name and namespace will be set into Info if the mapping's MetadataAccessor can retrieve them.
func (*Mapper) InfoForObject ¶
InfoForData creates an Info object for the given Object. An error is returned if the object cannot be introspected. Name and namespace will be set into Info if the mapping's MetadataAccessor can retrieve them.
type PathVisitor ¶
type PathVisitor struct { *Mapper // The file path to load Path string // Whether to ignore files that are not recognized as API objects IgnoreErrors bool }
PathVisitor visits a given path and returns an object representing the file at that path.
func (*PathVisitor) Visit ¶
func (v *PathVisitor) Visit(fn VisitorFunc) error
type RESTClient ¶
type RESTClient interface { Get() *client.Request Post() *client.Request Delete() *client.Request Put() *client.Request }
RESTClient is a client helper for dealing with RESTful resources in a generic way.
type ResourceMapping ¶
type ResourceMapping interface {
ResourceMapping() *meta.RESTMapping
}
ResourceMapping allows an object to return the resource mapping associated with the resource or resources it represents.
type Result ¶
type Result struct {
// contains filtered or unexported fields
}
Result contains helper methods for dealing with the outcome of a Builder.
func (*Result) Err ¶
Err returns one or more errors (via a util.ErrorList) that occurred prior to visiting the elements in the visitor. To see all errors including those that occur during visitation, invoke Infos().
func (*Result) IgnoreErrors ¶
func (r *Result) IgnoreErrors(fns ...ErrMatchFunc) *Result
IgnoreErrors will filter errors that occur when by visiting the result (but not errors that occur by creating the result in the first place), eliminating any that match fns. This is best used in combination with Builder.ContinueOnError(), where the visitors accumulate errors and return them after visiting as a slice of errors. If no errors remain after filtering, the various visitor methods on Result will return nil for err.
func (*Result) Infos ¶
Infos returns an array of all of the resource infos retrieved via traversal. Will attempt to traverse the entire set of visitors only once, and will return a cached list on subsequent calls.
func (*Result) IntoSingular ¶
IntoSingular sets the provided boolean pointer to true if the Builder input reflected a single item, or multiple.
func (*Result) Object ¶
Object returns a single object representing the output of a single visit to all found resources. If the Builder was a singular context (expected to return a single resource by user input) and only a single resource was found, the resource will be returned as is. Otherwise, the returned resources will be part of an api.List. The ResourceVersion of the api.List will be set only if it is identical across all infos returned.
func (*Result) ResourceMapping ¶
func (r *Result) ResourceMapping() (*meta.RESTMapping, error)
ResourceMapping returns a single meta.RESTMapping representing the resources located by the builder, or an error if more than one mapping was found.
func (*Result) Visit ¶
func (r *Result) Visit(fn VisitorFunc) error
Visit implements the Visitor interface on the items described in the Builder. Note that some visitor sources are not traversable more than once, or may return different results. If you wish to operate on the same set of resources multiple times, use the Infos() method.
func (*Result) Watch ¶
Watch retrieves changes that occur on the server to the specified resource. It currently supports watching a single source - if the resource source (selectors or pure types) can be watched, they will be, otherwise the list will be visited (equivalent to the Infos() call) and if there is a single resource present, it will be watched, otherwise an error will be returned.
type Selector ¶
type Selector struct { Client RESTClient Mapping *meta.RESTMapping Namespace string Selector labels.Selector }
Selector is a Visitor for resources that match a label selector.
func NewSelector ¶
func NewSelector(client RESTClient, mapping *meta.RESTMapping, namespace string, selector labels.Selector) *Selector
NewSelector creates a resource selector which hides details of getting items by their label selector.
func (*Selector) ResourceMapping ¶
func (r *Selector) ResourceMapping() *meta.RESTMapping
ResourceMapping returns the mapping for this resource and implements ResourceMapping
type StreamVisitor ¶
StreamVisitor reads objects from an io.Reader and walks them. A stream visitor can only be visited once. TODO: depends on objects being in JSON format before being passed to decode - need to implement a stream decoder method on runtime.Codec to properly handle this.
func (*StreamVisitor) Visit ¶
func (v *StreamVisitor) Visit(fn VisitorFunc) error
Visit implements Visitor over a stream.
type URLVisitor ¶
URLVisitor downloads the contents of a URL, and if successful, returns an info object representing the downloaded object.
func (*URLVisitor) Visit ¶
func (v *URLVisitor) Visit(fn VisitorFunc) error
type Visitor ¶
type Visitor interface {
Visit(VisitorFunc) error
}
Visitor lets clients walk a list of resources.
func NewDecoratedVisitor ¶
func NewDecoratedVisitor(v Visitor, fn ...VisitorFunc) Visitor
NewDecoratedVisitor will create a visitor that invokes the provided visitor functions before the user supplied visitor function is invoked, giving them the opportunity to mutate the Info object or terminate early with an error.
func NewFlattenListVisitor ¶
NewFlattenListVisitor creates a visitor that will expand list style runtime.Objects into individual items and then visit them individually.
func NewStreamVisitor ¶
NewStreamVisitor creates a visitor that will return resources that were encoded into the provided stream. If ignoreErrors is set, unrecognized or invalid objects will be skipped and logged. An empty stream is treated as an error for now. TODO: convert ignoreErrors into a func(data, error, count) bool that consumers can use to decide what to do with ignored errors.
type VisitorFunc ¶
VisitorFunc implements the Visitor interface for a matching function
func FilterNamespace ¶ added in v0.3.1
func FilterNamespace() VisitorFunc
FilterNamespace omits the namespace if the object is not namespace scoped
func RequireNamespace ¶
func RequireNamespace(namespace string) VisitorFunc
RequireNamespace will either set a namespace if none is provided on the Info object, or if the namespace is set and does not match the provided value, returns an error. This is intended to guard against administrators accidentally operating on resources outside their namespace.
func SetNamespace ¶
func SetNamespace(namespace string) VisitorFunc
SetNamespace ensures that every Info object visited will have a namespace set. If info.Object is set, it will be mutated as well.
type VisitorList ¶
type VisitorList []Visitor
VisitorList implements Visit for the sub visitors it contains. The first error returned from a child Visitor will terminate iteration.
func (VisitorList) Visit ¶
func (l VisitorList) Visit(fn VisitorFunc) error
Visit implements Visitor