generic

package
v0.21.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 26, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package generic provides generic builders and resources for operator components.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ApplyMutations 

func ApplyMutations[T client.Object, M FeatureMutator](
	current client.Object,
	newMutator func(T) M,
	mutations []Mutation[M],
	suspender func(M) error,
) (T, error)

ApplyMutations provides a shared implementation for the Mutate method in generic resources. It handles:

  1. Feature mutations
  2. Optional suspension mutations

func ExtractInto added in v0.18.0 

func ExtractInto[T client.Object, M FeatureMutator, V any](
	b *BaseBuilder[T, M], cell *concepts.Data[V], fn func(T) (V, error),
)

ExtractInto declares that the resource built by b produces the value of cell. fn computes the value from the reconciled object; the framework stores it in the cell and marks it present. The extraction runs immediately after the resource is applied or fetched, before subsequent resources reconcile.

This is a package-level function rather than a builder method because Go methods cannot introduce the extra type parameter V.

Extracting several values from one object means several ExtractInto calls, one per cell. Multiple resources may produce the same cell; the last registered producer's extraction wins at runtime.

A nil cell or nil fn is rejected when the builder's Build method runs.

func PreserveServerManagedFields 

func PreserveServerManagedFields(dst, src client.Object)

PreserveServerManagedFields restores server-managed and shared-controller metadata fields from src onto dst.

Call this after replacing an object via deep copy to ensure fields populated by the API server or other controllers are not lost. The preserved fields are:

Server-managed (read-only): ResourceVersion, UID, Generation, CreationTimestamp, DeletionTimestamp, DeletionGracePeriodSeconds, ManagedFields, SelfLink.

Shared across controllers: OwnerReferences, Finalizers.

func PreserveStatus 

func PreserveStatus[T client.Object](dst, src T)

PreserveStatus copies the Status field from src to dst using reflection.

Most Kubernetes resource types have a Status subresource that is managed by the API server or status-writing controllers, not by spec-level reconciliation. Field applicators that replace the entire object (e.g. *current = *desired) inadvertently overwrite the live status. Call this function after such a replacement to restore the status from the original live object.

If either object's underlying struct does not have a field named "Status", the call is a no-op.

func WrapExtraction added in v0.18.0 

func WrapExtraction[E any, V any](fn func(E) (V, error)) func(*E) (V, error)

WrapExtraction converts a value-receiver extraction callback into a pointer-receiver callback suitable for the generic layer's ExtractInto. If the input function is nil, nil is returned.

func WrapGuard added in v0.5.1 

func WrapGuard[E any](guard func(E) (concepts.GuardStatusWithReason, error)) func(*E) (concepts.GuardStatusWithReason, error)

WrapGuard converts a value-receiver guard callback into a pointer-receiver guard callback suitable for the generic builder layer. If the input function is nil, nil is returned.

Types

type BaseBuilder 

type BaseBuilder[T client.Object, M FeatureMutator] struct {
	BaseRes *BaseResource[T, M]
	// contains filtered or unexported fields
}

BaseBuilder provides shared behavior for all generic internal resource builders.

func (*BaseBuilder[T, M]) InitBase 

func (b *BaseBuilder[T, M]) InitBase(
	obj T,
	identityFunc func(T) string,
	newMutator func(T) M,
)

InitBase initializes the base resource configuration.

Safe defaults are configured for suspension handlers so that custom resource wrappers built on the generic layer do not need to set them explicitly:

  • SuspendMutationHandler: no-op (does nothing on suspend)
  • SuspendStatusHandler: reports Suspended immediately

DeleteOnSuspend defaults to false via a nil-check in BaseResource.DeleteOnSuspend.

func (*BaseBuilder[T, M]) MarkClusterScoped 

func (b *BaseBuilder[T, M]) MarkClusterScoped()

MarkClusterScoped marks the resource as cluster-scoped. ValidateBase will reject a non-empty namespace instead of requiring one.

func (*BaseBuilder[T, M]) ValidateBase 

func (b *BaseBuilder[T, M]) ValidateBase() error

ValidateBase validates the base resource configuration.

func (*BaseBuilder[T, M]) WithCustomSuspendDeletionDecision 

func (b *BaseBuilder[T, M]) WithCustomSuspendDeletionDecision(handler func(T) bool)

WithCustomSuspendDeletionDecision overrides the resource delete-on-suspend decision handler.

