cache

package
v0.5.0 Latest Latest
Warning

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

Go to latest
Published: Nov 7, 2026 License: Apache-2.0 Imports: 30 Imported by: 0

Documentation

Overview

Package cache keeps a shared, read-only informer cache of the kinds the UI watches and exposes it as immutable snapshots.

Index

Constants

View Source
const (
	BundleVersionAnnotation = "gateway.networking.k8s.io/bundle-version"
	ChannelAnnotation       = "gateway.networking.k8s.io/channel"
)

Annotations the Gateway API bundle sets on each of its CRDs.

View Source
const (
	// MaxEvents is how many Events the cache keeps; the oldest go first.
	MaxEvents = 10000
	// EventWindow is how long an observed count increase stays in Snapshot.EventDeltas.
	EventWindow = 15 * time.Minute
)
View Source
const ListTimeout = time.Minute

ListTimeout bounds every List call an informer makes, so a hung list ends as a recorded failure instead of keeping old evidence alive.

Variables

View Source
var (
	NamespacesGVR  = schema.GroupVersionResource{Version: "v1", Resource: "namespaces"}
	PodsGVR        = schema.GroupVersionResource{Version: "v1", Resource: "pods"}
	DeploymentsGVR = schema.GroupVersionResource{Group: "apps", Version: "v1", Resource: "deployments"}
	// ProxyPodsGVR keys the proxy Pod watch, apart from the controller Pods' PodsGVR.
	ProxyPodsGVR = schema.GroupVersionResource{Version: "v1", Resource: "pods#proxy"}
)

GVRs under which the typed informers report their Access.

View Source
var (
	ServicesGVR       = schema.GroupVersionResource{Version: "v1", Resource: "services"}
	EndpointSlicesGVR = schema.GroupVersionResource{Group: "discovery.k8s.io", Version: "v1", Resource: "endpointslices"}
)

Access keys of the Service and EndpointSlice watches.

View Source
var (
	ServicesKind       = objects.GroupKind{Kind: "Service"}
	EndpointSlicesKind = objects.GroupKind{Group: "discovery.k8s.io", Kind: "EndpointSlice"}
)

The kinds a check declares in its InputSet to read Snapshot.Services and Snapshot.EndpointSlices.

View Source
var CRDsGVR = schema.GroupVersionResource{Group: "apiextensions.k8s.io", Version: "v1", Resource: "customresourcedefinitions"}

CRDsGVR is the Access key of the Gateway API CRD metadata watch.

View Source
var CRDsKind = objects.GroupKind{Group: "apiextensions.k8s.io", Kind: "CustomResourceDefinition"}

CRDsKind is the kind a check declares in its InputSet to read Snapshot.CRDs.

View Source
var EventsGVR = schema.GroupVersionResource{Version: "v1", Resource: "events"}

EventsGVR is the Access key of the Warning Events watch.

View Source
var EventsKind = objects.GroupKind{Kind: "Event"}

EventsKind is the kind a check declares in its InputSet to read Snapshot.Events, EventDeltas, EventHistoryUnknown and EventsCapped.

View Source
var ProxyPodsKind = objects.GroupKind{Kind: "Pod#proxy"}

ProxyPodsKind is the kind a check declares in its InputSet to read Snapshot.ProxyPods.

Functions

This section is empty.

Types

type Access

type Access struct {
	OK  bool   `json:"ok"`
	Err string `json:"error,omitempty"`
	// Denied marks an Err the API server returned as 403 Forbidden.
	Denied bool `json:"denied,omitempty"`
}

Access reports whether a kind can currently be read.

type CRDMeta

type CRDMeta struct {
	Name, Group, BundleVersion, Channel string
}

CRDMeta is the metadata of one Gateway API CRD.

type Cache

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

Cache is a set of informers whose contents are read through Snapshot.

func New

func New(cfg Config) *Cache

New creates the informers. Nothing runs until Start.

func (*Cache) Fingerprint

func (c *Cache) Fingerprint() Fingerprint

Fingerprint walks the stores as Snapshot does, without copying or decoding anything, so it equals the Source of a snapshot taken from the same data.

func (*Cache) Settled

func (c *Cache) Settled() bool

Settled reports whether every informer has settled since Start and, with Config.Changes, the settle notification was sent. Later notifications come from events, failures and recoveries only.

func (*Cache) Snapshot

func (c *Cache) Snapshot() *Snapshot

Snapshot copies the current cache contents and fingerprints, in the same pass, exactly what it copied.

func (*Cache) Start

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

Start runs all informers until ctx is cancelled. With Config.Changes it notifies once when every informer has settled: its handler has received the initial list, or its List or Watch failed. Later failures and recoveries notify on their own. Wait returns once the goroutines Start launched have exited.

func (*Cache) Wait

func (c *Cache) Wait()

Wait returns once every goroutine Start launched, watch loops included, has exited after ctx is cancelled. Call it after Start; before Start it returns at once.

type Config

