instance

Documentation

Index

• Constants
• type CollectionInfo
• type ConditionsMarker
  • func NewConditionsMarkerFor(obj *unstructured.Unstructured) *ConditionsMarker
  • func (m *ConditionsMarker) GraphResolutionFailed(msg string, args ...any)
  • func (m *ConditionsMarker) GraphResolved()
  • func (m *ConditionsMarker) InstanceManaged()
  • func (m *ConditionsMarker) InstanceNotManaged(format string, a ...any)
  • func (m *ConditionsMarker) ResourcesNotReady(msg string, args ...any)
  • func (m *ConditionsMarker) ResourcesReady()
  • func (m *ConditionsMarker) ResourcesUnderDeletion(msg string, args ...any)
• type Controller
  • func NewController(log logr.Logger, reconcileConfig ReconcileConfig, ...) *Controller
  • func (c *Controller) Reconcile(ctx context.Context, req ctrl.Request) (err error)
• type InstanceState
• type NodeState
  • func (st *NodeState) SetDeleted()
  • func (st *NodeState) SetDeleting()
  • func (st *NodeState) SetError(err error)
  • func (st *NodeState) SetInProgress()
  • func (st *NodeState) SetReady()
  • func (st *NodeState) SetSkipped()
  • func (st *NodeState) SetWaitingForReadiness(err error)
• type ReconcileConfig
• type ReconcileContext
  • func NewReconcileContext(ctx context.Context, log logr.Logger, gvr schema.GroupVersionResource, ...) *ReconcileContext
  • func (rcx *ReconcileContext) InstanceClient() dynamic.ResourceInterface
• type StateManager
  • func (s *StateManager) NewNodeState(id string) *NodeState
  • func (s *StateManager) NodeErrors() error
  • func (s *StateManager) Update()

Constants

const (
	// NodeStateInProgress is the initial state when a node starts being processed.
	// Set at the beginning of processNode before any operations.
	NodeStateInProgress = "IN_PROGRESS"
	// NodeStateDeleting means delete was called but the node still exists.
	// Set when deletion is initiated but not yet confirmed.
	NodeStateDeleting = "DELETING"
	// NodeStateSkipped means the node was not applied.
	// Set when includeWhen=false, dependency is skipped, or external ref during deletion.
	NodeStateSkipped = "SKIPPED"
	// NodeStateError means something failed.
	// Set when resolution, apply, or delete fails.
	NodeStateError = "ERROR"
	// NodeStateSynced means the node was applied and is ready.
	// Set when apply succeeds and readyWhen is satisfied.
	NodeStateSynced = "SYNCED"
	// NodeStateDeleted means the node no longer exists.
	// Set when deletion is confirmed or resource was not found.
	NodeStateDeleted = "DELETED"
	// NodeStateWaitingForReadiness means apply succeeded but readyWhen is not satisfied.
	// Set when apply succeeds but readyWhen evaluates to false.
	NodeStateWaitingForReadiness = "WAITING_FOR_READINESS"
)

NodeState values track the lifecycle of individual nodes during reconciliation.

const (
	Ready           = "Ready"
	InstanceManaged = "InstanceManaged"
	GraphResolved   = "GraphResolved"
	ResourcesReady  = "ResourcesReady"
)

const FieldManagerForLabeler = "kro.run/labeller"

FieldManagerForLabeler is the field manager name used when applying labels.

Types

type CollectionInfo

type CollectionInfo struct {
	Index int
	Size  int
}

CollectionInfo holds collection item metadata for decorator.

type ConditionsMarker

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

func NewConditionsMarkerFor

func NewConditionsMarkerFor(obj *unstructured.Unstructured) *ConditionsMarker

func (*ConditionsMarker) GraphResolutionFailed

func (m *ConditionsMarker) GraphResolutionFailed(msg string, args ...any)

GraphResolutionFailed signals there was an issue creating the runtime graph or resolving resources.

func (*ConditionsMarker) GraphResolved

func (m *ConditionsMarker) GraphResolved()

GraphResolved signals the runtime graph has been created and resources resolved.

func (*ConditionsMarker) InstanceManaged

func (m *ConditionsMarker) InstanceManaged()

InstanceManaged signals the instance has proper finalizers and labels set.

func (*ConditionsMarker) InstanceNotManaged

func (m *ConditionsMarker) InstanceNotManaged(format string, a ...any)

InstanceNotManaged signals there was an issue setting up the instance management.

func (*ConditionsMarker) ResourcesNotReady

func (m *ConditionsMarker) ResourcesNotReady(msg string, args ...any)

ResourcesNotReady signals there are resources in the graph that are not ready.

func (*ConditionsMarker) ResourcesReady

func (m *ConditionsMarker) ResourcesReady()

ResourcesReady signals all resources in the graph are created and ready.

func (*ConditionsMarker) ResourcesUnderDeletion

func (m *ConditionsMarker) ResourcesUnderDeletion(msg string, args ...any)

ResourcesUnderDeletion signals the controller is currently deleting resources.

type Controller

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

Controller manages the reconciliation of a single instance of a ResourceGraphDefinition, / it is responsible for reconciling the instance and its sub-resources.

The controller is responsible for the following: - Reconciling the instance - Reconciling the sub-resources of the instance - Updating the status of the instance - Managing finalizers, owner references and labels - Handling errors and retries - Performing cleanup operations (garbage collection)

For each instance of a ResourceGraphDefinition, the controller creates a new instance of the InstanceGraphReconciler to manage the reconciliation of the instance and its sub-resources.

