deployment

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

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultConvergingStatusHandler 

func DefaultConvergingStatusHandler(
	op concepts.ConvergingOperation, deployment *appsv1.Deployment,
) (concepts.AliveStatusWithReason, error)

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

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

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

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

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

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

DefaultSuspensionStatusHandler monitors the progress of the suspension process.

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

NewBuilder initializes a new Builder with the provided Deployment object.

The Deployment object passed here serves as the "desired base state". During reconciliation, the framework uses Server-Side Apply to make the cluster's state match this base state, modified by any registered mutations.

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

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

The default behavior uses DefaultConvergingStatusHandler, which considers a Deployment ready when its ReadyReplicas count matches the desired replica count. Use this method if your Deployment requires more complex health checks, such as waiting for specific annotations, status conditions, or external signals.

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.Deployment) (concepts.GraceStatusWithReason, error),
) *Builder

WithCustomGraceStatus overrides how the Deployment reports its health while it is still converging (e.g., during a rollout).

The default behavior uses DefaultGraceStatusHandler.

This is used to provide more granular feedback in the component's status about the severity of a rollout's progress or failure.

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.Deployment) bool,
) *Builder

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

The default behavior uses DefaultDeleteOnSuspendHandler, which does not delete Deployments during suspension (only scaled down). Return true from this handler if you want the Deployment 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 Deployment should be modified when the component is suspended.

The default behavior uses DefaultSuspendMutationHandler, which scales the Deployment to zero replicas. You might override this if you want to suspend the workload by other means, such as changing labels, annotations, or updating a 'suspended' field in a custom controller.

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.Deployment) (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. Use this if your custom suspension strategy involves other measurable states.

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.Deployment) error,
) *Builder

WithDataExtractor registers a function to harvest information from the Deployment 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.Deployment) (concepts.GuardStatusWithReason, error),
) *Builder

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

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 Deployment'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 deployment 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 Deployment.

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

NewMutator creates a new Mutator for the given Deployment.

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

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. DeploymentSpec 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 Deployment as modified by all previous features.

Timing: No changes are made to the Deployment 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) EditDeploymentSpec 

func (m *Mutator) EditDeploymentSpec(edit func(*editors.DeploymentSpecEditor) error)

EditDeploymentSpec records a mutation for the Deployment's top-level spec.

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

Execution Order:

  • Within a feature, edits are applied in registration order.
  • Overall, deployment spec edits are executed AFTER deployment-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) 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 Deployment'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 Deployment'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 Deployment'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/deployment-metadata edits but BEFORE pod 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 Deployment. 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 Deployment.

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

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

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

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

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

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

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 Deployment 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 Deployment, 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 Deployment 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.

When to use: This is used by the framework after an Apply operation to determine if the reconciliation of this specific resource is complete or if further waiting is required.

func (*Resource) DeleteOnSuspend 

func (r *Resource) DeleteOnSuspend() bool

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

By default, it uses DefaultDeleteOnSuspendHandler, which returns false, meaning the Deployment is kept in the cluster but scaled to zero replicas. This preserves the resource definition and history while stopping the workload.

A custom decision handler can be registered via the Builder to change this behavior based on the current state of the Deployment.

func (*Resource) ExtractData 

func (r *Resource) ExtractData() error

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

This is called by the framework after a successful reconciliation of the resource. It allows the component to export details (like a generated name, assigned IP, or status fields) that might be needed by other resources or higher-level controllers.

Data extractors are provided with a deep copy of the current Deployment 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 Deployment 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.

This information is surfaced through the component's health reporting, allowing operators to understand the severity of a rollout delay or failure.

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 Deployment in the format "apps/v1/Deployment/<namespace>/<name>".

This identifier is used by the framework's internal tracking and recording mechanisms to distinguish this specific Deployment 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 Deployment 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 Deployment.
  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 Deployment 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.Deployment, error)

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

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

This is typically called by the framework when a component's .spec.suspended field is set to true.

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 Deployment has successfully scaled down to zero replicas or is still in the process of doing so. The framework uses this to determine when the component has reached a fully suspended state.

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.