ctrlfwk

func (*CustomResource[K]) GetCleanCustomResource ¶

func (cr *CustomResource[K]) GetCleanCustomResource() K

GetCleanCustomResource gives back the resource that was stored previously unedited of any changes that the resource may have went through, It is especially useful to generate patches between the time it was first seen and the second time.

func (*CustomResource[K]) GetCustomResource ¶

func (cr *CustomResource[K]) GetCustomResource() K

GetCustomResource gives back the resource that was stored previously, This resource can be edited as it should always be a client.Object which is a pointer to something

func (*CustomResource[K]) SetCustomResource ¶

func (cr *CustomResource[K]) SetCustomResource(key K)

SetCustomResource sets the resource and also the base resource, It should only be used once per reconciliation.

func (*Dependency[CustomResourceType, ContextType, DependencyType]) AfterReconcile ¶

func (c *Dependency[CustomResourceType, ContextType, DependencyType]) AfterReconcile(ctx ContextType, resource client.Object) error

func (*Dependency[CustomResourceType, ContextType, DependencyType]) BeforeReconcile ¶

func (c *Dependency[CustomResourceType, ContextType, DependencyType]) BeforeReconcile(ctx ContextType) error

func (*Dependency[CustomResourceType, ContextType, DependencyType]) Get ¶

func (c *Dependency[CustomResourceType, ContextType, DependencyType]) Get() client.Object

func (*Dependency[CustomResourceType, ContextType, DependencyType]) ID ¶

func (c *Dependency[CustomResourceType, ContextType, DependencyType]) ID() string

func (*Dependency[CustomResourceType, ContextType, DependencyType]) IsOptional ¶

func (c *Dependency[CustomResourceType, ContextType, DependencyType]) IsOptional() bool

func (*Dependency[CustomResourceType, ContextType, DependencyType]) IsReady ¶

func (c *Dependency[CustomResourceType, ContextType, DependencyType]) IsReady() bool

func (*Dependency[CustomResourceType, ContextType, DependencyType]) Key ¶

func (c *Dependency[CustomResourceType, ContextType, DependencyType]) Key() types.NamespacedName

func (*Dependency[CustomResourceType, ContextType, DependencyType]) Kind ¶

func (c *Dependency[CustomResourceType, ContextType, DependencyType]) Kind() string

func (*Dependency[CustomResourceType, ContextType, DependencyType]) New ¶

func (c *Dependency[CustomResourceType, ContextType, DependencyType]) New() client.Object

func (*Dependency[CustomResourceType, ContextType, DependencyType]) Set ¶

func (c *Dependency[CustomResourceType, ContextType, DependencyType]) Set(obj client.Object)

func (*Dependency[CustomResourceType, ContextType, DependencyType]) ShouldAddManagedByAnnotation ¶

func (c *Dependency[CustomResourceType, ContextType, DependencyType]) ShouldAddManagedByAnnotation() bool

func (*Dependency[CustomResourceType, ContextType, DependencyType]) ShouldWaitForReady ¶

func (c *Dependency[CustomResourceType, ContextType, DependencyType]) ShouldWaitForReady() bool

func (*DependencyBuilder[CustomResourceType, ContextType, DependencyType]) Build ¶

func (b *DependencyBuilder[CustomResourceType, ContextType, DependencyType]) Build() *Dependency[CustomResourceType, ContextType, DependencyType]

Build constructs and returns the final Dependency instance with all configured options.

This method finalizes the builder pattern and creates the dependency that can be used in reconciliation steps. The returned dependency contains all the configuration specified through the builder methods.

The dependency must be used with appropriate reconciliation steps (such as ResolveDynamicDependenciesStep) to actually perform the dependency resolution.

Returns a configured Dependency instance ready for use in reconciliation.

func (*DependencyBuilder[CustomResourceType, ContextType, DependencyType]) WithAddManagedByAnnotation ¶

func (b *DependencyBuilder[CustomResourceType, ContextType, DependencyType]) WithAddManagedByAnnotation(add bool) *DependencyBuilder[CustomResourceType, ContextType, DependencyType]

WithAddManagedByAnnotation controls whether to add a "managed-by" annotation to the dependency resource.

When enabled, this adds metadata to help identify which controller is managing or depending on this resource. This is useful for:

• Debugging resource relationships
• Resource lifecycle management
• Avoiding conflicts between controllers

Also, when enabled, if the reconciler has a Watcher configured, it will automatically watch for changes to this dependency resource and trigger reconciliations accordingly.

This is not enabled by default to avoid unnecessary annotations on resources.

The annotation typically follows the format:

"dependencies.ctrlfwk.com/managed-by": "[{'name':'<controller-name>','namespace':'<controller-namespace>','gvk':{'group':'<group>','version':'<version>','kind':'<kind>'}}]"

Example:

.WithAddManagedByAnnotation(true) // Mark this resource as managed by our controller

func (*DependencyBuilder[CustomResourceType, ContextType, DependencyType]) WithAfterReconcile ¶

func (b *DependencyBuilder[CustomResourceType, ContextType, DependencyType]) WithAfterReconcile(f func(ctx ContextType, resource DependencyType) error) *DependencyBuilder[CustomResourceType, ContextType, DependencyType]

WithAfterReconcile registers a hook function to execute after successful dependency resolution.

This function is called with the resolved dependency resource and can be used for post-processing, validation, or updating your custom resource's status. If the function returns an error, the reconciliation will fail.

The resource parameter contains the current state of the resolved dependency.

Common use cases:

• Extracting and caching dependency data
• Updating custom resource status with dependency information
• Triggering additional processing based on dependency state

Example:

.WithAfterReconcile(func(ctx MyContext, secret *corev1.Secret) error {
	// Cache database connection string from secret
	connStr := string(secret.Data["connection-string"])
	ctx.Data.DatabaseConnectionString = connStr
	return updateCustomResourceStatus(ctx, "DatabaseReady", "Connected")
})

func (*DependencyBuilder[CustomResourceType, ContextType, DependencyType]) WithBeforeReconcile ¶

func (b *DependencyBuilder[CustomResourceType, ContextType, DependencyType]) WithBeforeReconcile(f func(ctx ContextType) error) *DependencyBuilder[CustomResourceType, ContextType, DependencyType]

WithBeforeReconcile registers a hook function to execute before dependency resolution.

This function is called before attempting to resolve the dependency and can be used for setup tasks, validation, or logging. If the function returns an error, dependency resolution will be aborted.

Common use cases:

• Validating preconditions
• Setting up authentication
• Logging dependency resolution attempts

Example:

.WithBeforeReconcile(func(ctx MyContext) error {
	logger := ctx.GetLogger()
	logger.Info("Resolving database secret dependency")
	return nil
})

func (*DependencyBuilder[CustomResourceType, ContextType, DependencyType]) WithIsReadyFunc ¶

func (b *DependencyBuilder[CustomResourceType, ContextType, DependencyType]) WithIsReadyFunc(f func(obj DependencyType) bool) *DependencyBuilder[CustomResourceType, ContextType, DependencyType]

WithIsReadyFunc defines custom logic to determine if the dependency is ready for use.

The provided function is called with the resolved dependency resource and should return true if the dependency meets your readiness criteria, false otherwise.

If no readiness function is provided, the dependency is considered ready as soon as it exists in the cluster.

Common readiness patterns:

• Checking for specific data fields in secrets/configmaps
• Validating status conditions on custom resources
• Ensuring required labels or annotations are present

Example:

.WithIsReadyFunc(func(secret *corev1.Secret) bool {
	// Secret is ready when it contains required database credentials
	return secret.Data["host"] != nil &&
	       secret.Data["username"] != nil &&
	       secret.Data["password"] != nil
})

func (*DependencyBuilder[CustomResourceType, ContextType, DependencyType]) WithName ¶

func (b *DependencyBuilder[CustomResourceType, ContextType, DependencyType]) WithName(name string) *DependencyBuilder[CustomResourceType, ContextType, DependencyType]

WithName specifies the name of the Kubernetes resource to depend on.

This is the metadata.name field of the target resource. The name is required for dependency resolution and should match exactly with the existing resource.

Example:

.WithName("database-credentials") // Look for resource named "database-credentials"

func (*DependencyBuilder[CustomResourceType, ContextType, DependencyType]) WithNamespace ¶

