NGF: Document patching dataplane Service, Deployment, DaemonSet

content/ngf/how-to/data-plane-configuration.md

@@ -375,3 +375,119 @@ To view the full list of configuration options, see the `NginxProxy spec` in the
 
 ---
 
+### Patch data plane Service, Deployment, and DaemonSet
+
+NGINX Gateway Fabric supports advanced customization of the data plane Service, Deployment, and DaemonSet objects using patches in the `NginxProxy` resource. This allows you to apply Kubernetes-style patches to these resources, enabling custom labels, annotations, or other modifications that are not directly exposed via the NginxProxy spec.
+
+#### Supported Patch Types
+
+You can specify one or more patches for each of the following resources:
+
+- `spec.kubernetes.service.patches`
+- `spec.kubernetes.deployment.patches`
+- `spec.kubernetes.daemonSet.patches`
+
+Each patch has two fields:
+
+- `type`: The patch type. Supported values are:
+    - `StrategicMerge` (default): Strategic merge patch (Kubernetes default for most resources)
+    - `Merge`: JSON merge patch (RFC 7386)
+    - `JSONPatch`: JSON patch (RFC 6902)
+- `value`: The patch data. For `StrategicMerge` and `Merge`, this should be a JSON object. For `JSONPatch`, this should be a JSON array of patch operations.
+
+Patches are applied in the order they appear in the array. Later patches can override fields set by earlier patches.
+
+#### Example: Add a label to the Service
+
+```yaml
+apiVersion: gateway.nginx.org/v1alpha2
+kind: NginxProxy
+metadata:
+  name: ngf-proxy-patch-service
+spec:
+  kubernetes:
+    service:
+      patches:
+        - type: StrategicMerge
+          value:
+            metadata:
+              labels:
+                custom-label: "true"
+```
+
+#### Example: Patch the Deployment replicas and add an annotation
+
+```yaml
+apiVersion: gateway.nginx.org/v1alpha2
+kind: NginxProxy
+metadata:
+  name: ngf-proxy-patch-deployment
+spec:
+  kubernetes:
+    deployment:
+      patches:
+        - type: Merge
+          value:
+            metadata:
+              annotations:
+                custom-annotation: "patched"
+            spec:
+              replicas: 3
+```
+
+#### Example: Use JSONPatch to add a label to the DaemonSet
+
+```yaml
+apiVersion: gateway.nginx.org/v1alpha2
+kind: NginxProxy
+metadata:
+  name: ngf-proxy-patch-daemonset
+spec:
+  kubernetes:
+    daemonSet:
+      patches:
+        - type: JSONPatch
+          value:
+            - op: add
+              path: /metadata/labels/json-patched
+              value: "true"
+```
+
+#### Example: Multiple patches, later patch overrides earlier
+
+```yaml
+apiVersion: gateway.nginx.org/v1alpha2
+kind: NginxProxy
+metadata:
+  name: ngf-proxy-multi-patch
+spec:
+  kubernetes:
+    service:
+      patches:
+        - type: StrategicMerge
+          value:
+            metadata:
+              labels:
+                override-label: "first"
+        - type: StrategicMerge
+          value:
+            metadata:
+              labels:
+                override-label: "second"
+```
+
+In this example, the final Service will have `override-label: second`.
+
+{{< note >}}
+**Which patch type should I use?**
+
+- **StrategicMerge** is the default and most user-friendly for Kubernetes-native resources like Deployments and Services. It understands lists and merges fields intelligently (e.g., merging containers by name). Use this for most use cases.
+- **Merge** (JSON Merge Patch) is simpler and works well for basic object merges, but does not handle lists or complex merging. Use this if you want to replace entire fields or for non-Kubernetes-native resources.
+- **JSONPatch** is the most powerful and flexible, allowing you to add, remove, or replace specific fields using RFC 6902 operations. Use this for advanced or fine-grained changes, but it is more verbose and error-prone.
+
+If unsure, start with StrategicMerge. Use JSONPatch only if you need to surgically modify fields that cannot be addressed by the other patch types.
+
+Patches are applied after all other NginxProxy configuration is rendered. Invalid patches will result in a validation error and will not be applied.
+{{< /note >}}
+
+---