feat: add operations field to mutation ApplyTo spec #4135

pikilisaikiran · 2025-09-01T10:22:18Z

Add operations field to mutation ApplyTo specification

Summary

This PR introduces an operations field to the ApplyTo specification in Gatekeeper mutations, enabling granular control over which Kubernetes admission operations (CREATE, UPDATE, DELETE) trigger mutations.

Problem Solved

Fixes #4121: CronJob Pods getting stuck due to mutations attempting to modify immutable fields during UPDATE operations.

Before: Mutations always applied on both CREATE and UPDATE operations, causing failures when trying to mutate immutable Pod fields like environment variables.

After: Users can specify operations: ["CREATE"] to only mutate during resource creation, avoiding immutable field issues.

Key Changes

Core Implementation

✅ Add Operations []string field to ApplyTo struct
✅ Update mutation matching logic in MatchWithApplyTo function
✅ Add Operation field to Mutable type for context propagation
✅ Maintain 100% backward compatibility (defaults to CREATE+UPDATE)

Testing & Validation

✅ Comprehensive unit tests for operation matching logic
✅ Live cluster testing with existing CRDs (no breaking changes)
✅ Multiple test scenarios covering all operation combinations

Documentation & Examples

✅ Updated main mutation documentation with operations field explanation
✅ Added practical examples showing real-world usage patterns
✅ Created comprehensive README for mutation examples
✅ Enhanced Go code comments for better developer experience

Usage Examples

Solving Immutable Field Issues (Main Use Case)

apiVersion: mutations.gatekeeper.sh/v1
kind: Assign
metadata:
  name: fix-cronjob-env-vars
spec:
  applyTo:
  - groups: [""]
    kinds: ["Pod"]
    versions: ["v1"]
    operations: ["CREATE"]  # Only apply on creation
  location: "spec.containers[name:*].env[name:MY_VAR].value"
  parameters:
    assign:
      value: "production"

Other Supported Patterns

operations: ["CREATE"] - Creation-only mutations
operations: ["UPDATE"] - Update-only mutations
operations: ["CREATE", "UPDATE"] - Explicit default behavior
operations: ["DELETE"] - Advanced cleanup scenarios
No operations field - Backward compatible (CREATE+UPDATE)

Backward Compatibility

✅ Zero Breaking Changes

Existing mutations without operations field work unchanged
Default behavior preserved as CREATE+UPDATE operations
No required updates to existing deployments
Gradual adoption - users can migrate at their own pace

Testing Performed

Unit Tests: All new operation matching logic
Integration Tests: Live cluster deployment with existing CRDs
Backward Compatibility: Verified existing mutations unchanged
Schema Validation: Confirmed optional field works correctly
Multiple Mutation Types: Tested Assign, ModifySet, etc.

Related Issue

Closes #4121

Checklist

Add granular operation control to Gatekeeper mutations by introducing an 'operations' field in the ApplyTo specification. This allows users to specify which Kubernetes admission operations (CREATE, UPDATE, DELETE) should trigger mutations. Key Changes: - Add Operations []string field to ApplyTo struct - Update mutation matching logic to check operation compatibility - Add Operation field to Mutable type for context propagation - Maintain backward compatibility (defaults to CREATE+UPDATE) - Add comprehensive unit tests for operation matching - Update documentation with usage examples and best practices - Include practical examples demonstrating various operation patterns Fixes: Resolves issues with mutations attempting to modify immutable fields during UPDATE operations, such as Pod environment variables in CronJob scenarios. Backward Compatibility: Existing mutations without operations field continue working unchanged with default CREATE+UPDATE behavior. Testing: Added unit tests, live cluster validation, and comprehensive examples covering all supported operation combinations. Signed-off-by: sai kiran pikili <saikiranpikili@localhost.localdomain>

alex-berger · 2025-09-17T13:14:10Z

@JaydipGabani Any chance we can continue with this PR? It's solving a real pain point in our production environments and I would love to see this land in one of the next releases.

JaydipGabani · 2025-09-17T14:34:30Z

I am planning to discuss this in today's community meeting. I will take a look today to see if anything is missing. Thanks for the ping and thr PR.

JaydipGabani · 2025-09-18T20:28:54Z

@pikilisaikiran ptal - #4121 (comment)

chewong

Overall looks good!