func (b *DependencyBuilder[CustomResourceType, ContextType, DependencyType]) WithNamespace(namespace string) *DependencyBuilder[CustomResourceType, ContextType, DependencyType]

WithNamespace specifies the namespace where the dependency resource is located.

This is the metadata.namespace field of the target resource. If not specified, the dependency will be looked up in the same namespace as the custom resource.

For cluster-scoped resources, this field is ignored.

Example:

.WithNamespace("kube-system") // Look in kube-system namespace
.WithNamespace(ctx.GetCustomResource().Namespace) // Same namespace as custom resource

func (*DependencyBuilder[CustomResourceType, ContextType, DependencyType]) WithOptional ¶

func (b *DependencyBuilder[CustomResourceType, ContextType, DependencyType]) WithOptional(optional bool) *DependencyBuilder[CustomResourceType, ContextType, DependencyType]

WithOptional configures whether this dependency is required for reconciliation.

When set to true, the dependency resolution will continue even if this dependency is missing or not ready. When false (default), missing or unready dependencies will cause reconciliation to requeue and wait.

Use optional dependencies for:

• Feature flags or optional configurations
• Dependencies that provide enhanced functionality but aren't required
• Resources that may not exist in all environments

Example:

// Optional feature configuration
dep := NewDependencyBuilder(ctx, &corev1.ConfigMap{}).
	WithName("optional-features").
	WithOptional(true). // Don't block reconciliation if missing
	Build()

func (*DependencyBuilder[CustomResourceType, ContextType, DependencyType]) WithOutput ¶

func (b *DependencyBuilder[CustomResourceType, ContextType, DependencyType]) WithOutput(obj DependencyType) *DependencyBuilder[CustomResourceType, ContextType, DependencyType]

WithOutput specifies where to store the resolved dependency resource.

The provided object will be populated with the dependency's data after successful resolution. This allows other parts of your reconciliation logic to access the dependency's current state.

The output object should be a field in your context's data structure to ensure it's accessible throughout the reconciliation process.

Note: Setting an output is optional. If you only need to verify the dependency exists and is ready, you can use WithAfterReconcile for post-resolution actions without storing the full resource.

Example:

type MyContextData struct {
	DatabaseSecret *corev1.Secret
}

dep := NewDependencyBuilder(ctx, &corev1.Secret{}).
	WithName("database-creds").
	WithOutput(ctx.Data.DatabaseSecret). // Store resolved secret here
	Build()

This allows you to access ctx.Data.DatabaseSecret later in your reconciliation logic.

func (*DependencyBuilder[CustomResourceType, ContextType, DependencyType]) WithReadinessCondition ¶

func (b *DependencyBuilder[CustomResourceType, ContextType, DependencyType]) WithReadinessCondition(f func(obj DependencyType) bool) *DependencyBuilder[CustomResourceType, ContextType, DependencyType]

WithReadinessCondition is an alias for WithIsReadyFunc that defines custom readiness logic.

This method provides the same functionality as WithIsReadyFunc but with a more descriptive name. Use whichever method name feels more natural in your context.

See WithIsReadyFunc for detailed documentation and examples.

func (*DependencyBuilder[CustomResourceType, ContextType, DependencyType]) WithUserIdentifier ¶

func (b *DependencyBuilder[CustomResourceType, ContextType, DependencyType]) WithUserIdentifier(identifier string) *DependencyBuilder[CustomResourceType, ContextType, DependencyType]

WithUserIdentifier assigns a custom identifier for this dependency.

This identifier is used for logging, debugging, and distinguishing between multiple dependencies of the same type. If not provided, a default identifier will be generated based on the resource type and name.

Useful for:

• Debugging dependency resolution issues
• Providing meaningful names in logs
• Distinguishing between similar dependencies

Example:

.WithUserIdentifier("database-connection-secret") // Custom name for logs

func (*DependencyBuilder[CustomResourceType, ContextType, DependencyType]) WithWaitForReady ¶

func (b *DependencyBuilder[CustomResourceType, ContextType, DependencyType]) WithWaitForReady(waitForReady bool) *DependencyBuilder[CustomResourceType, ContextType, DependencyType]

WithWaitForReady determines whether reconciliation should wait for this dependency to become ready before proceeding.

When true (recommended), reconciliation will requeue if the dependency exists but is not yet ready according to the readiness function. When false, the dependency is only checked for existence.

This is particularly useful for:

• Resources that need initialization time
• External services that may be temporarily unavailable
• Custom resources with complex readiness conditions

Example:

.WithWaitForReady(true) // Wait for dependency to be ready, don't just check existence

func (*Resource[CustomResource, ContextType, ResourceType]) AfterReconcile ¶

func (c *Resource[CustomResource, ContextType, ResourceType]) AfterReconcile(ctx ContextType, resource client.Object) error

func (*Resource[CustomResource, ContextType, ResourceType]) BeforeReconcile ¶

func (c *Resource[CustomResource, ContextType, ResourceType]) BeforeReconcile(ctx ContextType) error

func (*Resource[CustomResource, ContextType, ResourceType]) CanBePaused ¶ added in v1.1.0

func (c *Resource[CustomResource, ContextType, ResourceType]) CanBePaused() bool

func (*Resource[CustomResource, ContextType, ResourceType]) Get ¶

func (c *Resource[CustomResource, ContextType, ResourceType]) Get() client.Object

func (*Resource[CustomResource, ContextType, ResourceType]) GetMutator ¶

func (c *Resource[CustomResource, ContextType, ResourceType]) GetMutator(obj client.Object) func() error

func (*Resource[CustomResource, ContextType, ResourceType]) ID ¶

func (c *Resource[CustomResource, ContextType, ResourceType]) ID() string

func (*Resource[CustomResource, ContextType, ResourceType]) IsReady ¶

func (c *Resource[CustomResource, ContextType, ResourceType]) IsReady(obj client.Object) bool

func (*Resource[CustomResource, ContextType, ResourceType]) Kind ¶

func (c *Resource[CustomResource, ContextType, ResourceType]) Kind() string

func (*Resource[CustomResource, ContextType, ResourceType]) ObjectMetaGenerator ¶

func (c *Resource[CustomResource, ContextType, ResourceType]) ObjectMetaGenerator() (obj client.Object, skip bool, err error)

func (*Resource[CustomResource, ContextType, ResourceType]) OnCreate ¶

func (c *Resource[CustomResource, ContextType, ResourceType]) OnCreate(ctx ContextType, resource client.Object) error

func (*Resource[CustomResource, ContextType, ResourceType]) OnDelete ¶

func (c *Resource[CustomResource, ContextType, ResourceType]) OnDelete(ctx ContextType, resource client.Object) error

func (*Resource[CustomResource, ContextType, ResourceType]) OnFinalize ¶

func (c *Resource[CustomResource, ContextType, ResourceType]) OnFinalize(ctx ContextType, resource client.Object) error

func (*Resource[CustomResource, ContextType, ResourceType]) OnUpdate ¶

func (c *Resource[CustomResource, ContextType, ResourceType]) OnUpdate(ctx ContextType, resource client.Object) error

func (*Resource[CustomResource, ContextType, ResourceType]) RequiresManualDeletion ¶

func (c *Resource[CustomResource, ContextType, ResourceType]) RequiresManualDeletion(obj client.Object) bool

func (*Resource[CustomResource, ContextType, ResourceType]) Set ¶

func (c *Resource[CustomResource, ContextType, ResourceType]) Set(obj client.Object)

func (*Resource[CustomResource, ContextType, ResourceType]) ShouldDeleteNow ¶

func (c *Resource[CustomResource, ContextType, ResourceType]) ShouldDeleteNow() bool

func (*ResourceBuilder[CustomResource, ContextType, ResourceType]) Build ¶

func (b *ResourceBuilder[CustomResource, ContextType, ResourceType]) Build() *Resource[CustomResource, ContextType, ResourceType]

Build constructs and returns the final Resource instance with all configured options.

This method finalizes the builder pattern and creates a resource that can be used in reconciliation steps. The returned resource contains all the configuration specified through the builder methods.

The resource must be used with appropriate reconciliation steps (such as ReconcileResourcesStep) to actually perform the resource management operations.

Validation:

• At least one of WithKey or WithKeyFunc must be called before Build()
• WithMutator is typically required for meaningful resource management

