cronjob

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

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultDeleteOnSuspendHandler 

func DefaultDeleteOnSuspendHandler(_ *batchv1.CronJob) bool

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

It always returns false, meaning the CronJob is kept in the cluster with spec.suspend set to true.

func DefaultGraceStatusHandler 

func DefaultGraceStatusHandler(_ *batchv1.CronJob) (concepts.GraceStatusWithReason, error)

DefaultGraceStatusHandler provides the default health assessment of a CronJob when the component's grace period has expired.

It always reports Healthy. A CronJob is a passive scheduler — once it exists, it is functioning correctly regardless of whether it has fired yet. The schedule interval may be longer than the grace period (e.g. monthly), so waiting for the first execution would produce false degradation signals.

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 DefaultOperationalStatusHandler 

func DefaultOperationalStatusHandler(
	_ concepts.ConvergingOperation, _ *batchv1.CronJob,
) (concepts.OperationalStatusWithReason, error)

DefaultOperationalStatusHandler is the default logic for determining if a CronJob is operational.

It always reports Operational. A CronJob is a passive scheduler: once it exists in the cluster it is functioning correctly regardless of whether it has fired yet. The schedule interval may be longer than the component's grace period, so treating a never-scheduled CronJob as Pending would produce false degradation signals. Failures are reported on the spawned Job resources, not on the CronJob itself.

Users who need visibility into whether the CronJob has executed can override this handler via Builder.WithCustomOperationalStatus.

func DefaultSuspendMutationHandler 

func DefaultSuspendMutationHandler(mutator *Mutator) error

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

It sets spec.suspend to true, which prevents the CronJob from creating new Job objects.

func DefaultSuspensionStatusHandler 

func DefaultSuspensionStatusHandler(cj *batchv1.CronJob) (concepts.SuspensionStatusWithReason, error)

DefaultSuspensionStatusHandler monitors the progress of the suspension process.

It reports Suspended when spec.suspend is true and no active jobs are running. It reports Suspending when spec.suspend is true but active jobs are still running.

Types

type Builder 

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

Builder is a configuration helper for creating and customizing a CronJob 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(cj *batchv1.CronJob) *Builder

NewBuilder initializes a new Builder with the provided CronJob object.

The CronJob 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 CronJob 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 CronJob object was provided.
  • The CronJob has both a name and a namespace set.

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

func (*Builder) WithCustomGraceStatus 

func (b *Builder) WithCustomGraceStatus(
	handler func(*batchv1.CronJob) (concepts.GraceStatusWithReason, error),
) *Builder

WithCustomGraceStatus overrides the default logic for assessing the health of the CronJob when the component's grace period has expired.

The default behavior uses DefaultGraceStatusHandler, which always reports Healthy. A CronJob is a passive scheduler — once it exists and is not suspended, it is functioning correctly regardless of whether it has fired yet.

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

func (*Builder) WithCustomOperationalStatus 

func (b *Builder) WithCustomOperationalStatus(
	handler func(concepts.ConvergingOperation, *batchv1.CronJob) (concepts.OperationalStatusWithReason, error),
) *Builder

WithCustomOperationalStatus overrides the default logic for determining if the CronJob is operational.

func (*Builder) WithCustomSuspendDeletionDecision 

func (b *Builder) WithCustomSuspendDeletionDecision(
	handler func(*batchv1.CronJob) bool,
) *Builder

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

func (*Builder) WithCustomSuspendMutation 

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

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

func (*Builder) WithCustomSuspendStatus 

func (b *Builder) WithCustomSuspendStatus(
	handler func(*batchv1.CronJob) (concepts.SuspensionStatusWithReason, error),
) *Builder

WithCustomSuspendStatus overrides how the progress of suspension is reported.

func (*Builder) WithDataExtractor 

func (b *Builder) WithDataExtractor(
	extractor func(batchv1.CronJob) error,
) *Builder

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

func (*Builder) WithGuard added in v0.4.0 