type Config struct {
	Dynamic             dynamic.Interface
	Kube                kubernetes.Interface
	Served              []kinds.Served
	PodSelectors        []labels.Selector
	DeploymentSelectors []labels.Selector
	// ProxyPodSelectors select gateway proxy Pods, watched apart from controller Pods.
	ProxyPodSelectors []labels.Selector
	// Events watches Warning Events on controller and proxy Pods.
	Events bool
	// CRDs watches Gateway API CRD metadata through Metadata; a nil Metadata means no watch.
	CRDs     bool
	Metadata metadata.Interface
	// Endpoints watches Services and EndpointSlices cluster-wide, cut down at the informer.
	Endpoints bool
	// Now stamps snapshots; nil means time.Now.
	Now func() time.Time
	// Changes is notified on every informer event (initial-list adds
	// included), on access transitions and once after every informer has
	// settled; nil means no notifications (D-019).
	Changes *trigger.Signal
}

Config configures a Cache. Pods and Deployments are only watched through the given label selectors, never cluster-wide (design §4.1).

type EventDeltas

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

EventDeltas turns Event counts into observed increases over EventWindow. Not safe for concurrent use.

type EventFact

type EventFact struct {
	UID, PodUID       types.UID
	Namespace, Reason string
	Count             int32
	First, Last       time.Time
	SeriesCount       int32
	SeriesLast        time.Time
}

EventFact is what the cache keeps of a Warning Event on a watched Pod: reason, counts and times. The message is never kept.

type Fingerprint

type Fingerprint struct {
	Kinds  map[string]KindPrint
	Access map[string]Access
}

Fingerprint identifies the source data of a snapshot (D-019 §2). Keys are GVR.String(), including NamespacesGVR, PodsGVR and DeploymentsGVR; every kind with an Access entry has a Kinds entry, empty kinds included.

func (Fingerprint) Equal

func (f Fingerprint) Equal(o Fingerprint) bool

Equal reports whether f and o describe the same objects and access states.

type Fingerprinter

type Fingerprinter interface{ Fingerprint() Fingerprint }

Fingerprinter returns the fingerprint of the live source data.

type KindPrint

type KindPrint struct {
	Count int
	Hash  uint64
}

KindPrint summarises one kind's objects: their count and the wrapping sum of objHash over each object's (uid, resourceVersion), so order does not matter.

type Observation

type Observation struct {
	At     time.Time
	Reason string
	Delta  int32
}

Observation is an increase of one Event's count by Delta, seen at At.

type ServiceFact

type ServiceFact struct {
	Namespace, Name, Type string
	Ports                 []ServicePort
}

ServiceFact is what the cache keeps of a Service.

type ServicePort

type ServicePort struct {
	Name         string
	Port, Target int32
	Protocol     string
}

ServicePort is one Service port. Target is the numeric target port, the port itself when unset, and 0 when the target port is a name. Protocol is "TCP" when unset.

type SliceFact

type SliceFact struct {
	Namespace, Service string
	Ports              []SlicePort
	Ready              []int
	Total              int
	AddressType        string
}

SliceFact is what the cache keeps of an EndpointSlice. A Service may have several, so slices are never merged. Ready[i] counts the slice's ready endpoints for Ports[i]; an endpoint with ready unset counts as ready. Total counts every endpoint, ready or not. AddressType is the slice's family, such as "IPv4"; a dual-stack Service has a slice per family.

type SlicePort

type SlicePort struct {
	Name string
	Port int32
}

SlicePort is one EndpointSlice port; an unnamed port has the name "".

type Snapshot

type Snapshot struct {
	// Objects lists each kind sorted by "namespace/name", so readers may
	// binary-search it (pkg/api does).
	Objects map[schema.GroupVersionResource][]*unstructured.Unstructured
	// Access holds every served kind plus NamespacesGVR, PodsGVR and
	// DeploymentsGVR, and the key of each optional watch that runs.
	Access      map[schema.GroupVersionResource]Access
	Namespaces  []*corev1.Namespace
	Pods        []*corev1.Pod
	Deployments []*appsv1.Deployment
	// ProxyPods are the Pods the proxy Pod selectors match.
	ProxyPods []*corev1.Pod
	// Events are the kept Warning Events of controller and proxy Pods, by UID.
	Events []EventFact
	// EventDeltas are the observed Event count increases of the last
	// EventWindow per Pod UID, oldest first.
	EventDeltas map[types.UID][]Observation
	// EventHistoryUnknown marks Pods with an Event whose earlier count was not observed.
	EventHistoryUnknown map[types.UID]bool
	// EventsCapped is true when MaxEvents made the cache drop Events.
	EventsCapped bool
	// CRDs are the Gateway API CRDs, by name.
	CRDs []CRDMeta
	// Services and EndpointSlices are the cut-down objects of the Service and
	// EndpointSlice watches, by namespace and name.
	Services       []ServiceFact
	EndpointSlices []SliceFact
	// Synced is true once every core informer (served kinds, Namespaces,
	// Pods and Deployments) has synced or failed. Optional watches and
	// list-only kinds never hold it back.
	Synced  bool
	TakenAt time.Time
	// Source is the fingerprint of exactly the objects and access states copied.
	Source Fingerprint
}

Snapshot is an immutable view of the cache at TakenAt. Callers must not mutate it.

type Snapshotter

type Snapshotter interface{ Snapshot() *Snapshot }

Snapshotter returns the current snapshot.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL