scanner

Documentation

Index

• Constants
• Variables
• func CacheReadOptions() metav1.ListOptions
• func ListAll(ctx context.Context, list ListPager) error
• type ListPager
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) All() map[string]Scanner
  • func (r *Registry) Get(name string) (Scanner, bool)
  • func (r *Registry) Names() []string
  • func (r *Registry) Register(name string, s Scanner)
• type Result
  • func ErroredResult(name string, err error) Result
  • func RunWithTimeout(ctx context.Context, s Scanner, client *kube.Client, timeout time.Duration) (Result, error)
  • func (r Result) Blind() bool
• type Scanner
• type ScannerFunc
  • func (f ScannerFunc) Scan(ctx context.Context, client *kube.Client) (Result, error)
• type State

Constants

const DefaultListLimit = 500

DefaultListLimit is the per-page size used by ListAll for scanner lists. Five hundred is the upstream client-go default for paginated lists and gives a reasonable tradeoff between request count and memory pressure on the apiserver.

const DefaultListTimeout = 30 * time.Second

DefaultListTimeout caps each individual list call so a slow apiserver cannot hang a full fleet sweep on one bad cluster.

const DefaultScanTimeout = 60 * time.Second

DefaultScanTimeout bounds how long a single scanner may run against one cluster before it is abandoned, so a hung API call on one outlier cluster cannot stall the whole fleet sweep.

Variables

var ErrScan = errors.New("scan failed")

ErrScan indicates a scanner failed to collect data from a cluster.

Functions

func CacheReadOptions

func CacheReadOptions() metav1.ListOptions

CacheReadOptions returns ListOptions configured to read from the apiserver watch cache. Use these for any read that does not need a strict-consistency guarantee against etcd; on a busy cluster this is an order-of-magnitude reduction in apiserver load. Scanners can also extend the returned options with their own FieldSelector or LabelSelector when needed.

func ListAll

func ListAll(ctx context.Context, list ListPager) error

ListAll drives a ListPager to completion, applying a per-list timeout and the watch-cache hint described above. The list function is invoked once per page; pagination stops when the apiserver returns an empty continue token.

Types

type ListPager

type ListPager func(ctx context.Context, opts metav1.ListOptions) (continueToken string, err error)

ListPager paginates an apiserver list call using Continue tokens and the supplied list function. The list function should call the typed client's List method with the provided options and return the raw list result; the caller is responsible for appending each page's items into its accumulator inside the callback. ResourceVersion is fixed at "0" with NotOlderThan match semantics so reads come from the apiserver watch cache rather than etcd, dramatically reducing load on large clusters.

type Registry

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

Registry maps scanner names to their implementations.

func NewRegistry

func NewRegistry() *Registry

NewRegistry creates an empty scanner registry.

func (*Registry) All

func (r *Registry) All() map[string]Scanner

All returns a copy of the internal scanner map.

func (*Registry) Get

func (r *Registry) Get(name string) (Scanner, bool)

Get returns the scanner registered under name, or false if not found.

func (*Registry) Names

func (r *Registry) Names() []string

Names returns all registered scanner names in sorted order.

func (*Registry) Register

func (r *Registry) Register(name string, s Scanner)

Register adds a scanner under the given name. Panics on duplicate names.

type Result

type Result struct {
	// Scanner is the name identifying which scanner produced this result.
	Scanner string `json:"scanner"`
	// State records how much to trust Data. The zero value means StateOK.
	State State `json:"state,omitempty"`
	// Reason is a short explanation when State is not OK. Empty otherwise.
	Reason string `json:"reason,omitempty"`
	// Data is the scanner-specific payload.
	Data any `json:"data"`
}

Result holds the output of a single scanner run against one cluster.

func ErroredResult

func ErroredResult(name string, err error) Result

ErroredResult builds a result that records a failed scan for one cluster so the fleet report can surface the failure instead of dropping it silently.

func RunWithTimeout

func RunWithTimeout(ctx context.Context, s Scanner, client *kube.Client, timeout time.Duration) (Result, error)

RunWithTimeout runs a scanner against a client under a deadline. A zero or negative timeout disables the deadline. A timeout surfaces as an ordinary scan error, which the caller records as degraded coverage rather than a clean result.

func (Result) Blind

func (r Result) Blind() bool

Blind reports whether the scanner failed to observe the cluster, so its data is a failed read rather than a measurement and must be excluded from fleet statistics instead of counted as zero.

type Scanner

type Scanner interface {
	Scan(ctx context.Context, client *kube.Client) (Result, error)
}

Scanner collects cluster-specific data for a single scan dimension.

type ScannerFunc

type ScannerFunc func(ctx context.Context, client *kube.Client) (Result, error)

ScannerFunc adapts a plain function to the Scanner interface.

func (ScannerFunc) Scan

func (f ScannerFunc) Scan(ctx context.Context, client *kube.Client) (Result, error)

Scan calls the underlying function.

type State

type State string

State describes how much to trust a scanner's data for one cluster. It exists so an unreachable or forbidden API produces a degraded or errored result instead of an empty payload that reads as a clean, zero-resource cluster.

const (
	// StateOK means the scanner completed and its data is complete. It is the
	// zero value's meaning, so scanners that cannot fail need not set it.
	StateOK State = ""
	// StateDegraded means the scanner completed but some data is missing
	// because one or more API calls failed. The data present is real but
	// partial, so consumers must not read absent fields as zero.
	StateDegraded State = "degraded"
	// StateErrored means the scanner could not collect its data because an API
	// call failed or access was denied. The data must never be read as a real
	// "clean, zero resources" result.
	StateErrored State = "errored"
	// StateUnavailable means the scanned feature is genuinely absent, such as a
	// CRD that is not installed. This is a trustworthy "nothing here", not a
	// failure.
	StateUnavailable State = "unavailable"
)