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
- Variables
- func NewScopedReader(kube kubernetes.Interface, clk clock.PassiveClock) endpoints.ScopedReader
- type Access
- type CRDMeta
- type Cache
- type Config
- type EventDeltas
- type EventFact
- type Fingerprint
- type Fingerprinter
- type KindPrint
- type Observation
- type ServiceFact
- type ServicePort
- type SliceFact
- type SlicePort
- type Snapshot
- type Snapshotter
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 ( ModeWatch = "watch" ModeList = "list" )
Snapshot modes: from a Cache's informers, or from ListOnce's LISTs.
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 ¶
func NewScopedReader ¶ added in v0.7.0
func NewScopedReader(kube kubernetes.Interface, clk clock.PassiveClock) endpoints.ScopedReader
NewScopedReader reads a Service's EndpointSlices with a paged, namespaced LIST by the Service-name label, within endpoints.DefaultBounds' page and endpoint limits, stamping results with clk. It keeps nothing; wrap it in endpoints.Bounded.
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
// Namespaces limits namespaced inputs to these namespaces, each read on its
// own; cluster-scoped kinds stay cluster-wide. Nil or empty means cluster-wide.
Namespaces []string
}
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
// NamespaceAccess is Snapshot.NamespaceAccess by GVR.String(); nil when cluster-wide.
NamespaceAccess map[string]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 ¶
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; TargetName is that 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; from ListOnce, once each
// was listed or denied. 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
// Mode is ModeWatch for a Cache's snapshot and ModeList for ListOnce's.
Mode string
// RequestedNamespaces is Config.Namespaces deduplicated and sorted; nil when cluster-wide.
RequestedNamespaces []string
// NamespaceAccess holds, for each namespaced input, its Access per requested
// namespace; Access holds the aggregate. Nil when cluster-wide.
NamespaceAccess map[schema.GroupVersionResource]map[string]Access
}
Snapshot is an immutable view of the cache at TakenAt. Callers must not mutate it.
func ListOnce ¶ added in v0.7.0
ListOnce fills the snapshot a synced Cache over cfg would give from one LIST per input, and never watches. cfg.Changes is ignored.
It returns an error only for a Config without clients or a cancelled ctx. A LIST that fails shows in Access: a 403 is denied, anything else failed and holds back Synced when the input is required.
type Snapshotter ¶
type Snapshotter interface{ Snapshot() *Snapshot }
Snapshotter returns the current snapshot.