Documentation
¶
Index ¶
- Constants
- func AreTypesStructurallyCompatible(output, expected *cel.Type, provider *DeclTypeProvider) (bool, error)
- func BaseDeclarations() []cel.EnvOption
- func DefaultEnvironment(options ...EnvOption) (*cel.Env, error)
- func FieldTypeMap(path string, t *apiservercel.DeclType) map[string]*apiservercel.DeclType
- func ListElementType(listType *cel.Type) (*cel.Type, error)
- func SchemaDeclTypeWithMetadata(s common.Schema, isResourceRoot bool) *apiservercel.DeclType
- func TypedEnvironment(schemas map[string]*spec.Schema) (*cel.Env, error)
- type DeclTypeProvider
- func (rt *DeclTypeProvider) EnumValue(enumName string) ref.Val
- func (rt *DeclTypeProvider) EnvOptions(tp types.Provider) ([]cel.EnvOption, error)
- func (rt *DeclTypeProvider) FindDeclType(typeName string) (*apiservercel.DeclType, bool)
- func (rt *DeclTypeProvider) FindIdent(identName string) (ref.Val, bool)
- func (rt *DeclTypeProvider) FindStructFieldNames(typeName string) ([]string, bool)
- func (rt *DeclTypeProvider) FindStructFieldType(typeName, fieldName string) (*types.FieldType, bool)
- func (rt *DeclTypeProvider) FindStructType(typeName string) (*types.Type, bool)
- func (rt *DeclTypeProvider) NativeToValue(val interface{}) ref.Val
- func (rt *DeclTypeProvider) NewValue(typeName string, fields map[string]ref.Val) ref.Val
- func (rt *DeclTypeProvider) SetRecognizeKeywordAsFieldName(recognize bool)
- func (rt *DeclTypeProvider) TypeNames() []string
- func (rt *DeclTypeProvider) WithTypeProvider(tp types.Provider) (*DeclTypeProvider, error)
- type EnvOption
- type Expression
Constants ¶
const ( // TypeNamePrefix is the prefix used for CEL type names when converting OpenAPI schemas. // Used to namespace custom types and avoid conflicts with built-in CEL types. // Example: "__type_schema.spec.ports" for a ports field in the schema resource. TypeNamePrefix = "__type_" )
const XKubernetesPreserveUnknownFields = "x-kubernetes-preserve-unknown-fields"
XKubernetesPreserveUnknownFields is the key for the named open api extension, declaration type metadata field and validator rule metadata field that indicates whether unknown fields should be preserved in the deserialized object. KRO effectively translates these fields into CEL Dyn types.
Variables ¶
This section is empty.
Functions ¶
func AreTypesStructurallyCompatible ¶
func AreTypesStructurallyCompatible(output, expected *cel.Type, provider *DeclTypeProvider) (bool, error)
AreTypesStructurallyCompatible checks if an output type from an expected or executed CEL expression is compatible with an expected type.
This performs deep structural comparison: - For primitives: checks kind equality - For lists: recursively checks element type compatibility - For maps: recursively checks key and value type compatibility - For structs: uses DeclTypeProvider to introspect fields and check all required fields exist with compatible types - For map → struct and struct → map compatibility if fields/keys are structurally compatible
The provider is required for introspecting struct field information. Returns true if types are compatible, false otherwise. If false, the error describes why.
func BaseDeclarations ¶ added in v0.2.0
BaseDeclarations returns the base CEL environment options shared by all kro CEL environments. Includes list/string extensions, optional types, encoders, and Kubernetes CEL libraries (URLs, Regex, Random). The result is cached via sync.Once since these options are stateless.
func DefaultEnvironment ¶
DefaultEnvironment returns the default CEL environment.
func FieldTypeMap ¶
func FieldTypeMap(path string, t *apiservercel.DeclType) map[string]*apiservercel.DeclType
FieldTypeMap constructs a map of the field and object types nested within a given type.
func ListElementType ¶
ListElementType extracts the element type from a CEL list type. Returns the element type if the input is a list type, or an error otherwise. This is useful for inferring the type of forEach iterator variables from the forEach expression's return type.
func SchemaDeclTypeWithMetadata ¶
func SchemaDeclTypeWithMetadata(s common.Schema, isResourceRoot bool) *apiservercel.DeclType
SchemaDeclTypeWithMetadata converts the structural schema to a CEL declaration, or returns nil if the structural schema should not be exposed in CEL expressions. Set isResourceRoot to true for the root of a custom resource or embedded resource.
Schemas with XPreserveUnknownFields not exposed unless they are objects. Array and "maps" schemas are not exposed if their items or additionalProperties schemas are not exposed. Object Properties are not exposed if their schema is not exposed.
The CEL declaration for objects with XPreserveUnknownFields does not expose unknown fields.
This functions acts like [SchemaDeclType] from k8s, but with additional logic to add unknown fields as a metadata field. This can then be used by a DeclTypeProvider to expose unknown fields in CEL expressions on demand without compromising type integrity of other types.
nolint:gocyclo // this function should stay as close to upstream k8s as possible to allow comparisons
Types ¶
type DeclTypeProvider ¶
type DeclTypeProvider struct {
// contains filtered or unexported fields
}
DeclTypeProvider extends the CEL ref.TypeProvider interface and provides an Open API Schema-based type-system.
func NewDeclTypeProvider ¶
func NewDeclTypeProvider(rootTypes ...*apiservercel.DeclType) *DeclTypeProvider
NewDeclTypeProvider returns an Open API Schema-based type-system which is CEL compatible.
func TypedEnvironmentWithProvider ¶ added in v0.2.0
func TypedEnvironmentWithProvider(schemas map[string]*spec.Schema) (*cel.Env, *DeclTypeProvider, error)
TypedEnvironmentWithProvider creates a typed CEL environment. It returns both the environment and the DeclTypeProvider.
func (*DeclTypeProvider) EnvOptions ¶
EnvOptions returns a set of cel.EnvOption values which includes the declaration set as well as a custom ref.TypeProvider.
If the DeclTypeProvider value is nil, an empty []cel.EnvOption set is returned.
func (*DeclTypeProvider) FindDeclType ¶
func (rt *DeclTypeProvider) FindDeclType(typeName string) (*apiservercel.DeclType, bool)
FindDeclType returns the CPT type description which can be mapped to a CEL type.
func (*DeclTypeProvider) FindIdent ¶
func (rt *DeclTypeProvider) FindIdent(identName string) (ref.Val, bool)
func (*DeclTypeProvider) FindStructFieldNames ¶
func (rt *DeclTypeProvider) FindStructFieldNames(typeName string) ([]string, bool)
FindStructFieldNames returns the field names associated with the type, if the type is found.
func (*DeclTypeProvider) FindStructFieldType ¶
func (rt *DeclTypeProvider) FindStructFieldType(typeName, fieldName string) (*types.FieldType, bool)
FindStructFieldType returns a field type given a type name and field name, if found.
Note, the type name for an Open API Schema type is likely to be its qualified object path. If, in the future an object instance rather than a type name were provided, the field resolution might more accurately reflect the expected type model. However, in this case concessions were made to align with the existing CEL interfaces.
func (*DeclTypeProvider) FindStructType ¶
func (rt *DeclTypeProvider) FindStructType(typeName string) (*types.Type, bool)
FindStructType attempts to resolve the typeName provided from the rule's rule-schema, or if not from the embedded ref.TypeProvider.
FindStructType overrides the default type-finding behavior of the embedded TypeProvider.
Note, when the type name is based on the Open API Schema, the name will reflect the object path where the type definition appears.
func (*DeclTypeProvider) NativeToValue ¶
func (rt *DeclTypeProvider) NativeToValue(val interface{}) ref.Val
NativeToValue is an implementation of the ref.TypeAdapter interface which supports conversion of rule values to CEL ref.Val instances.
func (*DeclTypeProvider) SetRecognizeKeywordAsFieldName ¶
func (rt *DeclTypeProvider) SetRecognizeKeywordAsFieldName(recognize bool)
func (*DeclTypeProvider) TypeNames ¶
func (rt *DeclTypeProvider) TypeNames() []string
TypeNames returns the list of type names declared within the DeclTypeProvider object.
func (*DeclTypeProvider) WithTypeProvider ¶
func (rt *DeclTypeProvider) WithTypeProvider(tp types.Provider) (*DeclTypeProvider, error)
WithTypeProvider returns a new DeclTypeProvider that sets the given TypeProvider If the original DeclTypeProvider is nil, the returned DeclTypeProvider is still nil.
type EnvOption ¶
type EnvOption func(*envOptions)
EnvOption is a function that modifies the environment options.
func WithCustomDeclarations ¶
WithCustomDeclarations adds custom declarations to the CEL environment.
func WithListVariables ¶
WithListVariables adds list-typed variable declarations to the CEL environment. Used for collection resources so they support list operations/macros like all() exists(), filter(), and map() etc...
func WithResourceIDs ¶
WithResourceIDs adds resource ids that will be declared as CEL variables.
type Expression ¶ added in v0.2.0
type Expression struct {
// Original is the CEL expression string used for compilation and evaluation.
// For compiled string templates, this contains the generated concatenation
// expression (e.g. `"prefix-" + expr`), not the user's original template.
// See OriginalTemplate for the user-facing form. Set by parser.
Original string
// OriginalTemplate is the user's original string template before compilation
// into a CEL concatenation expression. Only set for compiled templates
// (e.g. "prefix-${expr}" → Original: `"prefix-" + expr`).
OriginalTemplate string
// References lists all identifiers this expression accesses (e.g., "schema", "vpc").
// These are the keys that must be present in the context passed to Eval.
// Set by builder during dependency extraction.
//
// Note: References includes "schema" if used, but schema is NOT a DAG dependency.
// DAG dependencies are tracked separately at Node.Meta.Dependencies.
References []string
// Program is the compiled CEL program. Set by builder after type validation.
// It is stateless and thread-safe, allowing concurrent evaluation.
Program cel.Program
}
Expression wraps a CEL expression with its compiled program and metadata. Programs are compiled once at graph build time and reused across reconciliations. The struct is immutable and thread-safe after construction. It is save to use by multiple runtimes and reconciliations in parallel - thanks to Program being thread-safe.
Lifecycle:
- Parser: creates with Original set (References and Program nil)
- Builder: populates References during dependency extraction (via ast.Inspector)
- Builder: populates Program during compilation (after type validation)
- Runtime: calls Eval() with context containing values for References
func NewUncompiled ¶ added in v0.2.0
func NewUncompiled(expr string) *Expression
NewUncompiled creates an uncompiled Expression with only Original set. Use this in parser/tests where References and Program are set later by builder.
func NewUncompiledSlice ¶ added in v0.2.0
func NewUncompiledSlice(exprs ...string) []*Expression
NewUncompiledSlice creates a slice of uncompiled Expressions from strings. Use this in tests for condition slices (IncludeWhen, ReadyWhen).
func (*Expression) Eval ¶ added in v0.2.0
func (e *Expression) Eval(ctx map[string]any) (any, error)
Eval evaluates the compiled expression and returns the result.
func (*Expression) UserExpression ¶ added in v0.2.0
func (e *Expression) UserExpression() string
UserExpression returns the user-facing expression string for error messages.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package unstructured provides schema-aware conversion of Kubernetes unstructured data to CEL ref.Val values.
|
Package unstructured provides schema-aware conversion of Kubernetes unstructured data to CEL ref.Val values. |