chewong · 2025-10-14T20:45:16Z

examples/assign-with-operations.yaml

+    # No operations field - defaults to CREATE and UPDATE for backward compatibility
+  match:
+    scope: Namespaced
+  location: "metadata.labels.legacy-mutator"


I don't think this is a good example because Assign is not supposed to mutate metadata field per https://open-policy-agent.github.io/gatekeeper/website/docs/mutation#mutation-crds

chewong · 2025-10-14T20:48:17Z

pkg/mutation/match/apply_to.go

+	Versions   []string `json:"versions,omitempty"`
+	// Operations specifies which admission operations (CREATE, UPDATE, DELETE) should trigger
+	// this mutation. If empty, defaults to ["CREATE", "UPDATE"] for backward compatibility.
+	Operations []string `json:"operations,omitempty"`


Let's create type ApplyToOperation string instead of using raw string. We could also add a kubebuilder marker for API validation purposes.

Suggested change

Operations []string `json:"operations,omitempty"`

// +kubebuilder:validation:Enum=CREATE;UPDATE;DELETE

Operations []ApplyToOperation `json:"operations,omitempty"`

chewong · 2025-10-14T20:48:46Z

config/crd/bases/expansion.gatekeeper.sh_expansiontemplate.yaml

Could you also run make manifests so the updated CRDs can get copied to the staging helm chart?

chewong · 2025-10-14T20:49:36Z

pkg/mutation/match/apply_to.go

+func (a ApplyTo) MatchesOperation(operation string) bool {
+	// If no operations specified, default to CREATE and UPDATE for backward compatibility
+	if len(a.Operations) == 0 {
+		return operation == "CREATE" || operation == "UPDATE"


nit: let's rename the constants from admissionv1 package, or create new constants in the match package

Suggested change

return operation == "CREATE" || operation == "UPDATE"

return operation == admissionv1.Create || operation == admissionv1.Update

pikilisaikiran requested a review from a team as a code owner September 1, 2025 10:22

pikilisaikiran force-pushed the feat/mutation-operations-field branch from 6dc29a7 to 3babba5 Compare September 1, 2025 10:30

chewong reviewed Oct 14, 2025

View reviewed changes

JaydipGabani added this to the v3.22.0 milestone Oct 29, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add operations field to mutation ApplyTo spec #4135

feat: add operations field to mutation ApplyTo spec #4135

Uh oh!

pikilisaikiran commented Sep 1, 2025

Uh oh!

alex-berger commented Sep 17, 2025

Uh oh!

JaydipGabani commented Sep 17, 2025

Uh oh!

JaydipGabani commented Sep 18, 2025

Uh oh!

chewong left a comment

Uh oh!

chewong Oct 14, 2025

Uh oh!

chewong Oct 14, 2025

Uh oh!

chewong Oct 14, 2025

Uh oh!

chewong Oct 14, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	Operations []string `json:"operations,omitempty"`
	// +kubebuilder:validation:Enum=CREATE;UPDATE;DELETE
	Operations []ApplyToOperation `json:"operations,omitempty"`

	return operation == "CREATE" \|\| operation == "UPDATE"
	return operation == admissionv1.Create \|\| operation == admissionv1.Update

feat: add operations field to mutation ApplyTo spec #4135

Are you sure you want to change the base?

feat: add operations field to mutation ApplyTo spec #4135

Uh oh!

Conversation

pikilisaikiran commented Sep 1, 2025

Add operations field to mutation ApplyTo specification

Summary

Problem Solved

Key Changes

Core Implementation

Testing & Validation

Documentation & Examples

Usage Examples

Solving Immutable Field Issues (Main Use Case)

Other Supported Patterns

Backward Compatibility

Testing Performed

Related Issue

Checklist

Uh oh!

alex-berger commented Sep 17, 2025

Uh oh!

JaydipGabani commented Sep 17, 2025

Uh oh!

JaydipGabani commented Sep 18, 2025

Uh oh!

chewong left a comment

Choose a reason for hiding this comment

Uh oh!

chewong Oct 14, 2025

Choose a reason for hiding this comment

Uh oh!

chewong Oct 14, 2025

Choose a reason for hiding this comment

Uh oh!

chewong Oct 14, 2025

Choose a reason for hiding this comment

Uh oh!

chewong Oct 14, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants