Documentation
¶
Overview ¶
Package runner contains the chainsaw-test evaluation machinery used by the standalone `gate` CLI. It owns:
- Evaluate: run all components of a bundle once, aggregate per-component results
- LoadBundleDir: read a directory of *.yaml files into a name -> content map
- ComputeReadyState / ApplyDeadline: the pure stability-window and deadline state machine driving the aggregate Ready condition
Assertions are evaluated in-process by pkg/chainsaw — the same executor the deployment validator has used since #1236. The gate previously shelled out to a `chainsaw` binary embedded in the aicr-gate image; that binary was the image's only source of HIGH CVEs and could not be upgraded past them upstream, so #2038 removed it. The state machine and bundle loading remain free of Kubernetes types; only Evaluate touches the cluster, through the caller-supplied fetcher.
Index ¶
Constants ¶
const ( // ResultPass / ResultFail / ResultUnknown are the possible per-component outcomes. ResultPass = "Pass" ResultFail = "Fail" ResultUnknown = "Unknown" )
const ( StatusTrue = "True" StatusFalse = "False" )
Condition status values. These mirror metav1.ConditionStatus strings so callers that surface them on a Kubernetes condition need no translation.
const ( ReasonAllPass = "AllPass" ReasonStabilizing = "Stabilizing" ReasonComponentsFailing = "ComponentsFailing" ReasonDeadlineExceeded = "DeadlineExceeded" )
Well-known reasons surfaced on the Ready condition.
Variables ¶
This section is empty.
Functions ¶
func FailingSummary ¶
func FailingSummary(components map[string]ComponentResult) string
FailingSummary renders a deterministic, truncated summary of the failing components for use in a condition Message.
func LoadBundleDir ¶
LoadBundleDir reads every *.yaml file in dir into a name -> content map. The map key is the filename with the .yaml suffix stripped — matching the convention used by bundle ConfigMaps (one data key per component).
Subdirectories are ignored. Non-.yaml files are ignored. An empty directory is not an error here; callers can decide whether that's invalid.
func TruncHead ¶
TruncHead caps s to at most n bytes, backing off to a UTF-8 rune boundary so a multi-byte rune is never split, and appends an ellipsis when truncation occurred. n is a byte budget, not a rune count. Used for head-trimmed progress/summary lines.
func TruncTail ¶
TruncTail keeps the last (up to) n bytes of s, advancing to the next UTF-8 rune boundary so the retained tail never starts mid-rune, and prefixes an ellipsis when truncation occurred. n is a byte budget, not a rune count. Used for chainsaw failure output where the tail carries the error.
Types ¶
type ComponentResult ¶
type ComponentResult struct {
// Result is one of ResultPass, ResultFail, ResultUnknown.
Result string
// Message holds a truncated tail of stderr/stdout on failure. Empty on pass.
Message string
}
ComponentResult is the outcome of running one component's chainsaw test once.
type EvalResult ¶
type EvalResult struct {
// Components maps component name -> result. The name is the ConfigMap data
// key (or filename) with any ".yaml" suffix stripped.
Components map[string]ComponentResult
// AllPass is true iff every component returned ResultPass.
AllPass bool
}
EvalResult is the aggregate of running every component in a bundle once.
func Evaluate ¶
Evaluate runs each entry in bundle against the cluster once and returns the aggregate. Assertions are evaluated in-process against opts.Fetcher, with bounded parallelism across components (pkg/chainsaw applies defaults.ChainsawMaxParallel).
bundle is a name -> chainsaw-test-YAML map (typically the data field of a bundle ConfigMap, or the contents of a LoadBundleDir directory).
type Options ¶
type Options struct {
// Namespace is the default namespace for assertions whose resource
// block omits metadata.namespace. It preserves the behavior the
// `chainsaw --namespace` flag provided: without it, a namespace-less
// assertion would silently widen to every namespace. Cluster-scoped
// kinds ignore it (the fetcher resolves scope via the RESTMapper).
Namespace string
// Timeout is the per-component assertion budget.
Timeout time.Duration
// PollInterval is the cadence at which the caller re-evaluates the bundle.
// The runner itself does not loop — callers do.
PollInterval time.Duration
// StabilityWindow is the continuous-pass duration required before the
// aggregate state flips to Ready.
StabilityWindow time.Duration
// MaxWait is the upper bound on how long the caller may keep waiting
// for the bundle to pass before giving up. 0 disables the ceiling.
MaxWait time.Duration
// Fetcher reads cluster state for the assertions. Required: Evaluate
// rejects a nil fetcher rather than reporting components it never
// evaluated.
Fetcher chainsaw.ResourceFetcher
}
Options holds the parameters that govern one or more evaluations. The gate CLI populates all fields from its flags; the runner reads each field as described below.
type ReadyState ¶
type ReadyState struct {
// Status is one of StatusTrue / StatusFalse.
Status string
// Reason is a short machine-readable hint (see Reason* constants above).
Reason string
// Message is human-readable detail.
Message string
// FirstPassTime is the start of the current continuous-pass streak.
// Reset to nil on any failure.
FirstPassTime *time.Time
// RequeueIn is the suggested wait before the caller should re-evaluate.
// 0 means "do not requeue" (terminal).
RequeueIn time.Duration
}
ReadyState is the decision produced by ComputeReadyState, optionally overridden by ApplyDeadline.
func ApplyDeadline ¶
func ApplyDeadline(now time.Time, gateStartTime *time.Time, maxWait time.Duration, in ReadyState) ReadyState
ApplyDeadline overrides a non-Ready candidate state with a terminal DeadlineExceeded once now - gateStartTime exceeds maxWait. Inputs pass through unchanged when maxWait is disabled (<=0), gateStartTime is nil, the candidate is already Ready, or the budget is not yet exhausted.
func ComputeReadyState ¶
func ComputeReadyState( now time.Time, allPass bool, components map[string]ComponentResult, firstPassTime *time.Time, stabilityWindow, pollInterval time.Duration, ) ReadyState
ComputeReadyState is pure: given the current time, test results, and prior continuous-pass start time, return the new condition state and the suggested requeue interval. The caller is responsible for persisting FirstPassTime between calls.
Source Files