Returns a configured Resource instance ready for use in reconciliation.

func (*ResourceBuilder[CustomResource, ContextType, ResourceType]) WithAfterCreate ¶

func (b *ResourceBuilder[CustomResource, ContextType, ResourceType]) WithAfterCreate(f func(ctx ContextType, resource ResourceType) error) *ResourceBuilder[CustomResource, ContextType, ResourceType]

WithAfterCreate registers a hook function that executes only when a resource is newly created.

This function is called specifically when a resource is created for the first time, not when it's updated. It's useful for one-time initialization tasks, logging creation events, or triggering operations that should only happen on resource creation.

The function receives the newly created resource in its current state from the cluster, including any fields that were populated by Kubernetes (like UID, creation timestamp).

Common use cases:

• Logging resource creation events
• One-time initialization tasks
• Sending creation notifications to external systems
• Recording metrics for new resource creation
• Triggering initial configuration workflows

Example:

.WithAfterCreate(func(ctx MyContext, deployment *appsv1.Deployment) error {
	logger := ctx.GetLogger()
	logger.Info("Deployment created successfully",
		"name", deployment.Name,
		"namespace", deployment.Namespace,
		"uid", deployment.UID,
		"replicas", *deployment.Spec.Replicas)

	// Send notification to monitoring system
	return ctx.NotifyExternalSystem("deployment_created", deployment.Name)
})

func (*ResourceBuilder[CustomResource, ContextType, ResourceType]) WithAfterDelete ¶

func (b *ResourceBuilder[CustomResource, ContextType, ResourceType]) WithAfterDelete(f func(ctx ContextType, resource ResourceType) error) *ResourceBuilder[CustomResource, ContextType, ResourceType]

WithAfterDelete registers a hook function that executes after a resource is deleted.

This function is called when a resource has been successfully deleted from the cluster, either due to a delete condition being met or during custom resource finalization. It can be used for cleanup tasks, logging deletion events, or notifying external systems.

The function receives the resource object as it existed just before deletion. At this point, the resource no longer exists in the cluster.

Common use cases:

• Logging resource deletion events
• Cleaning up external resources or dependencies
• Notifying monitoring or auditing systems
• Recording metrics for resource deletion
• Updating custom resource status to reflect deletion

Example:

.WithAfterDelete(func(ctx MyContext, pvc *corev1.PersistentVolumeClaim) error {
	logger := ctx.GetLogger()
	logger.Info("PersistentVolumeClaim deleted",
		"name", pvc.Name,
		"namespace", pvc.Namespace,
		"storageClass", *pvc.Spec.StorageClassName)

	// Clean up any backup data associated with this PVC
	return ctx.CleanupBackupData(pvc.Name)
})

func (*ResourceBuilder[CustomResource, ContextType, ResourceType]) WithAfterFinalize ¶

func (b *ResourceBuilder[CustomResource, ContextType, ResourceType]) WithAfterFinalize(f func(ctx ContextType, resource ResourceType) error) *ResourceBuilder[CustomResource, ContextType, ResourceType]

WithAfterFinalize registers a hook function that executes during custom resource finalization.

This function is called when the custom resource is being deleted and the resource needs to be cleaned up as part of the finalization process. It's used for graceful shutdown procedures and cleanup of resources that require special handling.

The function should perform any necessary cleanup operations and ensure that external dependencies are properly handled before the custom resource is fully removed.

Common use cases:

• Graceful shutdown of applications
• Backup of important data before deletion
• Cleanup of external resources or registrations
• Notifying external systems of resource removal
• Removing finalizers from dependent resources

Example:

.WithAfterFinalize(func(ctx MyContext, deployment *appsv1.Deployment) error {
	logger := ctx.GetLogger()

	// Gracefully scale down before deletion
	if deployment.Spec.Replicas != nil && *deployment.Spec.Replicas > 0 {
		logger.Info("Scaling down deployment before finalization")
		zero := int32(0)
		deployment.Spec.Replicas = &zero
		return ctx.Update(deployment)
	}

	// Perform final cleanup
	return ctx.CleanupExternalResources(deployment.Name)
})

func (*ResourceBuilder[CustomResource, ContextType, ResourceType]) WithAfterReconcile ¶

func (b *ResourceBuilder[CustomResource, ContextType, ResourceType]) WithAfterReconcile(f func(ctx ContextType, resource ResourceType) error) *ResourceBuilder[CustomResource, ContextType, ResourceType]

WithAfterReconcile registers a hook function to execute after successful resource reconciliation.

This function is called after the resource has been successfully created, updated, or verified to exist with the correct configuration. It receives the current resource state from the cluster and can be used for post-processing, status updates, or triggering additional operations.

If the function returns an error, the reconciliation will fail even though the resource operation itself was successful.

Common use cases:

• Updating custom resource status with resource information
• Triggering external system notifications
• Caching resource data for future use
• Logging successful operations
• Initiating dependent operations

Example:

.WithAfterReconcile(func(ctx MyContext, service *corev1.Service) error {
	cr := ctx.GetCustomResource()

	// Update custom resource status with service information
	if cr.Status.ServiceStatus == nil {
		cr.Status.ServiceStatus = &ServiceStatus{}
	}
	cr.Status.ServiceStatus.Name = service.Name
	cr.Status.ServiceStatus.ClusterIP = service.Spec.ClusterIP

	// Set ready condition
	meta.SetStatusCondition(&cr.Status.Conditions, metav1.Condition{
		Type:   "ServiceReady",
		Status: metav1.ConditionTrue,
		Reason: "ServiceCreated",
	})

	return ctx.PatchStatus()
})

func (*ResourceBuilder[CustomResource, ContextType, ResourceType]) WithAfterUpdate ¶

func (b *ResourceBuilder[CustomResource, ContextType, ResourceType]) WithAfterUpdate(f func(ctx ContextType, resource ResourceType) error) *ResourceBuilder[CustomResource, ContextType, ResourceType]

WithAfterUpdate registers a hook function that executes only when a resource is updated.

This function is called specifically when an existing resource is modified, not when it's initially created. It's useful for tracking changes, logging update events, or triggering operations that should only happen when configuration changes.

The function receives the updated resource in its current state from the cluster after the update operation has completed successfully.

Common use cases:

• Logging configuration changes
• Triggering rolling updates or restarts
• Notifying external systems of changes
• Recording metrics for resource modifications
• Validating update results

Example:

.WithAfterUpdate(func(ctx MyContext, deployment *appsv1.Deployment) error {
	logger := ctx.GetLogger()
	cr := ctx.GetCustomResource()

	logger.Info("Deployment updated successfully",
		"name", deployment.Name,
		"generation", deployment.Generation,
		"replicas", *deployment.Spec.Replicas)

	// Update custom resource status with latest generation
	cr.Status.DeploymentGeneration = deployment.Generation
	return ctx.PatchStatus()
})

func (*ResourceBuilder[CustomResource, ContextType, ResourceType]) WithBeforeReconcile ¶

func (b *ResourceBuilder[CustomResource, ContextType, ResourceType]) WithBeforeReconcile(f func(ctx ContextType) error) *ResourceBuilder[CustomResource, ContextType, ResourceType]

WithBeforeReconcile registers a hook function to execute before resource reconciliation.

This function is called before any resource operations (create, update, or delete) are performed. It can be used for setup tasks, validation, or preparation work. If the function returns an error, resource reconciliation will be aborted.

Common use cases:

• Validating preconditions for resource creation
• Setting up external dependencies
• Performing cleanup of old resources
• Logging reconciliation attempts
• Initializing shared state

Example:

.WithBeforeReconcile(func(ctx MyContext) error {
	logger := ctx.GetLogger()
	cr := ctx.GetCustomResource()

	logger.Info("Reconciling application deployment", "version", cr.Spec.Version)

	// Validate configuration before proceeding
	if cr.Spec.Replicas < 0 {
		return fmt.Errorf("replica count cannot be negative: %d", cr.Spec.Replicas)
	}

	return nil
})

func (*ResourceBuilder[CustomResource, ContextType, ResourceType]) WithCanBePaused ¶ added in v1.1.0

func (b *ResourceBuilder[CustomResource, ContextType, ResourceType]) WithCanBePaused(canBePaused bool) *ResourceBuilder[CustomResource, ContextType, ResourceType]

