statefulset

package
v0.7.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 1, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package statefulset provides a builder and resource for managing Kubernetes StatefulSets.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultConvergingStatusHandler 

func DefaultConvergingStatusHandler(
	op concepts.ConvergingOperation, sts *appsv1.StatefulSet,
) (concepts.AliveStatusWithReason, error)

DefaultConvergingStatusHandler is the default logic for determining if a StatefulSet has reached its desired state.

It considers a StatefulSet ready when the statefulset controller has observed the current generation (Status.ObservedGeneration >= ObjectMeta.Generation) and Status.ReadyReplicas matches the Spec.Replicas (defaulting to 1 if nil). If the controller has not yet observed the latest spec, the handler reports Creating (when the resource was just created) or Updating (otherwise) to avoid falsely reporting health based on stale status fields.

This function is used as the default handler by the Resource if no custom handler is registered via Builder.WithCustomConvergeStatus. It can be reused within custom handlers to augment the default behavior.

func DefaultDeleteOnSuspendHandler 

func DefaultDeleteOnSuspendHandler(_ *appsv1.StatefulSet) bool

DefaultDeleteOnSuspendHandler provides the default decision of whether to delete the StatefulSet when the parent component is suspended.

It always returns false, meaning the StatefulSet is kept in the cluster but scaled to zero replicas.

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(sts *appsv1.StatefulSet) (concepts.GraceStatusWithReason, error)

DefaultGraceStatusHandler provides a default health assessment of the StatefulSet when it has not yet reached full readiness.

It categorizes the current state into:

  • GraceStatusHealthy: ReadyReplicas matches the desired replica count.
  • GraceStatusDegraded: At least one replica is ready, but the desired count is not met.
  • GraceStatusDown: No replicas are ready.

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 DefaultSuspendMutationHandler 

func DefaultSuspendMutationHandler(mutator *Mutator) error

DefaultSuspendMutationHandler provides the default mutation applied to a StatefulSet when the component is suspended.

It scales the StatefulSet to zero replicas by setting Spec.Replicas to 0.

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(sts *appsv1.StatefulSet) (concepts.SuspensionStatusWithReason, error)

DefaultSuspensionStatusHandler monitors the progress of the suspension process.

It reports whether the StatefulSet has successfully scaled down to zero replicas by checking if Status.Replicas is 0.

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 a StatefulSet 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(statefulset *appsv1.StatefulSet) *Builder

NewBuilder initializes a new Builder with the provided StatefulSet object.

The StatefulSet 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 StatefulSet must have at least a Name and Namespace set, which is validated during the Build() call.

func (*Builder) Build 

func (b *Builder) Build() (*Resource, error)

Build validates the configuration and returns the initialized Resource.

It ensures that:

  • A base StatefulSet object was provided.
  • The StatefulSet has both a name and a namespace set.

If validation fails, an error is returned and the Resource should not be used.

func (*Builder) WithCustomConvergeStatus 

func (b *Builder) WithCustomConvergeStatus(
	handler func(concepts.ConvergingOperation, *appsv1.StatefulSet) (concepts.AliveStatusWithReason, error),
) *Builder

WithCustomConvergeStatus overrides the default logic for determining if the StatefulSet has reached its desired state.

The default behavior uses DefaultConvergingStatusHandler, which considers a StatefulSet ready when its ReadyReplicas count matches the desired replica count.

func (*Builder) WithCustomGraceStatus 

func (b *Builder) WithCustomGraceStatus(
	handler func(*appsv1.StatefulSet) (concepts.GraceStatusWithReason, error),
) *Builder

WithCustomGraceStatus overrides how the StatefulSet reports its health while it is still converging.

The default behavior uses DefaultGraceStatusHandler.

func (*Builder) WithCustomSuspendDeletionDecision 

func (b *Builder) WithCustomSuspendDeletionDecision(
	handler func(*appsv1.StatefulSet) bool,
) *Builder

WithCustomSuspendDeletionDecision overrides the decision of whether to delete the StatefulSet when the component is suspended.

The default behavior uses DefaultDeleteOnSuspendHandler, which does not delete StatefulSets during suspension (only scaled down).

func (*Builder) WithCustomSuspendMutation 

func (b *Builder) WithCustomSuspendMutation(
	handler func(*Mutator) error,
) *Builder

WithCustomSuspendMutation defines how the StatefulSet should be modified when the component is suspended.

The default behavior uses DefaultSuspendMutationHandler, which scales the StatefulSet to zero replicas.

func (*Builder) WithCustomSuspendStatus 

func (b *Builder) WithCustomSuspendStatus(
	handler func(*appsv1.StatefulSet) (concepts.SuspensionStatusWithReason, error),
) *Builder

WithCustomSuspendStatus overrides how the progress of suspension is reported.

