replicaset

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 replicaset provides a builder and resource for managing Kubernetes ReplicaSets.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultConvergingStatusHandler 

func DefaultConvergingStatusHandler(
	op concepts.ConvergingOperation, rs *appsv1.ReplicaSet,
) (concepts.AliveStatusWithReason, error)

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

It considers a ReplicaSet ready when the replicaset 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.ReplicaSet) bool

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

It always returns false, meaning the ReplicaSet 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(rs *appsv1.ReplicaSet) (concepts.GraceStatusWithReason, error)

DefaultGraceStatusHandler provides a default health assessment of the ReplicaSet 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 ReplicaSet when the component is suspended.

It scales the ReplicaSet 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(rs *appsv1.ReplicaSet) (concepts.SuspensionStatusWithReason, error)

DefaultSuspensionStatusHandler monitors the progress of the suspension process.

It reports whether the ReplicaSet 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 ReplicaSet 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(replicaset *appsv1.ReplicaSet) *Builder

NewBuilder initializes a new Builder with the provided ReplicaSet object.

The ReplicaSet 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 replicaset 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 ReplicaSet object was provided.
  • The ReplicaSet 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.ReplicaSet) (concepts.AliveStatusWithReason, error),
) *Builder

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

The default behavior uses DefaultConvergingStatusHandler, which considers a ReplicaSet ready when its ReadyReplicas count matches the desired replica count. Use this method if your ReplicaSet requires more complex health checks.

If you want to augment the default behavior, you can call DefaultConvergingStatusHandler within your custom handler.

func (*Builder) WithCustomGraceStatus 

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

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

The default behavior uses DefaultGraceStatusHandler.

If you want to augment the default behavior, you can call DefaultGraceStatusHandler within your custom handler.

func (*Builder) WithCustomSuspendDeletionDecision 

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

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

The default behavior uses DefaultDeleteOnSuspendHandler, which does not delete ReplicaSets during suspension (only scaled down). Return true from this handler if you want the ReplicaSet to be completely removed from the cluster when suspended.

If you want to augment the default behavior, you can call DefaultDeleteOnSuspendHandler within your custom handler.

func (*Builder) WithCustomSuspendMutation 

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

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

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

If you want to augment the default behavior, you can call DefaultSuspendMutationHandler within your custom handler.

func (*Builder) WithCustomSuspendStatus 

func (b *Builder) WithCustomSuspendStatus(
	handler func(*appsv1.ReplicaSet) (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.

If you want to augment the default behavior, you can call DefaultSuspensionStatusHandler within your custom handler.

func (*Builder) WithDataExtractor 

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

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

This is useful for capturing auto-generated fields (like names or assigned IPs) 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.ReplicaSet) (concepts.GuardStatusWithReason, error),
) *Builder

WithGuard registers a guard precondition that is evaluated before the ReplicaSet is applied during reconciliation. If the guard returns Blocked, the ReplicaSet 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 ReplicaSet.

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 ReplicaSet's containers.

Since mutations are often version-gated, the provided feature.Mutation should contain the logic to determine if and how the mutation is applied based on the component's current version or configuration.

type Mutation 

type Mutation feature.Mutation[*Mutator]

Mutation defines a mutation that is applied to a replicaset 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 ReplicaSet.

It uses a "plan-and-apply" pattern: mutations are recorded first, and then applied to the ReplicaSet in a single controlled pass when Apply() is called.

This approach ensures that mutations are applied consistently and minimizes repeated scans of the underlying Kubernetes structures.

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.ReplicaSet) *Mutator

NewMutator creates a new Mutator for the given ReplicaSet.

It is typically used within a Feature's Mutation logic to express desired changes to the ReplicaSet. 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 ReplicaSet.

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. ReplicaSetSpec 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

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

Selection & Identity:

  • Container selectors target containers in the state they are in at the start of that feature's container phase (after presence operations of the SAME feature have been applied).
  • Selector matching within a phase is evaluated against a snapshot of containers at the start of that phase, not the progressively mutated live containers.
  • Later features observe the ReplicaSet as modified by all previous features.

Timing: No changes are made to the ReplicaSet until Apply() is called. Selectors and edit functions are executed during this pass.

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 ReplicaSet'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 ReplicaSet'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 replica/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 ReplicaSet'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 replica/replicaset-metadata edits but BEFORE pod spec/container edits within the same feature.

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

func (*Mutator) EditReplicaSetSpec 

func (m *Mutator) EditReplicaSetSpec(edit func(*editors.ReplicaSetSpecEditor) error)

EditReplicaSetSpec records a mutation for the ReplicaSet's top-level spec.

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

Execution Order:

  • Within a feature, edits are applied in registration order.
  • Overall, replicaset spec edits are executed AFTER replicaset-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 ReplicaSet. 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 ReplicaSet.

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 ReplicaSet.

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 ReplicaSet. 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 ReplicaSet.

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 ReplicaSet.

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 ReplicaSet.

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 ReplicaSet.

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 ReplicaSet.

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.

type Resource 

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

Resource is a high-level abstraction for managing a Kubernetes ReplicaSet 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 ReplicaSet, 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 ReplicaSet 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 (Ready, 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 ReplicaSet should be deleted from the cluster when the parent component is suspended.

By default, it uses DefaultDeleteOnSuspendHandler, which returns false, meaning the ReplicaSet 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 ReplicaSet.

Data extractors are provided with a deep copy of the current ReplicaSet to prevent accidental mutations during the extraction process.

func (*Resource) GraceStatus 

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

GraceStatus provides a health assessment of the ReplicaSet 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 ReplicaSet in the format "apps/v1/ReplicaSet/<namespace>/<name>".

This identifier is used by the framework's internal tracking and recording mechanisms to distinguish this specific ReplicaSet 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 ReplicaSet into the desired state.

The mutation process follows a specific order:

  1. Feature Mutations: All registered feature-based mutations are applied, allowing for granular, version-gated changes to the ReplicaSet.
  2. 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 ReplicaSet 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.ReplicaSet, error)

PreviewObject returns the ReplicaSet 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 ReplicaSet.

It registers a mutation that will be executed during the next Mutate call. The default behavior uses DefaultSuspendMutationHandler to scale the ReplicaSet to zero replicas.

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 ReplicaSet 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.