client-go – k8s.io/client-go/discovery Index | Files | Directories

package discovery

import "k8s.io/client-go/discovery"

Package discovery provides ways to discover server-supported API groups, versions and resources.

Index

Constants 

const (
	AcceptV1 = runtime.ContentTypeJSON
	// Aggregated discovery content-type (v2beta1). NOTE: content-type parameters
	// MUST be ordered (g, v, as) for server in "Accept" header (BUT we are resilient
	// to ordering when comparing returned values in "Content-Type" header).
	AcceptV2Beta1 = runtime.ContentTypeJSON + ";" + "g=apidiscovery.k8s.io;v=v2beta1;as=APIGroupDiscoveryList"
	AcceptV2      = runtime.ContentTypeJSON + ";" + "g=apidiscovery.k8s.io;v=v2;as=APIGroupDiscoveryList"
)

Functions

func ContentTypeIsGVK 

func ContentTypeIsGVK(contentType string, gvk schema.GroupVersionKind) (bool, error)

ContentTypeIsGVK checks of the content-type string is both "application/json" and matches the provided GVK. An error is returned if the content type string is malformed. NOTE: This function is resilient to the ordering of the content-type parameters, as well as parameters added by intermediaries such as proxies or gateways. Examples: 

("application/json; g=apidiscovery.k8s.io;v=v2beta1;as=APIGroupDiscoveryList", {apidiscovery.k8s.io, v2beta1, APIGroupDiscoveryList}) = (true, nil)
("application/json; as=APIGroupDiscoveryList;v=v2beta1;g=apidiscovery.k8s.io", {apidiscovery.k8s.io, v2beta1, APIGroupDiscoveryList}) = (true, nil)
("application/json; as=APIGroupDiscoveryList;v=v2beta1;g=apidiscovery.k8s.io;charset=utf-8", {apidiscovery.k8s.io, v2beta1, APIGroupDiscoveryList}) = (true, nil)
("application/json", any GVK) = (false, nil)
("application/json; charset=UTF-8", any GVK) = (false, nil)
("malformed content type string", any GVK) = (false, error)

func FilteredBy 

func FilteredBy(pred ResourcePredicate, rls []*metav1.APIResourceList) []*metav1.APIResourceList

FilteredBy filters by the given predicate. Empty APIResourceLists are dropped.

func GroupDiscoveryFailedErrorGroups 

func GroupDiscoveryFailedErrorGroups(err error) (map[schema.GroupVersion]error, bool)

GroupDiscoveryFailedErrorGroups returns true if the error is an ErrGroupDiscoveryFailed error, along with the map of group versions that failed discovery.

func GroupVersionResources 

func GroupVersionResources(rls []*metav1.APIResourceList) (map[schema.GroupVersionResource]struct{}, error)

GroupVersionResources converts APIResourceLists to the GroupVersionResources.

func IsGroupDiscoveryFailedError 

func IsGroupDiscoveryFailedError(err error) bool

IsGroupDiscoveryFailedError returns true if the provided error indicates the server was unable to discover a complete list of APIs for the client to use.

func IsResourceEnabled 

func IsResourceEnabled(client DiscoveryInterface, resourceToCheck schema.GroupVersionResource) (bool, error)

IsResourceEnabled queries the server to determine if the resource specified is present on the server. This is particularly helpful when writing a controller or an e2e test that requires a particular resource to function.

func MatchesServerVersion 

func MatchesServerVersion(clientVersion apimachineryversion.Info, client DiscoveryInterface) error

MatchesServerVersion queries the server to compares the build version (git hash) of the client with the server's build version. It returns an error if it failed to contact the server or if the versions are not an exact match.

func ServerGroupsAndResources 

func ServerGroupsAndResources(d DiscoveryInterface) ([]*metav1.APIGroup, []*metav1.APIResourceList, error)

func ServerPreferredNamespacedResources 

func ServerPreferredNamespacedResources(d DiscoveryInterface) ([]*metav1.APIResourceList, error)

