daemonset

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

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultConvergingStatusHandler 

func DefaultConvergingStatusHandler(
	op concepts.ConvergingOperation, ds *appsv1.DaemonSet,
) (concepts.AliveStatusWithReason, error)

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

It considers a DaemonSet ready when the DaemonSet controller has observed the current generation (Status.ObservedGeneration >= ObjectMeta.Generation) and either:

  • Status.NumberReady >= Status.DesiredNumberScheduled and DesiredNumberScheduled > 0, or
  • DesiredNumberScheduled is zero (no matching nodes is a valid converged state).

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.DaemonSet) bool

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

It always returns true because DaemonSets have no replicas field and cannot be scaled to zero in-place.

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

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

It categorizes the current state into:

  • GraceStatusHealthy: DesiredNumberScheduled is zero, the controller has observed the current generation (Status.ObservedGeneration >= Generation), and no nodes match the selector; this is a valid configuration state, not a failure. Also healthy when NumberReady matches DesiredNumberScheduled.
  • GraceStatusDegraded: DesiredNumberScheduled is zero but the controller has not yet observed the current generation, or DesiredNumberScheduled > 0 and at least one pod is ready, but below desired.
  • GraceStatusDown: DesiredNumberScheduled > 0 and no pods 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) error

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

It is a no-op because DaemonSets are deleted on suspension 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(_ *appsv1.DaemonSet) (concepts.SuspensionStatusWithReason, error)

DefaultSuspensionStatusHandler monitors the progress of the suspension process.

It always reports Suspended with a reason indicating that the DaemonSet is deleted on suspension, because there is no in-place scale-down mechanism for DaemonSets.

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 DaemonSet 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(daemonset *appsv1.DaemonSet) *Builder

NewBuilder initializes a new Builder with the provided DaemonSet object.

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

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

The default behavior uses DefaultConvergingStatusHandler, which:

  • Treats the DaemonSet as converged when DesiredNumberScheduled == 0 as soon as status.ObservedGeneration is greater than or equal to metadata.Generation.
  • When DesiredNumberScheduled > 0, treats the DaemonSet as converged once status.NumberReady is greater than or equal to status.DesiredNumberScheduled.

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

WithCustomGraceStatus overrides how the DaemonSet 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.DaemonSet) bool,
) *Builder

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

The default behavior uses DefaultDeleteOnSuspendHandler, which returns true because DaemonSets have no replicas field and cannot be scaled down.

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 DaemonSet should be modified when the component is suspended.

The default behavior uses DefaultSuspendMutationHandler, which is a no-op because DaemonSets are deleted on suspension 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(*appsv1.DaemonSet) (concepts.SuspensionStatusWithReason, error),
) *Builder

WithCustomSuspendStatus overrides how the progress of suspension is reported.

The default behavior uses DefaultSuspensionStatusHandler, which always reports Suspended because DaemonSets are deleted on suspension.

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

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

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

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 DaemonSet'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 daemonset 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 DaemonSet.

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

NewMutator creates a new Mutator for the given DaemonSet.

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

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. DaemonSetSpec 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 DaemonSet as modified by all previous features.

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

func (m *Mutator) EditDaemonSetSpec(edit func(*editors.DaemonSetSpecEditor) error)

EditDaemonSetSpec records a mutation for the DaemonSet's top-level spec.

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

Execution Order:

  • Within a feature, edits are applied in registration order.
  • Overall, DaemonSet spec edits are executed AFTER daemonset-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 DaemonSet'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 DaemonSet'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 DaemonSet'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 daemonset-metadata/spec 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 DaemonSet. 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 DaemonSet.

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

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

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

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

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

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 DaemonSet 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 deactivation via deletion.
  • 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 DaemonSet, 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 DaemonSet has successfully reached its desired state.

By default, it uses DefaultConvergingStatusHandler, which first ensures that status.ObservedGeneration is at least the DaemonSet's metadata.Generation. Once the generation has been observed:

  • If DesiredNumberScheduled is zero, the DaemonSet is considered converged (no pods expected).
  • If DesiredNumberScheduled is greater than zero, the DaemonSet is considered converged when NumberReady is greater than or equal to DesiredNumberScheduled.

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 DaemonSet should be deleted from the cluster when the parent component is suspended.

By default, it uses DefaultDeleteOnSuspendHandler, which returns true because DaemonSets have no replicas field and cannot be scaled to zero in-place.

func (*Resource) ExtractData 

func (r *Resource) ExtractData() error

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

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 DaemonSet when it has not yet reached full readiness.

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

  • GraceStatusHealthy: DesiredNumberScheduled is zero (no matching nodes).
  • GraceStatusDegraded: Some pods are ready but below the desired count.
  • GraceStatusDown: No pods 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 DaemonSet in the format "apps/v1/DaemonSet/<namespace>/<name>".

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

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

It registers a mutation that will be executed during the next Mutate call. The default behavior uses DefaultSuspendMutationHandler, which is a no-op because the DaemonSet is deleted on suspension 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 the DaemonSet is deleted on suspension.

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.