feat: implement job primitive by sourcehawk · Pull Request #26 · sourcehawk/operator-component-framework

sourcehawk · 2026-03-22T03:11:19Z

Implements the job Kubernetes resource primitive following the pattern established by the existing ConfigMap and Deployment primitives.

Summary

Adds job primitive package under pkg/primitives/job/
Implements required lifecycle interfaces
Includes editors, mutator, flavors, and builder

Checklist

Compiles cleanly
Tests pass
Follows naming conventions in CONTEXT.md
Does not modify shared files

Copilot

Pull request overview

Implements a new Kubernetes Job primitive for the operator-component-framework, mirroring the existing primitive patterns (builder/resource/handlers/mutator/flavors), and adds an example + documentation to demonstrate usage.

Changes:

Added pkg/primitives/job/ with builder/resource/handlers/flavors and a Job-specific mutator.
Added a shared JobSpecEditor under pkg/mutation/editors/ with tests.
Added a runnable examples/job-primitive/ plus new documentation at docs/primitives/job.md.

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
pkg/primitives/job/resource.go	Job primitive Resource wrapper over `internal/generic.TaskResource`.
pkg/primitives/job/builder.go	Builder for configuring Job resources (mutations, flavors, handlers, extractors).
pkg/primitives/job/handlers.go	Default completion + suspension handlers for Jobs.
pkg/primitives/job/mutator.go	Plan/apply mutator for Job (metadata/spec/pod/container mutations).
pkg/primitives/job/flavors.go	Field application flavors for preserving live labels/annotations.
pkg/primitives/job/*_test.go	Unit tests for builder, handlers, mutator, and flavors.
pkg/mutation/editors/jobspec.go	New shared typed editor for `batchv1.JobSpec`.
pkg/mutation/editors/jobspec_test.go	Tests for the new `JobSpecEditor`.
examples/job-primitive/**	Example controller + features demonstrating the job primitive.
docs/primitives/job.md	User-facing documentation for the new Job primitive API and behavior.

pkg/primitives/job/mutator.go

pkg/primitives/job/mutator_test.go

docs/primitives/job.md

pkg/primitives/job/resource.go

pkg/mutation/editors/jobspec.go

pkg/primitives/job/handlers.go

Copilot

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 3 comments.

pkg/primitives/job/handlers.go

pkg/primitives/job/resource.go

sourcehawk · 2026-03-22T13:28:55Z

Claude Review Cycle 1 Complete

Addressed:

handlers.go:38 — Use cond.Reason as fallback when cond.Message is empty in Job failure status handler. Added corresponding test case for reason-only failures.
resource.go:20 — Fixed doc comments to reference component.Resource (and other component.* interfaces) instead of concepts.*, matching conventions used by configmap and deployment primitives.
resource.go:114 — Added comprehensive resource_test.go covering Identity, Object deep-copy, Mutate with mutations and feature ordering, DeleteOnSuspend (default + custom handler), Suspend wiring, SuspensionStatus delegation, ConvergingStatus delegation, ExtractData, and custom field applicator.

Intentionally ignored:
None

Copilot

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 3 comments.

pkg/primitives/job/resource_test.go

pkg/mutation/editors/jobspec.go

docs/primitives/job.md

sourcehawk · 2026-03-23T02:57:09Z

Claude Review Cycle 1 Complete

Addressed:

resource_test.go:127 — Added TestResource_Mutate_CrossMutationSelectorSnapshot test that validates a container added by mutation A can be selected and configured by mutation B, exercising the cross-mutation feature-boundary semantics.

Intentionally ignored:

jobspec.go:52 — This is a PR description/checklist accuracy issue, not a code issue. The shared JobSpecEditor under pkg/mutation/editors is an intentional part of this PR (follows the same pattern as the existing PodSpecEditor and ContainerEditor). The PR description checklist should be updated to reflect this, but that is outside the scope of code changes.
docs/primitives/job.md:126 — The comment claims the feature-boundary mechanism is not invoked between registered mutations, but this is incorrect. The ApplyMutations helper in internal/generic/mutate_helper.go calls beginFeature() on the mutator before each mutation via the FeatureMutator interface. Each mutation gets its own featurePlan, and container selector snapshots are taken per-plan after presence operations. The documentation accurately describes the implemented behavior.

Copilot

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 2 comments.

pkg/primitives/job/resource.go

docs/primitives/job.md

sourcehawk · 2026-03-23T16:58:23Z

Claude Review Cycle 1 Complete

Addressed:
None

Intentionally ignored:

resource.go:16 (Status preservation): The code already preserves status via generic.PreserveStatus(current, original) on line 18, and this is verified by TestDefaultFieldApplicator_PreservesStatus. The Copilot suggestion achieves the same result with a different approach but the current implementation is correct and consistent with the framework's generic helpers.
job.md:123 (Table formatting): The table already uses single | delimiters correctly. The claim about || at the start of rows does not match the actual content. The suggestion only adds whitespace padding, which is a style preference.

Implements the Job primitive using the Task lifecycle (Completable, Suspendable) from internal/generic. Includes default handlers for completion status, suspension via Job.Spec.Suspend, and deletion on suspend. Follows the same pod-template mutation pattern as Deployment. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Provides SetCompletions, SetParallelism, SetBackoffLimit, SetActiveDeadlineSeconds, SetTTLSecondsAfterFinished, and SetCompletionMode methods with full test coverage. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Implements the Mutator for Job resources following the same pattern as the Deployment mutator. Supports editing job metadata, job spec, pod template metadata, pod spec, and container presence/edits with snapshot semantics. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Demonstrates building a Job primitive with version-gated image updates, tracing env vars, retry policy configuration, field preservation flavors, custom completion status handler, and data extraction. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Covers capabilities, building, mutations, internal ordering, editors, convenience methods, suspension behavior, flavors, and guidance. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Use corev1.ConditionTrue instead of string literal "True" in status condition checks (handlers.go) - Fix range variable address issue in findEnv test helper by iterating by index (mutator_test.go) - Fix doc comments to reference concepts.X instead of component.X for interface types (resource.go) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…ce tests - Use cond.Reason as fallback when cond.Message is empty in Job failure status handler, since Kubernetes often provides details in Reason only - Fix doc comments to reference component.Resource instead of concepts.Resource, matching conventions used by other primitives - Add resource_test.go with comprehensive coverage for Resource-level behaviors including Suspend/DeleteOnSuspend wiring, SuspensionStatus and ConvergingStatus delegation, ExtractData, and custom field applicator Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Validates that a container added by one mutation can be selected and configured by a subsequent mutation, exercising the feature-boundary semantics of the mutator's plan-and-apply pattern. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Match the pattern used by deployment/configmap primitives: initialize with an empty featurePlan directly instead of calling beginFeature(), which would create a duplicate empty feature when the generic mutate_helper also calls beginFeature(). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Align with upstream architectural fixes: export beginFeature() to BeginFeature() to satisfy the FeatureMutator interface, and add status preservation to DefaultFieldApplicator so spec-level reconciliation does not clear server-written status data. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 4 comments.

Copilot · 2026-03-25T16:11:41Z

pkg/mutation/editors/jobspec.go

@@ -0,0 +1,52 @@
+package editors


The PR description checklist says "Does not modify shared files", but this PR adds a new shared editor under pkg/mutation/editors/ (and also updates shared docs). Please either update the checklist item (if shared changes are expected for this primitive) or move/encapsulate the shared editor changes so the checklist remains accurate.

Copilot · 2026-03-25T16:11:42Z

pkg/primitives/job/resource.go

+// The return value includes a descriptive status (Completed, TaskRunning, TaskPending,
+// or TaskFailing) and a human-readable reason, which are used to update the component's
+// conditions.


The comment references statuses TaskRunning, TaskPending, and TaskFailing, but the code (and tests) use concepts.CompletionStatusRunning/Pending/Failing. Please align the terminology in this comment (and any similar text in docs) to the actual concepts.CompletionStatus* names to avoid confusing API consumers.

Suggested change

// The return value includes a descriptive status (Completed, TaskRunning, TaskPending,

// or TaskFailing) and a human-readable reason, which are used to update the component's

// conditions.

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

Copilot · 2026-03-25T16:11:42Z

pkg/primitives/job/mutator.go

+func (m *Mutator) EditObjectMetadata(edit func(*editors.ObjectMetaEditor) error) {
+	if edit == nil {
+		return
+	}
+	m.active.jobMetadataEdits = append(m.active.jobMetadataEdits, edit)
+}


m.active is dereferenced without a guard; calling any of the Edit*/Ensure* methods before BeginFeature() will cause a nil-pointer panic. Since this is a public helper type, consider adding a small internal guard (e.g., an ensureActive() that either initializes a plan or panics with a clear message) so failures are deterministic and actionable rather than a generic nil dereference.

