Documentation
¶
Overview ¶
Package pv provides a builder and resource for managing Kubernetes PersistentVolumes.
Index ¶
- func DefaultGraceStatusHandler(pv *corev1.PersistentVolume) (concepts.GraceStatusWithReason, error)
- func DefaultOperationalStatusHandler(_ concepts.ConvergingOperation, pv *corev1.PersistentVolume) (concepts.OperationalStatusWithReason, error)
- type Builder
- func (b *Builder) Build() (*Resource, error)
- func (b *Builder) WithCustomGraceStatus(handler func(*corev1.PersistentVolume) (concepts.GraceStatusWithReason, error)) *Builder
- func (b *Builder) WithCustomOperationalStatus(...) *Builder
- func (b *Builder) WithDataExtractor(extractor func(corev1.PersistentVolume) error) *Builder
- func (b *Builder) WithGuard(guard func(corev1.PersistentVolume) (concepts.GuardStatusWithReason, error)) *Builder
- func (b *Builder) WithMutation(m Mutation) *Builder
- type Mutation
- type Mutator
- func (m *Mutator) Apply() error
- func (m *Mutator) EditObjectMetadata(edit func(*editors.ObjectMetaEditor) error)
- func (m *Mutator) EditPVSpec(edit func(*editors.PVSpecEditor) error)
- func (m *Mutator) NextFeature()
- func (m *Mutator) SetMountOptions(options []string)
- func (m *Mutator) SetReclaimPolicy(policy corev1.PersistentVolumeReclaimPolicy)
- func (m *Mutator) SetStorageClassName(name string)
- type Resource
- func (r *Resource) ConvergingStatus(op concepts.ConvergingOperation) (concepts.OperationalStatusWithReason, error)
- 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() (*corev1.PersistentVolume, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DefaultGraceStatusHandler ¶
func DefaultGraceStatusHandler(pv *corev1.PersistentVolume) (concepts.GraceStatusWithReason, error)
DefaultGraceStatusHandler provides the default health assessment of a PersistentVolume when the component's grace period has expired.
It considers a PV healthy when its Status.Phase is Available or Bound. A PV in the Pending phase is reported as Degraded. A PV in the Released or Failed phase is reported as Down.
This function is used as the default handler by the Resource if no custom handler is registered via Builder.WithCustomGraceStatus. It can be reused within custom handlers to augment the default behavior.
func DefaultOperationalStatusHandler ¶
func DefaultOperationalStatusHandler( _ concepts.ConvergingOperation, pv *corev1.PersistentVolume, ) (concepts.OperationalStatusWithReason, error)
DefaultOperationalStatusHandler is the default logic for determining if a PersistentVolume is operationally ready.
It considers a PV operational when its Status.Phase is Available or Bound. A PV in the Pending phase is reported as concepts.OperationalStatusPending. A PV in the Released or Failed phase is reported as concepts.OperationalStatusFailing.
This function is used as the default handler by the Resource if no custom handler is registered via Builder.WithCustomOperationalStatus. It can be reused within custom handlers to augment the default behavior.
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder is a configuration helper for creating and customizing a PersistentVolume Resource.
It provides a fluent API for registering mutations, operational status handlers, and data extractors. Build() validates the configuration and returns an initialized Resource ready for use in a reconciliation loop.
func NewBuilder ¶
func NewBuilder(pv *corev1.PersistentVolume) *Builder
NewBuilder initializes a new Builder with the provided PersistentVolume object.
The PersistentVolume object serves as the desired base state. During reconciliation the Resource will make the cluster's state match this base, modified by any registered mutations.
PersistentVolumes are cluster-scoped; the provided object must have a Name set but must not have a Namespace. This is validated during the Build() call.
func (*Builder) Build ¶
Build validates the configuration and returns the initialized Resource.
It returns an error if:
- No PersistentVolume object was provided.
- The PersistentVolume is missing a Name.
- The PersistentVolume has a Namespace set (PVs are cluster-scoped).
- Identity function or mutator factory is nil.
func (*Builder) WithCustomGraceStatus ¶
func (b *Builder) WithCustomGraceStatus( handler func(*corev1.PersistentVolume) (concepts.GraceStatusWithReason, error), ) *Builder
WithCustomGraceStatus overrides the default logic for assessing the health of the PersistentVolume when the component's grace period has expired.
The default behavior uses DefaultGraceStatusHandler, which considers a PV healthy when its phase is Available or Bound, degraded when Pending, and down when Released or Failed.
If you want to augment the default behavior, you can call DefaultGraceStatusHandler within your custom handler.
func (*Builder) WithCustomOperationalStatus ¶
func (b *Builder) WithCustomOperationalStatus( handler func(concepts.ConvergingOperation, *corev1.PersistentVolume) (concepts.OperationalStatusWithReason, error), ) *Builder
WithCustomOperationalStatus overrides the default logic for determining if the PersistentVolume is operationally ready.
The default behavior uses DefaultOperationalStatusHandler, which considers a PV operational when its phase is Available or Bound. Use this method if your PV requires more complex readiness checks.
func (*Builder) WithDataExtractor ¶
func (b *Builder) WithDataExtractor(extractor func(corev1.PersistentVolume) error) *Builder
WithDataExtractor registers a function to read values from the PersistentVolume after it has been successfully reconciled.
The extractor receives a value copy of the reconciled PersistentVolume. This is useful for surfacing generated or updated fields to other components or resources.
A nil extractor is ignored.
func (*Builder) WithGuard ¶ added in v0.4.0
func (b *Builder) WithGuard(guard func(corev1.PersistentVolume) (concepts.GuardStatusWithReason, error)) *Builder
WithGuard registers a guard precondition that is evaluated before the PersistentVolume is applied during reconciliation. If the guard returns Blocked, the PersistentVolume and all resources registered after it are skipped until the guard clears. Passing nil clears any previously registered guard.
func (*Builder) WithMutation ¶
WithMutation registers a mutation for the PersistentVolume.
Mutations are applied sequentially during the Mutate() phase of reconciliation, after the baseline field applicator and any registered flavors have run. A mutation with a nil Feature is applied unconditionally; one with a non-nil Feature is applied only when that feature is enabled.
type Mutation ¶
Mutation defines a mutation that is applied to a pv Mutator only if its associated feature gate is enabled.
type Mutator ¶
type Mutator struct {
// contains filtered or unexported fields
}
Mutator is a high-level helper for modifying a Kubernetes PersistentVolume.
It uses a "plan-and-apply" pattern: mutations are recorded first, then applied to the PersistentVolume in a single controlled pass when Apply() is called.
The Mutator maintains feature boundaries: each feature's mutations are planned together and applied in the order the features were registered.
Mutator implements editors.ObjectMutator.
func NewMutator ¶
func NewMutator(pv *corev1.PersistentVolume) *Mutator
NewMutator creates a new Mutator for the given PersistentVolume. The constructor creates the initial feature scope automatically.
func (*Mutator) Apply ¶
Apply executes all recorded mutation intents on the underlying PersistentVolume.
Execution order across all registered features:
- Metadata edits (in registration order within each feature)
- Spec edits — EditPVSpec, SetStorageClassName, SetReclaimPolicy, SetMountOptions (in registration order within each feature)
Features are applied in the order they were registered. Later features observe the PersistentVolume as modified by all previous features.
func (*Mutator) EditObjectMetadata ¶
func (m *Mutator) EditObjectMetadata(edit func(*editors.ObjectMetaEditor) error)
EditObjectMetadata records a mutation for the PersistentVolume's own metadata.
Metadata edits are applied before spec edits within the same feature. A nil edit function is ignored.
func (*Mutator) EditPVSpec ¶
func (m *Mutator) EditPVSpec(edit func(*editors.PVSpecEditor) error)
EditPVSpec records a mutation for the PersistentVolume's spec via a PVSpecEditor.
The editor provides structured operations (SetCapacity, SetAccessModes, SetPersistentVolumeReclaimPolicy, etc.) as well as Raw() for free-form access. Spec edits are applied after metadata edits within the same feature, in registration order.
A nil edit function is ignored.
func (*Mutator) NextFeature ¶
func (m *Mutator) NextFeature()
NextFeature advances to a new feature planning scope. All subsequent mutation registrations will be grouped into this scope until NextFeature is called again.
The first scope is created automatically by NewMutator. This method is called by the framework between mutations to maintain per-feature ordering semantics.
func (*Mutator) SetMountOptions ¶
SetMountOptions records that the PV's mount options should be set to the given values.
Convenience wrapper over EditPVSpec.
func (*Mutator) SetReclaimPolicy ¶
func (m *Mutator) SetReclaimPolicy(policy corev1.PersistentVolumeReclaimPolicy)
SetReclaimPolicy records that the PV's reclaim policy should be set to the given value.
Convenience wrapper over EditPVSpec.
func (*Mutator) SetStorageClassName ¶
SetStorageClassName records that the PV's storage class should be set to the given name.
Convenience wrapper over EditPVSpec.
type Resource ¶
type Resource struct {
// contains filtered or unexported fields
}
Resource is a high-level abstraction for managing a Kubernetes PersistentVolume within a controller's reconciliation loop.
It implements the following component interfaces:
- component.Resource: for basic identity and mutation behaviour.
- concepts.Operational: for tracking whether the PV is operationally ready.
- concepts.Graceful: for assessing health after the grace period expires.
- concepts.Guardable: for conditional reconciliation based on a guard precondition.
- concepts.DataExtractable: for exporting values after successful reconciliation.
func (*Resource) ConvergingStatus ¶
func (r *Resource) ConvergingStatus(op concepts.ConvergingOperation) (concepts.OperationalStatusWithReason, error)
ConvergingStatus evaluates if the PersistentVolume is operationally ready.
By default, it uses DefaultOperationalStatusHandler, which considers a PV operational when its phase is Available or Bound.
func (*Resource) ExtractData ¶
ExtractData executes all registered data extractor functions against a deep copy of the reconciled PersistentVolume.
This is called by the framework after successful reconciliation, allowing the component to read generated or updated values from the PV.
func (*Resource) GraceStatus ¶
func (r *Resource) GraceStatus() (concepts.GraceStatusWithReason, error)
GraceStatus reports the health of the PersistentVolume after the component's grace period has expired.
By default, it uses DefaultGraceStatusHandler, which considers a PV healthy when its phase is Available or Bound, degraded when Pending, and down when Released or Failed.
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 PersistentVolume in the format "v1/PersistentVolume/<name>".
PersistentVolumes are cluster-scoped and do not include a namespace in their identity.
func (*Resource) Mutate ¶
Mutate transforms the current state of a Kubernetes PersistentVolume into the desired state.
The mutation process follows this order:
- The desired base state is applied to the current object.
- Feature mutations: all registered feature-gated mutations are applied in order.
This method is invoked by the framework during the Update phase of reconciliation.
func (*Resource) Object ¶
Object returns a deep copy of the underlying Kubernetes PersistentVolume object.
The returned object implements client.Object, making it compatible with controller-runtime's Client for Create, Update, and Patch operations.
func (*Resource) PreviewObject ¶ added in v0.6.0
func (r *Resource) PreviewObject() (*corev1.PersistentVolume, error)
PreviewObject returns the PersistentVolume 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.
Source Files