The handler receives BaseResource.DesiredObject and may be consulted twice in a suspension pass: once before the suspension apply, so an already-absent delete-on-suspend resource is not recreated, and once more only after the resource reports concepts.SuspensionStatusSuspended, to decide whether to delete it. The first call happens on every pass, so the decision must not depend on post-apply status fields, and it must answer the same way in both calls.

func (*BaseBuilder[T, M]) WithCustomSuspendMutation 

func (b *BaseBuilder[T, M]) WithCustomSuspendMutation(handler func(M) error)

WithCustomSuspendMutation overrides the resource suspension mutation handler.

The handler receives the mutator for the object that is about to be applied, before the patch is sent, and records the suspension intent on it. The framework then applies the recorded mutations and patches the result.

Like any mutation, it must be a pure function of the spec and the inputs available when the resource was built. Do not read live cluster state to decide what to write: the object behind the mutator is desired state on its way to the API server, not an observation of it.

func (*BaseBuilder[T, M]) WithCustomSuspendStatus 

func (b *BaseBuilder[T, M]) WithCustomSuspendStatus(
	handler func(T) (concepts.SuspensionStatusWithReason, error),
)

WithCustomSuspendStatus overrides the resource suspension status handler.

The handler receives BaseResource.DesiredObject as it stands after the suspension apply of the current reconcile. Mutate stores the mutated object in DesiredObject and the Server-Side Apply patch decodes the API server's response into that same object, so the handler observes server-populated fields, including Generation and Status. A handler may therefore compare status.observedGeneration against Generation to decide whether the object's own controller has already observed the suspension mutation, instead of reading a readiness field that is still describing the pre-suspension spec.

func (*BaseBuilder[T, M]) WithDataGuard added in v0.18.0 

func (b *BaseBuilder[T, M]) WithDataGuard(cells ...concepts.DataCell)

WithDataGuard declares that the resource reads the given cells and must not be applied until every one of them is set. The framework generates the guard and its reason (for example: waiting for data "db-host"), so the reason can never drift from the actual dependency. A blocked data guard surfaces as the same Blocked condition reason custom guards produce.

Data guards are evaluated before any custom guard registered with WithGuard; both may be combined. Component Build validates that a producer for each cell is registered strictly earlier in the component.

func (*BaseBuilder[T, M]) WithGuard added in v0.4.0 

func (b *BaseBuilder[T, M]) WithGuard(handler func(T) (concepts.GuardStatusWithReason, error))

WithGuard registers a guard precondition for the resource. The guard is evaluated before each apply during reconciliation. If it returns Blocked, the resource and all resources after it are skipped until the guard clears. Passing nil clears any previously registered guard.

func (*BaseBuilder[T, M]) WithMetricsIdentifier added in v0.20.0 

func (b *BaseBuilder[T, M]) WithMetricsIdentifier(identifier string)

WithMetricsIdentifier sets the resource's identifier for resource-level metrics. It becomes the value of the `resource` label on ocf_resource_apply_total and ocf_resource_apply_errors_total.

This is a Prometheus label value, not the name of anything in Kubernetes. It must be low-cardinality and stable across reconciles: a constant, or a value drawn from a small fixed set. Deriving it from a per-owner value such as the custom resource's name produces one time series per owner, and the framework never removes a series once created.

When unset, the framework labels the resource with its lowercased kind. Set an identifier to tell two resources of the same kind apart within one component, or when the object's name carries a generated suffix.

The identifier must not be blank. Build rejects an empty or whitespace-only value; omit the call to accept the default.

func (*BaseBuilder[T, M]) WithMutation 

func (b *BaseBuilder[T, M]) WithMutation(ms ...Mutation[M])

WithMutation registers one or more typed feature mutations for the resource. Mutations are appended in the order provided; calling it with no arguments is a no-op.

func (*BaseBuilder[T, M]) WithOptionalData added in v0.18.0 

func (b *BaseBuilder[T, M]) WithOptionalData(cells ...concepts.DataCell)

WithOptionalData declares that the resource reads the given cells without gating on them. The declaration exists so component Build still verifies a producer is registered earlier (an optional read with no producer is permanently absent, which is dead code and almost certainly a bug) and so the dependency stays visible to introspection. Consumers in this mode use Get and skip quietly when the cell is absent.

type BaseResource 