WithCanBePaused specifies whether this resource supports pausing reconciliation.

When set to true, the resource will respect the paused state of the custom resource. If the custom resource is marked as paused (e.g., via a label), reconciliation for this resource will be skipped until the pause is lifted.

This is useful for scenarios where you want to temporarily halt changes to certain resources without deleting them or affecting other parts of the system.

Common use cases:

• Temporarily halting updates during maintenance windows
• Pausing non-critical resources while troubleshooting issues
• Allowing manual intervention before resuming automated management

Example:

.WithCanBePaused(true) // Enable pausing for this resource

func (*ResourceBuilder[CustomResource, ContextType, ResourceType]) WithCanBePausedFunc ¶ added in v1.1.0

func (b *ResourceBuilder[CustomResource, ContextType, ResourceType]) WithCanBePausedFunc(f func() bool) *ResourceBuilder[CustomResource, ContextType, ResourceType]

WithCanBePausedFunc specifies a function to determine if this resource supports pausing reconciliation.

The provided function is called during reconciliation to check if the resource should respect the paused state of the custom resource. If it returns true, reconciliation for this resource will be skipped when the custom resource is paused.

This allows for dynamic control over which resources can be paused based on the current state or configuration of the custom resource.

Example:

.WithCanBePausedFunc(func() bool {
    // Custom logic to determine if the resource can be paused
    return someCondition
})

func (*ResourceBuilder[CustomResource, ContextType, ResourceType]) WithKey ¶

func (b *ResourceBuilder[CustomResource, ContextType, ResourceType]) WithKey(name types.NamespacedName) *ResourceBuilder[CustomResource, ContextType, ResourceType]

WithKey specifies a static NamespacedName for the resource.

This is useful when the resource name and namespace are known at build time and don't need to be computed dynamically based on the custom resource state.

For dynamic naming based on custom resource properties, use WithKeyFunc instead.

Example:

.WithKey(types.NamespacedName{
	Name:      "my-app-service",
	Namespace: "default",
}) // Static name for the service

func (*ResourceBuilder[CustomResource, ContextType, ResourceType]) WithKeyFunc ¶

func (b *ResourceBuilder[CustomResource, ContextType, ResourceType]) WithKeyFunc(f func() types.NamespacedName) *ResourceBuilder[CustomResource, ContextType, ResourceType]

WithKeyFunc specifies a function that dynamically determines the resource's NamespacedName.

This function is called during reconciliation to determine where the resource should be created or found. It's evaluated each time the resource is reconciled, allowing for dynamic naming based on the current state of the custom resource.

The function typically derives the name from the custom resource's metadata or spec, and should return a consistent result for the same custom resource state.

Common patterns:

• Prefixing with custom resource name: ctx.GetCustomResource().Name + "-suffix"
• Using custom resource namespace: ctx.GetCustomResource().Namespace
• Conditional naming based on custom resource spec
• When the name is stored in the spec, you might wanna refer to the status when the spec field is updated or disappears

Example:

.WithKeyFunc(func() types.NamespacedName {
	cr := ctx.GetCustomResource()
	return types.NamespacedName{
		Name:      cr.Name + "-" + cr.Spec.Component, // Dynamic based on spec
		Namespace: cr.Namespace,                        // Same namespace as CR
	}
})

func (*ResourceBuilder[CustomResource, ContextType, ResourceType]) WithMutator ¶

func (b *ResourceBuilder[CustomResource, ContextType, ResourceType]) WithMutator(f Mutator[ResourceType]) *ResourceBuilder[CustomResource, ContextType, ResourceType]

WithMutator specifies the function that configures the resource's desired state.

The mutator function is called whenever the resource needs to be created or updated. It receives the resource object and should configure all necessary fields to match the desired state defined by your custom resource.

The mutator should:

• Set all required fields on the resource
• Configure the resource based on custom resource spec
• Set owner references for garbage collection
• Apply labels, annotations, and other metadata
• Return an error if configuration fails

The mutator is called for both CREATE and UPDATE operations, so it should be idempotent and handle both scenarios gracefully.

Example:

.WithMutator(func(deployment *appsv1.Deployment) error {
	cr := ctx.GetCustomResource()

	// Configure deployment based on custom resource
	deployment.Spec.Replicas = cr.Spec.Replicas
	deployment.Spec.Selector = &metav1.LabelSelector{
		MatchLabels: map[string]string{"app": cr.Name},
	}
	deployment.Spec.Template.Spec.Containers = []corev1.Container{{
		Name:  "app",
		Image: cr.Spec.Image,
	}}

	// Set owner reference for garbage collection
	return controllerutil.SetOwnerReference(cr, deployment, ctx.GetScheme())
})

func (*ResourceBuilder[CustomResource, ContextType, ResourceType]) WithOutput ¶

func (b *ResourceBuilder[CustomResource, ContextType, ResourceType]) WithOutput(obj ResourceType) *ResourceBuilder[CustomResource, ContextType, ResourceType]

WithOutput specifies where to store the reconciled resource after successful operations.

The provided object will be populated with the resource's current state from the cluster after reconciliation completes. This allows other parts of your controller logic to access the resource's runtime state, such as generated fields, status information, or cluster-assigned values.

The output object should be a field in your context's data structure to ensure it's accessible throughout the reconciliation process.

Common use cases:

• Accessing service ClusterIP after creation
• Reading generated secret data
• Getting deployment status for custom resource status updates
• Obtaining persistent volume claim details

Example:

type MyContextData struct {
	AppService *corev1.Service
}

service := NewResourceBuilder(ctx, &corev1.Service{}).
	// ... other configuration ...
	WithOutput(ctx.Data.AppService). // Store reconciled service here
	Build()

func (*ResourceBuilder[CustomResource, ContextType, ResourceType]) WithReadinessCondition ¶

func (b *ResourceBuilder[CustomResource, ContextType, ResourceType]) WithReadinessCondition(f func(obj ResourceType) bool) *ResourceBuilder[CustomResource, ContextType, ResourceType]

WithReadinessCondition defines custom logic to determine when the resource is ready.

The provided function is called with the current resource state and should return true if the resource has reached the desired operational state. This affects when the overall custom resource is considered ready and can influence reconciliation flow.

If no readiness condition is provided, the resource is considered ready as soon as it exists and has been successfully created or updated.

Common readiness patterns:

• Deployments: Check that ReadyReplicas == DesiredReplicas
• Services: Verify endpoints are populated
• Jobs: Check for successful completion
• Custom resources: Examine status conditions

Example:

.WithReadinessCondition(func(deployment *appsv1.Deployment) bool {
	// Deployment is ready when all replicas are ready
	if deployment.Spec.Replicas == nil {
		return deployment.Status.ReadyReplicas > 0
	}
	return deployment.Status.ReadyReplicas == *deployment.Spec.Replicas &&
	       deployment.Status.UpdatedReplicas == *deployment.Spec.Replicas
})

func (*ResourceBuilder[CustomResource, ContextType, ResourceType]) WithRequireManualDeletionForFinalize ¶

func (b *ResourceBuilder[CustomResource, ContextType, ResourceType]) WithRequireManualDeletionForFinalize(f func(obj ResourceType) bool) *ResourceBuilder[CustomResource, ContextType, ResourceType]

WithRequireManualDeletionForFinalize specifies when a resource requires manual cleanup during custom resource finalization.

When the custom resource is being deleted, this function is called to determine if the resource requires special handling before the custom resource can be fully removed. If the function returns true, the resource must be manually cleaned up before finalization can complete.

This is typically used for resources that:

• Have external dependencies that need cleanup
• Store important data that needs backup
• Have complex deletion procedures
• Need graceful shutdown processes

The function receives the current resource state to make decisions based on the resource's current condition or configuration.

Example:

.WithRequireManualDeletionForFinalize(func(pvc *corev1.PersistentVolumeClaim) bool {
	// Require manual deletion for PVCs that contain important data
	if important, exists := pvc.Annotations["data.important"]; exists {
		return important == "true"
	}
	return false
})

// Another example: based on resource state
.WithRequireManualDeletionForFinalize(func(deployment *appsv1.Deployment) bool {
	// Require manual deletion if deployment is still running
	return deployment.Status.Replicas > 0
})

