pod

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: 8 Imported by: 0

Documentation

Overview

Package pod provides a builder and resource for managing Kubernetes Pods.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultConvergingStatusHandler 

func DefaultConvergingStatusHandler(
	op concepts.ConvergingOperation, pod *corev1.Pod,
) (concepts.AliveStatusWithReason, error)

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

It considers a Pod:

  • Healthy: when Status.Phase is Running AND all container statuses report Ready.
  • Failing: when any container is in CrashLoopBackOff or has terminated with an error.
  • Updating: when the converging operation is concepts.ConvergingOperationUpdated.
  • Creating: when Status.Phase is Pending and no restart failures are detected.

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(_ *corev1.Pod) bool

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

It always returns true because pods cannot be paused — they must be deleted when suspended.

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(pod *corev1.Pod) (concepts.GraceStatusWithReason, error)

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

It categorizes the current state into:

  • GraceStatusHealthy: Pod is Running and all containers are Ready.
  • GraceStatusDegraded: Pod is Running but not all containers are Ready, or container readiness is unknown.
  • GraceStatusDown: Pod phase is not Running.

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

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

It is a no-op because pods are deleted on suspend rather than mutated.

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(_ *corev1.Pod) (concepts.SuspensionStatusWithReason, error)

DefaultSuspensionStatusHandler monitors the progress of the suspension process.

It always reports Suspended because pod suspension is handled by deletion — once the framework decides to delete the pod, suspension is considered complete.

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 Pod 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(pod *corev1.Pod) *Builder

NewBuilder initializes a new Builder with the provided Pod object.

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

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

The default behavior uses DefaultConvergingStatusHandler, which checks the Pod's phase and container statuses. Use this method if your Pod 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(*corev1.Pod) (concepts.GraceStatusWithReason, error),
) *Builder

WithCustomGraceStatus overrides how the Pod reports its health while it has not yet reached full readiness.

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(*corev1.Pod) bool,
) *Builder

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

The default behavior uses DefaultDeleteOnSuspendHandler, which returns true because pods cannot be paused. Return false from this handler if you want the Pod to remain in 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 Pod should be modified when the component is suspended.

The default behavior uses DefaultSuspendMutationHandler, which is a no-op because pods are deleted on suspend rather than mutated.

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(*corev1.Pod) (concepts.SuspensionStatusWithReason, error),
) *Builder

WithCustomSuspendStatus overrides how the progress of suspension is reported.

The default behavior uses DefaultSuspensionStatusHandler, which always reports Suspended because pods are deleted on suspend.

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(corev1.Pod) error,
) *Builder

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

This is useful for capturing auto-generated fields (like pod IP or node assignment) 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(corev1.Pod) (concepts.GuardStatusWithReason, error),
) *Builder

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

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 Pod'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 feature-aware mutation applied by a Pod Mutator. If constructed with a non-nil feature.VersionGate, it is applied only when that feature is enabled; if the feature is nil, the mutation is always applied.

type Mutator 

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

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

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

NewMutator creates a new Mutator for the given Pod.

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

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. Pod spec edits
  3. Regular container presence operations
  4. Regular container edits
  5. Init container presence operations
  6. 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 Pod as modified by all previous features.

Timing: No changes are made to the Pod 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.
  • 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.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 Pod'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 Pod's 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) EnsureContainer 

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

EnsureContainer records that a regular container must be present in the Pod. 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 Pod.

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

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 Pod. If an init container with the same name exists, it is replaced; otherwise, it is appended.

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

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

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

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

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 Pod 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 deletion-based 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 Pod, 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 Pod has successfully reached its desired state.

By default, it uses DefaultConvergingStatusHandler, which checks the Pod's phase and container statuses to determine health.

The return value includes a descriptive status (Healthy, Creating, Updating, or Failing) 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 Pod should be deleted from the cluster when the parent component is suspended.

By default, it uses DefaultDeleteOnSuspendHandler, which returns true because pods cannot be paused — they must be deleted when suspended.

func (*Resource) ExtractData 

func (r *Resource) ExtractData() error

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

This is called by the framework after a successful reconciliation of the resource. It allows the component to export details (like pod IP, node name, 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 Pod 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 Pod when it has not yet reached full readiness.

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

  • GraceStatusHealthy: Pod is Running and all containers are Ready.
  • GraceStatusDegraded: Pod is Running but not all containers are Ready, or readiness is unknown.
  • GraceStatusDown: Pod phase is not Running.

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

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

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

It registers a mutation that will be executed during the next Mutate call. The default behavior uses DefaultSuspendMutationHandler, which is a no-op because pods are deleted on suspend rather than mutated.

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 because pod suspension is handled by deletion.

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.