cache

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 14, 2026 License: Apache-2.0 Imports: 26 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	IndexSandboxPool      = "sandboxPool"
	IndexClaimedSandboxID = "sandboxID"
	IndexUser             = "user"
	IndexTemplateID       = "templateID"
	IndexCheckpointID     = "checkpointID"
)

Index name constants (consistent with sandboxcr/index.go values)

Functions

func AddIndexesToCache 

func AddIndexesToCache(c ctrlcache.Cache) error

AddIndexesToCache registers all required field indexes on the controller-runtime cache.

func BuildCacheConfig 

func BuildCacheConfig(opts config.SandboxManagerOptions) (map[ctrlclient.Object]ctrlcache.ByObject, error)

BuildCacheConfig creates the informer filter configuration for the cache. It returns a byObject map that configures per-object informer filtering based on resource scope. This configuration is shared between NewControllerManager (production) and NewTestCache (testing) to ensure consistent behavior.

Informer Filter Options

A — Custom resources (sandbox namespace + optional label selector): 

Sandbox, SandboxSet, Checkpoint, SandboxTemplate

B — System namespace resources (requires opts.SystemNamespace to be set): 

Secret, ConfigMap

C — Cluster-scoped resources (no namespace filtering): 

PersistentVolume

func NewControllerManager 

func NewControllerManager(cfg *rest.Config, opts config.SandboxManagerOptions) (ctrl.Manager, error)

NewControllerManager creates a controller-runtime manager configured for the sandbox manager cache. It configures informer filtering based on resource scope and returns a manager that must be passed to NewCache.

Types

type Cache 

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

Cache is a controller-runtime based cache that replaces the legacy informer-based Cache.

func NewCache 

func NewCache(mgr ctrl.Manager) (*Cache, error)

NewCache creates a new Cache instance from a pre-configured controller manager. The metadata must have been returned by NewControllerManager.

func (*Cache) CheckpointUpdateFunc 

func (c *Cache) CheckpointUpdateFunc(ctx context.Context) cacheutils.UpdateFunc[*agentsv1alpha1.Checkpoint]

func (*Cache) GetAPIReader 

func (c *Cache) GetAPIReader() ctrlclient.Reader

func (*Cache) GetCheckpoint 

func (c *Cache) GetCheckpoint(ctx context.Context, opts GetCheckpointOptions) (*agentsv1alpha1.Checkpoint, error)

func (*Cache) GetClaimedSandbox 

func (c *Cache) GetClaimedSandbox(ctx context.Context, opts GetClaimedSandboxOptions) (*agentsv1alpha1.Sandbox, error)

func (*Cache) GetClient 

func (c *Cache) GetClient() ctrlclient.Client

func (*Cache) GetMockManager 

func (c *Cache) GetMockManager() *controllers.MockManager

GetMockManager extracts the MockManager from a Cache created by NewTestCache. This is only intended for test use.

func (*Cache) GetSandboxController 

func (c *Cache) GetSandboxController() *controllers.CacheSandboxCustomReconciler

GetSandboxController returns the sandbox custom reconciler for external handler registration.

func (*Cache) GetSandboxSetController 

func (c *Cache) GetSandboxSetController() *controllers.CacheSandboxSetCustomReconciler

GetSandboxSetController returns the sandboxset custom reconciler for external handler registration.

func (*Cache) GetWaitHooks 

func (c *Cache) GetWaitHooks() *sync.Map

GetWaitHooks returns the internal waitHooks map used for wait simulation. This is only intended for test infrastructure use.

func (*Cache) ListCheckpoints 

func (c *Cache) ListCheckpoints(ctx context.Context, opts ListCheckpointsOptions) ([]*agentsv1alpha1.Checkpoint, error)

func (*Cache) ListSandboxSets 

func (c *Cache) ListSandboxSets(ctx context.Context, opts ListSandboxSetsOptions) ([]*agentsv1alpha1.SandboxSet, error)

func (*Cache) ListSandboxes 

func (c *Cache) ListSandboxes(ctx context.Context, opts ListSandboxesOptions) ([]*agentsv1alpha1.Sandbox, error)

func (*Cache) ListSandboxesInPool 

func (c *Cache) ListSandboxesInPool(ctx context.Context, opts ListSandboxesInPoolOptions) ([]*agentsv1alpha1.Sandbox, error)