Copilot · 2026-03-25T16:11:42Z

examples/job-primitive/resources/job.go

+	builder.WithDataExtractor(func(j batchv1.Job) error {
+		fmt.Printf("Reconciling job: %s, active: %d, succeeded: %d, failed: %d\n",
+			j.Name, j.Status.Active, j.Status.Succeeded, j.Status.Failed)
+
+		// Print the complete job resource object as yaml
+		y, err := yaml.Marshal(j)
+		if err != nil {
+			return fmt.Errorf("failed to marshal job to yaml: %w", err)
+		}
+		fmt.Printf("Complete Job Resource:\n---\n%s\n---\n", string(y))
+
+		return nil
+	})


This example dumps the full Job object (including pod template) to stdout. In real usage, that can inadvertently expose sensitive env vars or other configuration in logs. Consider either removing the full YAML dump, redacting sensitive fields, or gating it behind an explicit debug flag/logger configuration (while keeping the rest of the example intact).

…ant names Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

sourcehawk · 2026-03-25T16:15:02Z

Claude Review Cycle 1 Complete

Addressed:

Fixed ConvergingStatus doc comment in pkg/primitives/job/resource.go to reference actual concepts.CompletionStatusCompleted, concepts.CompletionStatusRunning, concepts.CompletionStatusPending, and concepts.CompletionStatusFailing constant names instead of informal terminology.