func (*ResourceBuilder[CustomResource, ContextType, ResourceType]) WithSkipAndDeleteOnCondition ¶

func (b *ResourceBuilder[CustomResource, ContextType, ResourceType]) WithSkipAndDeleteOnCondition(f func() bool) *ResourceBuilder[CustomResource, ContextType, ResourceType]

WithSkipAndDeleteOnCondition specifies when to skip creating or delete an existing resource.

The provided function is evaluated during reconciliation. When it returns true:

• If the resource doesn't exist, it will be skipped (not created)
• If the resource exists, it will be deleted

This is useful for conditional resource management based on custom resource configuration, feature flags, or environmental conditions.

The condition function is called each reconciliation cycle, so resources can be dynamically created or removed based on changing conditions.

Common use cases:

• Feature toggles that enable/disable optional components
• Environment-specific resources (dev vs prod)
• Conditional scaling or resource allocation
• Migration scenarios where resources are phased out

Example:

.WithSkipAndDeleteOnCondition(func() bool {
	cr := ctx.GetCustomResource()
	// Only create monitoring service if monitoring is enabled
	return !cr.Spec.Monitoring.Enabled
})

// Another example: conditional based on environment
.WithSkipAndDeleteOnCondition(func() bool {
	// Skip expensive resources in development environment
	return ctx.GetCustomResource().Spec.Environment == "development"
})

func (*ResourceBuilder[CustomResource, ContextType, ResourceType]) WithUserIdentifier ¶

func (b *ResourceBuilder[CustomResource, ContextType, ResourceType]) WithUserIdentifier(identifier string) *ResourceBuilder[CustomResource, ContextType, ResourceType]

WithUserIdentifier assigns a custom identifier for this resource.

This identifier is used for logging, debugging, and distinguishing between multiple resources of the same type within your controller. If not provided, a default identifier will be generated based on the resource type.

The identifier appears in logs and error messages, making it easier to track specific resources during debugging and troubleshooting.

Useful for:

• Distinguishing between multiple deployments (e.g., "frontend", "backend")
• Providing meaningful names for different services
• Creating clear audit trails in logs
• Simplifying debugging of complex resource hierarchies

Example:

.WithUserIdentifier("frontend-deployment") // Clear name for logs
.WithUserIdentifier("database-service")    // Easy to identify in debugging

func (ResourceVersionChangedPredicate) Create ¶

func (ResourceVersionChangedPredicate) Create(e event.CreateEvent) bool

func (ResourceVersionChangedPredicate) Delete ¶

func (ResourceVersionChangedPredicate) Delete(e event.DeleteEvent) bool

func (ResourceVersionChangedPredicate) Generic ¶

func (ResourceVersionChangedPredicate) Generic(e event.GenericEvent) bool

func (ResourceVersionChangedPredicate) Update ¶

func (ResourceVersionChangedPredicate) Update(e event.UpdateEvent) bool

func (StepResult) FromSubStep ¶

func (result StepResult) FromSubStep() StepResult

func (StepResult) Normal ¶

func (result StepResult) Normal() (ctrl.Result, error)

func (StepResult) ShouldReturn ¶

func (result StepResult) ShouldReturn() bool

func (*Stepper[K, C]) Execute ¶

func (stepper *Stepper[K, C]) Execute(ctx C, req ctrl.Request) (ctrl.Result, error)

func (*StepperBuilder[K, C]) Build ¶

func (s *StepperBuilder[K, C]) Build() *Stepper[K, C]

WithLogger sets the logger for the Stepper.

func (*StepperBuilder[K, C]) WithStep ¶

func (s *StepperBuilder[K, C]) WithStep(step Step[K, C]) *StepperBuilder[K, C]

WithLogger sets the logger for the Stepper.

func (TypedNotPausedPredicate[object]) Create ¶ added in v1.1.0

func (p TypedNotPausedPredicate[object]) Create(e event.TypedCreateEvent[object]) bool

func (TypedNotPausedPredicate[object]) Delete ¶ added in v1.1.0

func (p TypedNotPausedPredicate[object]) Delete(e event.TypedDeleteEvent[object]) bool

func (TypedNotPausedPredicate[object]) Generic ¶ added in v1.1.0

func (p TypedNotPausedPredicate[object]) Generic(e event.TypedGenericEvent[object]) bool

func (TypedNotPausedPredicate[object]) Update ¶ added in v1.1.0

func (p TypedNotPausedPredicate[object]) Update(e event.TypedUpdateEvent[object]) bool

func (*UntypedDependency[CustomResourceType, ContextType]) Kind ¶

func (c *UntypedDependency[CustomResourceType, ContextType]) Kind() string

func (*UntypedDependency[CustomResourceType, ContextType]) New ¶

func (c *UntypedDependency[CustomResourceType, ContextType]) New() client.Object

func (*UntypedDependency[CustomResourceType, ContextType]) Set ¶

func (c *UntypedDependency[CustomResourceType, ContextType]) Set(obj client.Object)

func (*UntypedDependencyBuilder[CustomResourceType, ContextType]) Build ¶

func (b *UntypedDependencyBuilder[CustomResourceType, ContextType]) Build() *UntypedDependency[CustomResourceType, ContextType]

Build constructs and returns the final UntypedDependency instance with all configured options.

This method finalizes the builder pattern and creates an untyped dependency that can be used in reconciliation steps. The returned dependency contains all the configuration specified through the builder methods and will work with unstructured.Unstructured objects.

The dependency must be used with appropriate reconciliation steps (such as ResolveDynamicDependenciesStep) to actually perform the dependency resolution.

Returns a configured UntypedDependency instance ready for use in reconciliation.

func (*UntypedDependencyBuilder[CustomResourceType, ContextType]) WithAddManagedByAnnotation ¶

func (b *UntypedDependencyBuilder[CustomResourceType, ContextType]) WithAddManagedByAnnotation(add bool) *UntypedDependencyBuilder[CustomResourceType, ContextType]

WithAddManagedByAnnotation controls whether to add a "managed-by" annotation to the untyped dependency resource.

When enabled, this adds metadata to help identify which controller is managing or depending on this resource. This is especially useful for untyped dependencies since the relationship between controllers and third-party resources may not be obvious.

The annotation typically follows the format:

"app.kubernetes.io/managed-by": "<controller-name>"

Example:

.WithAddManagedByAnnotation(true) // Mark dependency relationship for debugging

func (*UntypedDependencyBuilder[CustomResourceType, ContextType]) WithAfterReconcile ¶

func (b *UntypedDependencyBuilder[CustomResourceType, ContextType]) WithAfterReconcile(f func(ctx ContextType, resource *unstructured.Unstructured) error) *UntypedDependencyBuilder[CustomResourceType, ContextType]

WithAfterReconcile registers a hook function to execute after successful dependency resolution.

This function is called with the resolved dependency as an unstructured.Unstructured object and can be used for post-processing, validation, or updating your custom resource's status. If the function returns an error, the reconciliation will fail.

Working with unstructured objects requires using helper functions to access nested fields:

Example:

.WithAfterReconcile(func(ctx MyContext, obj *unstructured.Unstructured) error {
	// Extract status from custom resource
	status, found, err := unstructured.NestedString(obj.Object, "status", "endpoint")
	if err != nil {
		return err
	}
	if found {
		ctx.Data.DatabaseEndpoint = status
	}
	return nil
})

func (*UntypedDependencyBuilder[CustomResourceType, ContextType]) WithBeforeReconcile ¶

func (b *UntypedDependencyBuilder[CustomResourceType, ContextType]) WithBeforeReconcile(f func(ctx ContextType) error) *UntypedDependencyBuilder[CustomResourceType, ContextType]

WithBeforeReconcile registers a hook function to execute before dependency resolution.

This function is called before attempting to resolve the untyped dependency and can be used for setup tasks, validation, or logging. If the function returns an error, dependency resolution will be aborted.

Common use cases:

• Validating that the target CRD is installed
• Setting up authentication for third-party resources
• Logging dependency resolution attempts for debugging

Example:

.WithBeforeReconcile(func(ctx MyContext) error {
	logger := ctx.GetLogger()
	logger.Info("Resolving third-party resource dependency", "gvk", gvk)
	return nil
})

func (*UntypedDependencyBuilder[CustomResourceType, ContextType]) WithIsReadyFunc ¶

