Documentation
¶
Overview ¶
Package hpa provides a builder and resource for managing Kubernetes HorizontalPodAutoscalers.
Index ¶
- func DefaultDeleteOnSuspendHandler(_ *autoscalingv2.HorizontalPodAutoscaler) bool
- func DefaultGraceStatusHandler(hpa *autoscalingv2.HorizontalPodAutoscaler) (concepts.GraceStatusWithReason, error)
- func DefaultOperationalStatusHandler(_ concepts.ConvergingOperation, hpa *autoscalingv2.HorizontalPodAutoscaler) (concepts.OperationalStatusWithReason, error)
- func DefaultSuspendMutationHandler(_ *Mutator) error
- func DefaultSuspensionStatusHandler(_ *autoscalingv2.HorizontalPodAutoscaler) (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(*autoscalingv2.HorizontalPodAutoscaler) bool) *Builder
- func (b *Builder) WithCustomSuspendMutation(handler func(*Mutator) error) *Builder
- func (b *Builder) WithCustomSuspendStatus(...) *Builder
- func (b *Builder) WithDataExtractor(extractor func(autoscalingv2.HorizontalPodAutoscaler) 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() (*autoscalingv2.HorizontalPodAutoscaler, 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(_ *autoscalingv2.HorizontalPodAutoscaler) bool
DefaultDeleteOnSuspendHandler provides the default decision of whether to delete the HPA when the parent component is suspended.
It always returns true. A retained HPA would conflict with the suspension of its scale target (e.g. a Deployment scaled to zero) because the Kubernetes HPA controller continuously enforces minReplicas and would scale the target back up. Deleting the HPA prevents this interference and guarantees clean suspension semantics. On resume the framework recreates the HPA with the desired spec.
Override this via Builder.WithCustomSuspendDeletionDecision if your use case requires the HPA to be retained during suspension.
This function is used as the default handler by the Resource if no custom handler is registered via Builder.WithCustomSuspendDeletionDecision. It can be reused within custom handlers.
func DefaultGraceStatusHandler ¶
func DefaultGraceStatusHandler( hpa *autoscalingv2.HorizontalPodAutoscaler, ) (concepts.GraceStatusWithReason, error)
DefaultGraceStatusHandler is the default logic for determining the grace status of a HorizontalPodAutoscaler after the allowed grace period has expired.
It inspects Status.Conditions to classify the HPA's health:
- GraceStatusHealthy: condition ScalingActive is True.
- GraceStatusDown: condition AbleToScale is False, or condition ScalingActive is False.
- GraceStatusDegraded: ScalingActive is Unknown, missing, or no conditions are present.
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, hpa *autoscalingv2.HorizontalPodAutoscaler, ) (concepts.OperationalStatusWithReason, error)
DefaultOperationalStatusHandler is the default logic for determining the operational status of a HorizontalPodAutoscaler.
It inspects Status.Conditions to classify the HPA's state:
- OperationalStatusOperational: condition ScalingActive is True.
- OperationalStatusPending: conditions are absent, ScalingActive is missing, or ScalingActive is Unknown.
- OperationalStatusFailing: condition ScalingActive is False, or condition AbleToScale is False.
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 an HPA when the component is suspended.
It is a no-op. The default suspension behavior deletes the HPA (DefaultDeleteOnSuspendHandler returns true), so no spec mutations are needed before deletion.
This function is used as the default handler by the Resource if no custom handler is registered via Builder.WithCustomSuspendMutation. It can be reused within custom handlers.
func DefaultSuspensionStatusHandler ¶
func DefaultSuspensionStatusHandler( _ *autoscalingv2.HorizontalPodAutoscaler, ) (concepts.SuspensionStatusWithReason, error)
DefaultSuspensionStatusHandler reports the suspension status of the HPA.
It always returns Suspended immediately. The default suspension behaviour deletes the HPA to prevent it from interfering with the scale target's suspension. Because deletion is handled by the framework after this status is reported, no additional work is required and the status is always Suspended.
The reason string is intentionally deletion-agnostic so that this handler remains accurate even when the deletion decision is overridden via Builder.WithCustomSuspendDeletionDecision. If you need a reason that reflects your custom deletion behaviour, override this handler via Builder.WithCustomSuspendStatus.
This function is used as the default handler by the Resource if no custom handler is registered via Builder.WithCustomSuspendStatus. It can be reused within custom handlers.
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder is a configuration helper for creating and customizing an HPA Resource.
It provides a fluent API for registering mutations, status handlers, and data extractors. This builder ensures that the resulting Resource is properly initialized and validated before use in a reconciliation loop.
func NewBuilder ¶
func NewBuilder(hpa *autoscalingv2.HorizontalPodAutoscaler) *Builder
NewBuilder initializes a new Builder with the provided HorizontalPodAutoscaler object.
The HPA object passed here serves as the "desired base state". During reconciliation, the Resource will attempt to make the cluster's state match this base state, modified by any registered mutations.
The provided HPA must have at least a 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 HPA object was provided.
- The HPA is missing a Name or Namespace.
func (*Builder) WithCustomGraceStatus ¶
func (b *Builder) WithCustomGraceStatus( handler func(*autoscalingv2.HorizontalPodAutoscaler) (concepts.GraceStatusWithReason, error), ) *Builder
WithCustomGraceStatus overrides the default logic for determining the HPA's grace status after the allowed grace period has expired.
The default behavior uses DefaultGraceStatusHandler, which inspects HPA conditions (ScalingActive, AbleToScale) to determine health.
func (*Builder) WithCustomOperationalStatus ¶
func (b *Builder) WithCustomOperationalStatus( handler func(concepts.ConvergingOperation, *autoscalingv2.HorizontalPodAutoscaler) (concepts.OperationalStatusWithReason, error), ) *Builder
WithCustomOperationalStatus overrides the default logic for determining the HPA's operational status.
The default behavior uses DefaultOperationalStatusHandler, which inspects HPA conditions (ScalingActive, AbleToScale) to determine status.
func (*Builder) WithCustomSuspendDeletionDecision ¶
func (b *Builder) WithCustomSuspendDeletionDecision( handler func(*autoscalingv2.HorizontalPodAutoscaler) bool, ) *Builder
WithCustomSuspendDeletionDecision overrides the decision of whether to delete the HPA when the component is suspended.
The default behavior uses DefaultDeleteOnSuspendHandler, which returns true. The HPA is deleted to prevent the Kubernetes HPA controller from scaling the target back up during suspension. On resume the framework recreates the HPA.
func (*Builder) WithCustomSuspendMutation ¶
WithCustomSuspendMutation defines how the HPA should be modified when the component is suspended.
The default behavior uses DefaultSuspendMutationHandler, which is a no-op since the HPA is deleted on suspend (no spec mutations are needed).
func (*Builder) WithCustomSuspendStatus ¶
func (b *Builder) WithCustomSuspendStatus( handler func(*autoscalingv2.HorizontalPodAutoscaler) (concepts.SuspensionStatusWithReason, error), ) *Builder
WithCustomSuspendStatus overrides how the progress of suspension is reported.
The default behavior uses DefaultSuspensionStatusHandler, which reports Suspended immediately because deletion is handled by the framework.
func (*Builder) WithDataExtractor ¶
func (b *Builder) WithDataExtractor( extractor func(autoscalingv2.HorizontalPodAutoscaler) error, ) *Builder
WithDataExtractor registers a function to read values from the HPA after it has been successfully reconciled.
The extractor receives a value copy of the reconciled HPA. 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(autoscalingv2.HorizontalPodAutoscaler) (concepts.GuardStatusWithReason, error), ) *Builder
WithGuard registers a guard precondition that is evaluated before the HPA is applied during reconciliation. If the guard returns Blocked, the HPA 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 feature-based mutation for the HPA.
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 an HPA 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 HorizontalPodAutoscaler.
It uses a "plan-and-apply" pattern: mutations are recorded first, then applied to the HPA 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(hpa *autoscalingv2.HorizontalPodAutoscaler) *Mutator
NewMutator creates a new Mutator for the given HorizontalPodAutoscaler. The constructor creates the initial feature scope automatically.
func (*Mutator) Apply ¶
Apply executes all recorded mutation intents on the underlying HPA.
Execution order across all registered features:
- Metadata edits (in registration order within each feature)
- HPA spec edits (in registration order within each feature)
Features are applied in the order they were registered. Later features observe the HPA as modified by all previous features.
func (*Mutator) EditHPASpec ¶
func (m *Mutator) EditHPASpec(edit func(*editors.HPASpecEditor) error)
EditHPASpec records a mutation for the HPA's spec.
HPA spec edits are applied after metadata edits within the same feature. A nil edit function is ignored.
func (*Mutator) EditObjectMetadata ¶
func (m *Mutator) EditObjectMetadata(edit func(*editors.ObjectMetaEditor) error)
EditObjectMetadata records a mutation for the HPA's own metadata.
Metadata edits are applied before HPA spec edits within the same feature. 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.
type Resource ¶
type Resource struct {
// contains filtered or unexported fields
}
Resource is a high-level abstraction for managing a Kubernetes HorizontalPodAutoscaler within a controller's reconciliation loop.
It implements the following component interfaces:
- component.Resource: for basic identity and mutation behaviour.
- concepts.Operational: for reporting operational status based on HPA conditions.
- concepts.Graceful: for reporting health after the allowed grace period has expired.
- concepts.Suspendable: for default delete-on-suspend behaviour that removes the HPA to prevent it from scaling the target back up during suspension.
- 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 reports the HPA's operational status using the configured handler.
By default, it uses DefaultOperationalStatusHandler, which inspects HPA conditions to determine if the autoscaler is active, pending, or failing.
func (*Resource) DeleteOnSuspend ¶
DeleteOnSuspend determines whether the HPA should be deleted from the cluster when the parent component is suspended.
By default, it uses DefaultDeleteOnSuspendHandler, which returns true. The HPA is deleted to prevent the Kubernetes HPA controller from scaling the target back up while it is suspended. On resume the framework recreates the HPA with the desired spec.
func (*Resource) ExtractData ¶
ExtractData executes all registered data extractor functions against a deep copy of the reconciled HPA.
This is called by the framework after successful reconciliation, allowing the component to read generated or updated values from the HPA.
func (*Resource) GraceStatus ¶
func (r *Resource) GraceStatus() (concepts.GraceStatusWithReason, error)
GraceStatus reports the HPA's health after the allowed grace period has expired.
By default, it uses DefaultGraceStatusHandler, which inspects HPA conditions to determine if the autoscaler is healthy, degraded, or down.
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 HPA in the format "autoscaling/v2/HorizontalPodAutoscaler/<namespace>/<name>".
func (*Resource) Mutate ¶
Mutate transforms the current state of a Kubernetes HorizontalPodAutoscaler into the desired state.
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 HorizontalPodAutoscaler 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() (*autoscalingv2.HorizontalPodAutoscaler, error)
PreviewObject returns the HorizontalPodAutoscaler 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 registers the configured suspension mutation for the next mutate cycle.
For HPA, the default suspension mutation is a no-op since the HPA is deleted on suspend (no spec mutations are needed before deletion).
func (*Resource) SuspensionStatus ¶
func (r *Resource) SuspensionStatus() (concepts.SuspensionStatusWithReason, error)
SuspensionStatus reports the suspension status of the HPA.
By default, it uses DefaultSuspensionStatusHandler, which reports Suspended immediately because deletion is handled by the framework after this status is reported.
Source Files