Documentation
¶
Overview ¶
Package state normalizes Kubernetes objects into protocol state, edges, scopes, and kube_* series.
Index ¶
- Constants
- Variables
- func KindOf(obj *unstructured.Unstructured) string
- func NodeAffinitySummary(na *corev1.VolumeNodeAffinity) string
- func Normalize(obj *unstructured.Unstructured) (protocol.Resource, []protocol.Edge, error)
- func PathPattern(path string) *regexp.Regexp
- func ProtocolKind(group, kind string) string
- func PublishedSubset() map[string]bool
- func RenderFieldCatalog() string
- func RenderKubeSeriesDoc() string
- func ResolveKinds(names []string) (kinds []string, unsupported []string)
- func ScopeKey(kind, namespace string) string
- func Transform(n *Normalizer, kind string) cache.TransformFunc
- type Collector
- type CollectorOptions
- type Coverage
- type Field
- type FieldType
- type KindSpec
- type Normalizer
- type Options
- type Placement
- type Redaction
- type ScopeReport
- type Series
- type SeriesSpec
- type Sink
- type Tracker
- func (t *Tracker) FlushEvents() []protocol.Op
- func (t *Tracker) Normalizer() *Normalizer
- func (t *Tracker) Reconcile(kind, namespace string, objects []*unstructured.Unstructured) ([]protocol.Op, map[string]bool, error)
- func (t *Tracker) Remove(obj *unstructured.Unstructured) ([]protocol.Op, error)
- func (t *Tracker) RemoveScope(kind, namespace string) []protocol.Op
- func (t *Tracker) ScopeLost(kind, namespace, reason string) []protocol.Op
- func (t *Tracker) ScopePartial(kind, namespace, reason string) []protocol.Op
- func (t *Tracker) ScopeRestored(kind, namespace string) []protocol.Op
- func (t *Tracker) Snapshot() *protocol.State
- func (t *Tracker) Upsert(obj *unstructured.Unstructured) ([]protocol.Op, error)
- type TrackerOptions
Constants ¶
const ( KindNamespace = "Namespace" KindNode = "Node" KindPod = "Pod" KindDeployment = "apps/Deployment" KindReplicaSet = "apps/ReplicaSet" KindStatefulSet = "apps/StatefulSet" KindDaemonSet = "apps/DaemonSet" KindJob = "batch/Job" KindCronJob = "batch/CronJob" KindService = "Service" KindIngress = "networking.k8s.io/Ingress" KindNetPol = "networking.k8s.io/NetworkPolicy" KindPVC = "PersistentVolumeClaim" KindPV = "PersistentVolume" KindStorageCls = "storage.k8s.io/StorageClass" KindConfigMap = "ConfigMap" KindHPA = "autoscaling/HorizontalPodAutoscaler" KindPDB = "policy/PodDisruptionBudget" KindEvent = "Event" )
Protocol kind strings (SPEC 4.2).
const ( EdgeOwns = "owns" EdgeRunsOn = "runs-on" EdgeSelects = "selects" EdgeMounts = "mounts" EdgeBinds = "binds" EdgeRoutes = "routes" EdgeTargets = "targets" EdgeScales = "scales" EdgeGuards = "guards" )
Edge types of the change graph.
const ( ReasonForbidden = "forbidden" ReasonNotServed = "not served" ReasonCollectionFailed = "collection failed" ReasonRelisting = "relisting" )
Scope failure reasons recorded on scope status.
const ( LimitationPinned = "volume is node-local (nodeAffinity): the coordinator is pinned to its node" LimitationZonal = "volume is zonal (nodeAffinity): the coordinator can only be rescheduled within its zone" LimitationRWO = "ReadWriteOnce without ReadWriteOncePod: single writer relies on the spool file lock" LimitationRWX = "ReadWriteMany is not supported for the coordinator spool" LimitationNoAccessMode = "no access mode reported" )
Placement limitations reported on the connector.
const CatalogSchema = 1
CatalogSchema is the field catalog version; it changes whenever an exported path changes meaning.
const ReasonScopeRemoved = "scope removed"
Scope removal reason recorded on the scope status.
Variables ¶
var DefaultAnnotationAllowlist = []string{}
DefaultAnnotationAllowlist is used when no annotation allowlist is configured: no annotations.
var DefaultLabelAllowlist = []string{
"app.kubernetes.io/name", "app.kubernetes.io/instance", "app.kubernetes.io/component",
"app.kubernetes.io/part-of", "app.kubernetes.io/version", "app", "k8s-app",
"topology.kubernetes.io/zone", "topology.kubernetes.io/region", "node-role.kubernetes.io/*",
}
DefaultLabelAllowlist is used when no label allowlist is configured.
var ErrAggregatedKind = errors.New("state: kind is aggregated, not exported")
ErrAggregatedKind reports an object that is aggregated onto other resources instead of exported.
var ErrUnsupportedKind = errors.New("state: unsupported kind")
ErrUnsupportedKind reports an object whose kind is not in the catalog; it is reported, never exported.
Functions ¶
func KindOf ¶
func KindOf(obj *unstructured.Unstructured) string
KindOf returns the protocol kind of obj.
func NodeAffinitySummary ¶
func NodeAffinitySummary(na *corev1.VolumeNodeAffinity) string
NodeAffinitySummary renders required node affinity terms canonically; terms are ORed.
func Normalize ¶
func Normalize(obj *unstructured.Unstructured) (protocol.Resource, []protocol.Edge, error)
Normalize normalizes obj with the default options.
func PathPattern ¶
PathPattern compiles a catalog path into a regular expression matching concrete field keys.
func ProtocolKind ¶
ProtocolKind returns the protocol kind string for an API group and kind.
func PublishedSubset ¶
PublishedSubset returns the set of published kube_* series names for rule validation.
func RenderFieldCatalog ¶
func RenderFieldCatalog() string
RenderFieldCatalog renders docs/field-catalog.md from the catalog.
func RenderKubeSeriesDoc ¶
func RenderKubeSeriesDoc() string
RenderKubeSeriesDoc renders docs/kube-series.md.
func ResolveKinds ¶
ResolveKinds maps configured resource names to catalog kinds and returns the unsupported names.
func ScopeKey ¶
ScopeKey returns the scope key "<kind>|<namespace>"; the namespace is empty for cluster-wide collection.
func Transform ¶
func Transform(n *Normalizer, kind string) cache.TransformFunc
Transform returns the informer transform that strips unexported and sensitive fields before caching.
Types ¶
type Collector ¶
type Collector struct {
// contains filtered or unexported fields
}
Collector runs read-only list and watch loops for every permitted scope and feeds the Tracker.
func NewCollector ¶
func NewCollector(o CollectorOptions) (*Collector, error)
NewCollector validates o and prepares the scopes.
type CollectorOptions ¶
type CollectorOptions struct {
Dynamic dynamic.Interface
Metadata metadata.Interface
Discovery discovery.DiscoveryInterface
Tracker *Tracker
Sink Sink
// OnSynced receives the state once every scope finished its first attempt; ops before it are not sent to Sink.
OnSynced func(st *protocol.State)
// Namespaces selects the namespace profile; empty collects cluster-wide.
Namespaces []string
ExcludeNamespaces []string
// Resources lists configured resource names; empty selects every catalog kind.
Resources []string
Logger *slog.Logger
Clock func() time.Time
// RetryBase and RetryMax bound the exponential backoff after access failures, default 30s and 30m.
RetryBase, RetryMax time.Duration
// FlushInterval is the event count flush period, default 30s.
FlushInterval time.Duration
// Wait sleeps for d or until ctx is done, reporting whether to continue; default uses a timer.
Wait func(ctx context.Context, d time.Duration) bool
ReflectorBackoff *wait.Backoff
}
CollectorOptions configures a Collector.
type Coverage ¶
type Coverage struct {
Scopes []ScopeReport
Unsupported []string
}
Coverage summarizes collection: every scope and the configured resources that are not supported.
type KindSpec ¶
type KindSpec struct {
Kind string
GVR schema.GroupVersionResource
APIKind string
Namespaced bool
MetadataOnly bool
Aggregated bool
Fields []Field
// contains filtered or unexported fields
}
KindSpec describes one collected kind.
func Catalog ¶
func Catalog() []KindSpec
Catalog returns a copy of the field catalog ordered by kind.
func LookupKind ¶
LookupKind returns the catalog entry for a protocol kind.
type Normalizer ¶
type Normalizer struct {
// contains filtered or unexported fields
}
Normalizer turns Kubernetes objects into normalized resources using the field catalog.
func NewNormalizer ¶
func NewNormalizer(o Options) (*Normalizer, error)
NewNormalizer validates o and builds a Normalizer.
func (*Normalizer) Normalize ¶
func (n *Normalizer) Normalize(obj *unstructured.Unstructured) (protocol.Resource, []protocol.Edge, error)
Normalize returns the normalized resource and its owner edges (owner uid -> child uid).
func (*Normalizer) Selected ¶
func (n *Normalizer) Selected(kind, path string) bool
Selected reports whether a catalog field is exported: default-on or deliberately selected.
type Options ¶
type Options struct {
// LabelAllowlist and AnnotationAllowlist hold exact keys or prefixes ending in "*"; nil selects the defaults.
LabelAllowlist []string
AnnotationAllowlist []string
// Fields selects non-default catalog fields as "<kind>:<path>", for example "Pod:containers.<container>.args".
Fields []string
Redactor *redact.Redactor
}
Options configures a Normalizer.
func OptionsFromConfig ¶
func OptionsFromConfig(k config.Kubernetes, r *redact.Redactor) Options
OptionsFromConfig derives normalizer options from the Kubernetes configuration section.
type Placement ¶
type Placement struct {
Claim string
Volume string
StorageClass string
AccessModes []string
Driver string
NodeAffinity string
// PinnedNodes lists hostnames the volume is restricted to when affinity uses kubernetes.io/hostname.
PinnedNodes []string
Pinned bool
// Zonal reports affinity to a topology zone without pinning to one node.
Zonal bool
Limitations []string
}
Placement describes where the coordinator spool volume lives (PRD A8).
func PlacementFromVolume ¶
func PlacementFromVolume(pv *corev1.PersistentVolume) Placement
PlacementFromVolume derives placement from a PersistentVolume.
func ReadPlacement ¶
func ReadPlacement(ctx context.Context, cs kubernetes.Interface, namespace, claim string) (Placement, error)
ReadPlacement reads the coordinator's own claim and its bound PersistentVolume with get requests only.
type Redaction ¶
type Redaction string
Redaction is the redaction class of an exported field.
const ( // RedactStructural fields hold API enumerations, numbers, and addresses, exported as is. RedactStructural Redaction = "structural" // RedactReference fields hold object and key names, never the referenced values. RedactReference Redaction = "reference" // RedactText fields hold free text and pass through internal/redact. RedactText Redaction = "text" // RedactAllowlist fields are exported only for allowlisted keys, with values passed through internal/redact. RedactAllowlist Redaction = "allowlist" )
type ScopeReport ¶
type ScopeReport struct {
Key string
Kind string
Namespace string
State protocol.ScopeState
Reason string
Attempts int
}
ScopeReport is the collection status of one scope.
type Series ¶
Series is one synthesized kube_* sample at time T (milliseconds).
func KubeSeries ¶
KubeSeries synthesizes the published kube_* subset from state with kube-state-metrics v2 semantics.
func NodeScoped ¶
NodeScoped returns the series pushed to one node: pod series for pods on it plus its kube_node_* series.
func PodSeriesFromPods ¶
func PodSeriesFromPods(n *Normalizer, pods []*unstructured.Unstructured, nowMs int64) ([]Series, error)
PodSeriesFromPods derives pod-scoped series from a node agent's own pod watch.
type SeriesSpec ¶
SeriesSpec documents one published kube_* series.
func KubeSeriesCatalog ¶
func KubeSeriesCatalog() []SeriesSpec
KubeSeriesCatalog returns the published series specifications.
type Sink ¶
Sink receives ops in state order; synthetic relist ops carry the interval where transients may be missed.
type Tracker ¶
type Tracker struct {
// contains filtered or unexported fields
}
Tracker holds the normalized state of a cluster and turns observations into canonical ops.
func (*Tracker) FlushEvents ¶
FlushEvents publishes event counts that are due: changed or decayed counts whose last update is older than the interval.
func (*Tracker) Normalizer ¶
func (t *Tracker) Normalizer() *Normalizer
Normalizer returns the tracker's normalizer.
func (*Tracker) Reconcile ¶
func (t *Tracker) Reconcile(kind, namespace string, objects []*unstructured.Unstructured) ([]protocol.Op, map[string]bool, error)
Reconcile diffs one scope against a fresh list and returns the ops and every UID they touch.
func (*Tracker) Remove ¶
func (t *Tracker) Remove(obj *unstructured.Unstructured) ([]protocol.Op, error)
Remove observes the deletion of obj.
func (*Tracker) RemoveScope ¶
RemoveScope deletes every resource of the scope with reason scope removed and marks the scope unavailable.
func (*Tracker) ScopeLost ¶
ScopeLost marks a scope unavailable (permission loss or collection failure); resources are kept, never deleted.
func (*Tracker) ScopePartial ¶
ScopePartial marks a scope partial, for example while it is relisted.
func (*Tracker) ScopeRestored ¶
ScopeRestored marks a scope complete.
func (*Tracker) Upsert ¶
func (t *Tracker) Upsert(obj *unstructured.Unstructured) ([]protocol.Op, error)
Upsert observes obj and returns ops for the resource and every changed edge, none when unchanged.
type TrackerOptions ¶
type TrackerOptions struct {
Normalizer *Normalizer
Clock func() time.Time
// EventWindow is the sliding window for Warning event counts, default 1h.
EventWindow time.Duration
// EventInterval bounds how often event counts of one object are updated, default 5m.
EventInterval time.Duration
}
TrackerOptions configures a Tracker.