type BaseResource[T client.Object, M FeatureMutator] struct {
	DesiredObject T

	IdentityFunc func(T) string

	// DataExtractions holds the declared data extractions recorded by
	// ExtractInto, run by ExtractData after the resource is applied or fetched.
	DataExtractions []DataExtraction[T]

	// DataConsumptions holds the declared data reads recorded by WithDataGuard
	// and WithOptionalData, in declaration order.
	DataConsumptions []concepts.DataConsumption

	NewMutator func(T) M
	Mutations  []Mutation[M]

	Suspender func(M) error

	GuardHandler func(T) (concepts.GuardStatusWithReason, error)

	SuspendStatusHandler   func(T) (concepts.SuspensionStatusWithReason, error)
	SuspendMutationHandler func(M) error
	DeleteOnSuspendHandler func(T) bool
	// contains filtered or unexported fields
}

BaseResource provides shared behavior for all generic internal resource implementations.

func (*BaseResource[T, M]) ConsumedData added in v0.18.0 

func (r *BaseResource[T, M]) ConsumedData() []concepts.DataConsumption

ConsumedData returns the resource's declared data reads in declaration order. It satisfies concepts.DataConsumer.

func (*BaseResource[T, M]) DeleteOnSuspend 

func (r *BaseResource[T, M]) DeleteOnSuspend() bool

DeleteOnSuspend reports whether the resource should be deleted when suspended.

func (*BaseResource[T, M]) ExtractData 

func (r *BaseResource[T, M]) ExtractData() error

ExtractData runs all declared data extractions against a deep copy of the reconciled object, storing each computed value in its cell.

For managed resources the reconciled object is the desired state produced by Mutate. For read-only resources it is the object most recently supplied via RecordObservation, which the read flow invokes after fetching from the cluster. Extractions run on every reconcile pass.

func (*BaseResource[T, M]) FiringSet added in v0.14.0 

func (r *BaseResource[T, M]) FiringSet() ([]string, error)

FiringSet returns the deduplicated Names of registered mutations whose gate is enabled for the version the resource was built at, in first-occurrence registration order. A mutation with a nil Feature fires unconditionally. It returns an error if any gate's Enabled evaluation fails. It satisfies concepts.MutationInspector.

func (*BaseResource[T, M]) GuardStatus added in v0.4.0 

func (r *BaseResource[T, M]) GuardStatus() (concepts.GuardStatusWithReason, error)

GuardStatus evaluates the resource's guard preconditions.

Declared data guards (WithDataGuard) are evaluated first: if any guarded cell is unset, the resource is Blocked with a framework-generated reason naming the missing cells. Only when every guarded cell is set is the custom guard handler (WithGuard) consulted. If neither is configured, the resource is unconditionally unblocked.

The custom handler receives a deep copy of the desired object to prevent accidental mutations.

func (*BaseResource[T, M]) Identity 

func (r *BaseResource[T, M]) Identity() string

Identity returns the stable framework identity for the resource.

func (*BaseResource[T, M]) MetricsIdentifier added in v0.20.0 

func (r *BaseResource[T, M]) MetricsIdentifier() string

MetricsIdentifier returns the resource's configured metrics identifier, or an empty string when none was set, in which case the framework labels the resource with its lowercased kind. It satisfies concepts.MetricsIdentifiable.

func (*BaseResource[T, M]) Mutate 

func (r *BaseResource[T, M]) Mutate(current client.Object) error

Mutate applies feature mutations and any active suspension mutation to the provided current object.

func (*BaseResource[T, M]) Object 

func (r *BaseResource[T, M]) Object() (client.Object, error)

Object returns a deep copy of the desired object.

func (*BaseResource[T, M]) Preview added in v0.11.0 

func (r *BaseResource[T, M]) Preview() (client.Object, error)

Preview renders the desired object as a client.Object with feature mutations applied, without modifying the resource's internal state. It wraps PreviewObject so resources can be previewed polymorphically through the component's Previewable capability.

Suspension mutations are not applied; the preview reflects content state only.

func (*BaseResource[T, M]) PreviewObject 

func (r *BaseResource[T, M]) PreviewObject() (T, error)

PreviewObject returns the object as it would appear after feature mutations have been applied, without modifying the resource's internal DesiredObject.

The desired object is used as a stand-in for the current cluster state.

Suspension mutations are not applied; the preview reflects content state only.

func (*BaseResource[T, M]) ProducedData added in v0.18.0 

func (r *BaseResource[T, M]) ProducedData() []concepts.DataCell

ProducedData returns the cells this resource declares extractions into, deduplicated by cell identity, in declaration order. It satisfies concepts.DataProducer.

func (*BaseResource[T, M]) RecordObservation added in v0.9.0 