func (b *UntypedDependencyBuilder[CustomResourceType, ContextType]) WithIsReadyFunc(f func(obj *unstructured.Unstructured) bool) *UntypedDependencyBuilder[CustomResourceType, ContextType]

WithIsReadyFunc defines custom logic to determine if the untyped dependency is ready for use.

The provided function is called with the resolved dependency as an unstructured.Unstructured object and should return true if the dependency meets your readiness criteria.

Working with unstructured objects requires using helper functions to access nested fields. Common patterns include checking status conditions, phase fields, or custom markers.

Example:

.WithIsReadyFunc(func(obj *unstructured.Unstructured) bool {
	// Check if a custom resource has reached "Ready" state
	phase, found, _ := unstructured.NestedString(obj.Object, "status", "phase")
	if !found {
		return false
	}
	return phase == "Ready" || phase == "Running"
})

func (*UntypedDependencyBuilder[CustomResourceType, ContextType]) WithName ¶

func (b *UntypedDependencyBuilder[CustomResourceType, ContextType]) WithName(name string) *UntypedDependencyBuilder[CustomResourceType, ContextType]

WithName specifies the name of the Kubernetes resource to depend on.

This is the metadata.name field of the target resource. The name is required for dependency resolution and should match exactly with the existing resource.

Example:

.WithName("my-database-instance") // Look for resource named "my-database-instance"

func (*UntypedDependencyBuilder[CustomResourceType, ContextType]) WithNamespace ¶

func (b *UntypedDependencyBuilder[CustomResourceType, ContextType]) WithNamespace(namespace string) *UntypedDependencyBuilder[CustomResourceType, ContextType]

WithNamespace specifies the namespace where the dependency resource is located.

This is the metadata.namespace field of the target resource. If not specified, the dependency will be looked up in the same namespace as the custom resource.

For cluster-scoped resources, this field is ignored.

Example:

.WithNamespace("monitoring") // Look in monitoring namespace
.WithNamespace(ctx.GetCustomResource().Namespace) // Same namespace as custom resource

func (*UntypedDependencyBuilder[CustomResourceType, ContextType]) WithOptional ¶

func (b *UntypedDependencyBuilder[CustomResourceType, ContextType]) WithOptional(optional bool) *UntypedDependencyBuilder[CustomResourceType, ContextType]

WithOptional configures whether this dependency is required for reconciliation.

When set to true, the dependency resolution will continue even if this dependency is missing or not ready. When false (default), missing or unready dependencies will cause reconciliation to requeue and wait.

This is particularly useful for untyped dependencies on optional operators or CRDs:

• Prometheus monitoring resources (when Prometheus operator is optional)
• Service mesh resources (when Istio/Linkerd might not be installed)
• Third-party integrations that enhance but don't break functionality

Example:

.WithOptional(true) // Don't fail if the CRD isn't installed

func (*UntypedDependencyBuilder[CustomResourceType, ContextType]) WithOutput ¶

func (b *UntypedDependencyBuilder[CustomResourceType, ContextType]) WithOutput(obj *unstructured.Unstructured) *UntypedDependencyBuilder[CustomResourceType, ContextType]

WithOutput specifies where to store the resolved untyped dependency resource.

The provided unstructured.Unstructured object will be populated with the dependency's data after successful resolution. This allows other parts of your reconciliation logic to access the dependency's current state.

The output object should be a field in your context's data structure to ensure it's accessible throughout the reconciliation process.

Example:

type MyContextData struct {
	DatabaseInstance *unstructured.Unstructured
}

dep := NewUntypedDependencyBuilder(ctx, gvk).
	WithName("my-db").
	WithOutput(ctx.Data.DatabaseInstance). // Store resolved resource here
	Build()

func (*UntypedDependencyBuilder[CustomResourceType, ContextType]) WithReadinessCondition ¶

func (b *UntypedDependencyBuilder[CustomResourceType, ContextType]) WithReadinessCondition(f func(obj *unstructured.Unstructured) bool) *UntypedDependencyBuilder[CustomResourceType, ContextType]

WithReadinessCondition is an alias for WithIsReadyFunc that defines custom readiness logic.

This method provides the same functionality as WithIsReadyFunc but with a more descriptive name for untyped dependencies. Use whichever method name feels more natural in your context.

See WithIsReadyFunc for detailed documentation and examples of working with unstructured.Unstructured objects.

func (*UntypedDependencyBuilder[CustomResourceType, ContextType]) WithUserIdentifier ¶

func (b *UntypedDependencyBuilder[CustomResourceType, ContextType]) WithUserIdentifier(identifier string) *UntypedDependencyBuilder[CustomResourceType, ContextType]

WithUserIdentifier assigns a custom identifier for this untyped dependency.

This identifier is used for logging, debugging, and distinguishing between multiple untyped dependencies. If not provided, a default identifier will be generated based on the GroupVersionKind and resource name.

This is especially useful for untyped dependencies since the resource types may not be immediately obvious from logs.

Example:

.WithUserIdentifier("prometheus-servicemonitor") // Clear name for logs and debugging

func (*UntypedDependencyBuilder[CustomResourceType, ContextType]) WithWaitForReady ¶

func (b *UntypedDependencyBuilder[CustomResourceType, ContextType]) WithWaitForReady(waitForReady bool) *UntypedDependencyBuilder[CustomResourceType, ContextType]

WithWaitForReady determines whether reconciliation should wait for this dependency to become ready before proceeding.

When true (recommended), reconciliation will requeue if the dependency exists but is not yet ready according to the readiness function. When false, the dependency is only checked for existence.

This is particularly important for untyped dependencies on custom resources that may have complex initialization or external dependencies.

Example:

.WithWaitForReady(true) // Wait for custom resource to be fully initialized

func (*UntypedResource[CustomResource, ContextType]) Kind ¶

func (c *UntypedResource[CustomResource, ContextType]) Kind() string

func (*UntypedResource[CustomResource, ContextType]) ObjectMetaGenerator ¶

func (c *UntypedResource[CustomResource, ContextType]) ObjectMetaGenerator() (obj client.Object, skip bool, err error)

func (*UntypedResourceBuilder[CustomResource, ContextType]) Build ¶

func (b *UntypedResourceBuilder[CustomResource, ContextType]) Build() *UntypedResource[CustomResource, ContextType]

Build constructs and returns the final UntypedResource instance with all configured options.

This method finalizes the builder pattern and creates an untyped resource that can be used in reconciliation steps. The returned resource contains all the configuration specified through the builder methods and will work with unstructured.Unstructured objects.

The resource must be used with appropriate reconciliation steps (such as ReconcileResourcesStep) to actually perform the resource management operations.

Validation:

• At least one of WithKey or WithKeyFunc must be called before Build()
• WithMutator is typically required for meaningful resource management

Returns a configured UntypedResource instance ready for use in reconciliation.

func (*UntypedResourceBuilder[CustomResource, ContextType]) WithAfterCreate ¶

func (b *UntypedResourceBuilder[CustomResource, ContextType]) WithAfterCreate(f func(ctx ContextType, resource *unstructured.Unstructured) error) *UntypedResourceBuilder[CustomResource, ContextType]

WithAfterCreate registers a hook function that executes only when an untyped resource is newly created.

This function is called specifically when a resource is created for the first time, not when it's updated. It's useful for one-time initialization tasks specific to untyped resources, such as setting up external integrations or logging creation events.

The function receives the newly created unstructured resource, including any fields populated by Kubernetes during creation.

Working with unstructured objects requires using helper functions to access nested fields.

Example:

.WithAfterCreate(func(ctx MyContext, obj *unstructured.Unstructured) error {
	// Log creation of custom resource
	logger := ctx.GetLogger()
	name, _, _ := unstructured.NestedString(obj.Object, "metadata", "name")
	logger.Info("Custom resource created", "name", name, "gvk", gvk)

	// Register with external monitoring system
	return ctx.RegisterWithExternalSystem(obj)
})

func (*UntypedResourceBuilder[CustomResource, ContextType]) WithAfterDelete ¶

func (b *UntypedResourceBuilder[CustomResource, ContextType]) WithAfterDelete(f func(ctx ContextType, resource *unstructured.Unstructured) error) *UntypedResourceBuilder[CustomResource, ContextType]

WithAfterDelete registers a hook function that executes after an untyped resource is deleted.

