Documentation
¶
Overview ¶
Package pvc provides a builder and resource for managing Kubernetes PersistentVolumeClaims.
Index ¶
- func DefaultDeleteOnSuspendHandler(_ *corev1.PersistentVolumeClaim) bool
- func DefaultGraceStatusHandler(pvc *corev1.PersistentVolumeClaim) (concepts.GraceStatusWithReason, error)
- func DefaultOperationalStatusHandler(_ concepts.ConvergingOperation, pvc *corev1.PersistentVolumeClaim) (concepts.OperationalStatusWithReason, error)
- func DefaultSuspendMutationHandler(_ *Mutator) error
- func DefaultSuspensionStatusHandler(_ *corev1.PersistentVolumeClaim) (concepts.SuspensionStatusWithReason, error)
- type Builder
- func (b *Builder) Build() (*Resource, error)
- func (b *Builder) WithCustomGraceStatus(...) *Builder
- func (b *Builder) WithCustomOperationalStatus(...) *Builder
- func (b *Builder) WithCustomSuspendDeletionDecision(handler func(*corev1.PersistentVolumeClaim) bool) *Builder
- func (b *Builder) WithCustomSuspendMutation(handler func(*Mutator) error) *Builder
- func (b *Builder) WithCustomSuspendStatus(...) *Builder
- func (b *Builder) WithDataExtractor(extractor func(corev1.PersistentVolumeClaim) error) *Builder
- func (b *Builder) WithGuard(...) *Builder
- func (b *Builder) WithMutation(m Mutation) *Builder
- type Mutation
- type Mutator
- type Resource
- func (r *Resource) ConvergingStatus(op concepts.ConvergingOperation) (concepts.OperationalStatusWithReason, 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() (*corev1.PersistentVolumeClaim, error)
- func (r *Resource) Suspend() error
- func (r *Resource) SuspensionStatus() (concepts.SuspensionStatusWithReason, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DefaultDeleteOnSuspendHandler ¶
func DefaultDeleteOnSuspendHandler(_ *corev1.PersistentVolumeClaim) bool
DefaultDeleteOnSuspendHandler provides the default decision of whether to delete the PVC when the parent component is suspended.
It always returns false, meaning the PVC is kept in the cluster to preserve its underlying storage. Deleting a PVC can lead to permanent data loss if the reclaim policy is Delete.
This function is used as the default handler by the Resource if no custom handler is registered via Builder.WithCustomSuspendDeletionDecision.
func DefaultGraceStatusHandler ¶
func DefaultGraceStatusHandler(pvc *corev1.PersistentVolumeClaim) (concepts.GraceStatusWithReason, error)
DefaultGraceStatusHandler provides the default health assessment of a PVC when the component's grace period has expired.
It maps the PVC's Status.Phase to a grace health status:
- Bound → Healthy
- Lost → Down
- All other phases (Pending, empty, etc.) → Degraded
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, pvc *corev1.PersistentVolumeClaim, ) (concepts.OperationalStatusWithReason, error)
DefaultOperationalStatusHandler is the default logic for determining if a PVC has reached its desired operational state.
It considers a PVC operational when its Status.Phase is Bound:
- Bound → Operational
- Pending → OperationPending
- Lost → OperationFailing
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.
func DefaultSuspendMutationHandler ¶
DefaultSuspendMutationHandler provides the default mutation applied to a PVC when the component is suspended.
It is a no-op: PVCs do not have runtime state (like replicas) that needs to be wound down. The consuming workload (e.g. a Deployment) is responsible for stopping its use of the PVC.
This function is used as the default handler by the Resource if no custom handler is registered via Builder.WithCustomSuspendMutation.
func DefaultSuspensionStatusHandler ¶
func DefaultSuspensionStatusHandler(_ *corev1.PersistentVolumeClaim) (concepts.SuspensionStatusWithReason, error)
DefaultSuspensionStatusHandler monitors the progress of the suspension process.
It always reports Suspended because PVCs themselves have no runtime state to wind down. Once Suspend() is called, the PVC is considered immediately suspended.
This function is used as the default handler by the Resource if no custom handler is registered via Builder.WithCustomSuspendStatus.
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder is a configuration helper for creating and customizing a PVC Resource.
It provides a fluent API for registering mutations, 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(pvc *corev1.PersistentVolumeClaim) *Builder
NewBuilder initializes a new Builder with the provided PersistentVolumeClaim object.
The PVC 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.
The provided PVC must have both Name and Namespace set, which is validated during the Build() call.
func (*Builder) Build ¶
Build validates the configuration and returns the initialized Resource.
It returns an error if:
- No PVC object was provided.
- The PVC is missing a Name or Namespace.
func (*Builder) WithCustomGraceStatus ¶
func (b *Builder) WithCustomGraceStatus( handler func(*corev1.PersistentVolumeClaim) (concepts.GraceStatusWithReason, error), ) *Builder
WithCustomGraceStatus overrides the default logic for assessing the health of the PVC when the component's grace period has expired.
The default behavior uses DefaultGraceStatusHandler, which considers a Bound PVC healthy, a Lost PVC down, and all other phases degraded.
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.PersistentVolumeClaim) (concepts.OperationalStatusWithReason, error), ) *Builder
WithCustomOperationalStatus overrides the default logic for determining if the PVC has reached its desired operational state.
The default behavior uses DefaultOperationalStatusHandler, which checks whether the PVC is Bound. Use this method if you need additional checks, such as verifying specific annotations or conditions.
func (*Builder) WithCustomSuspendDeletionDecision ¶
func (b *Builder) WithCustomSuspendDeletionDecision( handler func(*corev1.PersistentVolumeClaim) bool, ) *Builder
WithCustomSuspendDeletionDecision overrides the decision of whether to delete the PVC when the component is suspended.
The default behavior uses DefaultDeleteOnSuspendHandler, which does not delete PVCs during suspension to preserve data. Return true from this handler if you want the PVC to be completely removed from the cluster when suspended.
func (*Builder) WithCustomSuspendMutation ¶
WithCustomSuspendMutation defines how the PVC should be modified when the component is suspended.
The default behavior uses DefaultSuspendMutationHandler, which is a no-op. Override this if you need to add annotations or labels when suspended.
func (*Builder) WithCustomSuspendStatus ¶
func (b *Builder) WithCustomSuspendStatus( handler func(*corev1.PersistentVolumeClaim) (concepts.SuspensionStatusWithReason, error), ) *Builder
WithCustomSuspendStatus overrides how the progress of suspension is reported.
The default behavior uses DefaultSuspensionStatusHandler, which always reports Suspended since PVCs have no runtime state to wind down.
func (*Builder) WithDataExtractor ¶
func (b *Builder) WithDataExtractor(extractor func(corev1.PersistentVolumeClaim) error) *Builder
WithDataExtractor registers a function to read values from the PVC after it has been successfully reconciled.
The extractor receives a value copy of the reconciled PVC. This is useful for surfacing the bound volume name, capacity, or other status 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.PersistentVolumeClaim) (concepts.GuardStatusWithReason, error)) *Builder
WithGuard registers a guard precondition that is evaluated before the PVC is applied during reconciliation. If the guard returns Blocked, the PVC 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 PVC.
Mutations are applied sequentially during the Mutate() phase of reconciliation. 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 pvc 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 PersistentVolumeClaim.
It uses a "plan-and-apply" pattern: mutations are recorded first, then applied to the PVC 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(pvc *corev1.PersistentVolumeClaim) *Mutator
NewMutator creates a new Mutator for the given PersistentVolumeClaim. The constructor creates the initial feature scope automatically.
func (*Mutator) Apply ¶
Apply executes all recorded mutation intents on the underlying PVC.
Execution order across all registered features:
- Metadata edits (in registration order within each feature)
- Spec edits — EditPVCSpec, SetStorageRequest (in registration order within each feature)
Features are applied in the order they were registered. Later features observe the PVC as modified by all previous features.
func (*Mutator) EditObjectMetadata ¶
func (m *Mutator) EditObjectMetadata(edit func(*editors.ObjectMetaEditor) error)
EditObjectMetadata records a mutation for the PVC's own metadata.
Metadata edits are applied before spec edits within the same feature. A nil edit function is ignored.
func (*Mutator) EditPVCSpec ¶
func (m *Mutator) EditPVCSpec(edit func(*editors.PVCSpecEditor) error)
EditPVCSpec records a mutation for the PVC's spec via a PVCSpecEditor.
The editor provides structured operations (SetStorageRequest, SetAccessModes, 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) SetStorageRequest ¶
SetStorageRequest records that the PVC's storage request should be set to quantity.
Convenience wrapper over EditPVCSpec.
type Resource ¶
type Resource struct {
// contains filtered or unexported fields
}
Resource is a high-level abstraction for managing a Kubernetes PersistentVolumeClaim 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 PVC is bound and operational.
- concepts.Graceful: for health assessment after the component's grace period expires.
- concepts.Suspendable: for controlled suspension (e.g. retaining the PVC while suspending consumers).
- concepts.Guardable: for conditional reconciliation based on a guard precondition.
- concepts.DataExtractable: for exporting values after successful reconciliation.
PVC resources follow the Integration lifecycle: they are operationally significant (a PVC must be Bound to be useful) and support suspension semantics.
func (*Resource) ConvergingStatus ¶
func (r *Resource) ConvergingStatus(op concepts.ConvergingOperation) (concepts.OperationalStatusWithReason, error)
ConvergingStatus evaluates whether the PVC has reached its desired operational state.
By default, it uses DefaultOperationalStatusHandler, which checks the PVC's phase to determine if it is Bound (operational), Pending, or Lost (failing).
func (*Resource) DeleteOnSuspend ¶
DeleteOnSuspend determines whether the PVC should be deleted from the cluster when the parent component is suspended.
By default, it uses DefaultDeleteOnSuspendHandler, which returns false to preserve the PVC and its underlying storage during suspension.
func (*Resource) ExtractData ¶
ExtractData executes all registered data extractor functions against a deep copy of the reconciled PVC.
This is called by the framework after successful reconciliation, allowing the component to read generated or updated values from the PVC.
func (*Resource) GraceStatus ¶
func (r *Resource) GraceStatus() (concepts.GraceStatusWithReason, error)
GraceStatus reports the health of the PVC after the component's grace period has expired.
By default, it uses DefaultGraceStatusHandler, which considers a Bound PVC healthy, a Lost PVC down, and all other phases degraded.
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 PVC in the format "v1/PersistentVolumeClaim/<namespace>/<name>".
func (*Resource) Mutate ¶
Mutate transforms the current state of a Kubernetes PersistentVolumeClaim 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.
- Suspension: if the resource is in a suspending state, the suspension logic is applied.
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 PersistentVolumeClaim 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.PersistentVolumeClaim, error)
PreviewObject returns the PersistentVolumeClaim 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 PVC.
It registers a mutation that will be executed during the next Mutate call. The default behaviour uses DefaultSuspendMutationHandler, which is a no-op since PVCs do not require modification when suspended — the consuming workload is responsible for scaling down.
func (*Resource) SuspensionStatus ¶
func (r *Resource) SuspensionStatus() (concepts.SuspensionStatusWithReason, error)
SuspensionStatus monitors the progress of the suspension process.
By default, it uses DefaultSuspensionStatusHandler, which always reports Suspended since PVCs themselves have no runtime state to wind down.
Source Files