func (r *BaseResource[T, M]) RecordObservation(observed client.Object) error

RecordObservation stores the supplied object as the resource's most recently observed cluster state. The framework invokes this on read-only resources immediately after fetching them, so that subsequent capabilities such as ExtractData observe the live object rather than the inert base used to construct the resource.

RecordObservation returns an error when the supplied object is not assignable to the resource's underlying type.

func (*BaseResource[T, M]) RegisteredMutations added in v0.14.0 

func (r *BaseResource[T, M]) RegisteredMutations() []string

RegisteredMutations returns the deduplicated Names of every mutation registered on the resource, in registration order, independent of the version it was built at. It satisfies concepts.MutationInspector.

func (*BaseResource[T, M]) Suspend 

func (r *BaseResource[T, M]) Suspend() error

Suspend registers the configured suspension mutation for the next mutate cycle.

func (*BaseResource[T, M]) SuspensionStatus 

func (r *BaseResource[T, M]) SuspensionStatus() (concepts.SuspensionStatusWithReason, error)

SuspensionStatus reports the resource's suspension status using the configured handler.

type DataExtraction added in v0.18.0 

type DataExtraction[T client.Object] struct {
	// Cell is the destination cell, held through the non-generic DataCell view.
	Cell concepts.DataCell
	// Extract computes the value from the reconciled object and stores it in
	// the cell. A nil Extract is rejected at Build time.
	Extract func(T) error
}

DataExtraction records one declared write of a data cell by a resource: the destination cell plus the function that computes and stores its value. It is recorded by ExtractInto; constructing it manually is unsupported.

type FeatureMutator 

type FeatureMutator interface {
	MutatorApplier
	NextFeature()
}

FeatureMutator is the required interface for mutators used with the generic resource types. It extends MutatorApplier with NextFeature, which the framework calls between each registered mutation to maintain per-feature ordering boundaries.

type Gate added in v0.3.0 

type Gate = feature.Gate

Gate is an alias for feature.Gate.

type IntegrationBuilder 

type IntegrationBuilder[T client.Object, M FeatureMutator] struct {
	BaseBuilder[T, M]
	// contains filtered or unexported fields
}

IntegrationBuilder configures a generic internal integration resource for Kubernetes primitives such as Services, Ingresses, and Gateways.

func NewIntegrationBuilder 

func NewIntegrationBuilder[T client.Object, M FeatureMutator](
	obj T,
	identityFunc func(T) string,
	newMutator func(T) M,
) *IntegrationBuilder[T, M]

NewIntegrationBuilder creates a new generic integration builder.

The provided object is treated as the desired base state. The mutator factory is used to construct the typed mutator during Mutate.

func (*IntegrationBuilder[T, M]) Build 

func (b *IntegrationBuilder[T, M]) Build() (*IntegrationResource[T, M], error)

Build validates the integration builder configuration and returns the initialized resource.

It returns an error if the operational status handler has not been set.

func (*IntegrationBuilder[T, M]) WithCustomGraceStatus 

func (b *IntegrationBuilder[T, M]) WithCustomGraceStatus(
	handler func(T) (concepts.GraceStatusWithReason, error),
) *IntegrationBuilder[T, M]

WithCustomGraceStatus overrides the integration grace status handler.

func (*IntegrationBuilder[T, M]) WithCustomOperationalStatus 

func (b *IntegrationBuilder[T, M]) WithCustomOperationalStatus(
	handler func(concepts.ConvergingOperation, T) (concepts.OperationalStatusWithReason, error),
) *IntegrationBuilder[T, M]

WithCustomOperationalStatus overrides the integration operational status handler.

func (*IntegrationBuilder[T, M]) WithCustomSuspendDeletionDecision 

func (b *IntegrationBuilder[T, M]) WithCustomSuspendDeletionDecision(
	handler func(T) bool,
) *IntegrationBuilder[T, M]

WithCustomSuspendDeletionDecision overrides the integration delete-on-suspend decision handler.

The handler is consulted both before the suspension apply and after the resource reports Suspended, so the decision must be stable across both. See BaseBuilder.WithCustomSuspendDeletionDecision.

func (*IntegrationBuilder[T, M]) WithCustomSuspendMutation 

func (b *IntegrationBuilder[T, M]) WithCustomSuspendMutation(
	handler func(M) error,
) *IntegrationBuilder[T, M]

WithCustomSuspendMutation overrides the integration suspension mutation handler.

