feat: implement clusterrole primitive by sourcehawk · Pull Request #37 · sourcehawk/operator-component-framework

sourcehawk · 2026-03-22T03:12:14Z

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

Summary

Adds clusterrole primitive package under pkg/primitives/clusterrole/
Implements required lifecycle interfaces
Includes editors, mutator, flavors, and builder
Adds PolicyRulesEditor to pkg/mutation/editors/ (reusable for Role and ClusterRole)
Adds cluster-scoped resource support to internal/generic/builder_base.go

Checklist

Compiles cleanly
Tests pass
Follows naming conventions in CONTEXT.md
Shared infrastructure changes are limited to adding cluster-scope support (internal/generic/builder_base.go) and a new PolicyRulesEditor (pkg/mutation/editors/)

Copilot

Pull request overview

Adds a new clusterrole primitive to the operator-component-framework so controllers can manage Kubernetes rbac.authorization.k8s.io/v1 ClusterRole objects using the same builder/mutator/flavor patterns as existing primitives.

Changes:

Introduces pkg/primitives/clusterrole with Resource, Builder, Mutator, and field-application flavors for ClusterRole-specific behavior.
Adds a new shared mutation editor PolicyRulesEditor under pkg/mutation/editors to support typed .rules mutation.
Adds an end-to-end example (examples/clusterrole-primitive) and full primitive documentation (docs/primitives/clusterrole.md).

Reviewed changes

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

Show a summary per file