func (*Cache) NewCheckpointTask 

func (c *Cache) NewCheckpointTask(ctx context.Context, cp *agentsv1alpha1.Checkpoint) *cacheutils.WaitTask[*agentsv1alpha1.Checkpoint]

NewCheckpointTask builds a WaitTask that succeeds when the checkpoint's Status.Phase transitions to CheckpointSucceeded; returns error on Terminating / Failed.

func (*Cache) NewSandboxPauseTask 

func (c *Cache) NewSandboxPauseTask(ctx context.Context, sbx *agentsv1alpha1.Sandbox) (*cacheutils.WaitTask[*agentsv1alpha1.Sandbox], error)

NewSandboxPauseTask builds a pre-acquired WaitTask that succeeds when the sandbox reports status.conditions[type=Paused].status == True.

Pause is pre-acquired because it protects the caller-side spec.paused mutation from racing with an opposite Resume wait. WaitReady and Checkpoint stay lazy because they do not protect caller-side target-state mutation.

func (*Cache) NewSandboxResumeTask 

func (c *Cache) NewSandboxResumeTask(ctx context.Context, sbx *agentsv1alpha1.Sandbox) (*cacheutils.WaitTask[*agentsv1alpha1.Sandbox], error)

NewSandboxResumeTask builds a pre-acquired WaitTask that succeeds when the sandbox Ready condition is True.

Resume is pre-acquired because it protects the caller-side spec.paused mutation from racing with an opposite Pause wait. WaitReady and Checkpoint stay lazy because they do not protect caller-side target-state mutation.

func (*Cache) NewSandboxWaitReadyTask 

func (c *Cache) NewSandboxWaitReadyTask(ctx context.Context, sbx *agentsv1alpha1.Sandbox) *cacheutils.WaitTask[*agentsv1alpha1.Sandbox]

NewSandboxWaitReadyTask builds a WaitTask that encapsulates the readiness check

func (*Cache) PickSandboxSet 

func (c *Cache) PickSandboxSet(ctx context.Context, opts PickSandboxSetOptions) (*agentsv1alpha1.SandboxSet, error)

func (*Cache) Run 

func (c *Cache) Run(ctx context.Context) error

Run starts the controller manager and waits for cache sync.

func (*Cache) SandboxUpdateFunc 

func (c *Cache) SandboxUpdateFunc(ctx context.Context) cacheutils.UpdateFunc[*agentsv1alpha1.Sandbox]

func (*Cache) Stop 

func (c *Cache) Stop(ctx context.Context)

Stop shuts down the controller manager.

type GetCheckpointOptions 

type GetCheckpointOptions struct {
	Namespace    string
	CheckpointID string
}

type GetClaimedSandboxOptions 

type GetClaimedSandboxOptions struct {
	Namespace string
	SandboxID string
}

type IndexFunc 

type IndexFunc struct {
	Obj       client.Object
	FieldName string
	Extract   func(obj client.Object) []string
}

IndexFunc defines a field index function for a specific resource type.

func GetIndexFuncs 

func GetIndexFuncs() []IndexFunc

GetIndexFuncs returns all field index functions used by the cache. This is the single source of truth for index definitions, shared between AddIndexesToCache (production) and NewTestCache (testing).

type ListCheckpointsOptions 

type ListCheckpointsOptions struct {
	Namespace string
	User      string
}

type ListSandboxSetsOptions 

type ListSandboxSetsOptions struct {
	Namespace string
}

type ListSandboxesInPoolOptions 

type ListSandboxesInPoolOptions struct {
	Namespace string
	Pool      string
}

type ListSandboxesOptions 

type ListSandboxesOptions struct {
	Namespace string
	User      string
}

type PickSandboxSetOptions 

type PickSandboxSetOptions struct {
	Namespace string
	Name      string
}

type Provider 

