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 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