meta

package
v0.32.0-rc.1 Latest Latest
Warning

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

 Go to latest Published: Sep 20, 2024 License: Apache-2.0 Imports: 15 Imported by: 13,381

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,
}
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.

func AsPartialObjectMetadata 

func AsPartialObjectMetadata(m metav1.Object) *metav1.PartialObjectMetadata

AsPartialObjectMetadata takes the metav1 interface and returns a partial object. TODO: consider making this solely a conversion action.

func CommonAccessor 

func CommonAccessor(obj interface{}) (metav1.Common, error)

CommonAccessor returns a Common interface for the provided object or an error if the object does not provide List.

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.

If items passed to fn are retained for different durations, and you want to avoid retaining all items in obj as long as any item is referenced, use EachListItemWithAlloc instead.

func EachListItemWithAlloc added in v0.28.0 

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

EachListItemWithAlloc works like EachListItem, but avoids retaining references to the items slice in obj. It does this by making a shallow copy of non-pointer items in obj.

If the items passed to fn are not retained, or are retained for the same duration, use EachListItem instead for memory efficiency.

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).

If items in the returned list are retained for different durations, and you want to avoid retaining all items in obj as long as any item is referenced, use ExtractListWithAlloc instead.

func ExtractListWithAlloc added in v0.28.0 

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

ExtractListWithAlloc works like ExtractList, but avoids retaining references to the items slice in obj. It does this by making a shallow copy of non-pointer items in obj.

If the items in the returned list are not retained, or are retained for the same duration, use ExtractList instead for memory efficiency.

func FindStatusCondition added in v0.19.0 

func FindStatusCondition(conditions []metav1.Condition, conditionType string) *metav1.Condition

FindStatusCondition finds the conditionType in conditions.

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. TODO: this will be replaced with an interface in the future

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. TODO: Replace the code in this check with an interface comparison by creating and enforcing that lists implement a list accessor.

func IsNoMatchError 

func IsNoMatchError(err error) bool

func IsStatusConditionFalse added in v0.19.0 

func IsStatusConditionFalse(conditions []metav1.Condition, conditionType string) bool

IsStatusConditionFalse returns true when the conditionType is present and set to `metav1.ConditionFalse`

func IsStatusConditionPresentAndEqual added in v0.19.0 

func IsStatusConditionPresentAndEqual(conditions []metav1.Condition, conditionType string, status metav1.ConditionStatus) bool

IsStatusConditionPresentAndEqual returns true when conditionType is present and equal to status.

func IsStatusConditionTrue added in v0.19.0 

func IsStatusConditionTrue(conditions []metav1.Condition, conditionType string) bool

IsStatusConditionTrue returns true when the conditionType is present and set to `metav1.ConditionTrue`

func LenList 

func LenList(list runtime.Object) int

LenList returns the length of this list or 0 if it is not a list.

func MaybeResetRESTMapper added in v0.23.0 

func MaybeResetRESTMapper(mapper RESTMapper)

MaybeResetRESTMapper calls Reset() on the mapper if it is a ResettableRESTMapper.

func RemoveStatusCondition added in v0.19.0 

func RemoveStatusCondition(conditions *[]metav1.Condition, conditionType string) (removed bool)

RemoveStatusCondition removes the corresponding conditionType from conditions if present. Returns true if it was present and got removed. conditions must be non-nil.

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.

func SetStatusCondition added in v0.19.0 

func SetStatusCondition(conditions *[]metav1.Condition, newCondition metav1.Condition) (changed bool)

SetStatusCondition sets the corresponding condition in conditions to newCondition and returns true if the conditions are changed by this call. conditions must be non-nil.

  1. if the condition of the specified type already exists (all fields of the existing condition are updated to newCondition, LastTransitionTime is set to now if the new status differs from the old status)
  2. if a condition of the specified type does not exist (LastTransitionTime is set to now() if unset, and newCondition is appended)

func UnsafeGuessKindToResource 

func UnsafeGuessKindToResource(kind schema.GroupVersionKind) (schema.GroupVersionResource, schema.GroupVersionResource)

UnsafeGuessKindToResource 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.

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

func (*AmbiguousKindError) Is added in v0.26.0 