It is important to state that when the controller is reconciling an instance, it creates and uses a new instance of the ResourceGraphDefinitionRuntime to uniquely manage the state of the instance and its sub-resources. This ensure that at each reconciliation loop, the controller is working with a fresh state of the instance and its sub-resources. Controller owns reconciliation for instances of a ResourceGraphDefinition.

func NewController

func NewController(
	log logr.Logger,
	reconcileConfig ReconcileConfig,
	gvr schema.GroupVersionResource,
	rgd *graph.Graph,
	client kroclient.SetInterface,
	labeler metadata.Labeler,
) *Controller

NewController constructs a new controller with static RGD.

func (*Controller) Reconcile

func (c *Controller) Reconcile(ctx context.Context, req ctrl.Request) (err error)

Reconcile implements the controller-runtime Reconcile interface.

type InstanceState

type InstanceState string

InstanceState represents high-level reconciliation state for an instance.

const (
	// InstanceStateInProgress means reconciliation is ongoing.
	InstanceStateInProgress InstanceState = "IN_PROGRESS"
	// InstanceStateFailed is a legacy state kept for compatibility.
	InstanceStateFailed InstanceState = "FAILED"
	// InstanceStateActive means all nodes reached terminal success states.
	InstanceStateActive InstanceState = "ACTIVE"
	// InstanceStateDeleting means deletion workflow is running.
	InstanceStateDeleting InstanceState = "DELETING"
	// InstanceStateError means reconciliation hit an error.
	InstanceStateError InstanceState = "ERROR"
)

type NodeState

type NodeState struct {
	State string
	Err   error
}

NodeState holds the current reconciliation state for a node. Prefer mutating this struct via its helper methods.

func (*NodeState) SetDeleted

func (st *NodeState) SetDeleted()

SetDeleted marks the node as deleted and clears any error.

func (*NodeState) SetDeleting

func (st *NodeState) SetDeleting()

SetDeleting marks the node as deletion-in-progress and clears any error.

func (*NodeState) SetError

func (st *NodeState) SetError(err error)

SetError marks the node as failed and records err.

func (*NodeState) SetInProgress

func (st *NodeState) SetInProgress()

SetInProgress marks the node as in progress and clears any error.

func (*NodeState) SetReady

func (st *NodeState) SetReady()

SetReady marks the node as ready/synced and clears any error.

func (*NodeState) SetSkipped

func (st *NodeState) SetSkipped()

SetSkipped marks the node as intentionally skipped and clears any error.

func (*NodeState) SetWaitingForReadiness

func (st *NodeState) SetWaitingForReadiness(err error)

SetWaitingForReadiness marks the node as waiting for readiness, optionally recording err.

type ReconcileConfig

type ReconcileConfig struct {
	// DefaultRequeueDuration is the default duration to wait before requeuing a
	// a reconciliation if no specific requeue time is set.
	DefaultRequeueDuration time.Duration
	// DeletionGraceTimeDuration is the duration to wait after initializing a resource
	// deletion before considering it failed
	// Not implemented.
	DeletionGraceTimeDuration time.Duration
	// DeletionPolicy is the deletion policy to use when deleting resources in the graph
	// TODO(a-hilaly): need to define think the different deletion policies we need to
	// support.
	DeletionPolicy string
}

ReconcileConfig holds configuration parameters for the reconciliation process. It allows the customization of various aspects of the controller's behavior.

type ReconcileContext

type ReconcileContext struct {
	Ctx context.Context
	Log logr.Logger

	GVR        schema.GroupVersionResource
	Client     dynamic.Interface
	RestMapper meta.RESTMapper
	Labeler    metadata.Labeler

	Runtime  runtime.Interface
	Instance *unstructured.Unstructured
	Config   ReconcileConfig

	Mark         *ConditionsMarker
	StateManager *StateManager
}

func NewReconcileContext

func NewReconcileContext(
	ctx context.Context,
	log logr.Logger,
	gvr schema.GroupVersionResource,
	client dynamic.Interface,
	restMapper meta.RESTMapper,
	labeler metadata.Labeler,
	rt runtime.Interface,
	config ReconcileConfig,
	instance *unstructured.Unstructured,
) *ReconcileContext

NewReconcileContext constructs a ReconcileContext for a single reconciliation cycle. It bundles all dependencies needed to reconcile an instance's resources:

• client/restMapper: for Kubernetes API operations
• labeler: for applying kro metadata labels to resources
• rt: the runtime containing resolved resource templates, and helpers to figure out readiness, inclusion etc...
• instance: the instance CR being reconciled

It also initializes internal state (Mark for conditions, StateManager for node states).

func (*ReconcileContext) InstanceClient

func (rcx *ReconcileContext) InstanceClient() dynamic.ResourceInterface

type StateManager

type StateManager struct {
	State        InstanceState
	NodeStates   map[string]*NodeState
	ReconcileErr error
}

StateManager tracks instance and node states during reconciliation. It is not safe for concurrent use; reconciliation processes nodes sequentially.

func (*StateManager) NewNodeState

func (s *StateManager) NewNodeState(id string) *NodeState

NewNodeState initializes and registers node state. Callers should prefer this over allocating NodeState directly.

func (*StateManager) NodeErrors

func (s *StateManager) NodeErrors() error

NodeErrors aggregates errors across all node states.

func (*StateManager) Update

func (s *StateManager) Update()

Update recomputes the instance state from node states.