func (b *Builder) WithGuard(
	guard func(batchv1.CronJob) (concepts.GuardStatusWithReason, error),
) *Builder

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

Mutations are applied sequentially during the Mutate() phase of reconciliation.

type Mutation 

type Mutation feature.Mutation[*Mutator]

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

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

The Mutator maintains feature boundaries: each feature's mutations are planned together and applied in the order the features were registered.

func NewMutator 

func NewMutator(current *batchv1.CronJob) *Mutator

NewMutator creates a new Mutator for the given CronJob. 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 CronJob.

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. CronJobSpec edits
  3. JobSpec edits
  4. Pod template metadata edits
  5. Pod spec edits
  6. Regular container presence operations
  7. Regular container edits
  8. Init container presence operations
  9. Init container edits

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.

Selector matching is evaluated against a snapshot taken after the current feature's container presence operations are applied. If either selector or edit function is nil, the registration is ignored.

func (*Mutator) EditCronJobSpec 

func (m *Mutator) EditCronJobSpec(edit func(*editors.CronJobSpecEditor) error)

EditCronJobSpec records a mutation for the CronJob's top-level spec.

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.

Selector matching is evaluated against a snapshot taken after the current feature's init container presence operations are applied. If either selector or edit function is nil, the registration is ignored.

func (*Mutator) EditJobSpec 

func (m *Mutator) EditJobSpec(edit func(*editors.JobSpecEditor) error)

EditJobSpec records a mutation for the CronJob's embedded job template spec.

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

func (*Mutator) EditObjectMetadata 

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

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

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 CronJob's pod spec.

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 CronJob's pod template metadata.

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

func (*Mutator) EnsureContainerEnvVar 

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

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

func (*Mutator) EnsureInitContainer 

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

EnsureInitContainer records that an init container must be present in the CronJob. 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 CronJob.

func (*Mutator) RemoveContainerArgs 

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

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

func (*Mutator) RemoveContainerEnvVar 

func (m *Mutator) RemoveContainerEnvVar(name string)

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

func (*Mutator) RemoveContainerEnvVars 

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

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

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 CronJob 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.Operational: for operational status tracking.
  • concepts.Graceful: for health assessment after grace period expiry.
  • concepts.Suspendable: for controlled suspension via spec.suspend.
  • concepts.Guardable: for conditional reconciliation based on a guard precondition.
  • concepts.DataExtractable: for exporting information after successful reconciliation.

func (*Resource) ConvergingStatus 

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

ConvergingStatus reports the CronJob's operational status.

By default, it uses DefaultOperationalStatusHandler, which reports Pending when the CronJob has never been scheduled and Operational when it has scheduled at least once.

func (*Resource) DeleteOnSuspend 

func (r *Resource) DeleteOnSuspend() bool

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

By default, it returns false — the CronJob is kept with spec.suspend set to true.

func (*Resource) ExtractData 

func (r *Resource) ExtractData() error

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

func (*Resource) GraceStatus 

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

GraceStatus reports the health of the CronJob after the component's grace period has expired.

By default, it uses DefaultGraceStatusHandler, which always reports Healthy. A CronJob is a passive scheduler — once it exists and is not suspended, it is functioning correctly regardless of whether it has fired yet.

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

func (*Resource) Mutate 

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

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

The mutation process follows a specific order:

  1. Feature Mutations: All registered feature-based mutations are applied.
  2. Suspension: If the resource is in a suspending state, the suspension logic (setting spec.suspend = true) is applied.

func (*Resource) Object 

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

Object returns a copy of the underlying Kubernetes CronJob object.

func (*Resource) PreviewObject added in v0.6.0 

func (r *Resource) PreviewObject() (*batchv1.CronJob, error)

PreviewObject returns the CronJob 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 suspension of the CronJob.

It registers a mutation that will be executed during the next Mutate call. The default behavior sets spec.suspend 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 Suspended when spec.suspend is true and no active jobs are running.

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.