README
¶
Kubernetes Query Builder SDK
The discovery SDK provides means to prepare and query for the state of a clusters objects, schema and API resources to determine the details about a cluster and how best to interact with it.
The longer term goal is to also become the most query and resource efficient means of doing so, perhaps with some limited caching ability.
The Query Builder SDK can query for:
- Objects
- Annotation
- Labels
- Conditions
- Resources
- WithFields
- OpenAPI Schema
Once created, these prepared queries can be exported and used whenever necessary .
Example
// Define some standard objects, GVRs or schema
var ns = corev1.ObjectReference{
Kind: "namespace",
Name: "ian",
Namespace: "ian",
}
// Its important to our use case for this annotation to also match
var testAnnotations = map[string]string{
"cluster.x-k8s.io/provider": "infrastructure-fake",
}
// We want to ensure this version of pipelines exists, perhaps with specific fields
var testGVR = schema.GroupVersionResource{
Group: "tekton.dev",
Version: "v1beta1",
Resource: "pipelines",
}
// We will now generate a partial query to match our specific namespace
var testResource1 = Object(ns).WithAnnotations(testAnnotations).WithConditions([C])
// Our usecase requires us to match a specific GVR
var testGVR1 = GVR(testGVR).WithFields([field])
// This partial schema is importan to be available - it doesnt matter what GVR provides it, but the schema needs to be available.
var testSchema1 = PartialSchema(schema).NotExist()
c, err := NewClusterQueryClient()
if err != nil {
return err
}
// Build your query and use it where its necessary
OurCoolQuery := c.Query(testResource1, testGVR1, testSchema1).Prepare()
ok, err := OurCoolQuery()
if err != nil {
return err
}
if ok {
log.Log("W00T")
}
Documentation
¶
Overview ¶
Package discovery provides efficient means to query Kubernetes clusters for the state of its api surface and existing objects
Index ¶
- func QueryTargetsToCapabilityResource(queryTargets []QueryTarget) (*runv1alpha1.Capability, error)
- type ClusterQuery
- type ClusterQueryClient
- func NewClusterQueryClient(dynamicClient dynamic.Interface, discoveryClient discovery.DiscoveryInterface) (*ClusterQueryClient, error)
- func NewClusterQueryClientForConfig(config *rest.Config) (*ClusterQueryClient, error)
- func NewFakeClusterQueryClient(resources []*metav1.APIResourceList, scheme *runtime.Scheme, ...) (*ClusterQueryClient, error)
- type QueryFailure
- type QueryGVR
- type QueryObject
- func (q *QueryObject) Name() string
- func (q *QueryObject) QueryObjectExists(resources []*restmapper.APIGroupResources, config *clusterQueryClientConfig) (bool, error)
- func (q *QueryObject) Reason() string
- func (q *QueryObject) Run(config *clusterQueryClientConfig) (bool, error)
- func (q *QueryObject) WithAnnotations(a map[string]string) *QueryObject
- func (q *QueryObject) WithoutAnnotations(a map[string]string) *QueryObject
- type QueryPartialSchema
- type QueryResult
- type QueryTarget
- type Results
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func QueryTargetsToCapabilityResource ¶
func QueryTargetsToCapabilityResource(queryTargets []QueryTarget) (*runv1alpha1.Capability, error)
QueryTargetsToCapabilityResource is a helper function to generate a Capability v1alpha1 resource from a slice of QueryTarget.
Types ¶
type ClusterQuery ¶
type ClusterQuery struct {
// contains filtered or unexported fields
}
ClusterQuery provides a means of executing a queries targets to determine results
func (*ClusterQuery) Execute ¶
func (c *ClusterQuery) Execute() (bool, error)
Execute runs all the query targets and returns true only if *all* of them succeed. For granular results of each query, use the Results() method after calling this method. Normally this function is returned by Prepare() and stored as a constant to re-use
func (*ClusterQuery) Prepare ¶
func (c *ClusterQuery) Prepare() func() (bool, error)
Prepare queries for the discovery API on the resources, GVKs and/or partial schema a cluster has.
func (*ClusterQuery) Results ¶
func (c *ClusterQuery) Results() Results
Results returns all of the queries failures
type ClusterQueryClient ¶
type ClusterQueryClient struct {
// contains filtered or unexported fields
}
ClusterQueryClient allows clients to inspect the cluster objects, GVK and schema state of a cluster
func NewClusterQueryClient ¶
func NewClusterQueryClient(dynamicClient dynamic.Interface, discoveryClient discovery.DiscoveryInterface) (*ClusterQueryClient, error)
NewClusterQueryClient returns a new cluster query builder
func NewClusterQueryClientForConfig ¶
func NewClusterQueryClientForConfig(config *rest.Config) (*ClusterQueryClient, error)
NewClusterQueryClientForConfig returns a new cluster query builder for a REST config.
func NewFakeClusterQueryClient ¶
func NewFakeClusterQueryClient(resources []*metav1.APIResourceList, scheme *runtime.Scheme, objs []runtime.Object) (*ClusterQueryClient, error)
NewFakeClusterQueryClient returns a fake ClusterQueryClient for use in tests.
func (*ClusterQueryClient) PreparedQuery ¶
func (c *ClusterQueryClient) PreparedQuery(targets ...QueryTarget) func() (bool, error)
PreparedQuery provides a prepared object
func (*ClusterQueryClient) Query ¶
func (c *ClusterQueryClient) Query(targets ...QueryTarget) *ClusterQuery
Query provides a new query object to prepare
type QueryFailure ¶
type QueryFailure struct { Target QueryTarget Presence bool }
QueryFailure exposes detail on the query failure for consumers to parse
type QueryGVR ¶
type QueryGVR struct {
// contains filtered or unexported fields
}
QueryGVR provides insight to the clusters GVRs
func (*QueryGVR) WithResource ¶
WithResource checks if an API group with the specified resource exists. This method can be omitted to query any resource.
func (*QueryGVR) WithVersions ¶
WithVersions checks if an API group with all the specified versions exist. This method can be omitted to query any version.
type QueryObject ¶
type QueryObject struct {
// contains filtered or unexported fields
}
QueryObject allows for resource querying
func Object ¶
func Object(queryName string, obj *corev1.ObjectReference) *QueryObject
Object represents any runtime.Object that could exist on a cluster, with ability to specify: WithAnnotations() WithLabels() WithConditions()
func (*QueryObject) QueryObjectExists ¶
func (q *QueryObject) QueryObjectExists(resources []*restmapper.APIGroupResources, config *clusterQueryClientConfig) (bool, error)
QueryObjectExists uses dynamic and unstructured APIs to reason about object state
func (*QueryObject) Reason ¶
func (q *QueryObject) Reason() string
Reason for failures, in a standard structure
func (*QueryObject) Run ¶
func (q *QueryObject) Run(config *clusterQueryClientConfig) (bool, error)
Run the object discovery
func (*QueryObject) WithAnnotations ¶
func (q *QueryObject) WithAnnotations(a map[string]string) *QueryObject
WithAnnotations matches annotations on a resource
func (*QueryObject) WithoutAnnotations ¶
func (q *QueryObject) WithoutAnnotations(a map[string]string) *QueryObject
WithoutAnnotations ensures lack of presence annotations on a resource
type QueryPartialSchema ¶
type QueryPartialSchema struct {
// contains filtered or unexported fields
}
QueryPartialSchema allows for matching a partial schema currently this is quite naive string comparison but will be updated fpr better validation
func Schema ¶
func Schema(name, partialSchema string) *QueryPartialSchema
Schema represents any openapi schema that may exist on a cluster
func (*QueryPartialSchema) Name ¶
func (q *QueryPartialSchema) Name() string
Name is the name of the query.
func (*QueryPartialSchema) Reason ¶
func (q *QueryPartialSchema) Reason() string
Reason returns the query failure, of it failed todo: this should be a results{} struct
func (*QueryPartialSchema) Run ¶
func (q *QueryPartialSchema) Run(config *clusterQueryClientConfig) (bool, error)
Run the partial query match
type QueryResult ¶
type QueryResult struct { // Found indicates whether the entity being checked in the query exists. Found bool // NotFoundReason indicates the reason why Found was false. NotFoundReason string }
QueryResult is a result of a single query.
type QueryTarget ¶
type QueryTarget interface { Name() string Run(config *clusterQueryClientConfig) (bool, error) Reason() string }
QueryTarget implementations: Resource, GVK, Schema
type Results ¶
type Results map[string]*QueryResult
Results is a map of query names to their corresponding QueryResult.
func (Results) ForQuery ¶
func (r Results) ForQuery(queryName string) *QueryResult
ForQuery returns the QueryResult for a given query name. Return value is nil if the query target with the given name does not exist.