Intentionally ignored:

jobspec.go shared editor location: The pkg/mutation/editors/ package already contains deploymentspec.go, configmapdata.go, and other typed editors. Adding jobspec.go here follows the established pattern. This is a PR description checklist item, not a code issue.
Nil guard on m.active in mutator.go: The deployment primitive mutator follows the identical pattern with no nil guards. The doc comment already states "BeginFeature must be called before registering any mutations." Adding a guard here would be inconsistent with the existing primitives.
Example YAML dump of full Job object: The deployment primitive example (examples/deployment-primitive/resources/deployment.go) uses the exact same pattern of marshaling the full object to YAML. This is the established example convention and is appropriate for illustrative code.

Copilot

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated no new comments.

Resolve conflicts in docs/primitives.md (add job to expanded primitives table), jobspec.go (take main's doc comments), and jobspec_test.go (combine require.NotNil checks with editor variable naming convention). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 2 comments.

Copilot · 2026-03-25T19:07:58Z

docs/primitives.md

 | `pkg/primitives/statefulset`        | Workload    | [statefulset.md](primitives/statefulset.md)               |
 | `pkg/primitives/replicaset`         | Workload    | [replicaset.md](primitives/replicaset.md)                 |
 | `pkg/primitives/daemonset`          | Workload    | [daemonset.md](primitives/daemonset.md)                   |
+| `pkg/primitives/job`                | Task        | [job.md](primitives/job.md)                               |


PR description checklist says this PR “does not modify shared files”, but this PR updates shared docs (this file) and also changes shared editor tests (pkg/mutation/editors/jobspec_test.go). Please either update the checklist/description to reflect these shared changes, or revert them if they were unintended.

Copilot · 2026-03-25T19:07:59Z

docs/primitives/job.md

+| Capability              | Detail                                                                                          |
+| ----------------------- | ----------------------------------------------------------------------------------------------- |
+| **Completion tracking** | Monitors Job conditions and reports `Completed`, `TaskRunning`, `TaskPending`, or `TaskFailing` |
+| **Suspension**          | Sets `spec.suspend=true` or deletes the Job (default); reports `Suspending` / `Suspended`       |


The capabilities table says suspension “sets spec.suspend=true or deletes the Job (default)”, but in the framework suspension flow Suspend() is still called even when DeleteOnSuspend() is true, and deletion only happens after the resource reaches Suspended. Consider rewording this to avoid implying these are mutually exclusive (e.g., suspend/stop creation, then delete by default once suspended).

Suggested change

| **Suspension** | Sets `spec.suspend=true` or deletes the Job (default); reports `Suspending` / `Suspended` |

| **Suspension** | Suspends/stops the Job (for example via `spec.suspend=true`) and, by default, deletes it once `Suspended`; reports `Suspending` / `Suspended` |

sourcehawk requested a review from Copilot March 22, 2026 03:43

Copilot started reviewing on behalf of sourcehawk March 22, 2026 03:44 View session

Copilot AI reviewed Mar 22, 2026

View reviewed changes

sourcehawk requested a review from Copilot March 22, 2026 13:20

Copilot started reviewing on behalf of sourcehawk March 22, 2026 13:21 View session

Copilot AI reviewed Mar 22, 2026

View reviewed changes

pkg/primitives/job/handlers.go Show resolved Hide resolved

pkg/primitives/job/resource.go Show resolved Hide resolved

pkg/primitives/job/resource.go Outdated Show resolved Hide resolved

Copilot AI review requested due to automatic review settings March 22, 2026 19:51

Copilot started reviewing on behalf of sourcehawk March 22, 2026 19:51 View session

Copilot AI reviewed Mar 22, 2026

View reviewed changes

pkg/primitives/job/resource_test.go Show resolved Hide resolved

pkg/mutation/editors/jobspec.go Show resolved Hide resolved

docs/primitives/job.md Show resolved Hide resolved

Copilot AI review requested due to automatic review settings March 23, 2026 16:08

Copilot started reviewing on behalf of sourcehawk March 23, 2026 16:11 View session

Copilot AI reviewed Mar 23, 2026

View reviewed changes

pkg/primitives/job/resource.go Outdated Show resolved Hide resolved

docs/primitives/job.md Outdated Show resolved Hide resolved

sourcehawk and others added 12 commits March 23, 2026 20:17

Add JobSpecEditor for typed Job spec mutations

0cf92c9

Provides SetCompletions, SetParallelism, SetBackoffLimit, SetActiveDeadlineSeconds, SetTTLSecondsAfterFinished, and SetCompletionMode methods with full test coverage. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add Job primitive documentation

d59c276

Covers capabilities, building, mutations, internal ordering, editors, convenience methods, suspension behavior, flavors, and guidance. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Fix staticcheck lint: use tagged switch in status handler

2d257fd

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Preserve server-managed metadata in default field applicator

a46382a

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot AI review requested due to automatic review settings March 23, 2026 21:33

sourcehawk force-pushed the feature/job-primitive branch from c8fbe86 to 8f166b9 Compare March 23, 2026 21:33

Copilot started reviewing on behalf of sourcehawk March 23, 2026 21:34 View session

sourcehawk requested review from Copilot and removed request for Copilot March 25, 2026 16:07

Copilot AI reviewed Mar 25, 2026

View reviewed changes

Copilot started reviewing on behalf of sourcehawk March 25, 2026 16:12 View session

Fix ConvergingStatus doc comment to use actual CompletionStatus const…

639d12a

…ant names Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

sourcehawk requested review from Copilot and removed request for Copilot March 25, 2026 16:15

Copilot AI reviewed Mar 25, 2026

View reviewed changes

Copilot started reviewing on behalf of sourcehawk March 25, 2026 16:20 View session

Copilot started reviewing on behalf of sourcehawk March 25, 2026 16:23 View session

Copilot started reviewing on behalf of sourcehawk March 25, 2026 16:26 View session

Copilot started reviewing on behalf of sourcehawk March 25, 2026 16:27 View session

Copilot started reviewing on behalf of sourcehawk March 25, 2026 16:37 View session

sourcehawk and others added 2 commits March 25, 2026 18:57

Merge branch 'main' into feature/job-primitive

6059324

Copilot AI review requested due to automatic review settings March 25, 2026 18:59

sourcehawk merged commit 67521b4 into main Mar 25, 2026
4 checks passed

sourcehawk deleted the feature/job-primitive branch March 25, 2026 19:00

Copilot started reviewing on behalf of sourcehawk March 25, 2026 19:00 View session

Copilot AI reviewed Mar 25, 2026

View reviewed changes

-// The return value includes a descriptive status (Completed, TaskRunning, TaskPending,
-// or TaskFailing) and a human-readable reason, which are used to update the component's
-// conditions.
+// 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.

	\| Suspension \| Sets `spec.suspend=true` or deletes the Job (default); reports `Suspending` / `Suspended` \|
	\| Suspension \| Suspends/stops the Job (for example via `spec.suspend=true`) and, by default, deletes it once `Suspended`; reports `Suspending` / `Suspended` \|

Conversation

sourcehawk commented Mar 22, 2026

Summary

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sourcehawk commented Mar 22, 2026

Claude Review Cycle 1 Complete

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sourcehawk commented Mar 23, 2026

Claude Review Cycle 1 Complete

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

sourcehawk commented Mar 23, 2026

Claude Review Cycle 1 Complete

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

sourcehawk commented Mar 25, 2026

Claude Review Cycle 1 Complete

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!