Documentation
¶
Overview ¶
Package workload provides an unstructured resource primitive for long-running Kubernetes workload objects that require health tracking, graceful rollouts, and suspension support.
Index ¶
- type Builder
- func (b *Builder) Build() (*Resource, error)
- func (b *Builder) MarkClusterScoped() *Builder
- func (b *Builder) WithCustomConvergeStatus(...) *Builder
- func (b *Builder) WithCustomGraceStatus(handler func(*uns.Unstructured) (concepts.GraceStatusWithReason, error)) *Builder
- func (b *Builder) WithCustomSuspendDeletionDecision(handler func(*uns.Unstructured) bool) *Builder
- func (b *Builder) WithCustomSuspendMutation(handler func(*unstruct.Mutator) error) *Builder
- func (b *Builder) WithCustomSuspendStatus(handler func(*uns.Unstructured) (concepts.SuspensionStatusWithReason, error)) *Builder
- func (b *Builder) WithDataExtractor(extractor func(uns.Unstructured) error) *Builder
- func (b *Builder) WithGuard(guard func(uns.Unstructured) (concepts.GuardStatusWithReason, error)) *Builder
- func (b *Builder) WithMutation(m unstruct.Mutation) *Builder
- type Resource
- func (r *Resource) ConvergingStatus(op concepts.ConvergingOperation) (concepts.AliveStatusWithReason, error)
- func (r *Resource) DeleteOnSuspend() bool
- func (r *Resource) ExtractData() error
- func (r *Resource) GraceStatus() (concepts.GraceStatusWithReason, error)
- func (r *Resource) GuardStatus() (concepts.GuardStatusWithReason, error)
- func (r *Resource) Identity() string
- func (r *Resource) Mutate(current client.Object) error
- func (r *Resource) Object() (client.Object, error)
- func (r *Resource) PreviewObject() (*uns.Unstructured, error)
- func (r *Resource) Suspend() error
- func (r *Resource) SuspensionStatus() (concepts.SuspensionStatusWithReason, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder is a configuration helper for creating and customizing an unstructured workload Resource.
It provides a fluent API for registering mutations, status handlers, and data extractors. The converging status handler is required; all other handlers default to safe no-ops when omitted.
func NewBuilder ¶
func NewBuilder(obj *uns.Unstructured) *Builder
NewBuilder initializes a new Builder with the provided unstructured object.
The object serves as the desired base state. The converging status handler must be set via WithCustomConvergeStatus before Build(). All other handlers are optional.
func (*Builder) Build ¶
Build validates the configuration and returns the initialized Resource.
It returns an error if the converging status handler has not been set.
func (*Builder) MarkClusterScoped ¶
MarkClusterScoped marks the resource as cluster-scoped.
func (*Builder) WithCustomConvergeStatus ¶
func (b *Builder) WithCustomConvergeStatus( handler func(concepts.ConvergingOperation, *uns.Unstructured) (concepts.AliveStatusWithReason, error), ) *Builder
WithCustomConvergeStatus sets the handler that evaluates whether the resource has reached its desired state. This handler is required.
func (*Builder) WithCustomGraceStatus ¶
func (b *Builder) WithCustomGraceStatus( handler func(*uns.Unstructured) (concepts.GraceStatusWithReason, error), ) *Builder
WithCustomGraceStatus overrides the default grace status handler that assesses health during rollouts. The default reports Healthy.
func (*Builder) WithCustomSuspendDeletionDecision ¶
func (b *Builder) WithCustomSuspendDeletionDecision( handler func(*uns.Unstructured) bool, ) *Builder
WithCustomSuspendDeletionDecision overrides the default delete-on-suspend decision. The default returns false (keep the resource).
func (*Builder) WithCustomSuspendMutation ¶
WithCustomSuspendMutation overrides the default suspension mutation handler. The default is a no-op.
func (*Builder) WithCustomSuspendStatus ¶
func (b *Builder) WithCustomSuspendStatus( handler func(*uns.Unstructured) (concepts.SuspensionStatusWithReason, error), ) *Builder
WithCustomSuspendStatus overrides the default suspension status handler. The default reports Suspended immediately.
func (*Builder) WithDataExtractor ¶
func (b *Builder) WithDataExtractor(extractor func(uns.Unstructured) error) *Builder
WithDataExtractor registers a function to read values from the object after it has been successfully reconciled.
func (*Builder) WithGuard ¶ added in v0.4.0
func (b *Builder) WithGuard(guard func(uns.Unstructured) (concepts.GuardStatusWithReason, error)) *Builder
WithGuard registers a guard precondition that is evaluated before the object is applied during reconciliation. If the guard returns Blocked, the object and all resources registered after it are skipped until the guard clears. Passing nil clears any previously registered guard.
type Resource ¶
type Resource struct {
// contains filtered or unexported fields
}
Resource is a high-level abstraction for managing a long-running unstructured Kubernetes workload within a controller's reconciliation loop.
It implements the following interfaces:
- component.Resource: for basic identity and mutation behaviour.
- concepts.Alive: for health and readiness tracking.
- concepts.Graceful: for health assessment during rollouts.
- concepts.Suspendable: for graceful scale-down or temporary deactivation.
- concepts.Guardable: for conditional reconciliation based on a guard precondition.
- concepts.DataExtractable: for exporting values after successful reconciliation.
The converging status handler is required; all other handlers default to safe no-ops when omitted.
func (*Resource) ConvergingStatus ¶
func (r *Resource) ConvergingStatus(op concepts.ConvergingOperation) (concepts.AliveStatusWithReason, error)
ConvergingStatus evaluates whether the resource has reached its desired state.
func (*Resource) DeleteOnSuspend ¶
DeleteOnSuspend determines whether the resource should be deleted from the cluster when the parent component is suspended.
func (*Resource) ExtractData ¶
ExtractData executes all registered data extractor functions against a deep copy of the reconciled object.
func (*Resource) GraceStatus ¶
func (r *Resource) GraceStatus() (concepts.GraceStatusWithReason, error)
GraceStatus provides a health assessment of the resource when it has not yet reached full readiness.
func (*Resource) GuardStatus ¶ added in v0.4.0
func (r *Resource) GuardStatus() (concepts.GuardStatusWithReason, error)
GuardStatus evaluates the resource's guard precondition. If no guard was registered, the resource is unconditionally unblocked.
func (*Resource) Identity ¶
Identity returns a unique identifier for the resource derived from its GVK, namespace, and name.
func (*Resource) Mutate ¶
Mutate transforms the current state of the unstructured object into the desired state by applying all registered feature mutations and any active suspension mutation.
func (*Resource) Object ¶
Object returns a deep copy of the underlying unstructured Kubernetes object.
func (*Resource) PreviewObject ¶ added in v0.6.0
func (r *Resource) PreviewObject() (*uns.Unstructured, error)
PreviewObject returns the object as it would appear after feature mutations have been applied, without modifying the resource's internal state.
Suspension mutations are not applied; the preview reflects content state only.
func (*Resource) Suspend ¶
Suspend triggers the deactivation of the resource by registering a mutation that will be executed during the next Mutate call.
func (*Resource) SuspensionStatus ¶
func (r *Resource) SuspensionStatus() (concepts.SuspensionStatusWithReason, error)
SuspensionStatus monitors the progress of the suspension process.
Source Files