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 ¶
- func ExtractInto[V any](b *Builder, cell *concepts.Data[V], fn func(uns.Unstructured) (V, error))
- 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) WithDataGuard(cells ...concepts.DataCell) *Builder
- func (b *Builder) WithGuard(guard func(uns.Unstructured) (concepts.GuardStatusWithReason, error)) *Builder
- func (b *Builder) WithMetricsIdentifier(identifier string) *Builder
- func (b *Builder) WithMutation(ms ...unstruct.Mutation) *Builder
- func (b *Builder) WithOptionalData(cells ...concepts.DataCell) *Builder
- type Resource
- func (r *Resource) ConsumedData() []concepts.DataConsumption
- func (r *Resource) ConvergingStatus(op concepts.ConvergingOperation) (concepts.AliveStatusWithReason, error)
- func (r *Resource) DeleteOnSuspend() bool
- func (r *Resource) ExtractData() error
- func (r *Resource) FiringSet() ([]string, error)
- func (r *Resource) GraceStatus() (concepts.GraceStatusWithReason, error)
- func (r *Resource) GuardStatus() (concepts.GuardStatusWithReason, error)
- func (r *Resource) Identity() string
- func (r *Resource) MetricsIdentifier() string
- func (r *Resource) Mutate(current client.Object) error
- func (r *Resource) Object() (client.Object, error)
- func (r *Resource) Preview() (client.Object, error)
- func (r *Resource) ProducedData() []concepts.DataCell
- func (r *Resource) RecordObservation(observed client.Object) error
- func (r *Resource) RegisteredMutations() []string
- func (r *Resource) Suspend() error
- func (r *Resource) SuspensionStatus() (concepts.SuspensionStatusWithReason, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ExtractInto ¶ added in v0.18.0
ExtractInto declares that this unstructured object produces the value of cell. fn computes the value from a copy of the reconciled object; the framework stores it in the cell and marks it present, immediately after the object is applied or fetched. Extracting several values means several ExtractInto calls, one per cell. This is a package-level function because Go methods cannot introduce the extra type parameter V.
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 declared data extractions. 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) WithDataGuard ¶ added in v0.18.0
WithDataGuard declares that the unstructured object reads the given data cells and must not be applied until every one of them is set. The framework generates the guard and its reason (waiting for data "<name>"), and component Build validates that a producer for each cell is registered earlier. Data guards are evaluated before any custom guard registered with WithGuard.
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.
func (*Builder) WithMetricsIdentifier ¶ added in v0.20.0
WithMetricsIdentifier sets the object's identifier for resource-level metrics, used as the value of the `resource` label on ocf_resource_apply_total and ocf_resource_apply_errors_total.
It is a Prometheus label value, not a Kubernetes name: it must be low-cardinality and stable across reconciles, never derived from a per-owner value such as the owning custom resource's name. When unset, the resource is labelled with its lowercased kind. Build rejects a blank identifier.
func (*Builder) WithMutation ¶
WithMutation registers one or more mutations for the unstructured object.
func (*Builder) WithOptionalData ¶ added in v0.18.0
WithOptionalData declares that the unstructured object reads the given data cells without gating on them. Component Build still validates that a producer is registered earlier, and the dependency stays visible to introspection. Consumers in this mode use Get and skip quietly when a cell is absent.
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.
- concepts.ObservationRecorder: for surfacing live cluster state to declared data extractions on read-only reconciliation.
The converging status handler is required; all other handlers default to safe no-ops when omitted.
func (*Resource) ConsumedData ¶ added in v0.18.0
func (r *Resource) ConsumedData() []concepts.DataConsumption
ConsumedData returns the unstructured object's declared data reads. It satisfies concepts.DataConsumer for component topology validation and introspection.
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 declared data extractions against a deep copy of the reconciled object.
func (*Resource) FiringSet ¶ added in v0.14.0
FiringSet returns the Names of registered mutations whose gate is enabled for the version the unstructured object was built at. It satisfies concepts.MutationInspector.
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) MetricsIdentifier ¶ added in v0.20.0
MetricsIdentifier returns the identifier set with Builder.WithMetricsIdentifier, 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 (*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) Preview ¶ added in v0.11.0
Preview renders the object as a client.Object with feature mutations applied, without modifying the resource's internal state. It satisfies the component's Previewable capability so the component can assemble a cluster-free preview.
Suspension mutations are not applied; the preview reflects content state only. Callers needing the concrete type can type-assert the returned object.
func (*Resource) ProducedData ¶ added in v0.18.0
ProducedData returns the cells this unstructured object declares extractions into. It satisfies concepts.DataProducer for component topology validation and introspection.
func (*Resource) RecordObservation ¶ added in v0.9.1
RecordObservation stores the supplied object as the resource's most recently observed cluster state. The framework invokes this on read-only resources after fetching them so that declared data extractions observe the live object rather than the inert base used to construct the resource.
func (*Resource) RegisteredMutations ¶ added in v0.14.0
RegisteredMutations returns the deduplicated Names of every mutation registered on the unstructured object, independent of version. It satisfies concepts.MutationInspector so the resource can be introspected for version-matrix golden generation.
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