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
+41-13
Original file line number
Diff line number
Diff line change
@@ -11,9 +11,9 @@ Learn how to dynamically update the NGINX Gateway Fabric global data plane confi
11
11
12
12
## Overview
13
13
14
-
NGINX Gateway Fabric can dynamically update the global data plane configuration without restarting. The data plane configuration contains configuration for NGINX that is not available using the standard Gateway API resources. This includes such things as setting an OpenTelemetry collector config, disabling http2, changing the IP family, or setting the NGINX error log level.
14
+
NGINX Gateway Fabric can dynamically update the global data plane configuration without restarting. The data plane configuration is a global configuration for NGINX that has options that is not available using the standard Gateway API resources. This includes options such as configuring an OpenTelemetry collector, disabling HTTP/2, changing the IP family, modifying infrastructure-related fields, and setting the NGINX error log level.
15
15
16
-
The data plane configuration is stored in the NginxProxy custom resource, which is a namespace-scoped resource that can be attached to a GatewayClass or Gateway. When attached to a GatewayClass, the fields in the NginxProxy affect all Gateways that belong to the GatewayClass.
16
+
The data plane configuration is stored in the `NginxProxy` custom resource, which is a namespace-scoped resource that can be attached to a GatewayClass or Gateway. When attached to a GatewayClass, the fields in the NginxProxy affect all gateways that belong to the GatewayClass.
17
17
When attached to a Gateway, the fields in the NginxProxy only affect the Gateway. If a GatewayClass and its Gateway both specify an NginxProxy, the GatewayClass NginxProxy provides defaults that can be overridden by the Gateway NginxProxy. See the [Merging Semantics](#merging-semantics) section for more detail.
18
18
19
19
---
@@ -172,21 +172,19 @@ telemetry:
172
172
173
173
---
174
174
175
-
## Configuring the GatewayClass NginxProxy on Install
175
+
## Configuring the GatewayClass NginxProxy on install
176
176
177
-
By default, the NginxProxy resource is not created when installing NGINX Gateway Fabric. However, you can set configuration options in the `nginx.config` Helm values, and the resource will be created and attached to the GatewayClass when NGINX Gateway Fabric is installed using Helm. You can also [manually create and attach](#manually-creating-nginxproxies) the resource after NGINX Gateway Fabric is already installed.
177
+
By default, the `NginxProxy` resource is created in the same namespace where NGINX Gateway Fabric is installed. You can set configuration options in the `nginx.` Helm values, and the resource will be created and attached using the set values, when NGINX Gateway Fabric is installed using Helm. You can also manually create and attach specific `NginxProxy` resources to target different data planes [manually creating NginxProxies](#manually-creating-nginxProxies).
178
178
179
179
When installed using the Helm chart, the NginxProxy resource is named `<release-name>-proxy-config` and is created in the release Namespace.
180
180
181
-
**For a full list of configuration options that can be set, see the `NginxProxy spec` in the [API reference]({{< ref "/ngf/reference/api.md" >}}).**
182
-
183
181
{{< note >}} Some global configuration also requires an [associated policy]({{< ref "/ngf/overview/custom-policies.md" >}}) to fully enable a feature (such as [tracing]({{< ref "/ngf/how-to/monitoring/tracing.md" >}}), for example). {{< /note >}}
184
182
185
183
---
186
184
187
185
## Manually Creating NginxProxies
188
186
189
-
The following command creates a basic `NginxProxy` configuration that sets the IP family to `ipv4` instead of the default value of `dual`:
187
+
The following command creates a basic `NginxProxy` configuration in the `default` namespace that sets the IP family to `ipv4` instead of the default value of `dual`:
190
188
191
189
```yaml
192
190
kubectl apply -f - <<EOF
@@ -200,8 +198,6 @@ spec:
200
198
EOF
201
199
```
202
200
203
-
**For a full list of configuration options that can be set, see the `NginxProxy spec` in the [API reference]({{< ref "/ngf/reference/api.md" >}}).**
204
-
205
201
---
206
202
207
203
### Attaching NginxProxy to GatewayClass
@@ -282,11 +278,13 @@ Status:
282
278
283
279
If everything is valid, the `ResolvedRefs` condition should be `True`. Otherwise, you will see an `InvalidParameters` condition in the status.
284
280
281
+
{{< note >}} The `NginxProxy` resource must reside in the same namespace as the Gateway it is attached to. {{< /note >}}
282
+
285
283
---
286
284
287
285
## Configure the data plane log level
288
286
289
-
You can use the `NginxProxy` resource to dynamically configure the Data Plane Log Level.
287
+
You can use the `NginxProxy` resource at the GatewayClass level to dynamically configure the log level for all data plane instances.
290
288
291
289
The following command creates a basic `NginxProxy` configuration that sets the log level to `warn` instead of the default value of `info`:
292
290
@@ -302,7 +300,7 @@ spec:
302
300
EOF
303
301
```
304
302
305
-
To view the full list of supported log levels, see the `NginxProxy spec` in the [API reference]({{< ref "/ngf/reference/api.md" >}}).
303
+
Other log levels supported are debug, notice, error, crit, alert, emerg.
306
304
307
305
{{< note >}}For `debug` logging to work, NGINX needs to be built with `--with-debug` or "in debug mode". NGINX Gateway Fabric can easily
308
306
be [run with NGINX in debug mode](#run-nginx-gateway-fabric-with-nginx-in-debug-mode) upon startup through the addition
@@ -375,6 +373,36 @@ spec:
375
373
EOF
376
374
```
377
375
378
-
For the full configuration API, see the `NginxProxy spec` in the [API reference]({{< ref "/ngf/reference/api.md" >}}).
379
-
380
376
{{< note >}} When sending curl requests to a server expecting proxy information, use the flag `--haproxy-protocol` to avoid broken header errors. {{< /note >}}
377
+
378
+
---
379
+
380
+
## Configure infrastructure-related settings
381
+
382
+
You can configure deployment and service settings for all data plane instances by editing the `NginxProxy` resource at the GatewayClass level. These settings can also be specified under `nginx.` in the Helm values file.
383
+
384
+
Users can specify these settings for NGINX data plane deployments:
385
+
386
+
- _replicas_ specifies the number of data plane pod replicas..
387
+
- The `pod` section provides control over pod scheduling and lifecycle behavior. You can configure settings such as _terminationGracePeriodSeconds_, _tolerations_, _nodeSelector_, _affinity_, and _topologySpreadConstraints_. Use _extraVolumes_ to mount additional volumes, typically alongside container-level _extraVolumeMounts_.
388
+
- The `container` defines settings for the NGINX container itself., such as resource requests and limits using _resources_, and lifecycle hooks like preStop or postStart via _lifecycle_. You can also specify _extraVolumeMounts_ to mount additional volumes defined at the pod level.
389
+
390
+
Users can specify these settings for NGINX data plane service in the `service` config:
391
+
392
+
- _type_ specifies the service type for the NGINX data plane. Allowed values are ClusterIP, NodePort, or LoadBalancer.
393
+
- _externalTrafficPolicy_ sets how external traffic is handled. `Local` preserves the client’s source IP.
394
+
- _annotations_ adds custom annotations to the NGINX data plane service.
395
+
- Certain fields are only applicable when _service.type_ is set to `LoadBalancer`: _loadBalancerIP_ to assign a static IP, _loadBalancerClass_ to define the load balancer implementation, and _loadBalancerSourceRanges_ to restrict access to specific IP ranges (CIDRs).
396
+
397
+
The below fields can only be specified when the `service.type` is `LoadBalancer`:
398
+
- _loadBalancerIP_ specifies the static IP address of the load balancer.
399
+
- _loadBalancerClass_ specifies the class of the load balancer implementation this service belongs to.
400
+
- _loadBalancerSourceRanges_ specifies IP ranges (CIDR) that are allowed to access the load balancer.
401
+
402
+
---
403
+
404
+
## See also
405
+
406
+
For a full list of configuration options that can be set, see the `NginxProxy spec` in the [API reference]({{< ref "/ngf/reference/api.md" >}}).
0 commit comments