type Provider interface {
	GetClaimedSandbox(ctx context.Context, opts GetClaimedSandboxOptions) (*agentsv1alpha1.Sandbox, error)

	GetCheckpoint(ctx context.Context, opts GetCheckpointOptions) (*agentsv1alpha1.Checkpoint, error)

	PickSandboxSet(ctx context.Context, opts PickSandboxSetOptions) (*agentsv1alpha1.SandboxSet, error)

	ListSandboxSets(ctx context.Context, opts ListSandboxSetsOptions) ([]*agentsv1alpha1.SandboxSet, error)

	// ListSandboxes returns Sandbox CRD objects filtered by namespace and optional owner.
	// Ownership is determined by the AnnotationOwner annotation on the Sandbox resource when User is set.
	ListSandboxes(ctx context.Context, opts ListSandboxesOptions) ([]*agentsv1alpha1.Sandbox, error)

	// ListCheckpoints returns Checkpoint CRD objects filtered by namespace and optional owner.
	// Ownership is determined by the AnnotationOwner annotation on the Checkpoint resource when User is set.
	ListCheckpoints(ctx context.Context, opts ListCheckpointsOptions) ([]*agentsv1alpha1.Checkpoint, error)

	ListSandboxesInPool(ctx context.Context, opts ListSandboxesInPoolOptions) ([]*agentsv1alpha1.Sandbox, error)

	// NewSandboxPauseTask builds an immutable wait task encapsulating the Pause
	// readiness check and pre-acquires its wait hook before callers mutate
	// spec.paused. Call Release if Wait will not be reached; deferring Release
	// after successful construction is safe. Wait releases the acquired hook
	// when it returns.
	NewSandboxPauseTask(ctx context.Context, sbx *agentsv1alpha1.Sandbox) (*cacheutils.WaitTask[*agentsv1alpha1.Sandbox], error)

	// NewSandboxResumeTask builds an immutable wait task for Resume. The task
	// pre-acquires its wait hook before callers mutate spec.paused and succeeds
	// when the Ready condition is True. Call Release if Wait will not be reached;
	// deferring Release after successful construction is safe. Wait releases the
	// acquired hook when it returns.
	NewSandboxResumeTask(ctx context.Context, sbx *agentsv1alpha1.Sandbox) (*cacheutils.WaitTask[*agentsv1alpha1.Sandbox], error)

	// NewSandboxWaitReadyTask builds an immutable wait task for post-claim
	// readiness (Generation observed + Ready condition not StartContainerFailed
	// + not InplaceUpdating + Running + PodIP set).
	NewSandboxWaitReadyTask(ctx context.Context, sbx *agentsv1alpha1.Sandbox) *cacheutils.WaitTask[*agentsv1alpha1.Sandbox]

	// NewCheckpointTask builds an immutable wait task for a Checkpoint that
	// succeeds when Status.Phase == CheckpointSucceeded (with non-empty
	// CheckpointId); fails on Terminating/Failed.
	NewCheckpointTask(ctx context.Context, cp *agentsv1alpha1.Checkpoint) *cacheutils.WaitTask[*agentsv1alpha1.Checkpoint]

	// Run starts an owned manager and waits for cache sync.
	// Do not call Run for a cache backed by an externally owned manager.
	Run(ctx context.Context) error

	// Stop shuts down all underlying informers and releases associated resources.
	// After Stop returns, no further cache lookups or wait operations should be performed.
	Stop(ctx context.Context)

	// GetClient returns the underlying controller-runtime client.Client for direct
	// Kubernetes API operations. This should be used sparingly, preferring the
	// cache-backed methods above for read operations to avoid API server load.
	// The returned client is the same instance used internally by the Provider.
	GetClient() client.Client

	// GetAPIReader returns a client.Reader that bypasses the cache and reads
	// directly from the API server. Use this when you need the latest state
	// and can tolerate the additional latency of an API server round-trip.
	// Prefer GetClient() for most operations; use this only when cache staleness
	// is unacceptable (e.g., validating critical state transitions).
	GetAPIReader() client.Reader
}

Provider is a read-through, informer-backed local cache for all Kubernetes resources used by the sandbox manager. It provides low-latency lookups without hitting the API server on every request, and exposes async-wait primitives so callers can block until a resource reaches a desired state (e.g., sandbox becomes Running after Resume).

All Get/List methods read exclusively from the in-process informer store; they never issue live API calls. The underlying manager cache must be synced before any other method is used. Call Run for a Cache with an owned manager. When a Cache reuses another operator's manager, do not call Run; the owner manager starts and syncs the cache during manager.Start.

Source Files

View all Source files

Directories

Path Synopsis
Package cachetest provides test utilities for constructing Cache instances with a fake client.
 Package cachetest provides test utilities for constructing Cache instances with a fake client.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.