Documentation
¶
Overview ¶
Package constraints parses and evaluates constraint expressions (e.g. ">= 1.32.4", "== ubuntu", "1.33.5") against measurement values extracted from a snapshot.
Constraints follow a "<operator> <value>" grammar. The supported operators are >=, <=, >, <, ==, !=, and the empty operator (exact string match). The IsVersionComparison flag selects semver-aware ordering via pkg/version; without it comparisons use lexical ordering.
Two entry points are exposed:
- Parse(expr) returns a ParsedConstraint that callers can evaluate against arbitrary values.
- Evaluate(c, snap) walks the snapshot, extracts the named measurement reading, and reports a Result describing whether the constraint passed and why.
One constraint name carries a non-scalar form: the node-set constraint GPUNodesLabelConstraintName ("NodeTopology.gpu-nodes.label", issue #1755) quantifies a label predicate over the snapshot's GPU-node set instead of comparing a single reading. Its value grammar is "key=value" (every GPU node carries the label) or "!key" (no GPU node carries the key); it is dispatched by exact name before the scalar path and fails closed on truncated node lists and on an empty GPU-node universe.
Evaluation is deliberately side-effect free and never performs network or cluster I/O; consumers (pkg/validator, pkg/recipe) supply the snapshot context.
Package constraints provides constraint parsing, extraction, and evaluation utilities for comparing recipe constraints against snapshot measurements.
Index ¶
Constants ¶
const ( // OperatorGTE represents ">=" (greater than or equal). OperatorGTE = expr.OperatorGTE // OperatorLTE represents "<=" (less than or equal). OperatorLTE = expr.OperatorLTE // OperatorGT represents ">" (greater than). OperatorGT = expr.OperatorGT // OperatorLT represents "<" (less than). OperatorLT = expr.OperatorLT // OperatorEQ represents "==" (exact match). OperatorEQ = expr.OperatorEQ // OperatorNE represents "!=" (not equal). OperatorNE = expr.OperatorNE // OperatorExact represents no operator (exact string match). OperatorExact = expr.OperatorExact )
const GPUNodesLabelConstraintName = measurement.PathGPUNodesLabel
GPUNodesLabelConstraintName is the node-set constraint form from issue #1755 (declared in the GKE overlays' readiness constraints; ADR-015's GKE gpuStack profile consumes it — #1761). Unlike scalar constraint paths, it does not name a reading the snapshot carries directly; the evaluator synthesizes the GPU-node set from the snapshot's NodeTopology.label readings and quantifies the value predicate over it.
Value grammar (distinct from the scalar operator grammar):
key=value every GPU node carries label key with exactly this value
(an empty value — "key=" — is valid; Kubernetes permits it)
!key no GPU node carries label key (any value)
Both directions fail closed: on truncated node lists (snapshots taken with --max-nodes-per-entry), on an empty GPU-node universe, and on a value that parses as neither form.
The literal lives in pkg/measurement so the constraint-path catalog can accept it as a virtual path (issue #1783) without importing this package.
Variables ¶
This section is empty.
Functions ¶
func ValidateGPUNodesLabelValue ¶ added in v0.19.0
ValidateGPUNodesLabelValue checks a node-set constraint value against the grammar documented on GPUNodesLabelConstraintName ("key=value" or "!key"), snapshot-free. It exists for hermetic structural checks (the recipe-health constraints_wellformed dimension) that must mirror Evaluate's dispatch: the node-set form is deliberately NOT valid under the scalar ParseConstraintExpression grammar, so grading it with the scalar parser would fail every recipe carrying a well-formed node-set constraint.
Types ¶
type CompoundConstraint ¶ added in v0.20.0
type CompoundConstraint = expr.CompoundConstraint
CompoundConstraint represents a constraint expression with OR alternatives of AND-joined terms.
func ParseCompoundConstraint ¶ added in v0.20.0
func ParseCompoundConstraint(expression string) (*CompoundConstraint, error)
ParseCompoundConstraint parses a compound constraint expression that may contain OR clauses ("||") and AND groups (space-separated sub-expressions).
Example: ">= 1.34.3-gke.1318000 < 1.35.0 || >= 1.35.0-gke.2745000"
type ConstraintPath ¶
type ConstraintPath = measurement.Path
ConstraintPath is a parsed fully qualified constraint path.
Parsing and extraction live in pkg/measurement (issue #1783): the recipe loader validates constraint paths against the measurement catalog at load time, and pkg/constraints cannot be imported from pkg/recipe — this package imports pkg/recipe for recipe.Constraint, so the dependency only runs one way. Co-locating the path grammar with the catalog also keeps the two in sync: the catalog's job is to describe exactly the paths Extract resolves.
func ParseConstraintPath ¶
func ParseConstraintPath(path string) (*ConstraintPath, error)
ParseConstraintPath parses a fully qualified constraint path.
This is well-formedness only. Callers that need the path to actually be addressable — that a supported snapshot producer can emit it — want measurement.ValidatePath, which the recipe loader applies to every constraint name at load time.
type EvalResult ¶
type EvalResult struct {
// Passed indicates if the constraint was satisfied.
Passed bool
// Actual is the actual value extracted from the snapshot.
Actual string
// Error contains the error if evaluation failed.
Error error
}
EvalResult represents the result of evaluating a single constraint.
func Evaluate ¶
func Evaluate(constraint recipe.Constraint, snap *snapshotter.Snapshot) EvalResult
Evaluate evaluates a single constraint against a snapshot. Used by the recipe package to filter overlays based on constraint evaluation during snapshot-based recipe generation.
type ParsedConstraint ¶
type ParsedConstraint = expr.ParsedConstraint
ParsedConstraint represents a parsed constraint expression.
func ParseConstraintExpression ¶
func ParseConstraintExpression(expression string) (*ParsedConstraint, error)
ParseConstraintExpression parses a constraint value expression. Examples:
- ">= 1.32.4" -> {Operator: ">=", Value: "1.32.4", IsVersionComparison: true}
- "ubuntu" -> {Operator: "", Value: "ubuntu", IsVersionComparison: false}
- "== 24.04" -> {Operator: "==", Value: "24.04", IsVersionComparison: true}
Source Files
Directories