Add generic resource patches

README.md

@@ -18,6 +18,7 @@ Details:
 - [Serving Configuration](https://knative.dev/docs/install/operator/configuring-serving-cr/)
 - [Eventing Configuration](https://knative.dev/docs/install/operator/configuring-eventing-cr/)
 - [Upgrade](docs/upgrade.md)
+- [Customizing generated resources with patches](docs/resource-patches.md)
 - [Multi-cluster deployment](docs/multicluster.md)
 - [Development](docs/development.md)
 - [Multi-cluster E2E testing](docs/development/e2e-multicluster.md)

config/charts/knative-operator/templates/crds/knativeeventings.yaml

@@ -1685,6 +1685,57 @@ spec:
                     description: Labels overrides labels for the namespace and its template.
                     type: object
                 type: object
+              patches:
+                description: Patches customize generated resources after all built-in transformations have been applied.
+                items:
+                  description: ResourcePatch customizes one generated Kubernetes resource.
+                  properties:
+                    patch:
+                      description: Patch defines the patch type and content to apply.
+                      properties:
+                        content:
+                          description: Content is a JSON or YAML patch document.
+                          minLength: 1
+                          type: string
+                        type:
+                          description: 'Type is the patch type: "json", "merge", or "strategic".'
+                          enum:
+                          - json
+                          - merge
+                          - strategic
+                          type: string
+                      required:
+                      - content
+                      - type
+                      type: object
+                    target:
+                      description: Target identifies exactly one generated resource to patch.
+                      properties:
+                        apiVersion:
+                          description: APIVersion is the API version of the target resource, for example "apps/v1".
+                          minLength: 1
+                          type: string
+                        kind:
+                          description: Kind is the Kubernetes kind of the target resource, for example "Deployment".
+                          minLength: 1
+                          type: string
+                        name:
+                          description: Name is the name of the target resource, for example "activator".
+                          minLength: 1
+                          type: string
+                        namespace:
+                          description: Namespace optionally disambiguates resources with the same API version, kind, and name.
+                          type: string
+                      required:
+                      - apiVersion
+                      - kind
+                      - name
+                      type: object
+                  required:
+                  - patch
+                  - target
+                  type: object
+                type: array
               podDisruptionBudgets:
                 description: PodDisruptionBudgetOverride overrides PodDisruptionBudget configurations via minAvailable.
                 items:

config/charts/knative-operator/templates/crds/knativeservings.yaml

@@ -2012,6 +2012,57 @@ spec:
                     description: Labels overrides labels for the namespace and its template.
                     type: object
                 type: object
+              patches:
+                description: Patches customize generated resources after all built-in transformations have been applied.
+                items:
+                  description: ResourcePatch customizes one generated Kubernetes resource.
+                  properties:
+                    patch:
+                      description: Patch defines the patch type and content to apply.
+                      properties:
+                        content:
+                          description: Content is a JSON or YAML patch document.
+                          minLength: 1
+                          type: string
+                        type:
+                          description: 'Type is the patch type: "json", "merge", or "strategic".'
+                          enum:
+                          - json
+                          - merge
+                          - strategic
+                          type: string
+                      required:
+                      - content
+                      - type
+                      type: object
+                    target:
+                      description: Target identifies exactly one generated resource to patch.
+                      properties:
+                        apiVersion:
+                          description: APIVersion is the API version of the target resource, for example "apps/v1".
+                          minLength: 1
+                          type: string
+                        kind:
+                          description: Kind is the Kubernetes kind of the target resource, for example "Deployment".
+                          minLength: 1
+                          type: string
+                        name:
+                          description: Name is the name of the target resource, for example "activator".
+                          minLength: 1
+                          type: string
+                        namespace:
+                          description: Namespace optionally disambiguates resources with the same API version, kind, and name.
+                          type: string
+                      required:
+                      - apiVersion
+                      - kind
+                      - name
+                      type: object
+                  required:
+                  - patch
+                  - target
+                  type: object
+                type: array
               podDisruptionBudgets:
                 description: PodDisruptionBudgetOverride overrides PodDisruptionBudget configurations via minAvailable.
                 items:

config/crd/bases/operator.knative.dev_knativeeventings.yaml

@@ -1760,6 +1760,64 @@ spec:
                       template.
                     type: object
                 type: object
+              patches:
+                description: Patches customize generated resources after all built-in
+                  transformations have been applied.
+                items:
+                  description: ResourcePatch customizes one generated Kubernetes resource.
+                  properties:
+                    patch:
+                      description: Patch defines the patch type and content to apply.
+                      properties:
+                        content:
+                          description: Content is a JSON or YAML patch document.
+                          minLength: 1
+                          type: string
+                        type:
+                          description: 'Type is the patch type: "json", "merge", or
+                            "strategic".'
+                          enum:
+                          - json
+                          - merge
+                          - strategic
+                          type: string
+                      required:
+                      - content
+                      - type
+                      type: object
+                    target:
+                      description: Target identifies exactly one generated resource
+                        to patch.
+                      properties:
+                        apiVersion:
+                          description: APIVersion is the API version of the target
+                            resource, for example "apps/v1".
+                          minLength: 1
+                          type: string
+                        kind:
+                          description: Kind is the Kubernetes kind of the target resource,
+                            for example "Deployment".
+                          minLength: 1
+                          type: string
+                        name:
+                          description: Name is the name of the target resource, for
+                            example "activator".
+                          minLength: 1
+                          type: string
+                        namespace:
+                          description: Namespace optionally disambiguates resources
+                            with the same API version, kind, and name.
+                          type: string
+                      required:
+                      - apiVersion
+                      - kind
+                      - name
+                      type: object
+                  required:
+                  - patch
+                  - target
+                  type: object
+                type: array
               podDisruptionBudgets:
                 description: PodDisruptionBudgetOverride overrides PodDisruptionBudget
                   configurations via minAvailable.

config/crd/bases/operator.knative.dev_knativeservings.yaml

@@ -2118,6 +2118,64 @@ spec:
                       template.
                     type: object
                 type: object
+              patches:
+                description: Patches customize generated resources after all built-in
+                  transformations have been applied.
+                items:
+                  description: ResourcePatch customizes one generated Kubernetes resource.
+                  properties:
+                    patch:
+                      description: Patch defines the patch type and content to apply.
+                      properties:
+                        content:
+                          description: Content is a JSON or YAML patch document.
+                          minLength: 1
+                          type: string
+                        type:
+                          description: 'Type is the patch type: "json", "merge", or
+                            "strategic".'
+                          enum:
+                          - json
+                          - merge
+                          - strategic
+                          type: string
+                      required:
+                      - content
+                      - type
+                      type: object
+                    target:
+                      description: Target identifies exactly one generated resource
+                        to patch.
+                      properties:
+                        apiVersion:
+                          description: APIVersion is the API version of the target
+                            resource, for example "apps/v1".
+                          minLength: 1
+                          type: string
+                        kind:
+                          description: Kind is the Kubernetes kind of the target resource,
+                            for example "Deployment".
+                          minLength: 1
+                          type: string
+                        name:
+                          description: Name is the name of the target resource, for
+                            example "activator".
+                          minLength: 1
+                          type: string
+                        namespace:
+                          description: Namespace optionally disambiguates resources
+                            with the same API version, kind, and name.
+                          type: string
+                      required:
+                      - apiVersion
+                      - kind
+                      - name
+                      type: object
+                  required:
+                  - patch
+                  - target
+                  type: object
+                type: array
               podDisruptionBudgets:
                 description: PodDisruptionBudgetOverride overrides PodDisruptionBudget
                   configurations via minAvailable.

docs/resource-patches.md

@@ -0,0 +1,100 @@
+# Customizing generated resources with patches
+
+Cluster administrators can use `spec.patches` on a `KnativeServing` or
+`KnativeEventing` resource when an existing typed override does not cover the
+generated Kubernetes resource they need to change. Patches run after the
+Operator's built-in transformations and apply in declaration order. Each patch
+sees the result of earlier patches, so a later patch can override their changes.
+
+## Patch target
+
+Each patch must identify exactly one generated resource by API version, kind,
+and name. Set `namespace` only when resources in more than one namespace have
+the same identity. Reconciliation fails if the target matches zero or multiple
+resources; this makes a renamed or removed target visible during an upgrade.
+
+```yaml
+spec:
+  patches:
+  - target:
+      apiVersion: autoscaling/v2
+      kind: HorizontalPodAutoscaler
+      name: webhook
+    patch:
+      type: strategic
+      content: |
+        spec:
+          minReplicas: 2
+          maxReplicas: 10
+```
+
+Patches apply to all resources assembled for the component, including Serving
+or Eventing core resources, enabled Ingress or Source resources, extension
+resources, and `additionalManifests`.
+
+| Patch type | Use it for | Content format |
+| --- | --- | --- |
+| `strategic` | Kubernetes resources with named lists, such as Deployment containers | Strategic Merge Patch in YAML or JSON |
+| `merge` | Maps and scalar fields, including custom resources | RFC 7386 Merge Patch in YAML or JSON |
+| `json` | Exact add, replace, or remove operations | RFC 6902 JSON Patch in YAML or JSON |
+
+Strategic Merge Patch requires a Kubernetes type registered in the Operator's
+scheme. Use `merge` or `json` for an unregistered custom resource. A patch may
+not change the target's API version, kind, name, or namespace.
+
+## Letting KEDA manage replicas
+
+Knative 1.23 includes the following HorizontalPodAutoscalers. An ingress or
+broker HPA is present only when its corresponding optional component is
+enabled.
+
+| Custom resource | Workload | HPA name |
+| --- | --- | --- |
+| `KnativeServing` | `activator` | `activator` |
+| `KnativeServing` | `webhook` | `webhook` |
+| `KnativeServing` with Kourier | `3scale-kourier-gateway` | `3scale-kourier-gateway` |
+| `KnativeEventing` | `eventing-webhook` | `eventing-webhook` |
+| `KnativeEventing` with MTChannelBasedBroker | `mt-broker-ingress` | `broker-ingress-hpa` |
+| `KnativeEventing` with MTChannelBasedBroker | `mt-broker-filter` | `broker-filter-hpa` |
+
+Run `kubectl get hpa -n knative-serving` or `kubectl get hpa -n knative-eventing`
+to confirm which HPAs are present in the cluster.
+
+To replace the bundled `activator` HPA with KEDA, remove the HPA and leave
+`spec.replicas` unmanaged by the Operator:
+
+```yaml
+apiVersion: operator.knative.dev/v1beta1
+kind: KnativeServing
+metadata:
+  name: knative-serving
+  namespace: knative-serving
+spec:
+  patches:
+  - target:
+      apiVersion: autoscaling/v2
+      kind: HorizontalPodAutoscaler
+      name: activator
+    patch:
+      type: strategic
+      content: |
+        $patch: delete
+  - target:
+      apiVersion: apps/v1
+      kind: Deployment
+      name: activator
+    patch:
+      type: strategic
+      content: |
+        spec:
+          replicas: null
+```
+
+The root-level `$patch: delete` directive means the exact HPA identity must
+remain absent. Configure the external autoscaler to use another HPA name.
+Removing the delete patch causes the bundled HPA to be created again on the
+next reconciliation.
+
+A root-level `$patch: delete` cannot target a CustomResourceDefinition or
+Namespace. Knative Serving also requires its `apps/v1` Deployment named
+`webhook` during installation, so that Deployment cannot be deleted.

go.mod

@@ -3,6 +3,7 @@ module knative.dev/operator
 go 1.25.0
 
 require (
+	github.com/evanphx/json-patch/v5 v5.9.11
 	github.com/go-logr/zapr v1.3.0
 	github.com/google/go-cmp v0.7.0
 	github.com/google/go-github/v33 v33.0.0
@@ -69,7 +70,6 @@ require (
 	github.com/dimchansky/utfbom v1.1.1 // indirect
 	github.com/elliotchance/orderedmap v1.8.0 // indirect
 	github.com/emicklei/go-restful/v3 v3.13.0 // indirect
-	github.com/evanphx/json-patch/v5 v5.9.11 // indirect
 	github.com/fatih/color v1.18.0 // indirect
 	github.com/felixge/httpsnoop v1.0.4 // indirect
 	github.com/fxamacker/cbor/v2 v2.9.0 // indirect