The handler receives the mutator for the object that is about to be applied and records the suspension intent on it. Like any mutation it must be a pure function of the spec, never of live cluster state. See BaseBuilder.WithCustomSuspendMutation.

func (*IntegrationBuilder[T, M]) WithCustomSuspendStatus 

func (b *IntegrationBuilder[T, M]) WithCustomSuspendStatus(
	handler func(T) (concepts.SuspensionStatusWithReason, error),
) *IntegrationBuilder[T, M]

WithCustomSuspendStatus overrides the integration suspension status handler.

The handler receives the object as it stands after the suspension apply of the current reconcile, so it observes server-populated fields such as Generation and Status. See BaseBuilder.WithCustomSuspendStatus.

func (*IntegrationBuilder[T, M]) WithDataGuard added in v0.18.0 

func (b *IntegrationBuilder[T, M]) WithDataGuard(cells ...concepts.DataCell) *IntegrationBuilder[T, M]

WithDataGuard declares blocking data reads for the integration resource. See BaseBuilder.WithDataGuard.

func (*IntegrationBuilder[T, M]) WithGuard added in v0.4.0 

func (b *IntegrationBuilder[T, M]) WithGuard(
	handler func(T) (concepts.GuardStatusWithReason, error),
) *IntegrationBuilder[T, M]

WithGuard registers a guard precondition for the integration resource.

func (*IntegrationBuilder[T, M]) WithMetricsIdentifier added in v0.20.0 

func (b *IntegrationBuilder[T, M]) WithMetricsIdentifier(identifier string) *IntegrationBuilder[T, M]

WithMetricsIdentifier sets the integration resource's metrics identifier. See BaseBuilder.WithMetricsIdentifier.

func (*IntegrationBuilder[T, M]) WithMutation 

func (b *IntegrationBuilder[T, M]) WithMutation(
	ms ...Mutation[M],
) *IntegrationBuilder[T, M]

WithMutation registers one or more typed feature mutations for the integration, in the order provided.

func (*IntegrationBuilder[T, M]) WithOptionalData added in v0.18.0 

func (b *IntegrationBuilder[T, M]) WithOptionalData(cells ...concepts.DataCell) *IntegrationBuilder[T, M]

WithOptionalData declares non-blocking data reads for the integration resource. See BaseBuilder.WithOptionalData.

type IntegrationResource 

type IntegrationResource[T client.Object, M FeatureMutator] struct {
	BaseResource[T, M]

	OperationalStatusHandler func(concepts.ConvergingOperation, T) (concepts.OperationalStatusWithReason, error)
	GraceStatusHandler       func(T) (concepts.GraceStatusWithReason, error)
}

IntegrationResource is a generic internal resource implementation for Kubernetes integration objects such as Services, Ingresses, and Gateways.

It provides shared behavior for:

  • baseline field application
  • feature mutations
  • data extraction

Concrete integration packages are expected to wrap this type and provide kind-specific identity and status logic.

func (*IntegrationResource[T, M]) ConvergingStatus 

func (r *IntegrationResource[T, M]) ConvergingStatus(
	op concepts.ConvergingOperation,
) (concepts.OperationalStatusWithReason, error)

ConvergingStatus reports the integration's operational status using the configured handler.

func (*IntegrationResource[T, M]) GraceStatus 

func (r *IntegrationResource[T, M]) GraceStatus() (concepts.GraceStatusWithReason, error)

GraceStatus reports the integration's grace status using the configured handler.

type Mutation 

type Mutation[T any] = feature.Mutation[T]

Mutation is an alias for feature.Mutation.

Using the alias throughout internal/generic keeps the internal implementation consistent without redefining types that belong to the public API surface.

type MutatorApplier 

type MutatorApplier interface {
	Apply() error
}

MutatorApplier is implemented by mutators that can apply their planned changes to the underlying Kubernetes object.

type StaticBuilder 

type StaticBuilder[T client.Object, M FeatureMutator] struct {
	BaseBuilder[T, M]
	// contains filtered or unexported fields
}

StaticBuilder configures a generic internal static resource for Kubernetes objects such as ConfigMaps and Secrets.

It captures the common framework concepts for static desired-state resources while leaving concrete identity behavior to the caller.

func NewStaticBuilder 

func NewStaticBuilder[T client.Object, M FeatureMutator](
	obj T,
	identityFunc func(T) string,
	newMutator func(T) M,
) *StaticBuilder[T, M]

NewStaticBuilder creates a new generic static builder.