File	Description
pkg/primitives/clusterrole/resource.go	Defines the ClusterRole `Resource` wrapper and default field applicator.
pkg/primitives/clusterrole/mutator.go	Implements plan-and-apply mutator for metadata, rules, and aggregationRule.
pkg/primitives/clusterrole/builder.go	Provides fluent builder API and validation/workarounds for cluster-scoped objects.
pkg/primitives/clusterrole/flavors.go	Adds flavors to preserve labels/annotations and externally-added rules.
pkg/primitives/clusterrole/*_test.go	Adds unit tests for builder, mutator, and flavors.
pkg/mutation/editors/policyrules.go	Adds a reusable `PolicyRulesEditor` for Role/ClusterRole rules mutation.
pkg/mutation/editors/policyrules_test.go	Adds tests for `PolicyRulesEditor`.
examples/clusterrole-primitive/*	Adds a runnable example demonstrating mutation composition and reconciliation.
docs/primitives/clusterrole.md	Adds user-facing documentation for the new primitive API and usage patterns.

pkg/primitives/clusterrole/mutator.go

pkg/primitives/clusterrole/builder.go

pkg/mutation/editors/policyrules.go

docs/primitives/clusterrole.md

Copilot

Pull request overview

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

pkg/primitives/clusterrole/mutator.go

docs/primitives/clusterrole.md

pkg/mutation/editors/policyrules.go

internal/generic/builder_base.go

pkg/primitives/clusterrole/mutator_test.go

docs/primitives/clusterrole.md

Copilot

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 1 comment.

internal/generic/builder_base.go

sourcehawk · 2026-03-22T13:26:43Z

Claude Review Cycle 1 Complete

Addressed:

Updated PR description checklist to accurately reflect that shared infrastructure files are modified (internal/generic/builder_base.go for cluster-scope support, pkg/mutation/editors/policyrules.go as a new reusable editor). The old checklist item "Does not modify shared files" has been replaced with a specific description of the shared infrastructure changes.

Intentionally ignored:
None

sourcehawk · 2026-03-22T21:01:06Z

approved but wait until last

Copilot

Pull request overview

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

pkg/primitives/clusterrole/resource.go

pkg/primitives/clusterrole/builder_test.go

internal/generic/builder_base.go

examples/clusterrole-primitive/main.go

docs/primitives/clusterrole.md

sourcehawk · 2026-03-23T00:50:22Z

Claude Review Cycle 1 Complete

Addressed:

Removed duplicate "valid clusterrole without namespace" test case in builder_test.go (identical to "valid clusterrole")
Documented cluster-scoped ownership limitation in docs/primitives/clusterrole.md (namespaced owner cannot own a ClusterRole)
Added comment in examples/clusterrole-primitive/main.go explaining the namespaced owner limitation with real clusters

Intentionally ignored:

resource.go line 28: component.DataExtractable is the consistent convention used across all primitives (deployment, configmap, clusterrole). Changing to concepts.DataExtractable would break codebase consistency.
builder_base.go line 96: Valid architectural concern about SetControllerReference failing for cluster-scoped dependents with namespaced owners, but this requires a framework-level change (e.g., adding SkipOwnerReference to ResourceOptions and threading it through the reconciliation path). Documented the limitation instead; framework fix should be tracked as a separate issue.

Copilot

Pull request overview

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

docs/primitives/clusterrole.md

examples/clusterrole-primitive/resources/clusterrole.go

examples/clusterrole-primitive/main.go

examples/clusterrole-primitive/README.md

pkg/primitives/clusterrole/mutator.go

internal/generic/builder_static_test.go

sourcehawk · 2026-03-23T03:26:03Z

Claude Review Cycle 1 Complete

Addressed:

docs/primitives/clusterrole.md line 7: Updated ownership limitation note to reflect actual framework behavior (scope mismatch is detected, owner ref is skipped with a log message, reconciliation proceeds without GC ownership)
docs/primitives/clusterrole.md line 319: Removed PreserveExternalRules from the feature-gating walkthrough example and added a documentation note explaining the trade-off between PreserveExternalRules and feature-gated mutations
examples/clusterrole-primitive/resources/clusterrole.go line 40: Removed PreserveExternalRules from the example to avoid conflict with feature-gated mutation add/remove behavior
examples/clusterrole-primitive/main.go line 40: Updated comments to describe the actual scope-mismatch behavior (skip with log) rather than implying reconciliation is rejected
examples/clusterrole-primitive/README.md line 10: Removed the PreserveExternalRules bullet from the feature list to match the updated example code
pkg/primitives/clusterrole/mutator.go line 30: Adopted the per-feature planning pattern (beginFeature/featurePlan) consistent with ConfigMap and Deployment primitives, so mutation ordering respects registration order across features
internal/generic/builder_static_test.go line 113: Removed duplicate cluster-scoped validation subtests (kept the testify require/assert versions)

Intentionally ignored:
None

Copilot

Pull request overview

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

pkg/primitives/clusterrole/flavors.go

pkg/primitives/clusterrole/mutator.go

pkg/primitives/clusterrole/builder.go

sourcehawk · 2026-03-23T16:59:55Z

Claude Review Cycle 1 Complete

Addressed:

PreserveExternalRules slice-order equality (flavors.go:60): Replaced strict slice-order comparison with set-based (sort-then-compare) equality in policyRuleEqual, so reordered-but-equivalent rules from admission webhooks are correctly recognized as duplicates. Added test covering this case.
SetAggregationRule pointer aliasing (mutator.go:100): Added DeepCopy of the *AggregationRule at registration time so the mutator records intent immutably, consistent with AddRule which records by value. Added test verifying caller mutation after registration does not affect the applied result.
Build() duplicate validation (builder.go:106): Removed local nil-object and empty-name checks, delegating entirely to generic.StaticBuilder.Build() → ValidateBase(), consistent with the ConfigMap primitive. Removed unused errors import.

Intentionally ignored:
None

Copilot

Pull request overview

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

pkg/primitives/clusterrole/builder.go

pkg/primitives/clusterrole/flavors.go

docs/primitives/clusterrole.md

pkg/primitives/clusterrole/mutator.go

Introduces a typed editor for mutating the .rules field of Role and ClusterRole resources, following the same pattern as existing editors (ConfigMapDataEditor, ObjectMetaEditor). Provides AddRule, RemoveRuleByIndex, Clear, and Raw escape hatch operations. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Implements the ClusterRole primitive as a Static, cluster-scoped resource. Includes builder (with name-only validation, no namespace required), resource, mutator (EditObjectMetadata, EditRules, AddRule, SetAggregationRule), and flavors (PreserveCurrentLabels, PreserveCurrentAnnotations, PreserveExternalRules). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Documents the ClusterRole primitive API, mutation system, editors, flavors, aggregation rule support, and usage patterns. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 1 comment.

pkg/primitives/clusterrole/flavors.go

…ot set semantics The docs claimed slice fields were compared as "unordered sets" but the implementation treats duplicates as significant (multiset equality). Updated comments to accurately describe the behavior rather than changing the comparison logic. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

sourcehawk · 2026-03-24T02:12:04Z

Claude Review Cycle 2 Complete

Addressed:

flavors.go:72 — Updated PreserveExternalRules and policyRuleEqual doc comments to accurately describe the comparison as order-insensitive with significant duplicates (multiset equality), rather than incorrectly claiming set semantics.

Intentionally ignored:
None

Copilot

Pull request overview

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

…rimitive

Align with configmap and deployment mutators — NewMutator no longer creates an initial feature plan. BeginFeature must be called before registering any mutations. Updates all tests accordingly and adds constructor/plan invariant tests. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…rimitive

…tive Align with the framework's move to Server-Side Apply. Remove DefaultFieldApplicator, WithCustomFieldApplicator, WithFieldApplicationFlavor, the flavors.go file, and all associated tests. Update builder to use the new generic constructor signature (without defaultApplicator). Update Mutate tests to use Object() output instead of empty structs. Strip field applicator and flavor sections from primitive docs. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

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

Copilot · 2026-03-25T14:15:20Z

docs/primitives.md

+| `pkg/primitives/deployment`  | Workload | [deployment.md](primitives/deployment.md)   |
+| `pkg/primitives/configmap`   | Static   | [configmap.md](primitives/configmap.md)     |
+| `pkg/primitives/clusterrole` | Static   | [clusterrole.md](primitives/clusterrole.md) |



make run-examples currently runs a hard-coded list of examples and does not include the new clusterrole-primitive example (verified in Makefile:122-126). To keep CI/local smoke runs covering all examples, add go run ./examples/clusterrole-primitive/. to the run-examples target (or update docs/README to clarify it’s intentionally excluded).

Suggested change

The `clusterrole` primitive is exercised by the `examples/clusterrole-primitive` example. Because it requires

cluster-scoped RBAC and may need elevated permissions, it is intentionally not included in the default

`make run-examples` target used for CI/local smoke runs.

Copilot · 2026-03-25T14:15:20Z

pkg/primitives/clusterrole/builder.go

+// Builder is a configuration helper for creating and customizing a ClusterRole Resource.
+//
+// It provides a fluent API for registering mutations and data extractors.
+// Build() validates the configuration and returns an initialized Resource
+// ready for use in a reconciliation loop.
+type Builder struct {
+	base *generic.StaticBuilder[*rbacv1.ClusterRole, *Mutator]
+}


The PR description says the clusterrole primitive includes “flavors”, but there’s no flavor-related API/implementation in pkg/primitives/clusterrole (no Flavor references, and the builder only exposes mutations/data extractors). Either update the PR description to match what’s implemented or add the intended flavor support so the change set aligns with the stated scope.

Copilot · 2026-03-25T14:15:21Z

pkg/mutation/editors/policyrules.go

+func (e *PolicyRulesEditor) RemoveRuleByIndex(index int) {
+	if index < 0 || index >= len(*e.rules) {
+		return
+	}
+	*e.rules = append((*e.rules)[:index], (*e.rules)[index+1:]...)
+}


RemoveRuleByIndex uses the append(slice[:i], slice[i+1:]...) pattern, which can keep the removed element’s backing array referenced (and thus retain memory for any nested slices in rbacv1.PolicyRule). Since this repo already uses the slices package elsewhere, prefer slices.Delete(*e.rules, index, index+1) (or explicitly zero the removed slot) to avoid accidental retention and keep deletion semantics consistent.

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

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

Copilot AI reviewed Mar 22, 2026

View reviewed changes

pkg/primitives/clusterrole/mutator.go Outdated Show resolved Hide resolved

pkg/primitives/clusterrole/builder.go Outdated Show resolved Hide resolved

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

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

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

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

Copilot AI reviewed Mar 22, 2026

View reviewed changes

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

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

Copilot AI reviewed Mar 22, 2026

View reviewed changes

internal/generic/builder_base.go Show resolved Hide resolved

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

sourcehawk force-pushed the feature/clusterrole-primitive branch from 102978d to a1d3fca Compare March 23, 2026 00:18

Copilot started reviewing on behalf of sourcehawk March 23, 2026 00:18 View session

Copilot AI reviewed Mar 23, 2026

View reviewed changes

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:02 View session

Copilot AI reviewed Mar 23, 2026

View reviewed changes

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

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

Copilot AI reviewed Mar 23, 2026

View reviewed changes

pkg/primitives/clusterrole/flavors.go Outdated Show resolved Hide resolved

pkg/primitives/clusterrole/mutator.go Outdated Show resolved Hide resolved

pkg/primitives/clusterrole/builder.go Outdated Show resolved Hide resolved

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

Copilot started reviewing on behalf of sourcehawk March 23, 2026 17:00 View session

Copilot AI reviewed Mar 23, 2026

View reviewed changes

pkg/primitives/clusterrole/builder.go Show resolved Hide resolved

pkg/primitives/clusterrole/flavors.go Outdated Show resolved Hide resolved

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

pkg/primitives/clusterrole/mutator.go Outdated Show resolved Hide resolved

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

Add ClusterRole primitive documentation

b8664ac

Documents the ClusterRole primitive API, mutation system, editors, flavors, aggregation rule support, and usage patterns. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot AI reviewed Mar 24, 2026

View reviewed changes

pkg/primitives/clusterrole/flavors.go Outdated Show resolved Hide resolved

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

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

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

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

Copilot AI reviewed Mar 24, 2026

View reviewed changes

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

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

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

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

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

Merge remote-tracking branch 'origin/main' into feature/clusterrole-p…

88007dd

…rimitive

Merge remote-tracking branch 'origin/main' into feature/clusterrole-p…

6a1f43a

…rimitive

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

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

Copilot AI reviewed Mar 25, 2026

View reviewed changes

+The `clusterrole` primitive is exercised by the `examples/clusterrole-primitive` example. Because it requires
+cluster-scoped RBAC and may need elevated permissions, it is intentionally not included in the default
+`make run-examples` target used for CI/local smoke runs.

Conversation

sourcehawk commented Mar 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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!

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!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

sourcehawk commented Mar 22, 2026

Claude Review Cycle 1 Complete

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!

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!

Uh oh!

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!

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!

Uh oh!

Uh oh!

Copilot AI left a comment

sourcehawk commented Mar 22, 2026 •

edited

Loading