Documentation

Overview

    Package meta provides functions for retrieving API metadata from objects belonging to the Kubernetes API

    TODO: move everything in this file to pkg/api/rest

    Index

    Constants

    View Source
    const (
    	AnyGroup    = "*"
    	AnyVersion  = "*"
    	AnyResource = "*"
    	AnyKind     = "*"
    )

    Variables

    View Source
    var RESTScopeNamespace = &restScope{
    	name:             RESTScopeNameNamespace,
    	paramName:        "namespaces",
    	argumentName:     "namespace",
    	paramDescription: "object name and auth scope, such as for teams and projects",
    }
    View Source
    var RESTScopeRoot = &restScope{
    	name: RESTScopeNameRoot,
    }

    Functions

    func Accessor

    func Accessor(obj interface{}) (metav1.Object, error)

      Accessor takes an arbitrary object pointer and returns meta.Interface. obj must be a pointer to an API type. An error is returned if the minimum required fields are missing. Fields that are not required return the default value and are a no-op if set. TODO: return bool instead of error

      func EachListItem

      func EachListItem(obj runtime.Object, fn func(runtime.Object) error) error

        EachListItem invokes fn on each runtime.Object in the list. Any error immediately terminates the loop.

        func ExtractList

        func ExtractList(obj runtime.Object) ([]runtime.Object, error)

          ExtractList returns obj's Items element as an array of runtime.Objects. Returns an error if obj is not a List type (does not have an Items member).

          func GetItemsPtr

          func GetItemsPtr(list runtime.Object) (interface{}, error)

            GetItemsPtr returns a pointer to the list object's Items member. If 'list' doesn't have an Items member, it's not really a list type and an error will be returned. This function will either return a pointer to a slice, or an error, but not both.

            func IsAmbiguousError

            func IsAmbiguousError(err error) bool

            func IsListType

            func IsListType(obj runtime.Object) bool

              IsListType returns true if the provided Object has a slice called Items

              func IsNoMatchError

              func IsNoMatchError(err error) bool

              func KindToResource

                KindToResource converts Kind to a resource name. Broken. This method only "sort of" works when used outside of this package. It assumes that Kinds and Resources match and they aren't guaranteed to do so.

                func SetList

                func SetList(list runtime.Object, objects []runtime.Object) error

                  SetList sets the given list object's Items member have the elements given in objects. Returns an error if list is not a List type (does not have an Items member), or if any of the objects are not of the right type.

                  Types

                  type AmbiguousKindError

                  type AmbiguousKindError struct {
                  	PartialKind schema.GroupVersionKind
                  
                  	MatchingResources []schema.GroupVersionResource
                  	MatchingKinds     []schema.GroupVersionKind
                  }

                    AmbiguousKindError is returned if the RESTMapper finds multiple matches for a kind

                    func (*AmbiguousKindError) Error

                    func (e *AmbiguousKindError) Error() string

                    type AmbiguousResourceError

                    type AmbiguousResourceError struct {
                    	PartialResource schema.GroupVersionResource
                    
                    	MatchingResources []schema.GroupVersionResource
                    	MatchingKinds     []schema.GroupVersionKind
                    }

                      AmbiguousResourceError is returned if the RESTMapper finds multiple matches for a resource

                      func (*AmbiguousResourceError) Error

                      func (e *AmbiguousResourceError) Error() string

                      type DefaultRESTMapper

                      type DefaultRESTMapper struct {
                      	// contains filtered or unexported fields
                      }

                        DefaultRESTMapper exposes mappings between the types defined in a runtime.Scheme. It assumes that all types defined the provided scheme can be mapped with the provided MetadataAccessor and Codec interfaces.

                        The resource name of a Kind is defined as the lowercase, English-plural version of the Kind string. When converting from resource to Kind, the singular version of the resource name is also accepted for convenience.

                        TODO: Only accept plural for some operations for increased control? (`get pod bar` vs `get pods bar`)

                        func NewDefaultRESTMapper

                        func NewDefaultRESTMapper(defaultGroupVersions []schema.GroupVersion, f VersionInterfacesFunc) *DefaultRESTMapper

                          NewDefaultRESTMapper initializes a mapping between Kind and APIVersion to a resource name and back based on the objects in a runtime.Scheme and the Kubernetes API conventions. Takes a group name, a priority list of the versions to search when an object has no default version (set empty to return an error), and a function that retrieves the correct metadata for a given version.

                          func NewDefaultRESTMapperFromScheme

                          func NewDefaultRESTMapperFromScheme(defaultGroupVersions []schema.GroupVersion, interfacesFunc VersionInterfacesFunc,
                          	importPathPrefix string, ignoredKinds, rootScoped sets.String, scheme *runtime.Scheme) *DefaultRESTMapper

                            NewDefaultRESTMapperFromScheme instantiates a DefaultRESTMapper based on types registered in the given scheme.

                            func (*DefaultRESTMapper) Add

                            func (m *DefaultRESTMapper) Add(kind schema.GroupVersionKind, scope RESTScope)

                            func (*DefaultRESTMapper) AddResourceAlias

                            func (m *DefaultRESTMapper) AddResourceAlias(alias string, resources ...string)

                              AddResourceAlias maps aliases to resources

                              func (*DefaultRESTMapper) AliasesForResource

                              func (m *DefaultRESTMapper) AliasesForResource(alias string) ([]string, bool)

                                AliasesForResource returns whether a resource has an alias or not

                                func (*DefaultRESTMapper) KindFor

                                func (*DefaultRESTMapper) KindsFor

                                func (*DefaultRESTMapper) RESTMapping

                                func (m *DefaultRESTMapper) RESTMapping(gk schema.GroupKind, versions ...string) (*RESTMapping, error)

                                  RESTMapping returns a struct representing the resource path and conversion interfaces a RESTClient should use to operate on the provided group/kind in order of versions. If a version search order is not provided, the search order provided to DefaultRESTMapper will be used to resolve which version should be used to access the named group/kind.

                                  func (*DefaultRESTMapper) RESTMappings

                                  func (m *DefaultRESTMapper) RESTMappings(gk schema.GroupKind, versions ...string) ([]*RESTMapping, error)

                                    RESTMappings returns the RESTMappings for the provided group kind. If a version search order is not provided, the search order provided to DefaultRESTMapper will be used.

                                    func (*DefaultRESTMapper) ResourceFor

                                    func (*DefaultRESTMapper) ResourceSingularizer

                                    func (m *DefaultRESTMapper) ResourceSingularizer(resourceType string) (string, error)

                                      ResourceSingularizer implements RESTMapper It converts a resource name from plural to singular (e.g., from pods to pod)

                                      func (*DefaultRESTMapper) ResourcesFor

                                      func (*DefaultRESTMapper) String

                                      func (m *DefaultRESTMapper) String() string

                                      type FirstHitRESTMapper

                                      type FirstHitRESTMapper struct {
                                      	MultiRESTMapper
                                      }

                                        FirstHitRESTMapper is a wrapper for multiple RESTMappers which returns the first successful result for the singular requests

                                        func (FirstHitRESTMapper) KindFor

                                        func (FirstHitRESTMapper) RESTMapping

                                        func (m FirstHitRESTMapper) RESTMapping(gk schema.GroupKind, versions ...string) (*RESTMapping, error)

                                          RESTMapping provides the REST mapping for the resource based on the kind and version. This implementation supports multiple REST schemas and return the first match.

                                          func (FirstHitRESTMapper) ResourceFor

                                          func (FirstHitRESTMapper) String

                                          func (m FirstHitRESTMapper) String() string

                                          type List

                                          type List metav1.List

                                            List lets you work with list metadata from any of the versioned or internal API objects. Attempting to set or retrieve a field on an object that does not support that field will be a no-op and return a default value.

                                            func ListAccessor

                                            func ListAccessor(obj interface{}) (List, error)

                                              ListAccessor returns a List interface for the provided object or an error if the object does not provide List. IMPORTANT: Objects are a superset of lists, so all Objects return List metadata. Do not use this check to determine whether an object *is* a List. TODO: return bool instead of error

                                              type ListMetaAccessor

                                              type ListMetaAccessor interface {
                                              	GetListMeta() List
                                              }

                                              type MetadataAccessor

                                              type MetadataAccessor interface {
                                              	APIVersion(obj runtime.Object) (string, error)
                                              	SetAPIVersion(obj runtime.Object, version string) error
                                              
                                              	Kind(obj runtime.Object) (string, error)
                                              	SetKind(obj runtime.Object, kind string) error
                                              
                                              	Namespace(obj runtime.Object) (string, error)
                                              	SetNamespace(obj runtime.Object, namespace string) error
                                              
                                              	Name(obj runtime.Object) (string, error)
                                              	SetName(obj runtime.Object, name string) error
                                              
                                              	GenerateName(obj runtime.Object) (string, error)
                                              	SetGenerateName(obj runtime.Object, name string) error
                                              
                                              	UID(obj runtime.Object) (types.UID, error)
                                              	SetUID(obj runtime.Object, uid types.UID) error
                                              
                                              	SelfLink(obj runtime.Object) (string, error)
                                              	SetSelfLink(obj runtime.Object, selfLink string) error
                                              
                                              	Labels(obj runtime.Object) (map[string]string, error)
                                              	SetLabels(obj runtime.Object, labels map[string]string) error
                                              
                                              	Annotations(obj runtime.Object) (map[string]string, error)
                                              	SetAnnotations(obj runtime.Object, annotations map[string]string) error
                                              
                                              	runtime.ResourceVersioner
                                              }

                                                MetadataAccessor lets you work with object and list metadata from any of the versioned or internal API objects. Attempting to set or retrieve a field on an object that does not support that field (Name, UID, Namespace on lists) will be a no-op and return a default value.

                                                MetadataAccessor exposes Interface in a way that can be used with multiple objects.

                                                func NewAccessor

                                                func NewAccessor() MetadataAccessor

                                                  NewAccessor returns a MetadataAccessor that can retrieve or manipulate resource version on objects derived from core API metadata concepts.

                                                  type MultiRESTMapper

                                                  type MultiRESTMapper []RESTMapper

                                                    MultiRESTMapper is a wrapper for multiple RESTMappers.

                                                    func (MultiRESTMapper) AliasesForResource

                                                    func (m MultiRESTMapper) AliasesForResource(alias string) ([]string, bool)

                                                      AliasesForResource finds the first alias response for the provided mappers.

                                                      func (MultiRESTMapper) KindFor

                                                      func (MultiRESTMapper) KindsFor

                                                      func (m MultiRESTMapper) KindsFor(resource schema.GroupVersionResource) (gvk []schema.GroupVersionKind, err error)

                                                      func (MultiRESTMapper) RESTMapping

                                                      func (m MultiRESTMapper) RESTMapping(gk schema.GroupKind, versions ...string) (*RESTMapping, error)

                                                        RESTMapping provides the REST mapping for the resource based on the kind and version. This implementation supports multiple REST schemas and return the first match.

                                                        func (MultiRESTMapper) RESTMappings

                                                        func (m MultiRESTMapper) RESTMappings(gk schema.GroupKind, versions ...string) ([]*RESTMapping, error)

                                                          RESTMappings returns all possible RESTMappings for the provided group kind, or an error if the type is not recognized.

                                                          func (MultiRESTMapper) ResourceFor

                                                          func (MultiRESTMapper) ResourceSingularizer

                                                          func (m MultiRESTMapper) ResourceSingularizer(resource string) (singular string, err error)

                                                            ResourceSingularizer converts a REST resource name from plural to singular (e.g., from pods to pod) This implementation supports multiple REST schemas and return the first match.

                                                            func (MultiRESTMapper) ResourcesFor

                                                            func (MultiRESTMapper) String

                                                            func (m MultiRESTMapper) String() string

                                                            type NoKindMatchError

                                                            type NoKindMatchError struct {
                                                            	PartialKind schema.GroupVersionKind
                                                            }

                                                              NoKindMatchError is returned if the RESTMapper can't find any match for a kind

                                                              func (*NoKindMatchError) Error

                                                              func (e *NoKindMatchError) Error() string

                                                              type NoResourceMatchError

                                                              type NoResourceMatchError struct {
                                                              	PartialResource schema.GroupVersionResource
                                                              }

                                                                NoResourceMatchError is returned if the RESTMapper can't find any match for a resource

                                                                func (*NoResourceMatchError) Error

                                                                func (e *NoResourceMatchError) Error() string

                                                                type PriorityRESTMapper

                                                                type PriorityRESTMapper struct {
                                                                	// Delegate is the RESTMapper to use to locate all the Kind and Resource matches
                                                                	Delegate RESTMapper
                                                                
                                                                	// ResourcePriority is a list of priority patterns to apply to matching resources.
                                                                	// The list of all matching resources is narrowed based on the patterns until only one remains.
                                                                	// A pattern with no matches is skipped.  A pattern with more than one match uses its
                                                                	// matches as the list to continue matching against.
                                                                	ResourcePriority []schema.GroupVersionResource
                                                                
                                                                	// KindPriority is a list of priority patterns to apply to matching kinds.
                                                                	// The list of all matching kinds is narrowed based on the patterns until only one remains.
                                                                	// A pattern with no matches is skipped.  A pattern with more than one match uses its
                                                                	// matches as the list to continue matching against.
                                                                	KindPriority []schema.GroupVersionKind
                                                                }

                                                                  PriorityRESTMapper is a wrapper for automatically choosing a particular Resource or Kind when multiple matches are possible

                                                                  func (PriorityRESTMapper) AliasesForResource

                                                                  func (m PriorityRESTMapper) AliasesForResource(alias string) (aliases []string, ok bool)

                                                                  func (PriorityRESTMapper) KindFor

                                                                  func (m PriorityRESTMapper) KindFor(partiallySpecifiedResource schema.GroupVersionResource) (schema.GroupVersionKind, error)

                                                                    KindFor finds all kinds, then passes them through the KindPriority patterns to find a single matching hit.

                                                                    func (PriorityRESTMapper) KindsFor

                                                                    func (m PriorityRESTMapper) KindsFor(partiallySpecifiedResource schema.GroupVersionResource) (gvk []schema.GroupVersionKind, err error)

                                                                    func (PriorityRESTMapper) RESTMapping

                                                                    func (m PriorityRESTMapper) RESTMapping(gk schema.GroupKind, versions ...string) (mapping *RESTMapping, err error)

                                                                    func (PriorityRESTMapper) RESTMappings

                                                                    func (m PriorityRESTMapper) RESTMappings(gk schema.GroupKind, versions ...string) ([]*RESTMapping, error)

                                                                    func (PriorityRESTMapper) ResourceFor

                                                                    func (m PriorityRESTMapper) ResourceFor(partiallySpecifiedResource schema.GroupVersionResource) (schema.GroupVersionResource, error)

                                                                      ResourceFor finds all resources, then passes them through the ResourcePriority patterns to find a single matching hit.

                                                                      func (PriorityRESTMapper) ResourceSingularizer

                                                                      func (m PriorityRESTMapper) ResourceSingularizer(resource string) (singular string, err error)

                                                                      func (PriorityRESTMapper) ResourcesFor

                                                                      func (m PriorityRESTMapper) ResourcesFor(partiallySpecifiedResource schema.GroupVersionResource) ([]schema.GroupVersionResource, error)

                                                                      func (PriorityRESTMapper) String

                                                                      func (m PriorityRESTMapper) String() string

                                                                      type RESTMapper

                                                                      type RESTMapper interface {
                                                                      	// KindFor takes a partial resource and returns the single match.  Returns an error if there are multiple matches
                                                                      	KindFor(resource schema.GroupVersionResource) (schema.GroupVersionKind, error)
                                                                      
                                                                      	// KindsFor takes a partial resource and returns the list of potential kinds in priority order
                                                                      	KindsFor(resource schema.GroupVersionResource) ([]schema.GroupVersionKind, error)
                                                                      
                                                                      	// ResourceFor takes a partial resource and returns the single match.  Returns an error if there are multiple matches
                                                                      	ResourceFor(input schema.GroupVersionResource) (schema.GroupVersionResource, error)
                                                                      
                                                                      	// ResourcesFor takes a partial resource and returns the list of potential resource in priority order
                                                                      	ResourcesFor(input schema.GroupVersionResource) ([]schema.GroupVersionResource, error)
                                                                      
                                                                      	// RESTMapping identifies a preferred resource mapping for the provided group kind.
                                                                      	RESTMapping(gk schema.GroupKind, versions ...string) (*RESTMapping, error)
                                                                      	// RESTMappings returns all resource mappings for the provided group kind if no
                                                                      	// version search is provided. Otherwise identifies a preferred resource mapping for
                                                                      	// the provided version(s).
                                                                      	RESTMappings(gk schema.GroupKind, versions ...string) ([]*RESTMapping, error)
                                                                      
                                                                      	AliasesForResource(resource string) ([]string, bool)
                                                                      	ResourceSingularizer(resource string) (singular string, err error)
                                                                      }

                                                                        RESTMapper allows clients to map resources to kind, and map kind and version to interfaces for manipulating those objects. It is primarily intended for consumers of Kubernetes compatible REST APIs as defined in docs/devel/api-conventions.md.

                                                                        The Kubernetes API provides versioned resources and object kinds which are scoped to API groups. In other words, kinds and resources should not be assumed to be unique across groups.

                                                                        TODO: split into sub-interfaces

                                                                        type RESTMapping

                                                                        type RESTMapping struct {
                                                                        	// Resource is a string representing the name of this resource as a REST client would see it
                                                                        	Resource string
                                                                        
                                                                        	GroupVersionKind schema.GroupVersionKind
                                                                        
                                                                        	// Scope contains the information needed to deal with REST Resources that are in a resource hierarchy
                                                                        	Scope RESTScope
                                                                        
                                                                        	runtime.ObjectConvertor
                                                                        	MetadataAccessor
                                                                        }

                                                                          RESTMapping contains the information needed to deal with objects of a specific resource and kind in a RESTful manner.

                                                                          type RESTScope

                                                                          type RESTScope interface {
                                                                          	// Name of the scope
                                                                          	Name() RESTScopeName
                                                                          	// ParamName is the optional name of the parameter that should be inserted in the resource url
                                                                          	// If empty, no param will be inserted
                                                                          	ParamName() string
                                                                          	// ArgumentName is the optional name that should be used for the variable holding the value.
                                                                          	ArgumentName() string
                                                                          	// ParamDescription is the optional description to use to document the parameter in api documentation
                                                                          	ParamDescription() string
                                                                          }

                                                                            RESTScope contains the information needed to deal with REST resources that are in a resource hierarchy

                                                                            type RESTScopeName

                                                                            type RESTScopeName string
                                                                            const (
                                                                            	RESTScopeNameNamespace RESTScopeName = "namespace"
                                                                            	RESTScopeNameRoot      RESTScopeName = "root"
                                                                            )

                                                                            type Type

                                                                            type Type metav1.Type

                                                                              Type exposes the type and APIVersion of versioned or internal API objects.

                                                                              func TypeAccessor

                                                                              func TypeAccessor(obj interface{}) (Type, error)

                                                                                TypeAccessor returns an interface that allows retrieving and modifying the APIVersion and Kind of an in-memory internal object. TODO: this interface is used to test code that does not have ObjectMeta or ListMeta in round tripping (objects which can use apiVersion/kind, but do not fit the Kube api conventions).

                                                                                type VersionInterfaces

                                                                                type VersionInterfaces struct {
                                                                                	runtime.ObjectConvertor
                                                                                	MetadataAccessor
                                                                                }

                                                                                  VersionInterfaces contains the interfaces one should use for dealing with types of a particular version.

                                                                                  func InterfacesForUnstructured

                                                                                  func InterfacesForUnstructured(schema.GroupVersion) (*VersionInterfaces, error)

                                                                                    InterfacesForUnstructured returns VersionInterfaces suitable for dealing with unstructured.Unstructured objects.

                                                                                    type VersionInterfacesFunc

                                                                                    type VersionInterfacesFunc func(version schema.GroupVersion) (*VersionInterfaces, error)

                                                                                      VersionInterfacesFunc returns the appropriate typer, and metadata accessor for a given api version, or an error if no such api version exists.