Documentation
¶
Overview ¶
Package validators provides shared utilities for v2 validator containers.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EmitExtra ¶ added in v0.19.0
EmitExtra marshals a check's structured, low-cardinality outcome data to a single JSON line prefixed with ctrf.ExtraLinePrefix and writes it to stdout. The orchestrator (pkg/validator/job.ExtractResult) parses this line back into ctrf.TestResult.Extra, which — unlike the free-form Stdout/Message evidence — survives the default "minimal" redaction policy for allowlisted keys.
CONTRACT: values MUST be counts or enum codes only (e.g. "2", "no-gpu-nodes"), never node names, IPs, or hostnames. Anything operator-identifying belongs in fmt.Printf stdout, which is redacted by default. Emitting an empty map is a no-op. Key order in the JSON is not significant — the line is re-parsed structurally, and only redact-allowlisted keys are published.
func IsSkip ¶ added in v0.19.0
IsSkip reports whether err (or anything in its Unwrap chain) came from Skip. errSkip is unexported, so this is the supported way for callers and tests outside this package to classify a skip without matching on rendered error text.
func RecipeDeclares ¶ added in v0.19.0
RecipeDeclares reports whether component is present AND enabled in the resolved recipe's ComponentRefs (ctx.ValidationInput). A component that is absent or explicitly disabled is not declared: it will not be deployed, so its capability is genuinely inapplicable and a capability-gated check may Skip. Nil-safe: a nil Context or nil ValidationInput reports false, which is the standalone/no-recipe path that preserves capability-driven selection (#1327).
func Run ¶
Run is the main entry point for v2 validator containers. It loads the context, dispatches to the named check, and handles exit codes and termination log writing.
Usage in main.go:
func main() {
validators.Run(map[string]validators.CheckFunc{
"operator-health": checkOperatorHealth,
"expected-resources": checkExpectedResources,
})
}
Types ¶
type Capability ¶ added in v0.19.0
type Capability struct {
// Component is the recipe componentRef name that supplies this capability
// (e.g. "kai-scheduler"). RecipeDeclares(ctx, Component) decides whether the
// recipe makes the capability applicable.
Component string
// Subject names the probed prerequisite for diagnostics — the concrete
// object/API the probe read (e.g. "kai-scheduler Deployment
// kai-scheduler/kai-scheduler-default"). Used in the classified infra-error
// messages so operators see exactly what could not be read.
Subject string
// AbsentMsg is the actionable operator message emitted when the capability
// is DECLARED but its prerequisite is cleanly missing (NotFound / empty
// result). It should tell the operator how to remediate, e.g. "recipe
// declares kai-scheduler but its Deployment is absent — apply the bundle or
// check RBAC".
AbsentMsg string
// InapplicableMsg is the Skip reason emitted when the capability is NOT
// declared and is therefore genuinely inapplicable (e.g. "KAI scheduler not
// found — cluster may use a different scheduler"). Optional: when empty a
// generic reason is derived from Component and Subject.
InapplicableMsg string
}
Capability describes a recipe-declared capability whose live prerequisite a check probes before proceeding. Require() turns the probe outcome into the correct verdict (proceed / Skip / fail-closed) per the #2122 contract above.
func (Capability) Require ¶ added in v0.19.0
func (c Capability) Require(ctx *Context, probeErr error, present bool) error
Require resolves a capability-gated check's fate from the outcome of probing its live prerequisite:
- probeErr is the error the probe returned (nil on a clean read).
- present reports whether the probe found the prerequisite. It is consulted ONLY when probeErr is nil — e.g. a List that returned zero items, or a discovery call that returned without the expected resource.
Decision table (declared == RecipeDeclares(ctx, c.Component)):
│ recipe DECLARES │ recipe does NOT declare ────────────────────────────┼────────────────────────┼──────────────────────── clean read, present │ nil (proceed) │ nil (proceed) clean read, absent/empty │ FAIL (NotFound) │ Skip probe err: NotFound │ FAIL (NotFound) │ Skip probe err: Forbidden/401 │ FAIL (Unauthorized) — always probe err: timeout/deadline │ FAIL (Timeout) — always probe err: transport/503 │ FAIL (Unavailable) — always probe err: other/discovery │ FAIL (Internal) — always
Infra errors (Forbidden, timeout, transport, API discovery) NEVER Skip, even when the recipe does not declare the component: a missing RBAC grant or an apiserver hiccup is not evidence that the capability is inapplicable. Only a clean NotFound / empty result on a NON-declared capability may Skip (#2122).
func (Capability) RequireList ¶ added in v0.19.0
func (c Capability) RequireList(probeErr error) error
RequireList resolves a capability-gated check that probes a LIST/collection endpoint whose EMPTY (non-error) result — not an error — is what signals inapplicability. Unlike Require, a List *error* is never Skip-eligible: even a NotFound on a collection endpoint is an apiserver/aggregation-layer anomaly, not the clean absence of a single object, so every List error blocks with a classified code (Forbidden→Unauthorized, deadline→Timeout, transport→ Unavailable, else Internal) and never masquerades as an inapplicable Skip. Callers handle the empty-result inapplicability case themselves (e.g. len(items) == 0 → "", nil). This closes the #2122 fail-open where routing a List error through Require would Skip on the (rare but unenforced) NotFound shape for an undeclared capability.
type CheckFunc ¶
CheckFunc is the signature for a v2 validator check function. Return nil for pass, non-nil error for fail, Skip() for skip. Evidence goes to stdout, debug logs to stderr.
type Context ¶
type Context struct {
// Ctx is the parent context with timeout.
Ctx context.Context
// Cancel releases resources. Must be called when done.
Cancel context.CancelFunc
// Clientset is the Kubernetes typed client.
Clientset kubernetes.Interface
// RESTConfig is the Kubernetes REST config (for exec, dynamic client, etc.).
RESTConfig *rest.Config
// DynamicClient is the Kubernetes dynamic client for CRD access.
DynamicClient dynamic.Interface
// Snapshot is the captured cluster state.
Snapshot *snapshotter.Snapshot
// ValidationInput is the validation specification (config + context).
ValidationInput *v1.ValidationInput
// Namespace is the validation namespace.
Namespace string
// NodeSelector overrides platform-specific node selectors on inner workloads
// (e.g., NCCL benchmark worker pods). Nil means use the validator's default selectors.
// Set from the AICR_NODE_SELECTOR env var (comma-separated key=value pairs).
NodeSelector map[string]string
// Tolerations overrides the default tolerate-all policy on inner workloads.
// Nil means use the validator's default tolerations.
// Set from the AICR_TOLERATIONS env var (comma-separated key=value:effect entries).
Tolerations []corev1.Toleration
}
Context holds all dependencies for a validator check function.
func LoadContext ¶
LoadContext creates a Context from the v2 container environment. Reads snapshot and recipe from mounted ConfigMap paths. Builds a K8s client from in-cluster config or KUBECONFIG.
The caller MUST call ctx.Cancel() when done.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
conformance is a validator container for all conformance phase checks.
|
conformance is a validator container for all conformance phase checks. |
|
deployment is a validator container for all deployment phase checks.
|
deployment is a validator container for all deployment phase checks. |
|
Package helper provides shared utilities for v2 validator containers.
|
Package helper provides shared utilities for v2 validator containers. |
|
internal
|
|
|
performance is a validator container for all performance phase checks.
|
performance is a validator container for all performance phase checks. |