ServerPreferredNamespacedResources uses the provided discovery interface to look up preferred namespaced resources

func ServerPreferredResources 

func ServerPreferredResources(d DiscoveryInterface) ([]*metav1.APIResourceList, error)

ServerPreferredResources uses the provided discovery interface to look up preferred resources

func ServerSupportsVersion 

func ServerSupportsVersion(client DiscoveryInterface, requiredGV schema.GroupVersion) error

ServerSupportsVersion returns an error if the server doesn't have the required version

func SplitGroupsAndResources 

func SplitGroupsAndResources(aggregatedGroups apidiscovery.APIGroupDiscoveryList) (
	*metav1.APIGroupList,
	map[schema.GroupVersion]*metav1.APIResourceList,
	map[schema.GroupVersion]error)

SplitGroupsAndResources transforms "aggregated" discovery top-level structure into the previous "unaggregated" discovery groups and resources.

func SplitGroupsAndResourcesV2Beta1 

func SplitGroupsAndResourcesV2Beta1(aggregatedGroups apidiscoveryv2beta1.APIGroupDiscoveryList) (
	*metav1.APIGroupList,
	map[schema.GroupVersion]*metav1.APIResourceList,
	map[schema.GroupVersion]error)

SplitGroupsAndResourcesV2Beta1 transforms "aggregated" discovery top-level structure into the previous "unaggregated" discovery groups and resources. Deprecated: Please use SplitGroupsAndResources

Types

type AggregatedDiscoveryInterface 

type AggregatedDiscoveryInterface interface {
	DiscoveryInterface

	GroupsAndMaybeResources() (*metav1.APIGroupList, map[schema.GroupVersion]*metav1.APIResourceList, map[schema.GroupVersion]error, error)
}

AggregatedDiscoveryInterface extends DiscoveryInterface to include a method to possibly return discovery resources along with the discovery groups, which is what the newer aggregated discovery format does (APIGroupDiscoveryList).

type CachedDiscoveryInterface 

type CachedDiscoveryInterface interface {
	DiscoveryInterface
	// Fresh is supposed to tell the caller whether or not to retry if the cache
	// fails to find something (false = retry, true = no need to retry).
	//
	// TODO: this needs to be revisited, this interface can't be locked properly
	// and doesn't make a lot of sense.
	Fresh() bool
	// Invalidate enforces that no cached data that is older than the current time
	// is used.
	Invalidate()
}

CachedDiscoveryInterface is a DiscoveryInterface with cache invalidation and freshness. Note that If the ServerResourcesForGroupVersion method returns a cache miss error, the user needs to explicitly call Invalidate to clear the cache, otherwise the same cache miss error will be returned next time.

type DiscoveryClient 

type DiscoveryClient struct {
	LegacyPrefix string
	// Forces the client to request only "unaggregated" (legacy) discovery.
	UseLegacyDiscovery bool
	// contains filtered or unexported fields
}

DiscoveryClient implements the functions that discover server-supported API groups, versions and resources.

func NewDiscoveryClient 

func NewDiscoveryClient(c restclient.Interface) *DiscoveryClient

NewDiscoveryClient returns a new DiscoveryClient for the given RESTClient.

func NewDiscoveryClientForConfig 

func NewDiscoveryClientForConfig(c *restclient.Config) (*DiscoveryClient, error)

NewDiscoveryClientForConfig creates a new DiscoveryClient for the given config. This client can be used to discover supported resources in the API server. NewDiscoveryClientForConfig is equivalent to NewDiscoveryClientForConfigAndClient(c, httpClient), where httpClient was generated with rest.HTTPClientFor(c).

func NewDiscoveryClientForConfigAndClient 

func NewDiscoveryClientForConfigAndClient(c *restclient.Config, httpClient *http.Client) (*DiscoveryClient, error)

NewDiscoveryClientForConfigAndClient creates a new DiscoveryClient for the given config. This client can be used to discover supported resources in the API server. Note the http client provided takes precedence over the configured transport values.

func NewDiscoveryClientForConfigOrDie 