The default behavior uses DefaultSuspensionStatusHandler, which reports the progress of scaling down to zero replicas.

func (*Builder) WithDataExtractor 

func (b *Builder) WithDataExtractor(
	extractor func(appsv1.StatefulSet) error,
) *Builder

WithDataExtractor registers a function to harvest information from the StatefulSet after it has been successfully reconciled.

This is useful for capturing auto-generated fields and making them available to other components or resources via the framework's data extraction mechanism.

func (*Builder) WithGuard added in v0.4.0 

func (b *Builder) WithGuard(
	guard func(appsv1.StatefulSet) (concepts.GuardStatusWithReason, error),
) *Builder

WithGuard registers a guard precondition that is evaluated before the StatefulSet is applied during reconciliation. If the guard returns Blocked, the StatefulSet and all resources registered after it are skipped until the guard clears. Passing nil clears any previously registered guard.

func (*Builder) WithMutation 

func (b *Builder) WithMutation(m Mutation) *Builder

WithMutation registers a feature-based mutation for the StatefulSet.

Mutations are applied sequentially during the Mutate() phase of reconciliation. They are typically used by Features to inject environment variables, arguments, or other configuration into the StatefulSet's containers.

type Mutation 

type Mutation feature.Mutation[*Mutator]

Mutation defines a mutation that is applied to a statefulset Mutator only if its associated feature.VersionGate is enabled.

type Mutator 

type Mutator struct {
	// contains filtered or unexported fields
}

Mutator is a high-level helper for modifying a Kubernetes StatefulSet.

It uses a "plan-and-apply" pattern: mutations are recorded first, and then applied to the StatefulSet 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.

func NewMutator 

func NewMutator(current *appsv1.StatefulSet) *Mutator

NewMutator creates a new Mutator for the given StatefulSet.

It is typically used within a Feature's Mutation logic to express desired changes to the StatefulSet. The constructor creates the initial feature scope, so mutations can be registered immediately.

func (*Mutator) Apply 

func (m *Mutator) Apply() error

Apply executes all recorded mutation intents on the underlying StatefulSet.

Execution Order: Features are applied in the order they were registered. Within each feature, mutations are applied in this fixed category order:

  1. Object metadata edits
  2. StatefulSetSpec edits
  3. Pod template metadata edits
  4. Pod spec edits
  5. Regular container presence operations
  6. Regular container edits
  7. Init container presence operations
  8. Init container edits
  9. Volume claim template operations

Within each category of a single feature, edits are applied in their registration order.

func (*Mutator) EditContainers 

func (m *Mutator) EditContainers(selector selectors.ContainerSelector, edit func(*editors.ContainerEditor) error)

EditContainers records a mutation for containers matching the given selector.

Planning: All container edits are stored and executed during Apply().

Execution Order:

  • Within a feature, edits are applied in registration order.
  • Overall, container edits are executed AFTER container presence operations within the same feature.

Selection:

  • The selector determines which containers the edit function will be called for.
  • If either selector or edit function is nil, the registration is ignored.
  • Selectors are intended to target containers defined by the baseline resource structure or added by earlier presence operations.
  • Selector matching is evaluated against a snapshot taken after the current feature's container presence operations are applied.
  • Mutations should not rely on earlier edits in the SAME feature phase changing which selectors match.

func (*Mutator) EditInitContainers 

func (m *Mutator) EditInitContainers(selector selectors.ContainerSelector, edit func(*editors.ContainerEditor) error)

EditInitContainers records a mutation for init containers matching the given selector.

Planning: All init container edits are stored and executed during Apply().

Execution Order:

  • Within a feature, edits are applied in registration order.
  • Overall, init container edits apply only to spec.template.spec.initContainers.
  • They run in their own category during Apply(), after init container presence operations within the same feature.

Selection:

  • The selector determines which init containers the edit function will be called for.
  • If either selector or edit function is nil, the registration is ignored.
  • Selector matching is evaluated against a snapshot taken after the current feature's init container presence operations are applied.

func (*Mutator) EditObjectMetadata 

func (m *Mutator) EditObjectMetadata(edit func(*editors.ObjectMetaEditor) error)

EditObjectMetadata records a mutation for the StatefulSet's own metadata.

Planning: All object metadata edits are stored and executed during Apply().

Execution Order:

  • Within a feature, edits are applied in registration order.
  • Overall, object metadata edits are executed BEFORE all other categories within the same feature.

If the edit function is nil, the registration is ignored.

func (*Mutator) EditPodSpec 

func (m *Mutator) EditPodSpec(edit func(*editors.PodSpecEditor) error)

EditPodSpec records a mutation for the StatefulSet's pod spec.

Planning: All pod spec edits are stored and executed during Apply().

