generic

package
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Mar 30, 2026 License: Apache-2.0 Imports: 6 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 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.

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.

func (*BaseBuilder[T, M]) WithCustomSuspendMutation 

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

WithCustomSuspendMutation overrides the resource suspension mutation handler.

func (*BaseBuilder[T, M]) WithCustomSuspendStatus 

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

WithCustomSuspendStatus overrides the resource suspension status handler.

func (*BaseBuilder[T, M]) WithDataExtractor 

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

WithDataExtractor registers a typed data extractor to run after successful reconciliation.

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]) WithMutation 

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

WithMutation registers a typed feature mutation for the resource.

type BaseResource 

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

	IdentityFunc func(T) string

	DataExtractors []func(T) error

	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
}

BaseResource provides shared behavior for all generic internal resource implementations.

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 registered data extractors against a deep copy of the reconciled object.

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 precondition. If no guard handler is configured, the resource is unconditionally unblocked. The 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]) 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]) 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]) 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 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.

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.

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.

func (*IntegrationBuilder[T, M]) WithDataExtractor 

func (b *IntegrationBuilder[T, M]) WithDataExtractor(
	extractor func(T) error,
) *IntegrationBuilder[T, M]

WithDataExtractor registers a typed data extractor to run after successful reconciliation.

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]) WithMutation 

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

WithMutation registers a typed feature mutation for the integration.

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]) WithDataExtractor 

func (b *StaticBuilder[T, M]) WithDataExtractor(
	extractor func(T) error,
) *StaticBuilder[T, M]

WithDataExtractor registers a typed data extractor to run after successful reconciliation.

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]) WithMutation 

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

WithMutation registers a typed feature mutation for the static resource.

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.

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.

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.

func (*TaskBuilder[T, M]) WithDataExtractor 

func (b *TaskBuilder[T, M]) WithDataExtractor(
	extractor func(T) error,
) *TaskBuilder[T, M]

WithDataExtractor registers a typed data extractor to run after successful reconciliation.

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]) WithMutation 

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

WithMutation registers a typed feature mutation for the task.

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.

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.

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.

func (*WorkloadBuilder[T, M]) WithDataExtractor 

func (b *WorkloadBuilder[T, M]) WithDataExtractor(
	extractor func(T) error,
) *WorkloadBuilder[T, M]

WithDataExtractor registers a typed data extractor to run after successful reconciliation.

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]) WithMutation 

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

WithMutation registers a typed feature mutation for the workload.

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.