The provided object is treated as the desired base state. The identity function must return a stable framework identity for the object. The mutator factory constructs a typed mutator during each Mutate call.

func (*StaticBuilder[T, M]) Build 

func (b *StaticBuilder[T, M]) Build() (*StaticResource[T, M], error)

Build validates the static builder configuration and returns the initialized resource.

func (*StaticBuilder[T, M]) WithDataGuard added in v0.18.0 

func (b *StaticBuilder[T, M]) WithDataGuard(cells ...concepts.DataCell) *StaticBuilder[T, M]

WithDataGuard declares blocking data reads for the static resource. See BaseBuilder.WithDataGuard.

func (*StaticBuilder[T, M]) WithGuard added in v0.4.0 

func (b *StaticBuilder[T, M]) WithGuard(
	handler func(T) (concepts.GuardStatusWithReason, error),
) *StaticBuilder[T, M]

WithGuard registers a guard precondition for the static resource.

func (*StaticBuilder[T, M]) WithMetricsIdentifier added in v0.20.0 

func (b *StaticBuilder[T, M]) WithMetricsIdentifier(identifier string) *StaticBuilder[T, M]

WithMetricsIdentifier sets the static resource's metrics identifier. See BaseBuilder.WithMetricsIdentifier.

func (*StaticBuilder[T, M]) WithMutation 

func (b *StaticBuilder[T, M]) WithMutation(ms ...Mutation[M]) *StaticBuilder[T, M]

WithMutation registers one or more typed feature mutations for the static resource, in the order provided.

func (*StaticBuilder[T, M]) WithOptionalData added in v0.18.0 

func (b *StaticBuilder[T, M]) WithOptionalData(cells ...concepts.DataCell) *StaticBuilder[T, M]

WithOptionalData declares non-blocking data reads for the static resource. See BaseBuilder.WithOptionalData.

type StaticResource 

type StaticResource[T client.Object, M FeatureMutator] struct {
	BaseResource[T, M]
}

StaticResource is a generic internal resource implementation for Kubernetes objects that are treated as static desired-state resources, such as ConfigMaps and Secrets.

It supports:

  • default or custom baseline field application
  • feature mutations
  • data extraction after reconciliation

Unlike workload, task, and integration resources, it does not support convergence status, grace status, or suspension behavior.

type TaskBuilder 

type TaskBuilder[T client.Object, M FeatureMutator] struct {
	BaseBuilder[T, M]
	// contains filtered or unexported fields
}

TaskBuilder configures a generic internal task resource for Kubernetes primitives that run to completion, such as Jobs.

It captures the common framework concepts while leaving kind-specific defaults and wrappers to the concrete task packages.

func NewTaskBuilder 

func NewTaskBuilder[T client.Object, M FeatureMutator](
	obj T,
	identityFunc func(T) string,
	newMutator func(T) M,
) *TaskBuilder[T, M]

NewTaskBuilder creates a new generic task builder.

The provided object is treated as the desired base state. The mutator factory is used to construct the typed mutator during Mutate.

func (*TaskBuilder[T, M]) Build 

func (b *TaskBuilder[T, M]) Build() (*TaskResource[T, M], error)

Build validates the task builder configuration and returns the initialized resource.

It returns an error if the converging status handler has not been set.

func (*TaskBuilder[T, M]) WithCustomConvergeStatus 

func (b *TaskBuilder[T, M]) WithCustomConvergeStatus(
	handler func(concepts.ConvergingOperation, T) (concepts.CompletionStatusWithReason, error),
) *TaskBuilder[T, M]

WithCustomConvergeStatus overrides the task convergence status handler.

func (*TaskBuilder[T, M]) WithCustomSuspendDeletionDecision 

func (b *TaskBuilder[T, M]) WithCustomSuspendDeletionDecision(
	handler func(T) bool,
) *TaskBuilder[T, M]

WithCustomSuspendDeletionDecision overrides the task delete-on-suspend decision handler.

The handler is consulted both before the suspension apply and after the resource reports Suspended, so the decision must be stable across both. See BaseBuilder.WithCustomSuspendDeletionDecision.

func (*TaskBuilder[T, M]) WithCustomSuspendMutation 

func (b *TaskBuilder[T, M]) WithCustomSuspendMutation(
	handler func(M) error,
) *TaskBuilder[T, M]

WithCustomSuspendMutation overrides the task suspension mutation handler.

The handler receives the mutator for the object that is about to be applied and records the suspension intent on it. Like any mutation it must be a pure function of the spec, never of live cluster state. See BaseBuilder.WithCustomSuspendMutation.