This function is called when a resource has been successfully deleted from the cluster, either due to a delete condition being met or during custom resource finalization. It can be used for cleanup tasks specific to untyped resources.

The function receives the resource object as it existed just before deletion. Working with unstructured objects requires using helper functions to access nested fields.

Example:

.WithAfterDelete(func(ctx MyContext, obj *unstructured.Unstructured) error {
	// Clean up external references
	name, _, _ := unstructured.NestedString(obj.Object, "metadata", "name")
	logger := ctx.GetLogger()
	logger.Info("Cleaning up external resources", "resource", name)

	// Remove from external monitoring system
	return ctx.UnregisterFromExternalSystem(name)
})

func (*UntypedResourceBuilder[CustomResource, ContextType]) WithAfterFinalize ¶

func (b *UntypedResourceBuilder[CustomResource, ContextType]) WithAfterFinalize(f func(ctx ContextType, resource *unstructured.Unstructured) error) *UntypedResourceBuilder[CustomResource, ContextType]

WithAfterFinalize registers a hook function that executes during custom resource finalization for untyped resources that require special cleanup handling.

This function is called when the custom resource is being deleted and the untyped resource needs to be cleaned up as part of the finalization process. It's particularly important for untyped resources that may have external dependencies or special deletion requirements.

Working with unstructured objects requires using helper functions to access nested fields.

Example:

.WithAfterFinalize(func(ctx MyContext, obj *unstructured.Unstructured) error {
	// Graceful cleanup for third-party resources
	logger := ctx.GetLogger()

	// Check if resource has special cleanup requirements
	cleanupMode, found, _ := unstructured.NestedString(obj.Object, "spec", "cleanupMode")
	if found && cleanupMode == "preserve" {
		logger.Info("Preserving resource during finalization")
		return nil
	}

	// Perform graceful shutdown
	return ctx.GracefullyShutdownExternalResource(obj)
})

func (*UntypedResourceBuilder[CustomResource, ContextType]) WithAfterReconcile ¶

func (b *UntypedResourceBuilder[CustomResource, ContextType]) WithAfterReconcile(f func(ctx ContextType, resource *unstructured.Unstructured) error) *UntypedResourceBuilder[CustomResource, ContextType]

WithAfterReconcile registers a hook function to execute after successful untyped resource reconciliation.

This function is called after the untyped resource has been successfully created, updated, or verified. It receives the current resource state as an unstructured.Unstructured object and can be used for post-processing, status updates, or triggering additional operations.

Working with unstructured objects requires using helper functions to access nested fields.

Example:

.WithAfterReconcile(func(ctx MyContext, obj *unstructured.Unstructured) error {
	cr := ctx.GetCustomResource()

	// Extract status information from the untyped resource
	status, found, err := unstructured.NestedString(obj.Object, "status", "phase")
	if err != nil {
		return err
	}

	// Update custom resource status
	if found {
		cr.Status.ExternalResourcePhase = status
		meta.SetStatusCondition(&cr.Status.Conditions, metav1.Condition{
			Type:   "ExternalResourceReady",
			Status: metav1.ConditionTrue,
			Reason: "ResourceReconciled",
		})
	}

	return ctx.PatchStatus()
})

func (*UntypedResourceBuilder[CustomResource, ContextType]) WithAfterUpdate ¶

func (b *UntypedResourceBuilder[CustomResource, ContextType]) WithAfterUpdate(f func(ctx ContextType, resource *unstructured.Unstructured) error) *UntypedResourceBuilder[CustomResource, ContextType]

WithAfterUpdate registers a hook function that executes only when an untyped resource is updated.

This function is called specifically when an existing untyped resource is modified, not when it's initially created. It's useful for tracking changes to third-party resources and responding to configuration updates.

Working with unstructured objects requires using helper functions to access nested fields.

Example:

.WithAfterUpdate(func(ctx MyContext, obj *unstructured.Unstructured) error {
	logger := ctx.GetLogger()

	// Log the update with resource details
	name, _, _ := unstructured.NestedString(obj.Object, "metadata", "name")
	generation, _, _ := unstructured.NestedInt64(obj.Object, "metadata", "generation")

	logger.Info("External resource updated",
		"name", name,
		"generation", generation,
		"gvk", gvk)

	// Trigger external system update notification
	return ctx.NotifyExternalSystemOfUpdate(obj)
})

func (*UntypedResourceBuilder[CustomResource, ContextType]) WithBeforeReconcile ¶

func (b *UntypedResourceBuilder[CustomResource, ContextType]) WithBeforeReconcile(f func(ctx ContextType) error) *UntypedResourceBuilder[CustomResource, ContextType]

WithBeforeReconcile registers a hook function to execute before untyped resource reconciliation.

This function is called before any resource operations (create, update, or delete) are performed on the untyped resource. It's particularly useful for validating that the target CRD is installed and for preparing the environment.

Common use cases for untyped resources:

• Validating that the target CRD exists in the cluster
• Checking operator availability (e.g., Prometheus, Grafana operators)
• Setting up authentication for third-party APIs
• Performing environment-specific preparations

Example:

.WithBeforeReconcile(func(ctx MyContext) error {
	logger := ctx.GetLogger()
	client := ctx.GetClient()

	// Verify that the target CRD exists
	crdName := fmt.Sprintf("%ss.%s", strings.ToLower(gvk.Kind), gvk.Group)
	crd := &apiextensionsv1.CustomResourceDefinition{}
	err := client.Get(ctx, types.NamespacedName{Name: crdName}, crd)
	if err != nil {
		return fmt.Errorf("required CRD %s not found: %w", crdName, err)
	}

	logger.Info("Proceeding with untyped resource reconciliation", "gvk", gvk)
	return nil
})

func (*UntypedResourceBuilder[CustomResource, ContextType]) WithCanBePaused ¶ added in v1.1.0

func (b *UntypedResourceBuilder[CustomResource, ContextType]) WithCanBePaused(canBePaused bool) *UntypedResourceBuilder[CustomResource, ContextType]

WithCanBePaused specifies whether this resource supports pausing reconciliation.

When set to true, the resource will respect the paused state of the custom resource. If the custom resource is marked as paused (e.g., via a label), reconciliation for this resource will be skipped until the pause is lifted.

This is useful for scenarios where you want to temporarily halt changes to certain resources without deleting them or affecting other parts of the system.

Common use cases:

• Temporarily halting updates during maintenance windows
• Pausing non-critical resources while troubleshooting issues
• Allowing manual intervention before resuming automated management

Example:

.WithCanBePaused(true) // Enable pausing for this resource

func (*UntypedResourceBuilder[CustomResource, ContextType]) WithCanBePausedFunc ¶ added in v1.1.0

func (b *UntypedResourceBuilder[CustomResource, ContextType]) WithCanBePausedFunc(f func() bool) *UntypedResourceBuilder[CustomResource, ContextType]

WithCanBePausedFunc specifies a function to determine if this resource supports pausing reconciliation.

The provided function is called during reconciliation to check if the resource should respect the paused state of the custom resource. If it returns true, reconciliation for this resource will be skipped when the custom resource is paused.

This allows for dynamic control over which resources can be paused based on the current state or configuration of the custom resource.

Example:

.WithCanBePausedFunc(func() bool {
    // Custom logic to determine if the resource can be paused
    return someCondition
})

func (*UntypedResourceBuilder[CustomResource, ContextType]) WithKey ¶

func (b *UntypedResourceBuilder[CustomResource, ContextType]) WithKey(name types.NamespacedName) *UntypedResourceBuilder[CustomResource, ContextType]

WithKey specifies a static NamespacedName for the untyped resource.

This is useful when the resource name and namespace are known at build time and don't need to be computed dynamically based on the custom resource state.

For dynamic naming based on custom resource properties, use WithKeyFunc instead.

Example:

.WithKey(types.NamespacedName{
	Name:      "monitoring-config",
	Namespace: "monitoring",
}) // Static name for the monitoring resource

func (*UntypedResourceBuilder[CustomResource, ContextType]) WithKeyFunc ¶

func (b *UntypedResourceBuilder[CustomResource, ContextType]) WithKeyFunc(f func() types.NamespacedName) *UntypedResourceBuilder[CustomResource, ContextType]

WithKeyFunc specifies a function that dynamically determines the untyped resource's NamespacedName.

