You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: content/ngf/how-to/data-plane-configuration.md
+125Lines changed: 125 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -375,3 +375,128 @@ To view the full list of configuration options, see the `NginxProxy spec` in the
375
375
376
376
---
377
377
378
+
### Patch data plane Service, Deployment, and DaemonSet
379
+
380
+
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.
381
+
382
+
#### Supported Patch Types
383
+
384
+
You can specify one or more patches for each of the following resources:
385
+
386
+
- `spec.kubernetes.service.patches`
387
+
- `spec.kubernetes.deployment.patches`
388
+
- `spec.kubernetes.daemonSet.patches`
389
+
390
+
Each patch has two fields:
391
+
392
+
- `type`: The patch type. Supported values are:
393
+
- `StrategicMerge` (default): Strategic merge patch (Kubernetes default for most resources)
394
+
- `Merge`: JSON merge patch (RFC 7386)
395
+
- `JSONPatch`: JSON patch (RFC 6902)
396
+
- `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.
397
+
398
+
Patches are applied in the order they appear in the array. Later patches can override fields set by earlier patches.
399
+
400
+
#### Example: Configure Service with session affinity
401
+
402
+
```yaml
403
+
apiVersion: gateway.nginx.org/v1alpha2
404
+
kind: NginxProxy
405
+
metadata:
406
+
name: ngf-proxy-patch-service
407
+
spec:
408
+
kubernetes:
409
+
service:
410
+
patches:
411
+
- type: StrategicMerge
412
+
value:
413
+
spec:
414
+
sessionAffinity: ClientIP
415
+
sessionAffinityConfig:
416
+
clientIP:
417
+
timeoutSeconds: 300
418
+
```
419
+
420
+
#### Example: Configure Deployment with custom strategy
421
+
422
+
```yaml
423
+
apiVersion: gateway.nginx.org/v1alpha2
424
+
kind: NginxProxy
425
+
metadata:
426
+
name: ngf-proxy-patch-deployment
427
+
spec:
428
+
kubernetes:
429
+
deployment:
430
+
patches:
431
+
- type: Merge
432
+
value:
433
+
spec:
434
+
strategy:
435
+
type: RollingUpdate
436
+
rollingUpdate:
437
+
maxUnavailable: 0
438
+
maxSurge: 2
439
+
```
440
+
441
+
#### Example: Use JSONPatch to configure DaemonSet host networking and priority
442
+
443
+
```yaml
444
+
apiVersion: gateway.nginx.org/v1alpha2
445
+
kind: NginxProxy
446
+
metadata:
447
+
name: ngf-proxy-patch-daemonset
448
+
spec:
449
+
kubernetes:
450
+
daemonSet:
451
+
patches:
452
+
- type: JSONPatch
453
+
value:
454
+
- op: add
455
+
path: /spec/template/spec/hostNetwork
456
+
value: true
457
+
- op: add
458
+
path: /spec/template/spec/dnsPolicy
459
+
value: "ClusterFirstWithHostNet"
460
+
- op: add
461
+
path: /spec/template/spec/priorityClassName
462
+
value: "system-node-critical"
463
+
```
464
+
465
+
#### Example: Multiple patches, later patch overrides earlier
466
+
467
+
```yaml
468
+
apiVersion: gateway.nginx.org/v1alpha2
469
+
kind: NginxProxy
470
+
metadata:
471
+
name: ngf-proxy-multi-patch
472
+
spec:
473
+
kubernetes:
474
+
service:
475
+
patches:
476
+
- type: StrategicMerge
477
+
value:
478
+
spec:
479
+
sessionAffinity: ClientIP
480
+
publishNotReadyAddresses: false
481
+
- type: StrategicMerge
482
+
value:
483
+
spec:
484
+
sessionAffinity: None
485
+
publishNotReadyAddresses: true
486
+
```
487
+
488
+
In this example, the final Service will have `sessionAffinity: None` and `publishNotReadyAddresses: true` because the second patch overrides the values from the first patch.
489
+
490
+
{{< note >}}
491
+
**Which patch type should I use?**
492
+
493
+
- **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.
494
+
- **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.
495
+
- **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.
496
+
497
+
If unsure, start with StrategicMerge. Use JSONPatch only if you need to surgically modify fields that cannot be addressed by the other patch types.
498
+
499
+
Patches are applied after all other NginxProxy configuration is rendered. Invalid patches will result in a validation error and will not be applied.
Copy file name to clipboardExpand all lines: content/ngf/how-to/scaling.md
+45-15Lines changed: 45 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,36 +16,64 @@ It provides guidance on how to scale each plane effectively, and when you should
16
16
17
17
The data plane is the NGINX deployment that handles user traffic to backend applications. Every Gateway object created provisions its own NGINX deployment and configuration.
18
18
19
-
You have two options for scaling the data plane:
19
+
You have multiple options for scaling the data plane:
20
20
21
+
- Increasing the number of [worker connections](https://nginx.org/en/docs/ngx_core_module.html#worker_connections) for an existing deployment
21
22
- Increasing the number of replicas for an existing deployment
22
23
- Creating a new Gateway for a new data plane
23
24
24
-
#### When to increase replicas or create a new Gateway
25
+
#### When to increase worker connections, replicas, or create a new Gateway
25
26
26
-
Understanding when to increase replicas or create a new Gateway is key to managing traffic effectively.
27
+
Understanding when to increase worker connections, replicas, or create a new Gateway is key to managing traffic effectively.
27
28
28
-
Increasing data plane replicas is ideal when you need to handle more traffic without changing the configuration.
29
+
Increasing worker connections or replicas is ideal when you need to handle more traffic without changing the overall routing configuration. Setting the worker connections field allows a single NGINX data plane instance to handle more connections without needing to scale the replicas. However, scaling the replicas can be beneficial to reduce single points of failure.
29
30
30
-
For example, if you're routing traffic to `api.example.com` and notice an increase in load, you can scale the replicas from 1 to 5 to better distribute the traffic and reduce latency.
31
+
Scaling replicas can be done manually or automatically using a [Horizontal Pod Autoscaler](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/) (HPA).
31
32
32
-
All replicas will share the same configuration from the Gateway used to set up the data plane, simplifying configuration management.
33
+
To update worker connections (default: 1024), replicas, or enable autoscaling, you can edit the `NginxProxy` resource:
33
34
34
-
There are two ways to modify the number of replicas for an NGINX deployment:
First, at the time of installation you can modify the field `nginx.replicas` in the `values.yaml` or add the `--set nginx.replicas=` flag to the `helm install` command:
The NginxProxy resource in this example lives in the control plane namespace (default: `nginx-gateway`) and applies to the GatewayClass, but you can also define one per Gateway. See the [Data plane configuration]({{< ref "/ngf/how-to/data-plane-configuration.md" >}}) document for more information.
42
+
43
+
{{< /call-out >}}
44
+
45
+
- Worker connections is set using the `workerConnections` field:
46
+
47
+
```yaml
48
+
spec:
49
+
workerConnections: 4096
40
50
```
41
51
42
-
Secondly, you can update the `NginxProxy` resource while NGINX is running to modify the `kubernetes.deployment.replicas` field and scale the data plane deployment dynamically:
52
+
- Replicas are set using the `kubernetes.deployment.replicas` field:
- Autoscaling can be enabled using the `kubernetes.deployment.autoscaling` field. The default `replicas` value will be used until the Horizontal Pod Autoscaler is running.
62
+
63
+
```yaml
64
+
spec:
65
+
kubernetes:
66
+
deployment:
67
+
autoscaling:
68
+
enable: true
69
+
maxReplicas: 10
46
70
```
47
71
48
-
The alternate way to scale the data plane is by creating a new Gateway. This is beneficial when you need distinct configurations, isolation, or separate policies.
72
+
See the `NginxProxy` section of the [API reference]({{< ref "/ngf/reference/api.md" >}}) for the full specification.
73
+
74
+
All of these fields are also available at installation time by setting them in the [helm values](https://github.com/nginx/nginx-gateway-fabric/blob/main/charts/nginx-gateway-fabric/values.yaml).
75
+
76
+
An alternate way to scale the data plane is by creating a new Gateway. This is beneficial when you need distinct configurations, isolation, or separate policies.
49
77
50
78
For example, if you're routing traffic to a new domain `admin.example.com` and require a different TLS certificate, stricter rate limits, or separate authentication policies, creating a new Gateway could be a good approach.
51
79
@@ -60,7 +88,9 @@ Scaling the control plane can be beneficial in the following scenarios:
60
88
1. _Higher availability_ - When a control plane pod crashes, runs out of memory, or goes down during an upgrade, it can interrupt configuration delivery. By scaling to multiple replicas, another pod can quickly step in and take over, keeping things running smoothly with minimal downtime.
61
89
1. _Faster configuration distribution_ - As the number of connected NGINX instances grows, a single control plane pod may become a bottleneck in handling connections or streaming configuration updates. Scaling the control plane improves concurrency and responsiveness when delivering configuration over gRPC.
62
90
63
-
To scale the control plane, use the `kubectl scale` command on the control plane deployment to increase or decrease the number of replicas. For example, the following command scales the control plane deployment to 3 replicas:
91
+
To automatically scale the control plane, you can create a [Horizontal Pod Autoscaler](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/) (HPA) in the control plane namespace (default: `nginx-gateway`). At installation time, the [NGINX Gateway Fabric helm chart](https://github.com/nginx/nginx-gateway-fabric/blob/main/charts/nginx-gateway-fabric/values.yaml) allows you to set the HPA configuration in the `nginxGateway.autoscaling` section, which will provision an HPA for you. If NGINX Gateway Fabric is already running, then you can manually define the HPA and deploy it.
92
+
93
+
To manually scale the control plane, use the `kubectl scale` command on the control plane deployment to increase or decrease the number of replicas. For example, the following command scales the control plane deployment to 3 replicas:
Copy file name to clipboardExpand all lines: content/ngf/install/upgrade-version.md
+24-55Lines changed: 24 additions & 55 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,15 +13,13 @@ It covers the necessary steps for minor versions as well as major versions (such
13
13
14
14
Many of the nuances in upgrade paths relate to how custom resource definitions (CRDs) are managed.
15
15
16
-
{{< call-out "tip" >}}
17
16
18
-
To avoid interruptions, review the [Delay pod termination for zero downtime upgrades](#configure-delayed-pod-termination-for-zero-downtime-upgrades) section.
17
+
## Minor NGINX Gateway Fabric upgrades
19
18
19
+
{{< call-out "important" >}}
20
+
Upgrading from v2.0.x to v2.1 requires the NGINX Gateway Fabric control plane to be uninstalled and then reinstalled to avoid any downtime to user traffic. CRDs do not need to be removed. The NGINX data plane deployment is not affected by this process, and traffic should still flow uninterrupted. The steps are described below.
20
21
{{< /call-out >}}
21
22
22
-
23
-
## Minor NGINX Gateway Fabric upgrades
24
-
25
23
{{< call-out "important" >}} NGINX Plus users need a JWT secret before upgrading from version 1.4.0 to 1.5.x.
26
24
27
25
Follow the steps in [Set up the JWT]({{< ref "/ngf/install/nginx-plus.md#set-up-the-jwt" >}}) to create the Secret.
@@ -72,14 +70,23 @@ Warning: kubectl apply should be used on resource created by either kubectl crea
72
70
73
71
{{% tab name="Helm" %}}
74
72
75
-
{{< call-out "important" >}} If you are using NGINX Plus and have a different Secret name than the default `nplus-license` name, specify the Secret name by setting `--set nginx.usage.secretName=<secret-name>` when running `helm upgrade`. {{< /call-out >}}
73
+
{{< call-out "important" >}} If you are using NGINX Plus and have a different Secret name than the default `nplus-license` name, specify the Secret name by setting `--set nginx.usage.secretName=<secret-name>` when running `helm install` or `helm upgrade`. {{< /call-out >}}
76
74
77
75
To upgrade the release with Helm, you can use the OCI registry, or download the chart and upgrade from the source.
78
76
79
77
If needed, replace `ngf` with your chosen release name.
80
78
81
79
**Upgrade from the OCI registry**
82
80
81
+
To avoid downtime when upgrading from v2.0.x to v2.1, run the following commands. Be sure to include your previous installation flags and values if necessary. This will not affect user traffic, as the NGINX data plane deployment won't be removed as part of this process.
{{< include "/ngf/installation/helm/pulling-the-chart.md" >}}
90
97
91
-
To upgrade, run the following command:
98
+
To avoid downtime when upgrading from v2.0.x to v2.1, run the following. Be sure to include your previous installation flags and values if necessary. This will not affect user traffic, as the NGINX data plane deployment won't be removed as part of this process.
Select the deployment manifest that matches your current deployment from options available in the [Deploy NGINX Gateway Fabric]({{< ref "/ngf/install/manifests.md#deploy-nginx-gateway-fabric-1">}}) section and apply it.
115
+
Select the deployment manifest that matches your current deployment from options available in the [Deploy NGINX Gateway Fabric]({{< ref "/ngf/install/manifests.md#deploy-nginx-gateway-fabric-1">}}) section.
116
+
117
+
To avoid downtime when upgrading from v2.0.x to v2.1, delete the previous NGINX Gateway Fabric control plane deployment in the `nginx-gateway` namespace, using `kubectl delete deployment`. Then `kubectl apply` the updated manifest file. This will not affect user traffic, as the NGINX data plane deployment won't be removed as part of this process.
102
118
103
119
{{% /tab %}}
104
120
@@ -259,50 +275,3 @@ To upgrade from NGINX Open Source to NGINX Plus, update the Helm command to incl
## Delay pod termination for zero downtime upgrades {#configure-delayed-pod-termination-for-zero-downtime-upgrades}
264
-
265
-
{{< include "/ngf/installation/delay-pod-termination/delay-pod-termination-overview.md" >}}
266
-
267
-
Follow these steps to configure delayed pod termination:
268
-
269
-
1. Open the `values.yaml` for editing.
270
-
271
-
1.**Add delayed shutdown hooks**:
272
-
273
-
- In the `values.yaml` file, add `lifecycle: preStop` hooks to both the `nginx` and `nginx-gateway` container definitions. These hooks instruct the containers to delay their shutdown process, allowing time for connections to close gracefully. Update the `sleep` value to what works for your environment.
274
-
275
-
```yaml
276
-
nginxGateway:
277
-
<...>
278
-
lifecycle:
279
-
preStop:
280
-
exec:
281
-
command:
282
-
- /usr/bin/gateway
283
-
- sleep
284
-
- --duration=40s # This flag is optional, the default is 30s
285
-
286
-
nginx:
287
-
<...>
288
-
lifecycle:
289
-
preStop:
290
-
exec:
291
-
command:
292
-
- /bin/sleep
293
-
- "40"
294
-
```
295
-
296
-
1. **Set the termination grace period**:
297
-
298
-
- {{< include "/ngf/installation/delay-pod-termination/termination-grace-period.md">}}
299
-
300
-
1. Save the changes.
301
-
302
-
{{< call-out "note" >}}
303
-
For additional information on configuring and understanding the behavior of containers and pods during their lifecycle, refer to the following Kubernetes documentation:
Copy file name to clipboardExpand all lines: content/ngf/overview/gateway-api-compatibility.md
+4-1Lines changed: 4 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -136,9 +136,11 @@ See the [controller]({{< ref "/ngf/reference/cli-help.md#controller">}}) command
136
136
-`ResolvedRefs/True/ResolvedRefs`
137
137
-`ResolvedRefs/False/InvalidCertificateRef`
138
138
-`ResolvedRefs/False/InvalidRouteKinds`
139
+
-`ResolvedRefs/False/RefNotPermitted`
139
140
-`Conflicted/True/ProtocolConflict`
140
141
-`Conflicted/True/HostnameConflict`
141
142
-`Conflicted/False/NoConflicts`
143
+
-`OverlappingTLSConfig/True/OverlappingHostnames`
142
144
143
145
### HTTPRoute
144
146
@@ -167,7 +169,7 @@ See the [controller]({{< ref "/ngf/reference/cli-help.md#controller">}}) command
167
169
-`requestHeaderModifier`: Supported. If multiple filters are configured, NGINX Gateway Fabric will choose the first and ignore the rest.
168
170
-`urlRewrite`: Supported. If multiple filters are configured, NGINX Gateway Fabric will choose the first and ignore the rest. Incompatible with `requestRedirect`.
169
171
-`responseHeaderModifier`: Supported. If multiple filters are configured, NGINX Gateway Fabric will choose the first and ignore the rest.
170
-
-`requestMirror`: Supported. Multiple mirrors can be specified.
172
+
-`requestMirror`: Supported. Multiple mirrors can be specified. Percent and fraction-based mirroring are supported.
171
173
-`extensionRef`: Supported for SnippetsFilters.
172
174
-`backendRefs`: Partially supported. Backend ref `filters` are not supported.
173
175
-`status`
@@ -189,6 +191,7 @@ See the [controller]({{< ref "/ngf/reference/cli-help.md#controller">}}) command
189
191
-`ResolvedRefs/False/BackendNotFound`
190
192
-`ResolvedRefs/False/UnsupportedValue`: Custom reason for when one of the HTTPRoute rules has a backendRef with an unsupported value.
191
193
-`ResolvedRefs/False/InvalidIPFamily`: Custom reason for when one of the HTTPRoute rules has a backendRef that has an invalid IPFamily.
0 commit comments