apiserverstore

Documentation

Overview

Package apiserverstore stores resources using the Kubernetes API Server - using CRDs as a key-value store. We don't represent UCP data directly as Kubernetes resources because that would require the creation of many types. The complex hierarchies of data that are possible for UCP aren't a good fit for Kubernetes data model.

Our strategy is to use the resource name and hash of the object name in order to derive a *likely*-unique kubernetes object name. Then we affix labels to the object that match its scopes so we can easily author queries.

Since this scheme allows collisions we need to use optimistic concurrency controls when writing and consider the possibility of multiple resources being present when reading.

Each Kubernetes Resource object stores a list of UCP resources. Since we use SHA1 to generate hashes, we expect collisions to be extremely rare. The only case we need to be concerned about is when collisions cause the total size of the Kubernetes Resource object to be larger than the 8mb limit of Kubernetes.

This scheme allows us to perform O(1) reads and writes for key-based lookups while still handling collisions.

The kubernetes resource names we use are built according to the following format:

<resource name>.<id hash>

We also use a labeling scheme to attach each root scope segment and the resource type as a label to the Kubernetes objects. This allows us to filter the number of objects we transact with using the labels as hints.

Index

• Constants
• type APIServerClient
  • func NewAPIServerClient(client runtimeclient.Client, namespace string) *APIServerClient
  • func (c *APIServerClient) Delete(ctx context.Context, id string, options ...store.DeleteOptions) error
  • func (c *APIServerClient) Get(ctx context.Context, id string, options ...store.GetOptions) (*store.Object, error)
  • func (c *APIServerClient) Query(ctx context.Context, query store.Query, options ...store.QueryOptions) (*store.ObjectQueryResult, error)
  • func (c *APIServerClient) Save(ctx context.Context, obj *store.Object, options ...store.SaveOptions) error

Constants

const (
	// LabelKind is used to determine whether an object holds scopes or resources. Conflicts are not possible due to the way we do naming.
	// Each Kubernetes object holds only scopes or only resources.
	LabelKind = "ucp.dev/kind"

	// LabelScopeFormat is used format a label that describes the scope. The placeholder is replaced by the scope type (eg: resourceGroup).
	LabelScopeFormat = "ucp.dev/scope-%s"

	// LabelResourceType is used as the key of a label describing the resource type.
	LabelResourceType = "ucp.dev/resource-type"

	// LabelValueMultiple is used as the label value when a resource matches multiple scopes or types due to
	// hash collision.
	LabelValueMultiple = "m_u_l_t_i_p_l_e"

	// RetryCount is the number of retries we will make on optimistic concurrency failures. The need for retries is **rare** because
	// it only happens on concurrent operations to the same UCP resource or on a hash collision.
	RetryCount = 10
)

Types

type APIServerClient

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

func NewAPIServerClient

func NewAPIServerClient(client runtimeclient.Client, namespace string) *APIServerClient

NewAPIServerClient creates a new APIServerClient object which is used to interact with the API server.

func (*APIServerClient) Delete

func (c *APIServerClient) Delete(ctx context.Context, id string, options ...store.DeleteOptions) error

Delete deletes a resource from the store, returning an error if the resource does not exist or if there is a concurrency conflict.

func (*APIServerClient) Get

func (c *APIServerClient) Get(ctx context.Context, id string, options ...store.GetOptions) (*store.Object, error)

Get retrieves an object from the store given its ID, or returns an error if the object does not exist or if an error occurs.

func (*APIServerClient) Query

func (c *APIServerClient) Query(ctx context.Context, query store.Query, options ...store.QueryOptions) (*store.ObjectQueryResult, error)

Query searches for objects in the store that match the given query and returns them.

func (*APIServerClient) Save

func (c *APIServerClient) Save(ctx context.Context, obj *store.Object, options ...store.SaveOptions) error

Save saves an object to the store, or updates an existing object if it already exists, and returns an error if the operation fails.