This function is called during reconciliation to determine where the resource should be created or found. For untyped resources, this is particularly important as the naming often needs to be coordinated with external operators or systems.

Example:

.WithKeyFunc(func() types.NamespacedName {
	cr := ctx.GetCustomResource()
	return types.NamespacedName{
		// Name follows third-party operator conventions
		Name:      fmt.Sprintf("%s-%s-monitor", cr.Name, cr.Spec.Component),
		Namespace: cr.Namespace,
	}
})

func (*UntypedResourceBuilder[CustomResource, ContextType]) WithMutator ¶

func (b *UntypedResourceBuilder[CustomResource, ContextType]) WithMutator(f Mutator[*unstructured.Unstructured]) *UntypedResourceBuilder[CustomResource, ContextType]

WithMutator specifies the function that configures the untyped resource's desired state.

The mutator function receives an unstructured.Unstructured object and should configure all necessary fields using the unstructured helper functions. This is where you define how your custom resource's spec translates into the target third-party resource configuration.

Working with unstructured objects requires using helper functions like:

• unstructured.SetNestedField() to set individual values
• unstructured.SetNestedSlice() to set arrays
• unstructured.SetNestedMap() to set objects

The mutator should be idempotent and handle both CREATE and UPDATE operations.

Example:

.WithMutator(func(obj *unstructured.Unstructured) error {
	cr := ctx.GetCustomResource()

	// Set basic metadata
	obj.SetName(cr.Name + "-servicemonitor")
	obj.SetNamespace(cr.Namespace)

	// Configure ServiceMonitor spec using unstructured helpers
	err := unstructured.SetNestedMap(obj.Object, map[string]any{
		"app": cr.Name,
	}, "spec", "selector", "matchLabels")
	if err != nil {
		return err
	}

	// Set endpoint configuration
	endpoints := []any{
		map[string]any{
			"port": "metrics",
			"path": "/metrics",
		},
	}
	err = unstructured.SetNestedSlice(obj.Object, endpoints, "spec", "endpoints")
	if err != nil {
		return err
	}

	// Set owner reference for garbage collection
	return controllerutil.SetOwnerReference(cr, obj, ctx.GetScheme())
})

func (*UntypedResourceBuilder[CustomResource, ContextType]) WithOutput ¶

func (b *UntypedResourceBuilder[CustomResource, ContextType]) WithOutput(obj *unstructured.Unstructured) *UntypedResourceBuilder[CustomResource, ContextType]

WithOutput specifies where to store the reconciled untyped resource after successful operations.

The provided unstructured.Unstructured object will be populated with the resource's current state from the cluster after reconciliation completes. This is particularly useful for untyped resources where you need to extract status information or other runtime values generated by third-party operators.

Example:

type MyContextData struct {
	ServiceMonitor *unstructured.Unstructured
}

resource := NewUntypedResourceBuilder(ctx, gvk).
	// ... other configuration ...
	WithOutput(ctx.Data.ServiceMonitor). // Store reconciled resource here
	Build()

// Later, access the reconciled resource
if ctx.Data.ServiceMonitor != nil {
	status, found, _ := unstructured.NestedString(
		ctx.Data.ServiceMonitor.Object, "status", "phase")
}

func (*UntypedResourceBuilder[CustomResource, ContextType]) WithReadinessCondition ¶

func (b *UntypedResourceBuilder[CustomResource, ContextType]) WithReadinessCondition(f func(obj *unstructured.Unstructured) bool) *UntypedResourceBuilder[CustomResource, ContextType]

WithReadinessCondition defines custom logic to determine when the untyped resource is ready.

The provided function is called with the current unstructured resource state and should return true if the resource has reached the desired operational state. This is particularly important for untyped resources that may have complex initialization processes managed by third-party operators.

Working with unstructured objects requires using helper functions to access nested fields.

Example:

.WithReadinessCondition(func(obj *unstructured.Unstructured) bool {
	// Check if Prometheus ServiceMonitor is being scraped
	status, found, _ := unstructured.NestedString(obj.Object, "status", "conditions")
	if !found {
		return false
	}

	// More complex readiness check
	lastScrape, found, _ := unstructured.NestedString(obj.Object, "status", "lastScrapeTime")
	if !found {
		return false
	}

	// Consider ready if scraped within last 5 minutes
	scrapeTime, err := time.Parse(time.RFC3339, lastScrape)
	return err == nil && time.Since(scrapeTime) < 5*time.Minute
})

func (*UntypedResourceBuilder[CustomResource, ContextType]) WithRequireManualDeletionForFinalize ¶

func (b *UntypedResourceBuilder[CustomResource, ContextType]) WithRequireManualDeletionForFinalize(f func(obj *unstructured.Unstructured) bool) *UntypedResourceBuilder[CustomResource, ContextType]

WithRequireManualDeletionForFinalize specifies when an untyped resource requires manual cleanup during custom resource finalization.

This is particularly important for untyped resources managed by third-party operators, as they may have complex deletion procedures or external dependencies that need special handling.

Working with unstructured objects requires using helper functions to access nested fields.

Example:

.WithRequireManualDeletionForFinalize(func(obj *unstructured.Unstructured) bool {
	// Check if resource has special deletion requirements
	deletionPolicy, found, _ := unstructured.NestedString(
		obj.Object, "spec", "deletionPolicy")
	if found && deletionPolicy == "Retain" {
		return true // Requires manual cleanup
	}

	// Check for external dependencies
	externalDeps, found, _ := unstructured.NestedSlice(
		obj.Object, "status", "externalDependencies")
	return found && len(externalDeps) > 0
})

func (*UntypedResourceBuilder[CustomResource, ContextType]) WithSkipAndDeleteOnCondition ¶

func (b *UntypedResourceBuilder[CustomResource, ContextType]) WithSkipAndDeleteOnCondition(f func() bool) *UntypedResourceBuilder[CustomResource, ContextType]

WithSkipAndDeleteOnCondition specifies when to skip creating or delete an existing untyped resource.

This is particularly useful for untyped resources that depend on optional third-party operators or should only be created under certain conditions. The function is evaluated during each reconciliation cycle.

Common use cases for untyped resources:

• Optional monitoring resources (when Prometheus operator might not be installed)
• Feature flag controlled third-party integrations
• Environment-specific operator resources
• Conditional third-party service configurations

Example:

.WithSkipAndDeleteOnCondition(func() bool {
	cr := ctx.GetCustomResource()

	// Only create monitoring resources if monitoring is enabled
	if !cr.Spec.Monitoring.Enabled {
		return true
	}

	// Check if the required operator is available
	client := ctx.GetClient()
	prometheusOperator := &appsv1.Deployment{}
	err := client.Get(ctx, types.NamespacedName{
		Name: "prometheus-operator",
		Namespace: "monitoring",
	}, prometheusOperator)

	// Skip if operator not found or not ready
	return err != nil || prometheusOperator.Status.ReadyReplicas == 0
})

func (*UntypedResourceBuilder[CustomResource, ContextType]) WithUserIdentifier ¶

func (b *UntypedResourceBuilder[CustomResource, ContextType]) WithUserIdentifier(identifier string) *UntypedResourceBuilder[CustomResource, ContextType]

WithUserIdentifier assigns a custom identifier for this untyped resource.

This identifier is used for logging, debugging, and distinguishing between multiple untyped resources. It's especially important for untyped resources since the resource types may not be immediately obvious from logs, and you might be managing multiple third-party resources of different types.

The identifier should be descriptive and include both the resource purpose and type.

Example:

.WithUserIdentifier("prometheus-servicemonitor") // Clear purpose and type
.WithUserIdentifier("grafana-dashboard-app")     // Identifies both operator and purpose
.WithUserIdentifier("istio-virtualservice")     // Service mesh resource identifier

func (*WatchCache) AddWatchSource ¶

func (w *WatchCache) AddWatchSource(key WatchCacheKey)

func (*WatchCache) GetController ¶

func (w *WatchCache) GetController() controller.TypedController[reconcile.Request]

func (*WatchCache) IsWatchingSource ¶

func (w *WatchCache) IsWatchingSource(key WatchCacheKey) bool

func (*WatchCache) SetController ¶

func (w *WatchCache) SetController(ctrler controller.TypedController[reconcile.Request])