feat: implement ingress primitive by sourcehawk · Pull Request #21 · sourcehawk/operator-component-framework

sourcehawk · 2026-03-22T03:10:55Z

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

Summary

Adds ingress primitive package under pkg/primitives/ingress/
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

Adds a new Kubernetes Ingress primitive to the operator component framework, following the existing primitive patterns (builder/resource + mutator pipeline + flavors + lifecycle handlers), and includes an accompanying example and documentation.

Changes:

Introduces pkg/primitives/ingress (builder/resource, mutator, handlers, flavors) plus unit tests.
Adds a shared IngressSpecEditor under pkg/mutation/editors (with tests) to support typed ingress spec mutations.
Adds an examples/ingress-primitive walkthrough and new docs/primitives/ingress.md documentation.

Reviewed changes

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

Show a summary per file

File	Description
pkg/primitives/ingress/resource.go	Defines the ingress `Resource` wrapper over `generic.IntegrationResource`.
pkg/primitives/ingress/builder.go	Builder API wiring for applicators, flavors, mutations, status/suspension handlers, data extraction.
pkg/primitives/ingress/mutator.go	Plan/apply mutator with per-feature planning and category ordering.
pkg/primitives/ingress/handlers.go	Default operational/suspension handler implementations for integration lifecycle.
pkg/primitives/ingress/flavors.go	Ingress flavors (label/annotation preservation) via shared `pkg/flavors`.
pkg/primitives/ingress/*_test.go	Unit tests for ingress builder/mutator/handlers/flavors behavior.
pkg/mutation/editors/ingressspec.go	Adds typed `IngressSpecEditor` for ingress spec mutations.
pkg/mutation/editors/ingressspec_test.go	Tests for `IngressSpecEditor` operations (class name, backend, rules, TLS).
examples/ingress-primitive/main.go	Standalone example driving reconciliation steps using a fake client.
examples/ingress-primitive/resources/ingress.go	Example ingress resource factory using mutations, flavors, and data extraction.
examples/ingress-primitive/features/mutations.go	Example feature-gated ingress mutations (version annotation + TLS).
examples/ingress-primitive/app/controller.go	Example controller that builds a component around the ingress primitive.
examples/ingress-primitive/app/owner.go	Re-exports shared ExampleApp types for the example package.
examples/ingress-primitive/README.md	Documents how to run and understand the ingress example.
docs/primitives/ingress.md	New primitive documentation covering usage, ordering, handlers, flavors, guidance.

pkg/primitives/ingress/handlers.go

docs/primitives/ingress.md

pkg/mutation/editors/ingressspec.go

Copilot

Pull request overview

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

pkg/primitives/ingress/resource.go

docs/primitives/ingress.md

pkg/mutation/editors/ingressspec.go

docs/primitives/ingress.md

pkg/primitives/ingress/mutator.go

sourcehawk · 2026-03-22T13:31:33Z

Claude Review Cycle 1 Complete

Addressed:

Doc comment in resource.go: Fixed interface references from component.* to concepts.Operational, concepts.Suspendable, concepts.DataExtractable (kept component.Resource as that is the correct package)
Resource wrapper tests: Added resource_test.go with tests for Identity, Object deep-copy, Mutate, WithMutation, FeatureOrdering, CustomFieldApplicator, ConvergingStatus, DeleteOnSuspend, Suspend, SuspensionStatus, and ExtractData
Operational status names in docs: Changed Pending to OperationPending in the capabilities table and status handler table to match concepts.OperationalStatus constants
Link from primitives.md: Added ingress to the built-in primitives table and added IngressSpecEditor to the editors table
Cross-reference in ingress.md: Added link back to primitives overview page

Intentionally ignored:

PR description checklist (ingressspec.go comment): This is about the PR description metadata, not a code change. The shared editor is intentional and minimal.
FeatureMutator interface (mutator.go comment): The unexported beginFeature() pattern is identical across all primitives (configmap, deployment, ingress). This is a pre-existing architectural pattern in the framework, not an ingress-specific issue. Fixing it would require changes to internal/generic shared infrastructure, which is out of scope for this PR.

Copilot

Pull request overview

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

pkg/primitives/ingress/handlers.go

examples/ingress-primitive/features/mutations.go

sourcehawk · 2026-03-22T23:15:42Z

approved

Copilot

Pull request overview

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

pkg/primitives/ingress/resource.go

pkg/primitives/ingress/resource_test.go

docs/primitives.md

sourcehawk · 2026-03-23T03:24:50Z

Claude Review Cycle 1 Complete

Addressed:

Status preservation in DefaultFieldApplicator (resource.go:17): Save and restore the live Status field before overwriting with desired.DeepCopy() so that ingress-controller-owned fields like Status.LoadBalancer.Ingress are not cleared during reconciliation.
Status preservation test coverage (resource_test.go:191): Added TestDefaultFieldApplicator_PreservesStatus to verify Status.LoadBalancer.Ingress entries survive the field applicator. Added TestDefaultOperationalStatusHandler_Operational and TestDefaultOperationalStatusHandler_OperationalWithHostname to verify the handler returns Operational when an IP or hostname is assigned.

Intentionally ignored:

PR description/checklist accuracy (docs/primitives.md:135): This comment is about PR metadata (the description checklist), not a code issue. The PR description can be updated by the PR author separately.

Copilot

Pull request overview

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

Provides SetIngressClassName, SetDefaultBackend, EnsureRule (upsert by host), RemoveRule, EnsureTLS (upsert by first host), RemoveTLS, and Raw escape hatch. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Implements builder, resource, mutator, handlers, and flavors for the networking.k8s.io/v1 Ingress kind. Key design decisions: - DefaultDeleteOnSuspend = false (avoids ingress controller churn) - DefaultSuspendMutation = no-op (backend 502/503 is correct behaviour) - Operational status: Pending until load balancer address assigned - Suspension status: immediately Suspended with reason message Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Covers operational status, suspension strategy, mutation pipeline, editors, flavors, and guidance for common use cases. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Demonstrates base construction, feature mutations (version annotation, TLS toggle), field flavors, and data extraction using the ingress builder and mutator. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

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

Address Copilot review: DefaultOperationalStatusHandler now checks that at least one LoadBalancer.Ingress entry has a non-empty IP or Hostname, rather than only checking slice length. This prevents marking an Ingress as Operational when entries exist but have no assigned address. Update docs and add test for the empty-entry edge case. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Fix doc comments to reference concepts.Operational/Suspendable/DataExtractable instead of component.* for lifecycle interfaces - Use correct OperationPending status name in docs and code comments - Add ingress entry to built-in primitives table in docs/primitives.md - Add IngressSpecEditor to mutation editors table in docs/primitives.md - Add cross-reference link to primitives overview in ingress doc - Add resource_test.go with tests for Identity, Object deep-copy, Mutate, mutations, feature ordering, custom applicator, converging status, suspension, and data extraction Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

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

- Fix doc comments to reference concepts.Operational/Suspendable/DataExtractable instead of component.* for lifecycle interfaces - Use correct OperationPending status name in docs and code comments - Add ingress entry to built-in primitives table in docs/primitives.md - Add IngressSpecEditor to mutation editors table in docs/primitives.md - Add cross-reference link to primitives overview in ingress doc - Add resource_test.go with tests for Identity, Object deep-copy, Mutate, mutations, feature ordering, custom applicator, converging status, suspension, and data extraction Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

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

The DefaultFieldApplicator was replacing the entire object with the desired state, which wiped ingress-controller-owned fields like Status.LoadBalancer.Ingress. This caused DefaultOperationalStatusHandler to never see assigned addresses, keeping the resource permanently pending. Save and restore the live Status before overwriting with the desired spec so that readiness detection works correctly. Also adds test coverage for: - Status.LoadBalancer preservation through DefaultFieldApplicator - DefaultOperationalStatusHandler returning Operational with IP - DefaultOperationalStatusHandler returning Operational with Hostname Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Replace manual status save/restore with generic.PreserveStatus to match the deployment primitive pattern. Add Default Field Application section to ingress primitive docs. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Initialize plans slice and active pointer directly in the constructor, matching the fix already applied to deployment and configmap mutators. This prevents an empty feature from being created when the generic helper in mutator_helper.go calls beginFeature(). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

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

Copilot

Pull request overview

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

pkg/primitives/ingress/flavors_test.go

Resolve conflict in docs/primitives.md by combining main's table formatting with the ingress primitive row from the feature branch. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Run make fmt-md to apply consistent markdown formatting to ingress documentation and example README. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

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

sourcehawk · 2026-03-24T00:33:21Z

Claude Review Cycle 1 Complete

Addressed:

flavors_test.go:34 — Added require.NoError(t, buildErr) after Build() in "flavors run after baseline applicator" test
flavors_test.go:64 — Added require.NoError(t, buildErr) after Build() in "flavors run in registration order" test
flavors_test.go:80 — Added require.NoError(t, buildErr) after Build() in "flavor error is returned with context" test

Intentionally ignored:
None

Copilot

Pull request overview

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

docs/primitives.md

pkg/primitives/ingress/resource.go

Use framework-specific OperationPending (concepts.OperationalStatusPending) terminology instead of generic "Pending" to avoid confusion with other lifecycle states. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

sourcehawk · 2026-03-24T01:08:15Z

Claude Review Cycle 1 Complete

Addressed:

resource.go line 34: Updated operational status wording from generic "Pending" to framework-specific "OperationPending (concepts.OperationalStatusPending)" terminology.

Intentionally ignored:

docs/primitives.md line 160: This comment asks to update the PR description checklist, not the code itself. The PR description is a meta concern for the PR author to address, not a code change. Will update the PR description separately if needed.

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

…tive

Align the ingress Mutator with the configmap and deployment primitives: NewMutator no longer creates an initial feature plan. BeginFeature must be called before registering any mutations. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…tive

Align with the framework's switch to Server-Side Apply: remove DefaultFieldApplicator, WithCustomFieldApplicator, WithFieldApplicationFlavor, flavors.go, and all related tests and documentation. Update Mutate tests to use the Object()-first pattern. 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 3 comments.

Copilot · 2026-03-25T14:14:50Z

examples/ingress-primitive/README.md

+- **Field Flavors**: Preserving labels and annotations that might be managed by external tools (e.g., cert-manager,
+  ingress controllers).


This README describes "Field Flavors" that preserve labels/annotations, but there is no corresponding flavor API in the codebase (e.g., no WithFieldApplicationFlavor exists). Please update the README to reflect the actual supported behavior, or implement the described flavor mechanism and reference the real API names.

Suggested change

- **Field Flavors**: Preserving labels and annotations that might be managed by external tools (e.g., cert-manager,

ingress controllers).

Copilot · 2026-03-25T14:14:51Z

docs/primitives.md

 ## Built-in Primitives

-| Primitive                   | Category | Documentation                             |
-| --------------------------- | -------- | ----------------------------------------- |
-| `pkg/primitives/deployment` | Workload | [deployment.md](primitives/deployment.md) |
-| `pkg/primitives/configmap`  | Static   | [configmap.md](primitives/configmap.md)   |
+| Primitive                   | Category    | Documentation                             |
+| --------------------------- | ----------- | ----------------------------------------- |
+| `pkg/primitives/deployment` | Workload    | [deployment.md](primitives/deployment.md) |
+| `pkg/primitives/configmap`  | Static      | [configmap.md](primitives/configmap.md)   |
+| `pkg/primitives/ingress`    | Integration | [ingress.md](primitives/ingress.md)       |


The PR description checklist says "Does not modify shared files", but this change set updates shared framework docs (docs/primitives.md) and the shared editors package (pkg/mutation/editors/ingressspec.go). Please correct the PR description/checklist (or adjust scope) so reviewers aren't misled about the change surface.

Copilot · 2026-03-25T14:14:51Z

examples/ingress-primitive/resources/ingress.go

+	// 4. Configure flavors.
+	builder.WithFieldApplicationFlavor(ingress.PreserveCurrentLabels)
+	builder.WithFieldApplicationFlavor(ingress.PreserveCurrentAnnotations)
+


WithFieldApplicationFlavor and the referenced flavors (ingress.PreserveCurrentLabels / ingress.PreserveCurrentAnnotations) don't exist anywhere else in the repo (search only finds this example). As written, this example will not compile; either remove these calls or add the corresponding Builder API + flavor definitions in pkg/primitives/ingress (and any underlying generic support) so the example matches the public API.

Suggested change

// 4. Configure flavors.

builder.WithFieldApplicationFlavor(ingress.PreserveCurrentLabels)

builder.WithFieldApplicationFlavor(ingress.PreserveCurrentAnnotations)

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

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

Copilot AI reviewed Mar 22, 2026

View reviewed changes

pkg/primitives/ingress/handlers.go Outdated Show resolved Hide resolved

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

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

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

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

Copilot AI reviewed Mar 22, 2026

View reviewed changes

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

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

Copilot AI reviewed Mar 22, 2026

View reviewed changes

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

examples/ingress-primitive/features/mutations.go Show resolved Hide resolved

sourcehawk force-pushed the feature/ingress-primitive branch from c21b61c to c31fd20 Compare March 23, 2026 00:13

Copilot AI review requested due to automatic review settings March 23, 2026 03:00

Copilot started reviewing on behalf of sourcehawk March 23, 2026 03:01 View session

Copilot AI reviewed Mar 23, 2026

View reviewed changes

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

pkg/primitives/ingress/resource_test.go Outdated Show resolved Hide resolved

docs/primitives.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:09 View session

Copilot AI reviewed Mar 23, 2026

View reviewed changes

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

Add IngressSpecEditor for typed Ingress spec mutations

e97fa34

Provides SetIngressClassName, SetDefaultBackend, EnsureRule (upsert by host), RemoveRule, EnsureTLS (upsert by first host), RemoveTLS, and Raw escape hatch. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add documentation for the Ingress primitive

6e2be93

Covers operational status, suspension strategy, mutation pipeline, editors, flavors, and guidance for common use cases. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add Ingress primitive example

e357caf

Demonstrates base construction, feature mutations (version annotation, TLS toggle), field flavors, and data extraction using the ingress builder and mutator. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add package comment to features package for lint compliance

9f796d7

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

preserve server-managed metadata in default field applicator

38997d8

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

preserve server-managed metadata in default field applicator

5b2badb

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

sourcehawk and others added 3 commits March 23, 2026 20:19

Export BeginFeature() to satisfy updated FeatureMutator interface

3964dcf

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/ingress-primitive branch from e2ee083 to 3964dcf Compare March 23, 2026 21:33

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

Copilot AI reviewed Mar 23, 2026

View reviewed changes

pkg/primitives/ingress/flavors_test.go Outdated Show resolved Hide resolved

pkg/primitives/ingress/flavors_test.go Outdated Show resolved Hide resolved

pkg/primitives/ingress/flavors_test.go Outdated Show resolved Hide resolved

sourcehawk and others added 3 commits March 24, 2026 00:29

Merge main into feature/ingress-primitive and resolve conflict

0597a79

Resolve conflict in docs/primitives.md by combining main's table formatting with the ingress primitive row from the feature branch. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Format markdown files with prettier

373c591

Run make fmt-md to apply consistent markdown formatting to ingress documentation and example README. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Assert Build() errors in flavors_test.go to prevent silent failures

5e6242c

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

Copilot AI review requested due to automatic review settings March 24, 2026 00:33

Copilot started reviewing on behalf of sourcehawk March 24, 2026 00:33 View session

Copilot AI reviewed Mar 24, 2026

View reviewed changes

docs/primitives.md Show resolved Hide resolved

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

sourcehawk requested a review from Copilot March 24, 2026 02:06

Copilot started reviewing on behalf of sourcehawk March 24, 2026 02:06 View session

sourcehawk requested review from Copilot and removed request for Copilot March 24, 2026 02:07

Copilot AI reviewed Mar 24, 2026

View reviewed changes

sourcehawk and others added 4 commits March 24, 2026 17:51

Merge remote-tracking branch 'origin/main' into feature/ingress-primi…

fc6bfff

…tive

Merge remote-tracking branch 'origin/main' into feature/ingress-primi…

1464bb2

…tive

Copilot AI review requested due to automatic review settings March 25, 2026 14:08

Copilot started reviewing on behalf of sourcehawk March 25, 2026 14:10 View session

Copilot AI reviewed Mar 25, 2026

View reviewed changes

		- Field Flavors: Preserving labels and annotations that might be managed by external tools (e.g., cert-manager,
		ingress controllers).

	// 4. Configure flavors.
	builder.WithFieldApplicationFlavor(ingress.PreserveCurrentLabels)
	builder.WithFieldApplicationFlavor(ingress.PreserveCurrentAnnotations)

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!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

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!

sourcehawk commented Mar 22, 2026

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!

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 24, 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 24, 2026

Claude Review Cycle 1 Complete

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

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!