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 ¶
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.
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 )
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 ¶
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.
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.
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.
var CRDsGVR = schema.GroupVersionResource{Group: "apiextensions.k8s.io", Version: "v1", Resource: "customresourcedefinitions"}
CRDsGVR is the Access key of the Gateway API CRD metadata watch.
var CRDsKind = objects.GroupKind{Group: "apiextensions.k8s.io", Kind: "CustomResourceDefinition"}
CRDsKind is the kind a check declares in its InputSet to read Snapshot.CRDs.
var EventsGVR = schema.GroupVersionResource{Version: "v1", Resource: "events"}
EventsGVR is the Access key of the Warning Events watch.
var EventsKind = objects.GroupKind{Kind: "Event"}
EventsKind is the kind a check declares in its InputSet to read Snapshot.Events, EventDeltas, EventHistoryUnknown and EventsCapped.
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 (*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 ¶
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 ¶
Snapshot copies the current cache contents and fingerprints, in the same pass, exactly what it copied.
func (*Cache) Start ¶
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.
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 ¶
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 ¶
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 ¶
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 ¶
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 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.