func NewDiscoveryClientForConfigOrDie(c *restclient.Config) *DiscoveryClient

NewDiscoveryClientForConfigOrDie creates a new DiscoveryClient for the given config. If there is an error, it panics.

func (*DiscoveryClient) GroupsAndMaybeResources 

func (d *DiscoveryClient) GroupsAndMaybeResources() (
	*metav1.APIGroupList,
	map[schema.GroupVersion]*metav1.APIResourceList,
	map[schema.GroupVersion]error,
	error)

GroupsAndMaybeResources returns the discovery groups, and (if new aggregated discovery format) the resources keyed by group/version. Merges discovery groups and resources from /api and /apis (either aggregated or not). Legacy groups must be ordered first. The server will either return both endpoints (/api, /apis) as aggregated discovery format or legacy format. For safety, resources will only be returned if both endpoints returned resources. Returned "failedGVs" can be empty, but will only be nil in the case an error is returned.

func (*DiscoveryClient) OpenAPISchema 

func (d *DiscoveryClient) OpenAPISchema() (*openapi_v2.Document, error)

OpenAPISchema fetches the open api v2 schema using a rest client and parses the proto.

func (*DiscoveryClient) OpenAPIV3 

func (d *DiscoveryClient) OpenAPIV3() openapi.Client

func (*DiscoveryClient) RESTClient 

func (d *DiscoveryClient) RESTClient() restclient.Interface

RESTClient returns a RESTClient that is used to communicate with API server by this client implementation.

func (*DiscoveryClient) ServerGroups 

func (d *DiscoveryClient) ServerGroups() (*metav1.APIGroupList, error)

ServerGroups returns the supported groups, with information like supported versions and the preferred version.

func (*DiscoveryClient) ServerGroupsAndResources 

func (d *DiscoveryClient) ServerGroupsAndResources() ([]*metav1.APIGroup, []*metav1.APIResourceList, error)

ServerGroupsAndResources returns the supported resources for all groups and versions.

func (*DiscoveryClient) ServerPreferredNamespacedResources 

func (d *DiscoveryClient) ServerPreferredNamespacedResources() ([]*metav1.APIResourceList, error)

ServerPreferredNamespacedResources returns the supported namespaced resources with the version preferred by the server.

func (*DiscoveryClient) ServerPreferredResources 

func (d *DiscoveryClient) ServerPreferredResources() ([]*metav1.APIResourceList, error)

ServerPreferredResources returns the supported resources with the version preferred by the server.

func (*DiscoveryClient) ServerResourcesForGroupVersion 

func (d *DiscoveryClient) ServerResourcesForGroupVersion(groupVersion string) (resources *metav1.APIResourceList, err error)

ServerResourcesForGroupVersion returns the supported resources for a group and version.

func (*DiscoveryClient) ServerVersion 

func (d *DiscoveryClient) ServerVersion() (*version.Info, error)

ServerVersion retrieves and parses the server's version (git version).

func (*DiscoveryClient) WithLegacy 

func (d *DiscoveryClient) WithLegacy() DiscoveryInterface

WithLegacy returns copy of current discovery client that will only receive the legacy discovery format.

type DiscoveryInterface 

type DiscoveryInterface interface {
	RESTClient() restclient.Interface
	ServerGroupsInterface
	ServerResourcesInterface
	ServerVersionInterface
	OpenAPISchemaInterface
	OpenAPIV3SchemaInterface
	// Returns copy of current discovery client that will only
	// receive the legacy discovery format, or pointer to current
	// discovery client if it does not support legacy-only discovery.
	WithLegacy() DiscoveryInterface
}

DiscoveryInterface holds the methods that discover server-supported API groups, versions and resources.

type ErrGroupDiscoveryFailed 

type ErrGroupDiscoveryFailed struct {
	// Groups is a list of the groups that failed to load and the error cause
	Groups map[schema.GroupVersion]error
}

ErrGroupDiscoveryFailed is returned if one or more API groups fail to load.

func (*ErrGroupDiscoveryFailed) Error 