func (*TaskBuilder[T, M]) WithCustomSuspendStatus 

func (b *TaskBuilder[T, M]) WithCustomSuspendStatus(
	handler func(T) (concepts.SuspensionStatusWithReason, error),
) *TaskBuilder[T, M]

WithCustomSuspendStatus overrides the task suspension status handler.

The handler receives the object as it stands after the suspension apply of the current reconcile, so it observes server-populated fields such as Generation and Status. See BaseBuilder.WithCustomSuspendStatus.

func (*TaskBuilder[T, M]) WithDataGuard added in v0.18.0 

func (b *TaskBuilder[T, M]) WithDataGuard(cells ...concepts.DataCell) *TaskBuilder[T, M]

WithDataGuard declares blocking data reads for the task resource. See BaseBuilder.WithDataGuard.

func (*TaskBuilder[T, M]) WithGuard added in v0.4.0 

func (b *TaskBuilder[T, M]) WithGuard(
	handler func(T) (concepts.GuardStatusWithReason, error),
) *TaskBuilder[T, M]

WithGuard registers a guard precondition for the task resource.

func (*TaskBuilder[T, M]) WithMetricsIdentifier added in v0.20.0 

func (b *TaskBuilder[T, M]) WithMetricsIdentifier(identifier string) *TaskBuilder[T, M]

WithMetricsIdentifier sets the task resource's metrics identifier. See BaseBuilder.WithMetricsIdentifier.

func (*TaskBuilder[T, M]) WithMutation 

func (b *TaskBuilder[T, M]) WithMutation(
	ms ...Mutation[M],
) *TaskBuilder[T, M]

WithMutation registers one or more typed feature mutations for the task, in the order provided.

func (*TaskBuilder[T, M]) WithOptionalData added in v0.18.0 

func (b *TaskBuilder[T, M]) WithOptionalData(cells ...concepts.DataCell) *TaskBuilder[T, M]

WithOptionalData declares non-blocking data reads for the task resource. See BaseBuilder.WithOptionalData.

type TaskResource 

type TaskResource[T client.Object, M FeatureMutator] struct {
	BaseResource[T, M]

	ConvergingStatusHandler func(concepts.ConvergingOperation, T) (concepts.CompletionStatusWithReason, error)
}

TaskResource is a generic internal resource implementation for Kubernetes objects that run to completion, such as Jobs.

It provides shared behavior for:

  • baseline field application
  • feature mutations
  • suspension mutations
  • data extraction

Concrete task packages are expected to wrap this type and provide kind-specific identity and status logic.

func (*TaskResource[T, M]) ConvergingStatus 

func (r *TaskResource[T, M]) ConvergingStatus(
	op concepts.ConvergingOperation,
) (concepts.CompletionStatusWithReason, error)

ConvergingStatus reports the task's completion status using the configured handler.

type WorkloadBuilder 

type WorkloadBuilder[T client.Object, M FeatureMutator] struct {
	BaseBuilder[T, M]
	// contains filtered or unexported fields
}

WorkloadBuilder configures a generic internal workload resource for Kubernetes primitives such as Deployments, StatefulSets, and DaemonSets.

It captures the common framework concepts while leaving kind-specific defaults and wrappers to the concrete workload packages.

func NewWorkloadBuilder 

func NewWorkloadBuilder[T client.Object, M FeatureMutator](
	obj T,
	identityFunc func(T) string,
	newMutator func(T) M,
) *WorkloadBuilder[T, M]

NewWorkloadBuilder creates a new generic workload builder.

The provided object is treated as the desired base state. The mutator factory is used to construct the typed mutator during Mutate.

func (*WorkloadBuilder[T, M]) Build 

func (b *WorkloadBuilder[T, M]) Build() (*WorkloadResource[T, M], error)

Build validates the workload builder configuration and returns the initialized resource.

It returns an error if the converging status handler has not been set.

func (*WorkloadBuilder[T, M]) WithCustomConvergeStatus 

func (b *WorkloadBuilder[T, M]) WithCustomConvergeStatus(
	handler func(concepts.ConvergingOperation, T) (concepts.AliveStatusWithReason, error),
) *WorkloadBuilder[T, M]

WithCustomConvergeStatus overrides the workload convergence status handler.

func (*WorkloadBuilder[T, M]) WithCustomGraceStatus 

