Documentation
¶
Index ¶
- Constants
- func ContainsToken(tokens []string, target string) bool
- func EnsureStepRunTriggerTokens(ctx context.Context, cl client.Client, key types.NamespacedName, ...) ([]string, error)
- func EnsureTriggerTokens(ctx context.Context, cl client.Client, obj client.Object, annotationKey string, ...) ([]string, error)
- func ParseTriggerTokens(raw string) sets.Set[string]
- func SortedTokens(set sets.Set[string]) []string
- type EngramReconciler
- type ImpulseReconciler
- type StoryReconciler
- type TransportReconciler
Constants ¶
View Source
const (
// StoryFinalizer is the name of the finalizer used by the Story controller.
StoryFinalizer = "story.bubustack.io/finalizer"
)
Variables ¶
This section is empty.
Functions ¶
func ContainsToken ¶ added in v0.1.4
ContainsToken checks if a target token exists in the provided token slice.
Arguments:
- tokens []string: slice of tokens to search.
- target string: token to find.
Returns:
- bool: true if target exists in tokens.
func EnsureStepRunTriggerTokens ¶ added in v0.1.4
func EnsureStepRunTriggerTokens( ctx context.Context, cl client.Client, key types.NamespacedName, tokens ...string, ) ([]string, error)
EnsureStepRunTriggerTokens adds trigger tokens to a StepRun's annotations.
Behavior:
- Fetches the StepRun by key with conflict retry.
- Delegates to EnsureTriggerTokens to add tokens to annotations.
- Returns newly added tokens for caller tracking.
Arguments:
- ctx context.Context: propagated to Get and Patch operations.
- cl client.Client: the Kubernetes client.
- key types.NamespacedName: the StepRun's namespace and name.
- tokens ...string: trigger tokens to add.
Returns:
- []string: newly added tokens.
- error: on Get or Patch failures.
func EnsureTriggerTokens ¶ added in v0.1.4
func EnsureTriggerTokens( ctx context.Context, cl client.Client, obj client.Object, annotationKey string, tokens ...string, ) ([]string, error)
EnsureTriggerTokens trims, deduplicates, and patches annotationKey on the provided object with the supplied trigger tokens.
Behavior:
- Parses existing tokens from the annotation.
- Trims whitespace from each new token.
- Skips tokens that already exist.
- Patches the annotation with the merged, sorted token set.
Arguments:
- ctx context.Context: context for the patch operation.
- cl client.Client: Kubernetes client for performing the merge patch.
- obj client.Object: the object whose annotations will be modified.
- annotationKey string: the annotation key to modify.
- tokens ...string: trigger tokens to add to the annotation.
Returns:
- []string: tokens that were newly added (nil if no changes made).
- error: patch failure or nil on success.
Side Effects:
- Modifies obj's annotations and patches it to the API server.
- Performs merge patch using client.MergeFrom for atomic updates.
func ParseTriggerTokens ¶ added in v0.1.4
ParseTriggerTokens parses a comma-separated trigger token string into a deduplicated set.
Behavior:
- Splits the string by commas.
- Trims whitespace from each token.
- Filters out empty tokens.
- Returns a deduplicated set.
Arguments:
- raw string: comma-separated string of trigger tokens.
Returns:
- sets.String: deduplicated set of non-empty tokens.
func SortedTokens ¶ added in v0.1.4
SortedTokens converts a token set to a deterministically sorted string slice.
This ensures consistent annotation values across different reconciles, preventing unnecessary patch operations due to ordering differences.
Arguments:
- set sets.String: the token set to convert.
Returns:
- []string: sorted slice of tokens.
Types ¶
type EngramReconciler ¶
type EngramReconciler struct {
config.ControllerDependencies
Recorder events.EventRecorder
}
EngramReconciler reconciles Engram resources.
Responsibilities:
- Validate referenced EngramTemplate existence/resolution.
- Publish validation results, usage counts, and trigger statistics into Engram status.
- Emit warning events when template resolution fails (only on meaningful condition transitions).
Anti-storm strategy:
- Engram uses GenerationChangedPredicate so status updates do not requeue itself.
- Story watch is generation-only (spec changes) so Story status updates don't fan-out storms.
- StepRun watch uses a predicate that ignores annotation-only updates, preventing loops caused by trigger-token annotation writes performed during reconciliation.
Observability:
- Structured logs enriched with name/namespace.
- Reconcile timing and errors recorded via metrics.
func (*EngramReconciler) Reconcile ¶
func (r *EngramReconciler) Reconcile(ctx context.Context, req ctrl.Request) (res ctrl.Result, err error)
Reconcile validates the Engram's referenced EngramTemplate, computes Story usage and StepRun trigger statistics, and patches Engram.Status when changes are detected. For more details, check Reconcile and its Result here: - https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.23.0/pkg/reconcile
Behavior:
- Validates the referenced EngramTemplate exists and is resolvable.
- Computes Story usage count via field index.
- Computes trigger count by marking StepRuns with annotation tokens.
- Patches Engram.Status with validation results, usage, and trigger counts.
- Emits warning events only when conditions meaningfully change.
Arguments:
- ctx context.Context: controller context with optional timeout.
- req ctrl.Request: the Engram's namespace and name.
Returns:
- ctrl.Result{}: empty on success.
- ctrl.Result{RequeueAfter: ...}: when trigger backfill is incomplete.
- error: for transient errors to activate controller-runtime backoff.
Side Effects:
- Patches Engram.Status (ObservedGeneration, ValidationStatus/Errors, UsageCount, Triggers, Conditions).
- Patches StepRun metadata.annotations to add trigger-counting tokens.
func (*EngramReconciler) SetupWithManager ¶
func (r *EngramReconciler) SetupWithManager(mgr ctrl.Manager, opts controller.Options) error
SetupWithManager wires the controller watches and predicates.
Behavior:
- Registers the controller for Engram resources with GenerationChangedPredicate.
- Watches EngramTemplates to requeue Engrams by indexed spec.templateRef.name.
- Watches Stories to requeue Engrams referenced by Story steps (deduped).
- Watches StepRuns with a predicate that ignores annotation-only updates.
- Uses generation-only predicates to prevent reconciliation storms.
Arguments:
- mgr ctrl.Manager: the controller-runtime manager.
- opts controller.Options: controller configuration (concurrency, etc.).
Returns:
- error: nil on success, or controller setup error.
Side Effects:
- Registers the event recorder for engram-controller.
type ImpulseReconciler ¶
type ImpulseReconciler struct {
config.ControllerDependencies
Recorder events.EventRecorder
}
ImpulseReconciler reconciles Impulse resources.
Responsibilities:
- Resolve ImpulseTemplate and target Story.
- Resolve execution config and apply overrides.
- Ensure ServiceAccount and RBAC when using managed SA.
- Reconcile Service and workload (Deployment or StatefulSet).
- Aggregate trigger statistics from StoryRuns.
Anti-storm strategy:
- Impulse itself reconciles only on spec changes (GenerationChangedPredicate).
- Owned workloads reconcile only on spec changes (GenerationChangedPredicate).
- StoryRun watch reconciles on meaningful lifecycle transitions only (phase/timestamps), ignoring annotation-only changes caused by token marking.
func (*ImpulseReconciler) Reconcile ¶
func (r *ImpulseReconciler) Reconcile(ctx context.Context, req ctrl.Request) (res ctrl.Result, err error)
Reconcile converges Impulse runtime objects and status. For more details, check Reconcile and its Result here: - https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.23.0/pkg/reconcile
Behavior:
- Applies optional reconcile timeout from operator config.
- Loads Impulse and short-circuits for deletion/terminal phases.
- Loads ImpulseTemplate and target Story, blocking on NotFound.
- Resolves execution config and ensures SA/RBAC, Service, and workload.
- Syncs StoryRun-derived trigger statistics to Impulse status.
- Returns errors for controller-runtime backoff; watches handle re-triggers.
Arguments:
- ctx context.Context: propagated to all sub-operations.
- req ctrl.Request: contains the Impulse namespace and name.
Returns:
- ctrl.Result: typically empty on success; requeue handled by errors/watches.
- error: on transient failures for controller-runtime backoff.
func (*ImpulseReconciler) SetupWithManager ¶
func (r *ImpulseReconciler) SetupWithManager(mgr ctrl.Manager, opts controller.Options) error
SetupWithManager wires Impulse watches with storm-proof predicates.
Behavior:
- Registers the controller for Impulse resources with GenerationChangedPredicate.
- Watches ImpulseTemplates and Stories to requeue dependent Impulses.
- Watches StoryRuns with meaningful-update predicate to update trigger stats.
- Owns Deployments, StatefulSets, and Services with generation-only predicates.
Arguments:
- mgr ctrl.Manager: the controller-runtime manager.
- opts controller.Options: controller configuration (concurrency, etc.).
Returns:
- error: nil on success, or controller setup error.
Side Effects:
- Registers the event recorder for impulse-controller.
type StoryReconciler ¶
type StoryReconciler struct {
config.ControllerDependencies
Recorder events.EventRecorder
// contains filtered or unexported fields
}
StoryReconciler reconciles a Story object.
func (*StoryReconciler) Reconcile ¶
Reconcile converges Story validation status, usage counts, and trigger statistics. For more details, check Reconcile and its Result here: - https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.23.0/pkg/reconcile
Behavior:
- Applies optional reconcile timeout from operator config.
- Loads Story, handles deletion, and ensures finalizer.
- Validates Engram/Transport/Story references and updates status.
- Recomputes usage counts (Impulses) and trigger counts (StoryRuns).
- Returns errors for transient failures; validation failures are recorded in status.
Arguments:
- ctx context.Context: propagated to all sub-operations.
- req ctrl.Request: contains the Story namespace and name.
Returns:
- ctrl.Result: may include RequeueAfter for bounded trigger backfill.
- error: on transient failures for controller-runtime backoff.
func (*StoryReconciler) SetupWithManager ¶
func (r *StoryReconciler) SetupWithManager(mgr ctrl.Manager, opts controller.Options) error
SetupWithManager sets up the controller with the Manager.
Behavior:
- Registers the controller for Story resources with GenerationChangedPredicate.
- Watches Engrams and EngramTemplates to revalidate dependent Stories.
- Watches nested Stories for executeStory step validation.
- Watches StoryRuns with trigger-relevant predicate for trigger counting.
- Watches Impulses with usage-relevant predicate for usage counting.
- Avoids global WithEventFilter to allow watch-specific predicates.
Arguments:
- mgr ctrl.Manager: the controller-runtime manager.
- opts controller.Options: controller configuration (concurrency, etc.).
Returns:
- error: nil on success, or controller setup error.
Side Effects:
- Registers the event recorder for story-controller.
type TransportReconciler ¶ added in v0.1.4
type TransportReconciler struct {
config.ControllerDependencies
Recorder events.EventRecorder
// contains filtered or unexported fields
}
TransportReconciler validates Transport CRDs and tracks usage across Stories.
func (*TransportReconciler) Reconcile ¶ added in v0.1.4
Reconcile validates the Transport spec, gathers per-binding capabilities, and patches status so operators see up-to-date usage counts and readiness info.
Behavior:
- Fetches the Transport and validates its spec via validateTransport.
- Counts Stories referencing the Transport for usage tracking.
- Collects codec capabilities and binding health from TransportBindings.
- Updates Transport status with validation results, capabilities, and metrics.
Arguments:
- ctx context.Context: propagated to all sub-operations.
- req ctrl.Request: contains the Transport name (cluster-scoped).
Returns:
- ctrl.Result: empty on success.
- error: on validation, capability collection, or status update failures.
func (*TransportReconciler) SetupWithManager ¶ added in v0.1.4
func (r *TransportReconciler) SetupWithManager(mgr ctrl.Manager, opts controller.Options) error
SetupWithManager wires the controller into controller-runtime.
Behavior:
- Sets MaxConcurrentReconciles to 2 if not specified.
- Registers the event recorder for transport-controller.
- Watches TransportBindings to requeue parent Transports.
- Watches Story spec-generation changes to requeue referenced Transports.
Arguments:
- mgr ctrl.Manager: the controller-runtime manager.
- opts controller.Options: controller configuration.
Returns:
- error: nil on success, or controller setup error.
Source Files
¶
Directories
Click to show internal directories.
Click to hide internal directories.