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 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 struct {
// Alternatives holds the OR clauses; each inner slice is an AND group.
Alternatives [][]ParsedConstraint
// contains filtered or unexported fields
}
CompoundConstraint is a disjunction (OR) of conjunction (AND) groups of ParsedConstraints. It evaluates as true when at least one AND group is fully satisfied. This supports per-track GKE version floors such as:
>= 1.34.3-gke.1318000 < 1.35.0 || >= 1.35.0-gke.2745000
which the single-expression ParseConstraintExpression cannot represent.
No overlay or mixin emits compound expressions yet; this is groundwork for per-track GB300 GKE version floors. See #1985.
func ParseCompoundConstraint ¶ added in v0.20.0
func ParseCompoundConstraint(expr string) (*CompoundConstraint, error)
ParseCompoundConstraint parses a compound constraint expression that may contain OR clauses ("||") and AND groups (space-separated sub-expressions). Simple single-term expressions ("ubuntu", ">= 1.32.4") are handled as a degenerate case with one alternative containing one term.
Examples:
">= 1.32.4" ">= 1.34.3-gke.1318000 < 1.35.0 || >= 1.35.0-gke.2745000"
func (*CompoundConstraint) Evaluate ¶ added in v0.20.0
func (cc *CompoundConstraint) Evaluate(actual string) (bool, error)
Evaluate evaluates the compound constraint against an actual value. Returns true if at least one OR alternative is fully satisfied (all AND terms in that group pass). If any individual term evaluation returns an error, the error is propagated immediately (fail-closed).
func (*CompoundConstraint) String ¶ added in v0.20.0
func (cc *CompoundConstraint) String() string
String returns the original expression string.
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 Operator ¶
type Operator string
Operator represents a comparison operator in constraint expressions.
const ( // OperatorGTE represents ">=" (greater than or equal). OperatorGTE Operator = ">=" // OperatorLTE represents "<=" (less than or equal). OperatorLTE Operator = "<=" // OperatorGT represents ">" (greater than). OperatorGT Operator = ">" // OperatorLT represents "<" (less than). OperatorLT Operator = "<" // OperatorEQ represents "==" (exact match). OperatorEQ Operator = "==" // OperatorNE represents "!=" (not equal). OperatorNE Operator = "!=" // OperatorExact represents no operator (exact string match). OperatorExact Operator = "" )
type ParsedConstraint ¶
type ParsedConstraint struct {
// Operator is the comparison operator (or empty for exact match).
Operator Operator
// Value is the expected value after the operator.
Value string
// IsVersionComparison indicates if this should be treated as a version comparison.
IsVersionComparison bool
}
ParsedConstraint represents a parsed constraint expression.
func ParseConstraintExpression ¶
func ParseConstraintExpression(expr 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: false}
func (*ParsedConstraint) Evaluate ¶
func (pc *ParsedConstraint) Evaluate(actual string) (bool, error)
Evaluate evaluates the constraint against an actual value. Returns true if the constraint is satisfied, false otherwise.
func (*ParsedConstraint) String ¶
func (pc *ParsedConstraint) String() string
String returns a string representation of the parsed constraint.
Source Files