func (b *WorkloadBuilder[T, M]) WithCustomGraceStatus(
	handler func(T) (concepts.GraceStatusWithReason, error),
) *WorkloadBuilder[T, M]

WithCustomGraceStatus overrides the workload grace status handler.

func (*WorkloadBuilder[T, M]) WithCustomSuspendDeletionDecision 

func (b *WorkloadBuilder[T, M]) WithCustomSuspendDeletionDecision(
	handler func(T) bool,
) *WorkloadBuilder[T, M]

WithCustomSuspendDeletionDecision overrides the workload delete-on-suspend decision handler.

The handler is consulted both before the suspension apply and after the resource reports Suspended, so the decision must be stable across both. See BaseBuilder.WithCustomSuspendDeletionDecision.

func (*WorkloadBuilder[T, M]) WithCustomSuspendMutation 

func (b *WorkloadBuilder[T, M]) WithCustomSuspendMutation(
	handler func(M) error,
) *WorkloadBuilder[T, M]

WithCustomSuspendMutation overrides the workload suspension mutation handler.

The handler receives the mutator for the object that is about to be applied and records the suspension intent on it. Like any mutation it must be a pure function of the spec, never of live cluster state. See BaseBuilder.WithCustomSuspendMutation.

func (*WorkloadBuilder[T, M]) WithCustomSuspendStatus 

func (b *WorkloadBuilder[T, M]) WithCustomSuspendStatus(
	handler func(T) (concepts.SuspensionStatusWithReason, error),
) *WorkloadBuilder[T, M]

WithCustomSuspendStatus overrides the workload suspension status handler.

The handler receives the object as it stands after the suspension apply of the current reconcile, so it observes server-populated fields such as Generation and Status. See BaseBuilder.WithCustomSuspendStatus.

func (*WorkloadBuilder[T, M]) WithDataGuard added in v0.18.0 

func (b *WorkloadBuilder[T, M]) WithDataGuard(cells ...concepts.DataCell) *WorkloadBuilder[T, M]

WithDataGuard declares blocking data reads for the workload resource. See BaseBuilder.WithDataGuard.

func (*WorkloadBuilder[T, M]) WithGuard added in v0.4.0 

func (b *WorkloadBuilder[T, M]) WithGuard(
	handler func(T) (concepts.GuardStatusWithReason, error),
) *WorkloadBuilder[T, M]

WithGuard registers a guard precondition for the workload resource.

func (*WorkloadBuilder[T, M]) WithMetricsIdentifier added in v0.20.0 

func (b *WorkloadBuilder[T, M]) WithMetricsIdentifier(identifier string) *WorkloadBuilder[T, M]

WithMetricsIdentifier sets the workload resource's metrics identifier. See BaseBuilder.WithMetricsIdentifier.

func (*WorkloadBuilder[T, M]) WithMutation 

func (b *WorkloadBuilder[T, M]) WithMutation(
	ms ...Mutation[M],
) *WorkloadBuilder[T, M]

WithMutation registers one or more typed feature mutations for the workload, in the order provided.

func (*WorkloadBuilder[T, M]) WithOptionalData added in v0.18.0 

func (b *WorkloadBuilder[T, M]) WithOptionalData(cells ...concepts.DataCell) *WorkloadBuilder[T, M]

WithOptionalData declares non-blocking data reads for the workload resource. See BaseBuilder.WithOptionalData.

type WorkloadResource 

type WorkloadResource[T client.Object, M FeatureMutator] struct {
	BaseResource[T, M]

	ConvergingStatusHandler func(concepts.ConvergingOperation, T) (concepts.AliveStatusWithReason, error)
	GraceStatusHandler      func(T) (concepts.GraceStatusWithReason, error)
}

WorkloadResource is a generic internal resource implementation for long-running Kubernetes workload objects such as Deployments, StatefulSets, and DaemonSets.

It provides shared behavior for:

  • baseline field application
  • feature mutations
  • suspension mutations
  • data extraction

Concrete workload packages are expected to wrap this type and provide kind-specific identity and status logic.

func (*WorkloadResource[T, M]) ConvergingStatus 

func (r *WorkloadResource[T, M]) ConvergingStatus(
	op concepts.ConvergingOperation,
) (concepts.AliveStatusWithReason, error)

ConvergingStatus reports the workload's convergence status using the configured handler.

func (*WorkloadResource[T, M]) GraceStatus 

func (r *WorkloadResource[T, M]) GraceStatus() (concepts.GraceStatusWithReason, error)

GraceStatus reports the workload's grace status using the configured handler.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.