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

• type ClusterQuery
  • func (c *ClusterQuery) Execute() (bool, error)
  • func (c *ClusterQuery) Prepare() func() (bool, error)
  • func (c *ClusterQuery) QueryFailures() []string
• 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(group string) *QueryGVR
  • 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(obj *corev1.ObjectReference) *QueryObject
  • 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) Reason() string
  • func (q *QueryPartialSchema) Run(config *clusterQueryClientConfig) (bool, error)
• type 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 actually executes the function 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) QueryFailures

func (c *ClusterQuery) QueryFailures() []string

QueryFailures 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(group string) *QueryGVR

Group represents any API group that may exist on a cluster, with ability to specify versions and resource to check for GVR.

func (*QueryGVR) Reason

func (q *QueryGVR) Reason() string

Reason surfaces what didnt 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. WithVersions needs to be used before calling this function.

func (*QueryGVR) WithVersions

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

WithVersions checks if an API group with all the specified versions exist.

type QueryObject

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

QueryObject allows for resource querying

func Object

func Object(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) 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 QueryTarget

type QueryTarget interface {
	Run(config *clusterQueryClientConfig) (bool, error)
	Reason() string
}

QueryTarget implementations: Resource, GVK, Schema