cel

Documentation

Index

• Constants
• func MapIsCorrelatable(mapType *string) bool
• func UnstructuredToVal(unstructured interface{}, schema *structuralschema.Structural) ref.Val
• func ValidFieldPath(jsonPath string, schema *schema.Structural, options ...ValidFieldPathOption) (validFieldPath *field.Path, foundSchema *schema.Structural, err error)
• type CompilationResult
  • func Compile(s *schema.Structural, declType *apiservercel.DeclType, perCallLimit uint64, ...) ([]CompilationResult, error)
• type EnvLoader
  • func NewExpressionsEnvLoader() EnvLoader
  • func StoredExpressionsEnvLoader() EnvLoader
• type Option
  • func WithRatcheting(correlation *common.CorrelatedObject) Option
• type ValidFieldPathOption
  • func WithFieldPathAllowArrayNotation(allow bool) ValidFieldPathOption
• type Validator
  • func NewValidator(s *schema.Structural, isResourceRoot bool, perCallLimit uint64) *Validator
  • func (s *Validator) Validate(ctx context.Context, fldPath *field.Path, sts *schema.Structural, ...) (errs field.ErrorList, remainingBudget int64)

Constants

const (
	// ScopedVarName is the variable name assigned to the locally scoped data element of a CEL validation
	// expression.
	ScopedVarName = "self"

	// OldScopedVarName is the variable name assigned to the existing value of the locally scoped data element of a
	// CEL validation expression.
	OldScopedVarName = "oldSelf"
)

Functions

func MapIsCorrelatable

func MapIsCorrelatable(mapType *string) bool

MapIsCorrelatable returns true if the mapType can be used to correlate the data elements of a map after an update with the data elements of the map from before the updated.

func UnstructuredToVal

func UnstructuredToVal(unstructured interface{}, schema *structuralschema.Structural) ref.Val

UnstructuredToVal converts a Kubernetes unstructured data element to a CEL Val. The root schema of custom resource schema is expected contain type meta and object meta schemas. If Embedded resources do not contain type meta and object meta schemas, they will be added automatically.

func ValidFieldPath

func ValidFieldPath(jsonPath string, schema *schema.Structural, options ...ValidFieldPathOption) (validFieldPath *field.Path, foundSchema *schema.Structural, err error)

ValidFieldPath validates that jsonPath is a valid JSON Path containing only field and map accessors that are valid for the given schema, and returns a field.Path representation of the validated jsonPath or an error.

Types

type CompilationResult

type CompilationResult struct {
	Program cel.Program
	Error   *apiservercel.Error
	// If true, the compiled expression contains a reference to the identifier "oldSelf".
	UsesOldSelf bool
	// Represents the worst-case cost of the compiled expression in terms of CEL's cost units, as used by cel.EstimateCost.
	MaxCost uint64
	// MaxCardinality represents the worse case number of times this validation rule could be invoked if contained under an
	// unbounded map or list in an OpenAPIv3 schema.
	MaxCardinality uint64
	// MessageExpression represents the cel Program that should be evaluated to generate an error message if the rule
	// fails to validate. If no MessageExpression was given, or if this expression failed to compile, this will be nil.
	MessageExpression cel.Program
	// MessageExpressionError represents an error encountered during compilation of MessageExpression. If no error was
	// encountered, this will be nil.
	MessageExpressionError *apiservercel.Error
	// MessageExpressionMaxCost represents the worst-case cost of the compiled MessageExpression in terms of CEL's cost units,
	// as used by cel.EstimateCost.
	MessageExpressionMaxCost uint64
	// NormalizedRuleFieldPath represents the relative fieldPath specified by user after normalization.
	NormalizedRuleFieldPath string
}

CompilationResult represents the cel compilation result for one rule

func Compile

func Compile(s *schema.Structural, declType *apiservercel.DeclType, perCallLimit uint64, baseEnvSet *environment.EnvSet, envLoader EnvLoader) ([]CompilationResult, error)

Compile compiles all the XValidations rules (without recursing into the schema) and returns a slice containing a CompilationResult for each ValidationRule, or an error. declType is expected to be a CEL DeclType corresponding to the structural schema. Each CompilationResult may contain:

• non-nil Program, nil Error: The program was compiled successfully
• nil Program, non-nil Error: Compilation resulted in an error
• nil Program, nil Error: The provided rule was empty so compilation was not attempted

perCallLimit was added for testing purpose only. Callers should always use const PerCallLimit from k8s.io/apiserver/pkg/apis/cel/config.go as input. baseEnv is used as the base CEL environment, see common.BaseEnvironment.

type EnvLoader

type EnvLoader interface {
	// RuleEnv returns the appropriate environment from the EnvSet for the given CEL rule.
	RuleEnv(envSet *environment.EnvSet, expression string) *cel.Env
	// MessageExpressionEnv returns the appropriate environment from the EnvSet for the given
	// CEL messageExpressions.
	MessageExpressionEnv(envSet *environment.EnvSet, expression string) *cel.Env
}

EnvLoader delegates the decision of which CEL environment to use for each expression. Callers should return the appropriate CEL environment based on the guidelines from environment.NewExpressions and environment.StoredExpressions.

func NewExpressionsEnvLoader

func NewExpressionsEnvLoader() EnvLoader

NewExpressionsEnvLoader creates an EnvLoader that always uses the NewExpressions environment type.

func StoredExpressionsEnvLoader

func StoredExpressionsEnvLoader() EnvLoader

StoredExpressionsEnvLoader creates an EnvLoader that always uses the StoredExpressions environment type.

type Option

type Option func(*options)

func WithRatcheting

func WithRatcheting(correlation *common.CorrelatedObject) Option

type ValidFieldPathOption

type ValidFieldPathOption func(*validFieldPathOptions)

ValidFieldPathOption provides vararg options for ValidFieldPath.

func WithFieldPathAllowArrayNotation

func WithFieldPathAllowArrayNotation(allow bool) ValidFieldPathOption

WithFieldPathAllowArrayNotation sets of array annotation ('[<index or map key>]') is allowed in field paths. Defaults to true

type Validator

type Validator struct {
	Items      *Validator
	Properties map[string]Validator

	AdditionalProperties *Validator
	// contains filtered or unexported fields
}

Validator parallels the structure of schema.Structural and includes the compiled CEL programs for the x-kubernetes-validations of each schema node.

func NewValidator

func NewValidator(s *schema.Structural, isResourceRoot bool, perCallLimit uint64) *Validator

NewValidator returns compiles all the CEL programs defined in x-kubernetes-validations extensions of the Structural schema and returns a custom resource validator that contains nested validators for all items, properties and additionalProperties that transitively contain validator rules. Returns nil if there are no validator rules in the Structural schema. May return a validator containing only errors. Adding perCallLimit as input arg for testing purpose only. Callers should always use const PerCallLimit from k8s.io/apiserver/pkg/apis/cel/config.go as input

func (*Validator) Validate

func (s *Validator) Validate(ctx context.Context, fldPath *field.Path, sts *schema.Structural, obj, oldObj interface{}, costBudget int64, opts ...Option) (errs field.ErrorList, remainingBudget int64)

Validate validates all x-kubernetes-validations rules in Validator against obj and returns any errors. If the validation rules exceed the costBudget, subsequent evaluations will be skipped, the list of errs returned will not be empty, and a negative remainingBudget will be returned. Most callers can ignore the returned remainingBudget value unless another validate call is going to be made context is passed for supporting context cancellation during cel validation