kclient

Documentation

Index

• func CreateOrUpdate[T controllers.Object](c Writer[T], object T) (T, error)
• func ToOpts(c kube.Client, gvr schema.GroupVersionResource, filter Filter) kubetypes.InformerOptions
• type Client
  • func New[T controllers.ComparableObject](c kube.Client) Client[T]
  • func NewFiltered[T controllers.ComparableObject](c kube.Client, filter Filter) Client[T]
• type EventRecorder
  • func NewEventRecorder(client kube.Client, component string) EventRecorder
  • func (e *EventRecorder) Shutdown()
  • func (e *EventRecorder) Write(object runtime.Object, eventtype, reason, messageFmt string, ...)
• type Filter
• type Index
  • func CreateIndex[K fmt.Stringer, O controllers.ComparableObject](client Informer[O], extract func(o O) []K) Index[K, O]
  • func CreateStringIndex[O controllers.ComparableObject](client Informer[O], extract func(o O) []string) Index[string, O]
• type Informer
  • func NewDelayedInformer[T controllers.ComparableObject](c kube.Client, gvr schema.GroupVersionResource, ...) Informer[T]
  • func NewMetadata(c kube.Client, gvr schema.GroupVersionResource, filter Filter) Informer[*metav1.PartialObjectMetadata]
• type Patcher
  • func ToPatcher[T controllers.Object](w Writer[T]) Patcher
• type RawIndexer
• type ReadWriter
• type Reader
• type Untyped
  • func NewDynamic(c kube.Client, gvr schema.GroupVersionResource, filter Filter) Untyped
  • func NewUntypedInformer(c kube.Client, gvr schema.GroupVersionResource, filter Filter) Untyped
• type Writer
  • func NewWriteClient[T controllers.ComparableObject](c kube.Client) Writer[T]

Functions

func CreateOrUpdate

func CreateOrUpdate[T controllers.Object](c Writer[T], object T) (T, error)

func ToOpts

func ToOpts(c kube.Client, gvr schema.GroupVersionResource, filter Filter) kubetypes.InformerOptions

Types

type Client

type Client[T controllers.Object] interface {
	Reader[T]
	Writer[T]
	Informer[T]
}

Client wraps a Kubernetes client providing cached read access and direct write access.

func New

func New[T controllers.ComparableObject](c kube.Client) Client[T]

New returns a Client for the given type. Internally, this uses a shared informer, so calling this multiple times will share the same internals.

func NewFiltered

func NewFiltered[T controllers.ComparableObject](c kube.Client, filter Filter) Client[T]

NewFiltered returns a Client with some filter applied. Internally, this uses a shared informer, so calling this multiple times will share the same internals. This is keyed on unique {Type,LabelSelector,FieldSelector}.

Warning: if conflicting filter.ObjectTransform are used for the same key, the first one registered wins. This means there must only be one filter configuration for a given type using the same kube.Client. Use with caution.

type EventRecorder

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

func NewEventRecorder

func NewEventRecorder(client kube.Client, component string) EventRecorder

NewEventRecorder creates a new EventRecorder. This should be shutdown after usage.

func (*EventRecorder) Shutdown

func (e *EventRecorder) Shutdown()

Shutdown terminates the event recorder. This must be called upon completion of writing events, and events should not be written once terminated.

func (*EventRecorder) Write

func (e *EventRecorder) Write(object runtime.Object, eventtype, reason, messageFmt string, args ...interface{})

Write creates a single event.

type Filter

type Filter = kubetypes.Filter

Filter allows filtering read operations. This is aliased to allow easier access when constructing clients.

type Index

type Index[K any, O controllers.ComparableObject] interface {
	Lookup(k K) []O
}

func CreateIndex

func CreateIndex[K fmt.Stringer, O controllers.ComparableObject](
	client Informer[O],
	extract func(o O) []K,
) Index[K, O]

CreateIndex creates a simple index, keyed by key K, over an informer for O. This is similar to Informer.AddIndex, but is easier to use and can be added after an informer has already started. Keys can be any object, but they must encode down to a *unique* value with String().

func CreateStringIndex

func CreateStringIndex[O controllers.ComparableObject](
	client Informer[O],
	extract func(o O) []string,
) Index[string, O]

CreateStringIndex creates a simple index, keyed by a string, over an informer for O. This is similar to Informer.AddIndex, but is easier to use and can be added after an informer has already started. This is split from CreateIndex because string does not implement fmt.Stringer.

type Informer