func (e *ErrGroupDiscoveryFailed) Error() string

Error implements the error interface

func (*ErrGroupDiscoveryFailed) Is 

func (e *ErrGroupDiscoveryFailed) Is(target error) bool

Is makes it possible for the callers to use `errors.Is(` helper on errors wrapped with ErrGroupDiscoveryFailed error.

type OpenAPISchemaInterface 

type OpenAPISchemaInterface interface {
	// OpenAPISchema retrieves and parses the swagger API schema the server supports.
	OpenAPISchema() (*openapi_v2.Document, error)
}

OpenAPISchemaInterface has a method to retrieve the open API schema.

type OpenAPIV3SchemaInterface 

type OpenAPIV3SchemaInterface interface {
	OpenAPIV3() openapi.Client
}

type ResourcePredicate 

type ResourcePredicate interface {
	Match(groupVersion string, r *metav1.APIResource) bool
}

ResourcePredicate has a method to check if a resource matches a given condition.

type ResourcePredicateFunc 

type ResourcePredicateFunc func(groupVersion string, r *metav1.APIResource) bool

ResourcePredicateFunc returns true if it matches a resource based on a custom condition.

func (ResourcePredicateFunc) Match 

func (fn ResourcePredicateFunc) Match(groupVersion string, r *metav1.APIResource) bool

Match is a wrapper around ResourcePredicateFunc.

type ServerGroupsInterface 

type ServerGroupsInterface interface {
	// ServerGroups returns the supported groups, with information like supported versions and the
	// preferred version.
	ServerGroups() (*metav1.APIGroupList, error)
}

ServerGroupsInterface has methods for obtaining supported groups on the API server

type ServerResourcesInterface 

type ServerResourcesInterface interface {
	// ServerResourcesForGroupVersion returns the supported resources for a group and version.
	ServerResourcesForGroupVersion(groupVersion string) (*metav1.APIResourceList, error)
	// ServerGroupsAndResources returns the supported groups and resources for all groups and versions.
	//
	// The returned group and resource lists might be non-nil with partial results even in the
	// case of non-nil error.
	ServerGroupsAndResources() ([]*metav1.APIGroup, []*metav1.APIResourceList, error)
	// ServerPreferredResources returns the supported resources with the version preferred by the
	// server.
	//
	// The returned group and resource lists might be non-nil with partial results even in the
	// case of non-nil error.
	ServerPreferredResources() ([]*metav1.APIResourceList, error)
	// ServerPreferredNamespacedResources returns the supported namespaced resources with the
	// version preferred by the server.
	//
	// The returned resource list might be non-nil with partial results even in the case of
	// non-nil error.
	ServerPreferredNamespacedResources() ([]*metav1.APIResourceList, error)
}

ServerResourcesInterface has methods for obtaining supported resources on the API server

type ServerVersionInterface 

type ServerVersionInterface interface {
	// ServerVersion retrieves and parses the server's version (git version).
	ServerVersion() (*version.Info, error)
}

ServerVersionInterface has a method for retrieving the server's version.

type StaleGroupVersionError 

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

StaleGroupVersionError encasulates failed GroupVersion marked "stale" in the returned AggregatedDiscovery format.

func (StaleGroupVersionError) Error 

func (s StaleGroupVersionError) Error() string

type SupportsAllVerbs 

type SupportsAllVerbs struct {
	Verbs []string
}

SupportsAllVerbs is a predicate matching a resource iff all given verbs are supported.

func (SupportsAllVerbs) Match 

func (p SupportsAllVerbs) Match(groupVersion string, r *metav1.APIResource) bool

Match checks if a resource contains all the given verbs.

Source Files

aggregated_discovery.go discovery_client.go doc.go helper.go

Directories

PathSynopsis
discovery/cached
discovery/cached/disk
discovery/cached/memory
discovery/fake
Version
v0.33.0 (latest)
Published
Apr 23, 2025
Platform
linux/amd64
Imports
26 packages
Last checked
1 hour ago –

Tools for package owners.