Execution Order:

  • Within a feature, edits are applied in registration order.
  • Overall, pod spec edits are executed AFTER metadata edits but BEFORE container edits within the same feature.

If the edit function is nil, the registration is ignored.

func (*Mutator) EditPodTemplateMetadata 

func (m *Mutator) EditPodTemplateMetadata(edit func(*editors.ObjectMetaEditor) error)

EditPodTemplateMetadata records a mutation for the StatefulSet's pod template metadata.

Planning: All pod template metadata edits are stored and executed during Apply().

Execution Order:

  • Within a feature, edits are applied in registration order.
  • Overall, pod template metadata edits are executed AFTER statefulset spec edits but BEFORE pod spec/container edits within the same feature.

If the edit function is nil, the registration is ignored.

func (*Mutator) EditStatefulSetSpec 

func (m *Mutator) EditStatefulSetSpec(edit func(*editors.StatefulSetSpecEditor) error)

EditStatefulSetSpec records a mutation for the StatefulSet's top-level spec.

Planning: All statefulset spec edits are stored and executed during Apply().

Execution Order:

  • Within a feature, edits are applied in registration order.
  • Overall, statefulset spec edits are executed AFTER statefulset-metadata edits but BEFORE pod template/spec/container edits within the same feature.

If the edit function is nil, the registration is ignored.

func (*Mutator) EnsureContainer 

func (m *Mutator) EnsureContainer(container corev1.Container)

EnsureContainer records that a regular container must be present in the StatefulSet. If a container with the same name exists, it is replaced; otherwise, it is appended.

func (*Mutator) EnsureContainerArg 

func (m *Mutator) EnsureContainerArg(arg string)

EnsureContainerArg records that a command-line argument must be present in all containers of the StatefulSet.

This is a convenience wrapper over EditContainers.

func (*Mutator) EnsureContainerEnvVar 

func (m *Mutator) EnsureContainerEnvVar(ev corev1.EnvVar)

EnsureContainerEnvVar records that an environment variable must be present in all containers of the StatefulSet.

This is a convenience wrapper over EditContainers.

func (*Mutator) EnsureInitContainer 

func (m *Mutator) EnsureInitContainer(container corev1.Container)

EnsureInitContainer records that an init container must be present in the StatefulSet. If an init container with the same name exists, it is replaced; otherwise, it is appended.

func (*Mutator) EnsureReplicas 

func (m *Mutator) EnsureReplicas(replicas int32)

EnsureReplicas records the desired number of replicas for the StatefulSet.

func (*Mutator) EnsureVolumeClaimTemplate 

func (m *Mutator) EnsureVolumeClaimTemplate(pvc corev1.PersistentVolumeClaim)

EnsureVolumeClaimTemplate records that a PersistentVolumeClaim template must be present in the StatefulSet. If a VolumeClaimTemplate with the same name exists, it is replaced; otherwise, it is appended.

Note: VolumeClaimTemplates are immutable once the StatefulSet exists in the cluster. During Apply, these operations are silently skipped for existing resources (identified by a non-empty ResourceVersion) because the Kubernetes API server would reject such changes. This method is primarily useful for initial creation or when recreating a StatefulSet.

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) RemoveContainer 

func (m *Mutator) RemoveContainer(name string)

RemoveContainer records that a regular container should be removed by name.

func (*Mutator) RemoveContainerArg 

func (m *Mutator) RemoveContainerArg(arg string)

RemoveContainerArg records that a command-line argument should be removed from all containers of the StatefulSet.

This is a convenience wrapper over EditContainers.

func (*Mutator) RemoveContainerArgs 

func (m *Mutator) RemoveContainerArgs(args []string)

RemoveContainerArgs records that multiple command-line arguments should be removed from all containers of the StatefulSet.

This is a convenience wrapper over EditContainers.

func (*Mutator) RemoveContainerEnvVar 

func (m *Mutator) RemoveContainerEnvVar(name string)

RemoveContainerEnvVar records that an environment variable should be removed from all containers of the StatefulSet.

This is a convenience wrapper over EditContainers.

func (*Mutator) RemoveContainerEnvVars 

func (m *Mutator) RemoveContainerEnvVars(names []string)

RemoveContainerEnvVars records that multiple environment variables should be removed from all containers of the StatefulSet.

This is a convenience wrapper over EditContainers.

func (*Mutator) RemoveContainers 

func (m *Mutator) RemoveContainers(names []string)

RemoveContainers records that multiple regular containers should be removed by name.

func (*Mutator) RemoveInitContainer 

func (m *Mutator) RemoveInitContainer(name string)

RemoveInitContainer records that an init container should be removed by name.

func (*Mutator) RemoveInitContainers 

func (m *Mutator) RemoveInitContainers(names []string)

RemoveInitContainers records that multiple init containers should be removed by name.