type Informer[T controllers.Object] interface {
	Reader[T]
	// ListUnfiltered is like List but ignores any *client side* filters previously configured.
	ListUnfiltered(namespace string, selector klabels.Selector) []T
	// AddEventHandler inserts a handler. The handler will be called for all Create/Update/Removals.
	// When ShutdownHandlers is called, the handler is removed.
	AddEventHandler(h cache.ResourceEventHandler)
	// HasSynced returns true when the informer is initially populated and that all handlers added
	// via AddEventHandler have been called with the initial state.
	// note: this differs from a standard informer HasSynced, which does not check handlers have been called.
	HasSynced() bool
	// ShutdownHandlers terminates all handlers added by AddEventHandler.
	// Warning: this only applies to handlers called via AddEventHandler; any handlers directly added
	// to the underlying informer are not touched
	ShutdownHandlers()
	// Start starts just this informer. Typically, this is not used. Instead, the `kube.Client.Run()` is
	// used to start all informers at once.
	// However, in some cases we need to run individual informers directly.
	// This function should only be called once. It does not wait for the informer to become ready nor does it block,
	// so it should generally not be called in a goroutine.
	Start(stop <-chan struct{})
	// Index creates an index. The extract function takes an object, and returns all keys to that object.
	// Later, all objects with a given key can be looked up.
	// It is strongly recommended to use the typed variants of this with NewIndex; this is needed to workaround Go type limitations.
	Index(extract func(o T) []string) RawIndexer
}

func NewDelayedInformer

func NewDelayedInformer[T controllers.ComparableObject](
	c kube.Client,
	gvr schema.GroupVersionResource,
	informerType kubetypes.InformerType,
	filter Filter,
) Informer[T]

NewDelayedInformer returns a "delayed" client for the given GVR. This is read-only. A delayed client is used for CRD watches when the CRD may or may not exist. When the CRD is not present, the client will return empty results for all operations and watch for the CRD creation. Once created, watchers will be started and read operations will begin returning results. HasSynced will only return true if the CRD was not present upon creation OR the watch is fully synced. This ensures the creation is fully consistent if the CRD was present during creation; otherwise it is eventually consistent.

func NewMetadata

func NewMetadata(c kube.Client, gvr schema.GroupVersionResource, filter Filter) Informer[*metav1.PartialObjectMetadata]

NewMetadata returns a metadata client for a given GVR. This is read-only.

type Patcher

type Patcher interface {
	// Patch patches the resource, returning the newly applied resource.
	Patch(name, namespace string, pt apitypes.PatchType, data []byte) error
	// PatchStatus patches the resource's status, returning the newly applied resource.
	PatchStatus(name, namespace string, pt apitypes.PatchType, data []byte) error
	// ApplyStatus does a server-side Apply of the the resource's status, returning the newly applied resource.
	// fieldManager is a required field; see https://kubernetes.io/docs/reference/using-api/server-side-apply/#managers.
	ApplyStatus(name, namespace string, pt apitypes.PatchType, data []byte, fieldManager string) error
}

Patcher is a type-erased writer that can be used for patching

func ToPatcher

func ToPatcher[T controllers.Object](w Writer[T]) Patcher

type RawIndexer

type RawIndexer interface {
	Lookup(key string) []any
}

RawIndexer is an internal-ish interface for indexes. Strongly recommended to use NewIndex.

type ReadWriter

type ReadWriter[T controllers.Object] interface {
	Reader[T]
	Writer[T]
}

type Reader

type Reader[T controllers.Object] interface {
	// Get looks up an object by name and namespace. If it does not exist, nil is returned
	Get(name, namespace string) T
	// List looks up an object by namespace and labels.
	// Use metav1.NamespaceAll and klabels.Everything() to select everything.
	List(namespace string, selector klabels.Selector) []T
}

Reader wraps a Kubernetes client providing cached read access. This is based on informers, so most of the same caveats to informers apply here.

type Untyped

type Untyped = Informer[controllers.Object]

func NewDynamic

func NewDynamic(c kube.Client, gvr schema.GroupVersionResource, filter Filter) Untyped

NewDynamic returns a dynamic client for a given GVR. This is read-only.

func NewUntypedInformer

func NewUntypedInformer(c kube.Client, gvr schema.GroupVersionResource, filter Filter) Untyped

NewUntypedInformer returns an untyped client for a given GVR. This is read-only.

type Writer

type Writer[T controllers.Object] interface {
	// Create creates a resource, returning the newly applied resource.
	Create(object T) (T, error)
	// Update updates a resource, returning the newly applied resource.
	Update(object T) (T, error)
	// UpdateStatus updates a resource's status, returning the newly applied resource.
	UpdateStatus(object T) (T, error)
	// Patch patches the resource, returning the newly applied resource.
	Patch(name, namespace string, pt apitypes.PatchType, data []byte) (T, error)
	// PatchStatus patches the resource's status, returning the newly applied resource.
	PatchStatus(name, namespace string, pt apitypes.PatchType, data []byte) (T, error)
	// ApplyStatus does a server-side Apply of the the resource's status, returning the newly applied resource.
	// fieldManager is a required field; see https://kubernetes.io/docs/reference/using-api/server-side-apply/#managers.
	ApplyStatus(name, namespace string, pt apitypes.PatchType, data []byte, fieldManager string) (T, error)
	// Delete removes a resource.
	Delete(name, namespace string) error
}

func NewWriteClient

func NewWriteClient[T controllers.ComparableObject](c kube.Client) Writer[T]

NewWriteClient is exposed for testing.