graph

Documentation

Index

• Constants
• Variables
• type Builder
  • func NewBuilder(schemaResolver resolver.SchemaResolver) *Builder
  • func (b *Builder) NewResourceGraphDefinition(rg *v1beta1.ResourceGraph, xrSchema *spec.Schema, rgdConfig RGDConfig) (*Graph, error)
• type ForEachDimension
• type Graph
• type Node
  • func (n *Node) DeepCopy() *Node
• type NodeMeta
• type NodeType
  • func (t NodeType) String() string
• type RGDConfig

Constants

const (
	// SchemaVarName is the variable name for accessing instance spec in CEL.
	SchemaVarName = "schema"
	// InstanceNodeID is the ID of the instance node (same as SchemaVarName since
	// that's how it's accessed in CEL expressions).
	InstanceNodeID = SchemaVarName
	// EachVarName is the variable name for collection item iteration in CEL.
	EachVarName = "each"
)

Well-known node/variable identifiers used in CEL expressions.

const (
	// MetadataNamePath is the path to the resource name field.
	MetadataNamePath = "metadata.name"
	// MetadataNamespacePath is the path to the resource namespace field.
	MetadataNamespacePath = "metadata.namespace"
)

often used field paths in resource templates.

Variables

var (
	// ErrNamingConvention is the base error message for naming convention violations
	ErrNamingConvention = "naming convention violation"
)

Types

type Builder

type Builder struct {
	// contains filtered or unexported fields
}

Builder is an object that is responsible for constructing and managing resourceGraphDefinitions. It is responsible for transforming the resourceGraphDefinition CRD into a runtime representation that can be used to create the resources in the cluster.

The GraphBuild performs several key functions:

  1/ It validates the resource definitions and their naming conventions.
  2/ It interacts with the API Server to retrieve the OpenAPI schema for the
     resources, and validates the resources against the schema.
  3/ Extracts and processes the CEL expressions from the resources definitions.
  4/ Builds the dependency graph between the resources, by inspecting the CEL
	    expressions.
  5/ It infers and generates the schema for the instance resource, based on the
		SimpleSchema format.

If any of the above steps fail, the Builder will return an error.

The resulting ResourceGraphDefinition object is a fully processed and validated representation of a resource graph definition CR, it's underlying resources, and the relationships between the resources. This object can be used to instantiate a "runtime" data structure that can be used to create the resources in the cluster.

func NewBuilder

func NewBuilder(schemaResolver resolver.SchemaResolver) *Builder

NewBuilder creates a new GraphBuilder instance.

func (*Builder) NewResourceGraphDefinition

func (b *Builder) NewResourceGraphDefinition(rg *v1beta1.ResourceGraph, xrSchema *spec.Schema, rgdConfig RGDConfig) (*Graph, error)

NewResourceGraphDefinition creates a new ResourceGraphDefinition object from the given ResourceGraphDefinition CRD. The ResourceGraphDefinition object is a fully processed and validated representation of the resource graph definition CRD, it's underlying resources, and the relationships between the resources.

type ForEachDimension

type ForEachDimension struct {
	// Name is the iterator variable name (e.g., "region")
	Name string
	// Expression is the compiled CEL expression that returns a list (e.g., "schema.spec.regions")
	Expression *krocel.Expression
}

ForEachDimension represents a parsed forEach dimension from an RGD resource.

type Graph

type Graph struct {
	// DAG is the directed acyclic graph of node dependencies.
	DAG *dag.DirectedAcyclicGraph[string]

	// Instance is the instance node (the generated CRD instance).
	Instance *Node

	// Nodes maps node ID to immutable node spec.
	Nodes map[string]*Node

	// Resources is an alias for Nodes kept for backward compatibility in tests and tooling.
	Resources map[string]*Node

	// TopologicalOrder is the sorted order of node IDs for processing.
	// This excludes the instance node.
	TopologicalOrder []string

	// CRD is the generated CustomResourceDefinition for the instance.
	CRD *extv1.CustomResourceDefinition

	// ResourceSchemas maps node ID to the OpenAPI schema for that resource.
	// Includes resource schemas (keyed by resource ID) and the instance schema
	// (keyed by InstanceNodeID). Used at runtime for schema-aware CEL value conversion.
	ResourceSchemas map[string]*spec.Schema
}

Graph represents a processed ResourceGraphDefinition. It contains the DAG and immutable node specs produced by the builder.

type Node

type Node struct {
	// Meta contains identification metadata (ID, Type, GVR, etc.)
	Meta NodeMeta

	// Template is the resource template with CEL expressions.
	// This is the original object from the RGD with expressions intact.
	Template *unstructured.Unstructured

	// Variables holds the CEL expression fields found in the template.
	Variables []*variable.ResourceField

	// IncludeWhen are compiled CEL expressions that must all evaluate to true
	// for this resource to be included. Empty means always include.
	IncludeWhen []*krocel.Expression

	// ReadyWhen are compiled CEL expressions that must all evaluate to true
	// for this resource to be considered ready.
	ReadyWhen []*krocel.Expression

	// ForEach holds the forEach dimensions for collection resources.
	// nil or empty means this is not a collection.
	ForEach []ForEachDimension
}

Node is the immutable node spec produced by the builder. It contains the template, variables, and conditions for a resource. No CRD/schema references are kept here - schemas are only used during build for CEL type-checking.

func (*Node) DeepCopy

func (n *Node) DeepCopy() *Node

DeepCopy creates a deep copy of the Node. Use this when runtime needs a per-runtime clone to avoid shared slices/maps.

type NodeMeta

type NodeMeta struct {
	// ID is the unique identifier of the node within the graph.
	ID string
	// Index is the position of this node in the original RGD resource list.
	// Used to preserve user-defined ordering when building the dependency graph.
	Index int
	// Type identifies the kind of node (Resource, Collection, External, Instance).
	Type NodeType
	// NOTE: GVR and Namespaced removed — Crossplane manages resource identity and namespace scoping.
	// Dependencies lists the IDs of nodes this node depends on.
	Dependencies []string
}

NodeMeta contains immutable metadata about a node. This is grouped separately for clarity and to distinguish identification data from behavioral data.

type NodeType

type NodeType int

NodeType identifies the kind of node in the resource graph. This is set by the builder based on the resource definition.

const (
	// NodeTypeResource is a regular managed resource.
	NodeTypeResource NodeType = iota
	// NodeTypeCollection is a forEach collection that expands into multiple resources.
	NodeTypeCollection
	// NodeTypeExternal is an external reference (read-only, not applied).
	NodeTypeExternal
	// NodeTypeInstance is the instance node (ID: "instance").
	NodeTypeInstance
	// NodeTypeExternalCollection is an external reference with a label selector
	// that matches multiple resources (read-only collection, not applied).
	NodeTypeExternalCollection
)

func (NodeType) String

func (t NodeType) String() string

String returns a human-readable string for the node type.

type RGDConfig

type RGDConfig struct {
	MaxCollectionSize          int
	MaxCollectionDimensionSize int
}

RGDConfig holds RGD runtime configuration parameters.