func (*AmbiguousKindError) Is(target error) bool

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

func (*AmbiguousResourceError) Is added in v0.26.0 

func (*AmbiguousResourceError) Is(target error) bool

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) *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 (*DefaultRESTMapper) Add 

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

func (*DefaultRESTMapper) AddSpecific 

func (m *DefaultRESTMapper) AddSpecific(kind schema.GroupVersionKind, plural, singular schema.GroupVersionResource, scope RESTScope)

func (*DefaultRESTMapper) KindFor 

func (m *DefaultRESTMapper) KindFor(resource schema.GroupVersionResource) (schema.GroupVersionKind, error)

func (*DefaultRESTMapper) KindsFor 

func (m *DefaultRESTMapper) KindsFor(input schema.GroupVersionResource) ([]schema.GroupVersionKind, error)

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 (m *DefaultRESTMapper) ResourceFor(resource schema.GroupVersionResource) (schema.GroupVersionResource, error)

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 (m *DefaultRESTMapper) ResourcesFor(input schema.GroupVersionResource) ([]schema.GroupVersionResource, error)

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 (m FirstHitRESTMapper) KindFor(resource schema.GroupVersionResource) (schema.GroupVersionKind, error)

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) Reset added in v0.23.0 

func (m FirstHitRESTMapper) Reset()

func (FirstHitRESTMapper) ResourceFor 

func (m FirstHitRESTMapper) ResourceFor(resource schema.GroupVersionResource) (schema.GroupVersionResource, error)

func (FirstHitRESTMapper) String 

func (m FirstHitRESTMapper) String() string

type List 

type List metav1.ListInterface

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 NOT a superset of lists. Do not use this check to determine whether an object *is* a List.

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

	Continue(obj runtime.Object) (string, error)
	SetContinue(obj runtime.Object, c 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) KindFor 

func (m MultiRESTMapper) KindFor(resource schema.GroupVersionResource) (schema.GroupVersionKind, error)

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) Reset added in v0.23.0 

func (m MultiRESTMapper) Reset()

func (MultiRESTMapper) ResourceFor 

func (m MultiRESTMapper) ResourceFor(resource schema.GroupVersionResource) (schema.GroupVersionResource, error)

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 (m MultiRESTMapper) ResourcesFor(resource schema.GroupVersionResource) ([]schema.GroupVersionResource, error)

func (MultiRESTMapper) String 

func (m MultiRESTMapper) String() string

type NoKindMatchError 

type NoKindMatchError struct {
	// GroupKind is the API group and kind that was searched
	GroupKind schema.GroupKind
	// SearchedVersions is the optional list of versions the search was restricted to
	SearchedVersions []string
}

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

func (*NoKindMatchError) Error 

func (e *NoKindMatchError) Error() string

func (*NoKindMatchError) Is added in v0.26.0 

func (*NoKindMatchError) Is(target error) bool

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

func (*NoResourceMatchError) Is added in v0.26.0 

func (*NoResourceMatchError) Is(target error) bool

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) 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) Reset added in v0.23.0 

func (m PriorityRESTMapper) Reset()

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)

	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

func NewLazyRESTMapperLoader 

func NewLazyRESTMapperLoader(fn func() (RESTMapper, error)) RESTMapper

NewLazyRESTMapperLoader handles unrecoverable errors when creating a RESTMapper / ObjectTyper by returning those initialization errors when the interface methods are invoked. This defers the initialization and any server calls until a client actually needs to perform the action.

type RESTMapping 

type RESTMapping struct {
	// Resource is the GroupVersionResource (location) for this endpoint
	Resource schema.GroupVersionResource

	// GroupVersionKind is the GroupVersionKind (data format) to submit to this endpoint
	GroupVersionKind schema.GroupVersionKind

	// Scope contains the information needed to deal with REST Resources that are in a resource hierarchy
	Scope RESTScope
}

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
}

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 ResettableRESTMapper added in v0.23.0 

type ResettableRESTMapper interface {
	RESTMapper
	Reset()
}

ResettableRESTMapper is a RESTMapper which is capable of resetting itself from discovery. All rest mappers that delegate to other rest mappers must implement this interface and dynamically check if the delegate mapper supports the Reset() operation.

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).

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.