Documentation
¶
Overview ¶
Package job provides a builder and resource for managing Kubernetes Jobs.
Index ¶
- func DefaultConvergingStatusHandler(op concepts.ConvergingOperation, job *batchv1.Job) (concepts.CompletionStatusWithReason, error)
- func DefaultDeleteOnSuspendHandler(_ *batchv1.Job) bool
- func DefaultSuspendMutationHandler(mutator *Mutator) error
- func DefaultSuspensionStatusHandler(job *batchv1.Job) (concepts.SuspensionStatusWithReason, error)
- type Builder
- func (b *Builder) Build() (*Resource, error)
- func (b *Builder) WithCustomConvergeStatus(...) *Builder
- func (b *Builder) WithCustomSuspendDeletionDecision(handler func(*batchv1.Job) bool) *Builder
- func (b *Builder) WithCustomSuspendMutation(handler func(*Mutator) error) *Builder
- func (b *Builder) WithCustomSuspendStatus(handler func(*batchv1.Job) (concepts.SuspensionStatusWithReason, error)) *Builder
- func (b *Builder) WithDataExtractor(extractor func(batchv1.Job) error) *Builder
- func (b *Builder) WithGuard(guard func(batchv1.Job) (concepts.GuardStatusWithReason, error)) *Builder
- func (b *Builder) WithMutation(m Mutation) *Builder
- type Mutation
- type Mutator
- func (m *Mutator) Apply() error
- func (m *Mutator) EditContainers(selector selectors.ContainerSelector, ...)
- func (m *Mutator) EditInitContainers(selector selectors.ContainerSelector, ...)
- func (m *Mutator) EditJobSpec(edit func(*editors.JobSpecEditor) error)
- func (m *Mutator) EditObjectMetadata(edit func(*editors.ObjectMetaEditor) error)
- func (m *Mutator) EditPodSpec(edit func(*editors.PodSpecEditor) error)
- func (m *Mutator) EditPodTemplateMetadata(edit func(*editors.ObjectMetaEditor) error)
- func (m *Mutator) EnsureContainer(container corev1.Container)
- func (m *Mutator) EnsureContainerEnvVar(ev corev1.EnvVar)
- func (m *Mutator) EnsureInitContainer(container corev1.Container)
- func (m *Mutator) NextFeature()
- func (m *Mutator) RemoveContainer(name string)
- func (m *Mutator) RemoveContainerEnvVar(name string)
- func (m *Mutator) RemoveContainers(names []string)
- func (m *Mutator) RemoveInitContainer(name string)
- func (m *Mutator) RemoveInitContainers(names []string)
- type Resource
- func (r *Resource) ConvergingStatus(op concepts.ConvergingOperation) (concepts.CompletionStatusWithReason, error)
- func (r *Resource) DeleteOnSuspend() bool
- func (r *Resource) ExtractData() error
- func (r *Resource) GuardStatus() (concepts.GuardStatusWithReason, error)
- func (r *Resource) Identity() string
- func (r *Resource) Mutate(current client.Object) error
- func (r *Resource) Object() (client.Object, error)
- func (r *Resource) PreviewObject() (*batchv1.Job, error)
- func (r *Resource) Suspend() error
- func (r *Resource) SuspensionStatus() (concepts.SuspensionStatusWithReason, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DefaultConvergingStatusHandler ¶
func DefaultConvergingStatusHandler( op concepts.ConvergingOperation, job *batchv1.Job, ) (concepts.CompletionStatusWithReason, error)
DefaultConvergingStatusHandler is the default logic for determining if a Job has completed or is still running.
It checks the Job's status conditions for Complete or Failed, and reports the appropriate CompletionStatus based on the current state.
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 ¶
DefaultDeleteOnSuspendHandler provides the default decision of whether to delete the Job when the parent component is suspended.
It always returns true, meaning the Job is deleted from the cluster during suspension. Jobs cannot be meaningfully scaled to zero like Deployments, so deletion is the standard approach for suspending a task resource.
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 DefaultSuspendMutationHandler ¶
DefaultSuspendMutationHandler provides the default mutation applied to a Job when the component is suspended.
It sets the Job's Suspend field to true, which prevents the Job controller from creating new pods while allowing existing pods to complete.
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(job *batchv1.Job) (concepts.SuspensionStatusWithReason, error)
DefaultSuspensionStatusHandler monitors the progress of the suspension process.
It reports whether the Job has been successfully suspended by checking if the Job's Suspend field is true and there are no active pods.
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 Job 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 ¶
NewBuilder initializes a new Builder with the provided Job object.
The Job 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 Job must have at least a Name and Namespace set, which is validated during the Build() call.
func (*Builder) Build ¶
Build validates the configuration and returns the initialized Resource.
It ensures that:
- A base Job object was provided.
- The Job 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, *batchv1.Job) (concepts.CompletionStatusWithReason, error), ) *Builder
WithCustomConvergeStatus overrides the default logic for determining if the Job has completed, is running, or has failed.
The default behavior uses DefaultConvergingStatusHandler, which checks the Job's status conditions. Use this method if your Job requires more complex checks, such as waiting for specific annotations or external signals.
If you want to augment the default behavior, you can call DefaultConvergingStatusHandler within your custom handler.
func (*Builder) WithCustomSuspendDeletionDecision ¶
WithCustomSuspendDeletionDecision overrides the decision of whether to delete the Job when the component is suspended.
The default behavior uses DefaultDeleteOnSuspendHandler, which returns true, meaning Jobs are deleted during suspension. Return false from this handler if you want the Job 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 ¶
WithCustomSuspendMutation defines how the Job should be modified when the component is suspended.
The default behavior uses DefaultSuspendMutationHandler, which sets the Job's Suspend field to true. You might override this if you want to suspend the Job by other means.
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(*batchv1.Job) (concepts.SuspensionStatusWithReason, error), ) *Builder
WithCustomSuspendStatus overrides how the progress of suspension is reported.
The default behavior uses DefaultSuspensionStatusHandler, which reports the progress based on the Job's Suspend field and active pod count. 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 ¶
WithDataExtractor registers a function to harvest information from the Job after it has been successfully reconciled.
This is useful for capturing auto-generated fields (like completion status or pod names) 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(batchv1.Job) (concepts.GuardStatusWithReason, error), ) *Builder
WithGuard registers a guard precondition that is evaluated before the Job is applied during reconciliation. If the guard returns Blocked, the Job and all resources registered after it are skipped until the guard clears. Passing nil clears any previously registered guard.
func (*Builder) WithMutation ¶
WithMutation registers a feature-based mutation for the Job.
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 Job'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 ¶
Mutation defines a mutation that is applied to a job Mutator only if its associated feature gate is enabled.
type Mutator ¶
type Mutator struct {
// contains filtered or unexported fields
}
Mutator is a high-level helper for modifying a Kubernetes Job.
It uses a "plan-and-apply" pattern: mutations are recorded first, then applied to the Job 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.
Mutator implements editors.ObjectMutator.
func NewMutator ¶
NewMutator creates a new Mutator for the given Job.
It is typically used within a Feature's Mutation logic to express desired changes to the Job. The constructor creates the initial feature scope, so mutations can be registered immediately.
func (*Mutator) Apply ¶
Apply executes all recorded mutation intents on the underlying Job.
Execution order across all registered features:
- Object metadata edits
- Job spec edits
- Pod template metadata edits
- Pod spec edits
- Regular container presence operations
- Regular container edits
- Init container presence operations
- Init container edits
Features are applied in the order they were registered. Within each category of a single feature, edits are applied in their registration order.
Container selectors are evaluated against a snapshot taken after the current feature's container presence operations have been applied.
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.
Edits are applied after container presence operations within the same feature. Selector matching is evaluated against a snapshot taken after the current feature's container presence operations have been applied.
If either selector or 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.
Edits are applied after init container presence operations within the same feature. Selector matching is evaluated against a snapshot taken after the current feature's init container presence operations have been 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 Job's top-level spec.
Job spec edits are applied after metadata edits but before pod template edits within the same feature. A nil edit function is ignored.
func (*Mutator) EditObjectMetadata ¶
func (m *Mutator) EditObjectMetadata(edit func(*editors.ObjectMetaEditor) error)
EditObjectMetadata records a mutation for the Job's own metadata.
Metadata edits are applied before all other categories within the same feature. A nil edit function is ignored.
func (*Mutator) EditPodSpec ¶
func (m *Mutator) EditPodSpec(edit func(*editors.PodSpecEditor) error)
EditPodSpec records a mutation for the Job's pod spec.
Pod spec edits are applied after pod template metadata edits but before container edits within the same feature. A nil edit function is ignored.
func (*Mutator) EditPodTemplateMetadata ¶
func (m *Mutator) EditPodTemplateMetadata(edit func(*editors.ObjectMetaEditor) error)
EditPodTemplateMetadata records a mutation for the Job's pod template metadata.
Pod template metadata edits are applied after job spec edits but before pod spec edits within the same feature. A nil edit function is ignored.
func (*Mutator) EnsureContainer ¶
EnsureContainer records that a regular container must be present in the Job. If a container with the same name exists, it is replaced; otherwise, it is appended.
func (*Mutator) EnsureContainerEnvVar ¶
EnsureContainerEnvVar records that an environment variable must be present in all containers of the Job.
This is a convenience wrapper over EditContainers.
func (*Mutator) EnsureInitContainer ¶
EnsureInitContainer records that an init container must be present in the Job. 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 ¶
RemoveContainer records that a regular container should be removed by name.
func (*Mutator) RemoveContainerEnvVar ¶
RemoveContainerEnvVar records that an environment variable should be removed from all containers of the Job.
This is a convenience wrapper over EditContainers.
func (*Mutator) RemoveContainers ¶
RemoveContainers records that multiple regular containers should be removed by name.
func (*Mutator) RemoveInitContainer ¶
RemoveInitContainer records that an init container should be removed by name.
func (*Mutator) RemoveInitContainers ¶
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 Job 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.Completable: for run-to-completion tracking.
- concepts.Suspendable: for controlled deactivation (suspend or delete).
- 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 Job, including initial creation, updates via feature mutations, and completion status monitoring.
func (*Resource) ConvergingStatus ¶
func (r *Resource) ConvergingStatus(op concepts.ConvergingOperation) (concepts.CompletionStatusWithReason, error)
ConvergingStatus evaluates if the Job has completed, is still running, or has failed.
By default, it uses DefaultConvergingStatusHandler, which checks the Job's status conditions for Complete or Failed.
The return value includes a descriptive status (concepts.CompletionStatusCompleted, concepts.CompletionStatusRunning, concepts.CompletionStatusPending, or concepts.CompletionStatusFailing) and a human-readable reason, which are used to update the component's conditions.
func (*Resource) DeleteOnSuspend ¶
DeleteOnSuspend determines whether the Job should be deleted from the cluster when the parent component is suspended.
By default, it uses DefaultDeleteOnSuspendHandler, which returns true, meaning the Job is deleted during suspension. Jobs cannot be meaningfully scaled to zero like Deployments, so deletion is the standard approach.
A custom decision handler can be registered via the Builder to change this behavior based on the current state of the Job.
func (*Resource) ExtractData ¶
ExtractData executes registered data extraction functions to harvest information from the reconciled Job.
This is called by the framework after a successful reconciliation of the resource. It allows the component to export details (like completion status or generated names) that might be needed by other resources or higher-level controllers.
Data extractors are provided with a deep copy of the current Job to prevent accidental mutations during the extraction process.
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 ¶
Identity returns a unique identifier for the Job in the format "batch/v1/Job/<namespace>/<name>".
This identifier is used by the framework's internal tracking and recording mechanisms to distinguish this specific Job from other resources managed by the same component.
func (*Resource) Mutate ¶
Mutate transforms the current state of a Kubernetes Job into the desired state.
The mutation process follows a specific order:
- Core State: The desired base state is applied to the current object.
- Feature Mutations: All registered feature-based mutations are applied, allowing for granular, version-gated changes to the Job.
- Suspension: If the resource is in a suspending state, the suspension logic (e.g., setting suspend=true) 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 ¶
Object returns a copy of the underlying Kubernetes Job 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
PreviewObject returns the Job 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 ¶
Suspend triggers the deactivation of the Job.
It registers a mutation that will be executed during the next Mutate call. The default behavior uses DefaultSuspendMutationHandler to set the Job's Suspend field to true, which prevents new pods from being created.
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 Job has been successfully suspended by checking if the Suspend field is true and there are no active pods. The framework uses this to determine when the component has reached a fully suspended state.
Source Files