discovery

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
  • func (c *ClusterQuery) Execute() (bool, error)
  • func (c *ClusterQuery) Prepare() func() (bool, error)
  • func (c *ClusterQuery) Results() Results
• 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)
  • func (c *ClusterQueryClient) PreparedQuery(targets ...QueryTarget) func() (bool, error)
  • func (c *ClusterQueryClient) Query(targets ...QueryTarget) *ClusterQuery
• type QueryFailure
• type QueryGVR
  • func Group(queryName, group string) *QueryGVR
  • func (q *QueryGVR) Name() string
  • func (q *QueryGVR) Reason() string
  • func (q *QueryGVR) Run(config *clusterQueryClientConfig) (bool, error)
  • func (q *QueryGVR) WithResource(resource string) *QueryGVR
  • func (q *QueryGVR) WithVersions(versions ...string) *QueryGVR
• type QueryObject
  • func Object(queryName string, obj *corev1.ObjectReference) *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
  • func Schema(name, partialSchema string) *QueryPartialSchema
  • func (q *QueryPartialSchema) Name() string
  • func (q *QueryPartialSchema) Reason() string
  • func (q *QueryPartialSchema) Run(config *clusterQueryClientConfig) (bool, error)
• type QueryResult
• type QueryTarget
• type Results
  • func (r Results) ForQuery(queryName string) *QueryResult

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 Group

func Group(queryName, group string) *QueryGVR

Group represents any API group that may exist on a cluster.

func (*QueryGVR) Name

func (q *QueryGVR) Name() string

Name returns the name of the query.

func (*QueryGVR) Reason

func (q *QueryGVR) Reason() string

Reason surfaces what didn't match.

func (*QueryGVR) Run

func (q *QueryGVR) Run(config *clusterQueryClientConfig) (bool, error)

Run discovery.

func (*QueryGVR) WithResource

func (q *QueryGVR) WithResource(resource string) *QueryGVR

WithResource checks if an API group with the specified resource exists. This method can be omitted to query any resource.

func (*QueryGVR) WithVersions

func (q *QueryGVR) WithVersions(versions ...string) *QueryGVR

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

func (q *QueryObject) Name() string

Name is the name of the query.

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.