Add generic resource patches

[kahirokunn]

Summary

This adds a general-purpose spec.patches mechanism to KnativeServing and KnativeEventing.

It covers the long tail of customizations that the Operator does not expose today, without requiring a dedicated API field and transformer for every use case. Patches are applied to the final generated resources, so the same mechanism works for core Serving and Eventing resources, optional Ingress and Source resources, extensions, and additionalManifests.

Existing custom resources are unaffected when spec.patches is empty.

Motivation

The Operator already provides typed overrides for common settings. Those remain the preferred interface because they are discoverable and can be validated as part of the API.

However, Kubernetes resources have many fields that are useful only in particular environments. Adding each one to the Operator API would require more API surface, transformation code, generated CRDs, and tests. spec.patches provides an escape hatch for those cases while keeping the common paths typed.

Proposed Changes

• Add spec.patches to both KnativeServing and KnativeEventing.
• Support JSON Patch, JSON Merge Patch, and Strategic Merge Patch.
• Apply patches in declaration order after namespace injection and all existing component transforms.
• Require each target to match exactly one generated resource. namespace can disambiguate otherwise identical targets.
• Prevent patches from changing apiVersion, kind, metadata.name, or metadata.namespace.
• Support root-level Strategic Merge Patch $patch: delete for removing a generated resource from the desired manifest.
• Keep the existing CRD lifecycle behavior by rejecting CRD deletion.

The full usage guide is in docs/resource-patches.md.

Usage

For example, this changes the rolling update strategy of the Serving controller, which does not need a dedicated Operator API field:

apiVersion: operator.knative.dev/v1beta1
kind: KnativeServing
metadata:
  name: knative-serving
  namespace: knative-serving
spec:
  patches:
  - target:
      apiVersion: apps/v1
      kind: Deployment
      name: controller
    patch:
      type: strategic
      content: |
        spec:
          strategy:
            rollingUpdate:
              maxUnavailable: 0
              maxSurge: 1

Targets use the final apiVersion, kind, name, and optional namespace of the generated resource. A missing or ambiguous target fails reconciliation so that stale patches are visible during upgrades.

The usage guide also includes an external autoscaler example: deleting a bundled HPA and removing spec.replicas from its Deployment lets a controller such as KEDA manage scaling without the Operator restoring those fields.

Release Note

Add spec.patches to KnativeServing and KnativeEventing for customizing generated resources with JSON, merge, or strategic merge patches.

[knative-prow]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: kahirokunn
Once this PR has been reviewed and has the lgtm label, please assign dprotaso for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[codecov]

Codecov Report

❌ Patch coverage is 82.22222% with 24 lines in your changes missing coverage. Please review.
✅ Project coverage is 65.49%. Comparing base (8f00498) to head (3553b0f).

Files with missing lines	Patch %	Lines
pkg/reconciler/common/patches.go	83.45%	12 Missing and 10 partials ⚠️
pkg/apis/operator/base/common.go	0.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2337      +/-   ##
==========================================
+ Coverage   63.89%   65.49%   +1.59%     
==========================================
  Files          55       56       +1     
  Lines        2479     2614     +135     
==========================================
+ Hits         1584     1712     +128     
+ Misses        776      771       -5     
- Partials      119      131      +12     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[kahirokunn]

/ok-to-test

[kahirokunn]

/test integration-tests-multicluster

[kahirokunn]

@dsimansk Hi ✋ PTAL. Thank you 🙏