func (*Mutator) RemoveVolumeClaimTemplate 

func (m *Mutator) RemoveVolumeClaimTemplate(name string)

RemoveVolumeClaimTemplate records that a VolumeClaimTemplate should be removed by name.

Note: VolumeClaimTemplates are immutable once the StatefulSet exists in the cluster. During Apply, these operations are silently skipped for existing resources (identified by a non-empty ResourceVersion). This method is primarily useful when constructing the initial desired state.

type Resource 

type Resource struct {
	// contains filtered or unexported fields
}

Resource is a high-level abstraction for managing a Kubernetes StatefulSet within a controller's reconciliation loop.

It implements several component interfaces to integrate with the operator-component-framework:

  • component.Resource: for basic identity and mutation behavior.
  • concepts.Alive: for health and readiness tracking.
  • concepts.Suspendable: for graceful scale-down or temporary deactivation.
  • concepts.Guardable: for conditional reconciliation based on a guard precondition.
  • concepts.DataExtractable: for exporting information after successful reconciliation.

This resource handles the lifecycle of a StatefulSet, including initial creation, updates via feature mutations, and status monitoring.

func (*Resource) ConvergingStatus 

func (r *Resource) ConvergingStatus(op concepts.ConvergingOperation) (concepts.AliveStatusWithReason, error)

ConvergingStatus evaluates if the StatefulSet has successfully reached its desired state.

By default, it uses DefaultConvergingStatusHandler, which checks if the number of ReadyReplicas matches the desired replica count.

The return value includes a descriptive status (Healthy, Creating, Updating, or Scaling) and a human-readable reason, which are used to update the component's conditions.

func (*Resource) DeleteOnSuspend 

func (r *Resource) DeleteOnSuspend() bool

DeleteOnSuspend determines whether the StatefulSet should be deleted from the cluster when the parent component is suspended.

By default, it uses DefaultDeleteOnSuspendHandler, which returns false, meaning the StatefulSet is kept in the cluster but scaled to zero replicas.

func (*Resource) ExtractData 

func (r *Resource) ExtractData() error

ExtractData executes registered data extraction functions to harvest information from the reconciled StatefulSet.

This is called by the framework after a successful reconciliation of the resource. It allows the component to export details that might be needed by other resources or higher-level controllers.

func (*Resource) GraceStatus 

func (r *Resource) GraceStatus() (concepts.GraceStatusWithReason, error)

GraceStatus provides a health assessment of the StatefulSet when it has not yet reached full readiness.

By default, it uses DefaultGraceStatusHandler, which categorizes the current state into:

  • GraceStatusDegraded: At least one replica is ready, but the desired count is not met.
  • GraceStatusDown: No replicas are ready.

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 

func (r *Resource) Identity() string

Identity returns a unique identifier for the StatefulSet in the format "apps/v1/StatefulSet/<namespace>/<name>".

This identifier is used by the framework's internal tracking and recording mechanisms to distinguish this specific StatefulSet from other resources managed by the same component.

func (*Resource) Mutate 

func (r *Resource) Mutate(current client.Object) error

Mutate transforms the current state of a Kubernetes StatefulSet into the desired state.

The mutation process follows a specific order:

  1. Core State: The desired base state is applied to the current object.
  2. Feature Mutations: All registered feature-based mutations are applied, allowing for granular, version-gated changes to the StatefulSet.
  3. Suspension: If the resource is in a suspending state, the suspension logic (e.g., scaling to zero) is applied.

This method is invoked by the framework during the "Update" phase of reconciliation. It ensures that the in-memory object reflects all configuration and feature requirements before it is sent to the API server.

func (*Resource) Object 

func (r *Resource) Object() (client.Object, error)

Object returns a copy of the underlying Kubernetes StatefulSet object.

The returned object implements the client.Object interface, making it fully compatible with controller-runtime's Client for operations like Get, Create, Update, and Patch.

This method is called by the framework to obtain the current state of the resource before applying mutations.

func (*Resource) PreviewObject added in v0.6.0 

func (r *Resource) PreviewObject() (*appsv1.StatefulSet, error)

PreviewObject returns the StatefulSet 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 

func (r *Resource) Suspend() error

Suspend triggers the deactivation of the StatefulSet.

It registers a mutation that will be executed during the next Mutate call. The default behavior uses DefaultSuspendMutationHandler to scale the StatefulSet to zero replicas, which effectively stops the application while keeping the Kubernetes resource intact.

func (*Resource) SuspensionStatus 

func (r *Resource) SuspensionStatus() (concepts.SuspensionStatusWithReason, error)

SuspensionStatus monitors the progress of the suspension process.

By default, it uses DefaultSuspensionStatusHandler, which reports whether the StatefulSet has successfully scaled down to zero replicas or is still in the process of doing so.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.